How to Write Custom Decodes
When writing a custom decoder, you must create a decoder file named <decoder_name>.ets.c, which you will compile and include in a shared object library. This C file needs to implement an initialization function, a loading function, and any callback functions used to perform the decode (typically, the callbacks that create the summary line and detail lines).
The primary data structure used when writing a custom decoder is of type AceT_Decoder_Plugin. This data structure, defined in ace_client_api.h, is created by the Transaction Analyzer decoder manager and passed into the initialization function of the decoder (init_proc), where it is filled in with your custom callback functions and lists. The following table lists the data structure in detail.
Table 1: AceT_Decoder_Plugin Data Elements
| Element | Data Type | Description |
|---|---|---|
protocols_lptr |
PrgT_List * |
List of protocol names handled by the decoder plug-in. |
prior_protocols_lptr |
PrgT_List * |
Not used. |
preproc_proc |
AceT_Decoder_Preproc_Proc |
Callback function used for pre-processing. |
can_decode_proc |
AceT_Decoder_Can_Decode_Proc |
Not used. |
decode_proc |
AceT_Decoder_Decode_Proc |
Callback function used to generate summary lines. |
details_proc |
AceT_Decoder_Details_Proc |
Callback function used to generate detail lines. |
delete_proc |
AceT_Decoder_Delete_Proc |
Callback function used to destroy memory allocated by the load_proc. |
done_proc |
AceT_Decoder_Done_Proc |
Callback function used for post-processing, such as writing messages to a log. |
A custom decoder requires that at least four procedures be defined in the <decoder_name>.ets.c file. These procedures correspond to the following four activities:
- Initializing the custom decoder.
- Loading any required information.
- Creating summary lines.
- Creating detail lines.
Initializing
When the Riverbed analysis software initializes Transaction Analyzer, it also initializes any custom decoders specified in the ace_decoder_config.gdf file. To initialize the custom decoders, it calls the init_proc for each decoder. The init_proc is a callback defined in the decoder’s shared object library. Details about this callback appear in AceT_Decoder_Plugin_Init_Proc.
Each init_proc is called once to initialize the callback functions and lists that implement its custom decoder. The callback performs this initialization by filling in the decoder plugin data structure (see Table 1) associated with the custom decoder. Most custom decoders require only three elements from this data structure: the decode_proc callback, details_proc callback, and protocols_lptr list. For example:
plugin_ptr->decode_proc = (AceT_Decoder_Decode_Proc) op_http_decoder_decode;
plugin_ptr->details_proc = (AceT_Decoder_Details_Proc) op_http_decoder_details;
plugin_ptr->protocols_lptr = prg_list_create ();
prg_list_strings_append (plugin_ptr->protocols_lptr, "HTTP", VOSC_NIL);
Loading
After initializing a custom decoder, the Riverbed analysis software calls the load_proc defined for that decoder. This callback, defined in the decoder’s shared object library, loads any information required by the decoder. For example, it can allocate state memory, set up a state pointer, or read in a file. Details about this callback appear in AceT_Decoder_Plugin_Load_Proc
Typically, the load_proc takes in an AceT_Import_Handle and is responsible for setting the state information used by the decoder. The import handle is an opaque data structure, passed in by the Riverbed analysis software, that provides context for decode operations. Most load_proc implementations need only a single line, such as:
*client_state_pptr = import_handle_ptr;
Creating the Summary Line
When a user expands a frame in the Protocol Decode Viewer, Transaction Analyzer calls various functions to create summary lines for each protocol in the frame. For each protocol not handled by a built-in decoder, Transaction Analyzer looks for and—if defined—calls the decode_proc for that protocol. The decode_proc reads the data, parses it, creates the summary line text, and adds the summary line to an AceT_Pk_Protocol_Info data structure.
See AceT_Decoder_Decode_Proc for a description and example of the decode_proc callback.
Creating the Detail Lines
When a user expands a summary line in the Protocol Decode Viewer, Transaction Analyzer calls a function to create the detail lines for that protocol. For custom protocols, this will be the details_proc specified in the AceT_Decoder_Plugin data structure for that protocol. The details_proc gets the data for the protocol being decoded, parses it, creates the detail lines, and returns the detail lines in a list.
See AceT_Decoder_Details_Proc for a description and example of the details_proc callback.