How it Works

How it Works
Prev	Chapter 22. Raw Event Handler Interface	Next

The compiler generates parser functions. These functions have the following signature:

         int asn1PP_<type> (OSCTXT* pctxt, ASN1RawEventResp parseIndicator);

Your program will begin by calling one of these parser functions and passing ASN1RER_PARSE. The parser function will parse the ASN.1 value and fire events by invoking your event handlers.

The interface supports three events:

component
actual-type
component-end

The component event fires when a component is ready to be parsed. You receive the numeric identifier for the component (componentID), and a flag (nestedValues) which indicates whether component events may fire for child components. You may respond with:

ASN1RER_CONSUMED: This indicates that you have consumed the value yourself. The parser will continue as if it had parsed the value. You will not receive a component-end event for this component.
ASN1RER_PARSE: This indicates that you want the parser to parse the component's value, continuing to fire events for child components, if applicable. If nestedValues is true, component events will fire for any child components present, followed by a component-end event when the end of the current component is reached. If nestedValues is false, there are no child components to receive events for, and you will not receive a component-end event for this component.
ASN1RER_QUIET_PARSE: This indicates that you want the parser to handle parsing the component's value without firing any events for any child components. You will not receive a component-end event for this component. Return this value when you are neither interested in a component's value nor in any of its sub-values, in order to let the parser move past the value as efficiently as possible.
ASN1RER_STOP_PARSE: This indicates that you want the parser to stop parsing and not consume any more data. The parse function will log and return error RTERR_ABORT_REQUESTED.

The actual-type event fires when an open type is ready to be parsed. It notifies you of the actual type, allowing you to make type-specific decisions. This event only is only fired when -table-unions is used (otherwise, the parser does not attempt to determine the actual type). You receive the numeric identifier for the actual type (actualTypeID), and a length. If the actual type is unknown, the actualTypeID will be 0. If an open type is encoded with fragmentation and -perindef was not used, an error will be returned. Otherwise, the length will represent the defragmented length of the actual type encoding, and the context will hold a defragmented version of the encoding. Thus, your event handler does not need to worry about fragmentation.

The actual-type event is always preceded by a component event with nestedValues equal to true. If you respond to the component event with ASN1RER_CONSUMED or ASN1RER_QUIET_PARSE, the actual-type event will not fire. If you are not interested in receiving events for the open type value, responding to the component event with ASN1RER_QUIET_PARSE lets the parser skip past the open type value in the most efficient way.

You may respond to the actual-type event with:

ASN1RER_CONSUMED: This indicates that you have consumed the actual type value yourself. In this case, the component-end event will not fire for the component. When the actual type is unknown (actualTypeID equals 0), you will need the length parameter (len) in order to know how much data to consume.
ASN1RER_PARSE: This indicates that you want the parser to parse the actual type. When the end of the open type value is reached, so is the end of the component value, and the component-end event will fire.
ASN1RER_QUIET_PARSE: This indicates that you want the parser to handle parsing the actual type, but you don't want to receive events for any child components. The component-end event will not fire for the open type component.
ASN1RER_STOP_PARSE: This indicates that you want the parser to stop parsing and not consume any more data. The parse function will log and return error RTERR_ABORT_REQUESTED.

Implementing a handler for the actual-type event is optional. If you do not implement a handler, the behavior is the same as if you did and returned ASN1RER_PARSE for every event.

The component-end event indicates that the end of a component value has been reached. You receive the numeric component identifier, the same as with the component event. As mentioned above, whether or not you receive this event depends on the nestedValues parameter of the component event, as well as how you respond to the component and/or actual-type events. Basically, if the event is not needed in order for you to know that you won't receive further events for the component, then the event is not fired.

Implementing a handler for the component-end event is optional.