Python API Reference

Modules

UDDEnum

In order to use the mandatory built-in enumerations, the script must import UDDEnum Python module.

Enumerations

BitOrder

This enumeration represents the Bit Order of a field.

ByteOrder

This enumeration represents the Byte order of a multi-byte field.

Classes

OutContext

This class is a singleton and may not be instantiated in the script. The single instance is called “out”, which may be used by the OnDecode function to communicate special decoding results back to the application.

Members

Result

If this member is set to 1 by the OnDecode function, then any decoded fields added will be kept; otherwise, any decoded fields will be rolled back.

Spec

This class represents the static field definitions of a protocol’s message formats.

Methods

DefineField(name, abbreviation, tooltip, bit_order, byte_order)

Defines a new field or updates an existing field.

Return Value: 1 - success, 0 - error

Methods

DefineFieldDecode(name, decode_value, length, decode_name, decode_description)

Define a custom decoding for an existing field. This decoding may override the application’s built-in decoding for a field.

Return Value: 1 - success, 0 - error

RenameField(name, new_name)

Change an existing field name to a new name.

Return Value: 1 - success, 0 - error

InputContext

This class represents the packet/frame to be decoded. It provides access to the raw data, and it is the container for any decoded fields that are added.

Methods

AddField(name, length, parent_id)

Adds a field to the current packet being decoded.

Return Value: If a field has been successfully added to a Packet, its identifier will be returned as the return value.

GetFieldData(field_id, start_pos, length)

Retrieves data from a field.

Return Value: A buffer list of Bytes retrieved data from a field.

GetData(start_pos, length)

Retrieves data from a raw packet.

Return Value: A buffer list of Bytes retrieved data from a field.

Globals

OutContext out

The "out" singleton needs to be used inside the function. If you confirmed the changes of decoding in the script, then out.Result must set to 1; otherwise, the decoding will not be applied.

Entry Point Functions

OnInitialize(spec)

This function must be defined in the decoding script. It allows you to initialize, define, and rename the fields for an existing built-in decoder or a custom script decoder. The application calls this function to initialize the Spec object that represents the protocol decoded by the script. In this function, the script must define the fields handled by the script by adding them to the Spec object. If you make any modifications on the fields definitions for a defined and assigned protocol type in the trace, then application just calls this function once to reorganize the structure of the fields. This function has one parameter named "spec" which is the interface to communicate with application for initialization of the user-defined fields’ declarations and definitions.

Return Value: None

OnDecode(incontext)

This function must be defined in the decoding script. The application calls this function for each packet to be decoded. This function provides one parameter named "incontext" as an interface between application and your script. This parameter allows you to use your already defined fields from the OnInitialize function, add them to the packet and fetch the data from a field or packet in order to support your decoding procedure.

If you set “out.Result = 1” and then return from the function, then the decoded fields will be applied; otherwise, they will be rolled back.

Return Value: None