RecognizeFrame

The RecognizeFrame export function indicates whether a piece of data is recognized as the protocol that the parser detects. The RecognizeFrame export function must be implemented for each parser that the parser DLL supports.

LPBYTERecognizeFrame(HFRAMEhFrame,
LPBYTElpFrame,
LPBYTElpProtocol,
DWORDMacType,
DWORDBytesLeft,
HPROTOCOLhPreviousProtocol,
DWORDnPreviousProtocolOffset,
LPDWORDProtocolStatusCode,
LPHPROTOCOLphNextProtocol,
PDWORD_PTRlpInstData);

Parameters

• hFrame
  [in] Handle to the frame that contains the data.

• lpFrame
  [in] Pointer to the first byte of a frame. The pointer provides a way to view data that other parsers recognize.

• lpProtocol
  [in] Pointer to the start of the unclaimed data. Typically, the unclaimed data is located in the middle of a frame because a previous parser has claimed data before this parser. The parser must test the unclaimed data first.

• MacType
  [in] MAC value of the first protocol in a frame. Typically, the MacType value is used when the parser must identify the first protocol in a frame. The MacType value can be one of the following:

  Value	Meaning
  MAC_TYPE_ETHERNET	802.3
  MAC_TYPE_TOKENRING	802.5
  MAC_TYPE_FDDI	ANSI X3T9.5

• BytesLeft
  [in] The remaining number of bytes from a location in a frame to the end of the frame.

• hPreviousProtocol
  [in] Handle of the previous protocol.

• nPreviousProtocolOffset
  [in] Offset of the previous protocol — beginning of the frame.

• ProtocolStatusCode
  [out] Protocol status indicator. The parser DLL must set one of the following status codes.

  Value	Meaning
  PROTOCOL_STATUS_RECOGNIZED	The parser recognizes the data but does not know which protocol follows. After setting the code, return a pointer to the remaining unclaimed data that follow the recognized protocol. Network Monitor uses the follow set of the protocol to continue parsing.
  PROTOCOL_STATUS_NOT_RECOGNIZED	The parser does not recognize the data. After setting this code, return the pointer to the beginning of the data — using the pointer that the lpProtocol parameter passes to the parser DLL. Network Monitor uses the follow set of the previous protocol to continue parsing.
  PROTOCOL_STATUS_CLAIMED	The parser recognizes the data and claims the remaining data. After setting the code, return NULL for Network Monitor to terminate parsing a frame.
  PROTOCOL_STATUS_NEXT_PROTOCOL	The parser recognizes the data and knows which protocol follows. After setting the code, set the phNextProtocol parameter, and return a pointer to the remaining unclaimed data that follow the recognized protocol. Network Monitor continues parsing the frame.

• phNextProtocol
  [out] Pointer to the handle of the next protocol. This parameter is set when a protocol identifies the protocol that follows a protocol. To obtain the handle of the next protocol, call the GetProtocolFromTable function.

• lpInstData
  [in, out] On input, a pointer to the instance data from the previous protocol.

  On output, a pointer to the instance data for the current protocol. Instance data cannot be longer than a DWORD_PTR in length.

Return Values

If the function is successful, the return value is a pointer to the first byte after the recognized parser data. If the parser claims all the remaining data, the return value is NULL.

If the function is unsuccessful, the return value is an initial pointer that the lpProtocol parameter passes-in.

Remarks

The RecognizeFrame function determines whether the parser recognizes the raw data — starting at the lpProtocol pointer.

• If the protocol recognizes the data, the RecognizeFrame function returns a pointer to the remaining data, or returns NULL if the current protocol is the last protocol in a frame.
• If the protocol does not recognize the data, the RecognizeFrame function returns the pointer passed to the parser DLL in the lpProtocol parameter.

Note  **  RecognizeFrame** can be called before the Register function is called to register the protocol properties. For that reason, the implementation of the RecognizeFrame function does not rely on any properties or structures that are created or initialized during the implementation of the protocol Register function.

Handoff Set and Follow Set

A parser can use a handoff set or follow set to identify for Network Monitor the protocol that follows recognized data.

• If information is available in recognized data, the parser uses its handoff set to obtain a handle to the next protocol, and then passes that handle to Network Monitor.
• If information is not available, the parser does not pass a handle, and Network Monitor uses the parser follow set to determine which protocol follows.

Passing information between protocols

Use the lpInstData parameter to pass information between protocols. On input, you can retrieve the information from the previous protocol. On output, you can pass information to the next protocol.

Instance data can be any data that is less than or equal to a DWORD_PTR in length, or a pointer to data, such as raw frame data, that does not need to be allocated by or freed by the parser.

Requirements

See Also

GetProtocolFromTable