ExpertGetFrame function

The ExpertGetFrame function returns the requested frame from a loaded capture.

Syntax

DWORD WINAPI ExpertGetFrame(
  _In_  HEXPERTKEY              hExpertKey,
  _In_  DWORD                   Direction,
  _In_  DWORD                   RequestFlags,
  _In_  DWORD                   RequestedFrameNumber,
  _In_  HFILTER                 hFilter,
  _Out_ LPEXPERTFRAMEDESCRIPTOR pEFrameDescriptor
);

Parameters

hExpertKey [in]

A unique expert identifier. Network Monitor passes the hExpertKey identifier to the expert when it calls the Run function.

Direction [in]

A value that identifies how Network Monitor searches for the frame.

Value	Meaning
GET_SPECIFIED_FRAME	Return the requested frame.
GET_FRAME_NEXT_FORWARD	Return the next frame.
GET_FRAME_NEXT_BACKWARD	Return the previous frame.

RequestFlags [in]

The flags that specify how Network Monitor should handle the request. Specify one or more of the following flags.

Value	Meaning
FLAGS_DEFER_TO_UI_FILTER	Before applying the display filter parameter of the expert which is specified in hFilter, apply the display filter that Network Monitor is using when the expert starts.
FLAGS_ATTACH_PROPERTIES	The properties that all protocol parsers find with claimed sections of this frame are attached to the frame. If the flag is not set, the lpPropertyTable field of the EXPERTFRAMEDESCRIPTOR structure (returned by pEFrameDescriptor) will be set to NULL.

RequestedFrameNumber [in]

The number of the requested frame.

hFilter [in]

A handle to the expert display filter. If the expert does not have a display filter, set the parameter to NULL.

pEFrameDescriptor [out]

The EXPERTFRAMEDESCRIPTOR structure that, on return, describes the frame. The expert must allocate and free the memory that this structure uses.

Return value

If the function is successful, the return value is NMERR_SUCCESS.

If the function is unsuccessful, the return value indicates the reason for the failure. If the return value is NMERR_EXPERT_TERMINATE, the expert must immediately clean up and return; the user has aborted the expert run.

Remarks

If you set FLAGS_ATTACH_PROPERTIES, the call requires more resources than if you do not set the flag. If the flag is not set, a pointer points to the raw frame and to data about the frame. If this flag is set, Network Monitor attaches all properties to the frame by calling every parser that claims a portion of the frame. This can be a slow process.

Experts should not set the FLAGS_ATTACH_PROPERTIES flag unless the experts require the properties that parsers attach to the frame. If possible, experts should call the ExpertGetFrame function without the flag, and then extract the required data directly from the frame.

If the expert calls ExpertGetFrame without the FLAGS_ATTACH_PROPERTIES flag and requires the properties associated with that frame (an event, for example), the expert calls ExpertGetFrame with the same parameters except for the following:

Direction = EXPERT_GET_SPECIFIED_FRAME;
RequestFlags &= (~EXPERT_DEFER_TO_UI_FILTER) | EXPERT_ATTACH_PROPERTIES;
RequestedFrameNumber= (The actual frame number you want);
hFilter = NULL;
pEFrameDescriptor = (The same one as last time);

Using the preceding code ensures that the expert gets the required frame without having to call filter code again.

You can set the hFilter parameter as an LPVOID. If it exists, the returned frame passes this filter. If the expert does not have a display filter to pass to the function (if hFilter is NULL ), then the frame returned is not filtered.

The ExpertGetFrame function can only be called by experts that implement the Run or Configure export function.

Requirements