FindNextFrame

The FindNextFrame function finds the next frame in the current capture context that matches the filter.

HFRAME FindNextFrame(
  HFRAME hCurrentFrame,       
  LPSTR ProtocolName,         
  LPADDRESS DestinationAddress,  
  LPADDRESS SourceAddress,    
  LPWORD ProtocolOffset,      
  DWORD OriginalFrameNumber,  
  DWORD HighestFrame          
);
 

Parameters

hCurrentFrame
Specifies a handle to the frame.
ProtocolName
Specifies the protocol name, such as "TCP."
DestinationAddress
Specifies the destination address.
SourceAddress
Specifies the source address.
ProtocolOffset
Specifies a pointer to a WORD that will receive the protocol offset.
OriginalFrameNumber
Starting point for this search. By default this API will search forward 1000 frames from here. The search forward distance can be changed by adding a MAXLOOKBACK=<new lookforward distance> line to the NMAPI.INI file in the Network Monitor Installed directory.
HighestFrame
Highest frame number in the capture to search to.

Return Values

The return value is the handle to the frame. If the return value is not NULL, then the protocol offset is valid; if it is NULL, then BHGetLastError is valid.

Error code Meaning
BHERR_SUCCESS No problems were encountered.
BHERR_INTERNAL_ERROR An internal error occurred.
BHERR_INVALID_HFRAME The hframe was invalid.

Remarks

This function finds the next frame in the current capture context that matches the filter. The filter is defined primarily by the ProtocolName, and this is the only required filter input. The DestinationAddress and SourceAddress can be given as a speed enhancement. The ProtocolOffset is returned to the calling parser, which adds this word to the pointer returned by locking the frame (with the ParserTemporaryLockFrame API call) to get the LPBYTE of the protocol that is being searched for. On return, the HFRAME that passed the filter is given to the parser. If the parser finds that this frame is not the one it is looking for, it can hand this HFRAME back to FindNextFrame to get the next one back. The source and destination addresses are not required and can be passed in as NULL.