RecognizeFrame

The RecognizeFrame entry point is called to quickly determine if the raw data (starting at lpProtocol passed in) belongs to the protocol the parser understands.

LPBYTE RecognizeFrame(
  HFRAME hFrame,              
  LPBYTE lpFrame,             
  LPBYTE lpProtocol,          
  DWORD MacType,              
  DWORD BytesLeft,            
  HPROTOCOL hPreviousProtocol,  
  DWORD nPreviousProtocolOffset,  
  LPDWORD ProtocolStatusCode,  
  LPHPROTOCOL hNextProtocol,  
  LPDWORD lpInstData          
);
 

Parameters

hFrame

Specifies the handle to the frame being recognized.

lpFrame

Specifies the pointer to the first byte of the whole frame.

lpProtocol

Specifies the pointer to the current unclaimed portion of the frame.

Note This data is probably somewhere in the middle of the frame, because a previous parser has claimed data before this parser.

MacType

Specifies a value as follows:

MacType	Meaning
MAC_TYPE_ETHERNET	802.3
MAC_TYPE_TOKENRING	802.5
MAC_TYPE_FDDI	ANSI X3T9.5

BytesLeft

Specifies the number of bytes in the frame left to process.

hPreviousProtocol

Specifies the handle of the previous protocol.

nPreviousProtocolOffset

Specifies the offset of the previous protocol.

ProtocolStatusCode

When a protocol parser gets called in its recognize function, it can return one of four return codes:

Value	Meaning
PROTOCOL_STATUS_RECOGNIZED	The parser recognized the frame and moved the pointer to the end of its protocol header. Network Monitor uses the protocol's follow set to continue parsing.
PROTOCOL_STATUS_NOT_RECOGNIZED	The parser did not recognize the frame and did not move the pointer (that is, the start data pointer which was passed in). Network Monitor uses the previous protocol's follow set to continue parsing.
PROTOCOL_STATUS_CLAIMED	The parser recognized the frame, claimed it all for itself, and parser recognition terminates.
PROTOCOL_STATUS_NEXT_PROTOCOL	The parser recognized the frame and moved the pointer to the end of its protocol header. The current protocol requests that Network Monitor continue parsing at a known next protocol by returning the next protocol's handle to Network Monitor. In this case, the FollowSet of the current protocol, if any, is not used.

hNextProtocol

The spot to return the handle of the next protocol.

lpInstData

Instance data from the previous protocol, and where instance data is passed to the next protocol parser.

Return Values

The return value is a pointer to the next place in the frame. If the parser recognizes the frame, then it should return a pointer to the first byte beyond its recognized data. If the parser does not recognize the frame, then it should return the lpProtocol as passed in. If the parser wishes to claim all of the rest of the data, the parser should return NULL.

Remarks

The task of RecognizeFrame is to as quickly as possible determine if the raw data (starting at lpProtocol passed in) is pointing to data that the parser recognizes as data belonging to the protocol it understands. It should not attach any properties or do any more processing beyond noting the end point of the data belonging to its protocol, or determining that no such data is present. A parser should not search for data beyond lpProtocol.

Note RecognizeFrame may still be called even if Register has not been called. Thus, RecognizeFrame should not rely on any properties or structures that are created or initialized in the Register entry point.