Document Version: 6.2.1.0
API Version: 12
Last Updated: 04/1/2008

Table of Contents

Overview

This document provides a reference for the development of analysis modules (formerly known as plug-ins) for the Omnipeek Console. Analysis modules utilize a simple API composed of the messages, callbacks, and structures described herein for extending Omnipeek capabilities, allowing Savvius customers to easily create custom solutions.

This document does not apply to the creation of Omni Distributed Analysis Modules, also known as Capture Engine plug-ins, which are COM-based extensions for the Capture Engine. You must refer the Omni Distributed Analysis Module SDK to develop those types of analysis modules.

Analysis modules generally provide one or more of the following features:

  1. Process packets and look for specific network events.
  2. Enhance the display of information in Omnipeek, either by integrating with the packet list or providing a custom UI view.
  3. Filter packets.
  4. Provide remote adapters.

Most of the analysis modules supplied with Peek perform the first three functions. An analysis module controls which of these features to implement by specifying its Analysis Module Properties.

Versions

This API has undergone several revisions since it was first introduced in EtherPeek v3.0, where the API version was 3. API versions and the products in which they are used are listed below. Version 12 is described herein.

API Version Products
12
  • Omnipeek v5.0 (local capture only)
11
  • Omnipeek v5.0 (local capture only)
  • Omnipeek v4.0 (local capture only)
  • AiroPeek SE v3.0
  • AiroPeek NX v3.0
  • AiroPeek VX v1.0
10
  • Omnipeek v5.0 (local capture only)
  • Omnipeek v4.0 (local capture only)
  • Omnipeek v3.0 (local capture only)
  • Omnipeek v2.0 (local capture only)
  • Omnipeek v1.5 (local capture only)
  • WANPeek NX v1.0
  • EtherPeek v6.0
  • EtherPeek NX v3.0
  • EtherPeek VX v1.0
9
  • GigaPeek NX v1.0
  • EtherPeek v5.1
  • EtherPeek NX v2.1
8
  • AiroPeek v2.0
  • AiroPeek NX v2.0
7
  • N/A
6
  • EtherPeek v5.0
  • EtherPeek NX v2.0
5
  • AiroPeek v1.2
  • AiroPeek NX v1.0 through v1.2
  • EtherPeek v4.5
  • EtherPeek NX v1.0 through v1.1
  • TokenPeek v4.5
4
  • EtherPeek v4.1 and v4.2
  • TokenPeek v4.1 and v4.2
  • AiroPeek v1.0 and v1.1
3
  • EtherPeek v4.0
  • EtherPeek for Macintosh v4.0

Compatibility

Version 12 of the API is fully backward compatible with version 11, which in turn is compatible with version 10. As illustrated by the above table, Omnipeek v4.0 supports both API versions 10 and 11 while Omnipeek v5.0 supports API versions 10, 11, and 12.

Sections new to API v11 are labeled with "(11)" and sections introduced v12 are labeled with "(12)".

Omnipeek sets the fApiVersion field of the PluginLoadParam structure to the highest level API that it supports. If the analysis module returns a failure in response to the kPluginMsg_Load message, then Peek will send the message the kPluginMsg_Load message again but with the fAPIVersion field set to the next lowest supported version number. If the analysis module does not return success for any of Omnipeek's supported API versions, then the analysis module can not be hosted by Omnipeek and will be unloaded from memory. Omnipeek will not send messages introduced in a newer version of the API to an analysis module using an older version.

Architecture

Analysis modules are implemented as simple Dynamic Link Libraries (DLLs). They must be located in the "Plugins" subdirectory of the Peek installation to be detected and loaded.

Analysis modules are notified of events from Peek via a message-based interface. Messages are received by analysis modules through their message dispatching routine, which must be exported under the name "PlugInMain" and conform to the following prototype. See Messages and Their Parameters for a description of each message and its accompanying parameters.

typedef int (WINAPI *PluginInMain)( SInt16 inMessage, PluginParamBlock* ioParams );

This API also includes a set of routines exported by Omnipeek, dubbed Callbacks in this document, that can be utilized by analysis modules to access particular features.

Analysis Module Properties

Attributes

Attributes are used by Peek to determine the properties of an analysis module. An analysis module reports its attributes to Peek during processing of the kPluginMsg_Load message by assigning the flags below to the fAttributes and fAttributesEx fields of the PluginLoadParam structure. The fAttributes field is 16-bits wide and can be assigned any of the kPluginAttr flags. The fAttributesEx field, new to version 12 of the API, is 64-bits wide and can be assigned any of kPluginAttrEx flags.

Attribute Flag Description
kPluginAttr_ProcessPackets Indicates that an analysis module wants to receive kPluginMsg_ProcessPacket messages to process the contents of packets.
kPluginAttr_GetPacketString Indicates that an analysis module wants to receive kPluginMsg_GetPacketString messages. Set this attribute if the analysis module wishes to display text in the Summary column of Peek's packet list view.
kPluginAttr_HandlesSelection Indicates that an analysis module can handle kPluginMsg_Select messages. When this attribute is set, Peek will add the analysis module to a pop-up menu in the Select dialog. This allows analysis modules to provide an advanced method of post-capture filtering.
kPluginAttr_HandlesSummaries Indicates that an analysis module wants to receive kPluginMsg_Summary messages. Set this attribute if you have added support for summary statistics to your analysis module.
kPluginAttr_HasOptions Indicates that your analysis module allows the user to configure options that are global to it. (If your analysis module requires per-capture-context options, use kPluginAttrEx_HasContextOptions). Peek uses this attribute to enable an Options... button in the Analysis Module Options dialog and will send the kPluginMsg_Options message when the user clicks it.
kPluginAttr_Filters This attribute indicates that the analysis module can handle kPluginMsg_Filter messages. When this attribute is set, Peek will add the analysis module to a pop-up menu in the dialog for editing analysis module filter nodes. This allows analysis modules to provide an advanced method of filtering.
kPluginAttr_HandlesErrorPackets Indicates that the analysis module wishes to receive error packets. When this attribute is set, Peek will send error packets (CRC, Runt, Oversize, etc.) to the analysis module in addition to normal packets. Most analysis modules should elect NOT to receive error packets. Note that Peek will only receive error packets (and thus, give error packets to an analysis module) if a NIC driver is being used which supports error capture. See the Peek manual for more information about error packet capture.
kPluginAttr_HandlesNotify(11) Indicates that the analysis module wishes to receive kPluginMsg_HandleNotify messages in order to handle notifications (log entries).
kPluginAttr_NameTableUpdates Indicates that the analysis module wishes to be made aware of name table changes via the kPluginMsg_NameTableUpdate message.
kPluginAttr_ProvidesAnalysis Indicates that an analysis module wants to receive kPluginMsg_GetPacketAnalysis messages. Set this attribute if the analysis module will display text in the Expert column of Peek's packet list view.
kPluginAttr_HandlesApply Indicates that an analysis module chooses to receive the kPluginMsg_Apply message.
kPluginAttr_PluginAdapter Indicates that an analysis module is able to serve as a capture adapter, providing packets to Peek.
kPluginAttr_DecodePackets Indicates that an analysis module is to be sent packet information for each packet decoded by the application.
kPluginAttr_UserDecode ### Indicates that an analysis module provides decodes.
kPluginAttr_MediaSpecific

Indicates that an analysis module supports only certain media types, choosing whether to participate in file/capture contexts via the kPluginMsg_IsMediaSupported message.

kPluginAttr_ProcessPluginMessages(11) Indicates that an analysis module communicates with an Omni Distributed Analysis Module running remotely on an Capture Engine. See the kPluginMsg_ProcessPluginMessage message.
kPluginAttrEx_HasContextOptions(12) Indicates that an analysis module supports user-configurable per-context options. Omnipeek uses this attribute to show an Options... button in the Analysis Module Options tab of the Capture Options dialog and will send kPluginMsg_ContextOptions when the user clicks it. The kPluginMsg_SetContextPrefs, and kPluginMsg_GetContextPrefs messages will also be sent to assign or retrieve the settings for a particular context.
kPluginAttr_HandlesProcessTime(12) Indicates that an analysis module wants to receive kPluginMsg_ProcessTime messages. This message is sent to the plugin at one-second intervals and is sent even when the user has disabled plugins from the Performance tab.

Actions

Action flags are specified by an analysis module during handling of the kPluginMsg_Load in the fSupportedActions and fDefaultActions fields. Setting these flags allows the user to enable/disable the analysis module's feedback in the Analysis Modules page of Options dialog.

Action Flag Description
kPluginAction_Display Enables display of text in the Summary or Expert columns of Peek's packet list view. If this action is supported and enabled, then Peek will send the kPluginAttr_GetPacketString and/or the kPluginAttr_GetPacketAnalysis message when it needs to display information for the Summary and Expert columns respectively.
kPluginAction_Notify This action flag indicates that the analysis module should use the NotifyProc to trigger Notifications from within Peek when it needs to report network events.

For example, the Duplicate Address analysis module that comes with Omnipeek examines the physical to IP address mapping for each packet. When an address is detected as in use by two or more nodes, it will give feedback to the user in two ways: by adding text to the Summary column of the packet list, and by sending notifications via the NotifyProc callback. Thus, both actions above are supported. However, the user can choose to turn this feedback off by unchecking the Display and Notify columns for the Duplicate Address analysis module in the Anlaysis Modules page of the Options dialog.

Messages and Their Parameters

Messages are sent to an analysis module by Peek when an analysis module is loaded or unloaded, to process a packet, get a packet info string, notify of an event, or to perform some user interaction such as show an about box. Messages are passed to the analysis module's main dispatch routine, conforming to this prototype:

typedef int (WINAPI *PluginInMain)( SInt16 inMessage, PluginParamBlock* ioParams );

The inMessage parameter indicates the event as one of the following enumeration members:

enum
{
	kPluginMsg_Load,                     //  0 PluginLoadParam
	kPluginMsg_Unload,                   //  1 NULL
	kPluginMsg_ReadPrefs,                //  2 NULL
	kPluginMsg_WritePrefs,               //  3 NULL
	kPluginMsg_CreateContext,            //  4 PluginCreateContextParam
	kPluginMsg_DisposeContext,           //  5 PluginDisposeContextParam
	kPluginMsg_ProcessPacket,            //  6 PluginProcessPacketParam
	kPluginMsg_GetPacketString,          //  7 PluginGetPacketStringParam
	kPluginMsg_Apply,                    //  8 PluginApplyParam
	kPluginMsg_Select,                   //  9 PluginSelectParam
	kPluginMsg_Reset,                    // 10 PluginResetParam
	kPluginMsg_StartCapture,             // 11 PluginStartCaptureParam
	kPluginMsg_StopCapture,              // 12 PluginStopCaptureParam
	kPluginMsg_PacketsLoaded,            // 13 PluginPacketsLoadedParam
	kPluginMsg_About,                    // 14 NULL
	kPluginMsg_Options,                  // 15 NULL
	kPluginMsg_Summary,                  // 16 PluginSummaryParam
	kPluginMsg_Filter,                   // 17 PluginFilterParam
	kPluginMsg_FilterOptions,            // 18 NULL
	kPluginMsg_SummaryDescr,             // 19 NULL
	kPluginMsg_NameTableUpdate,          // 20 PluginNameTableUpdateParam
	kPluginMsg_GetPacketAnalysis,        // 21 PluginGetPacketStringParam
	kPluginMsg_CreateNewAdapter,         // 22 PluginCreateNewAdapterParam
	kPluginMsg_GetAdapterList,           // 23 PluginGetAdapterListParam
	kPluginMsg_DeleteAdapter,            // 24 PluginDeleteAdapterParam
	kPluginMsg_SetAdapterAttribs,        // 25 PluginAdapterAttribsParam
	kPluginMsg_GetAdapterAttribs,        // 26 PluginAdapterAttribsParam
	kPluginMsg_DecodePacket,             // 27 PluginDecodePacketParam
	kPluginMsg_AdapterProperties,        // 28 PluginAdapterPropertiesParam
	kPluginMsg_UserDecode,               // 29 PluginUserDecodeParam
	kPluginMsg_DecodersLoaded,           // 30 NULL
	kPluginMsg_IsMediaSupported,         // 31 PluginMediaSupportedParam
	kPluginMsg_ProcessPluginMessage,     // 32 PluginProcessPluginMessageParam
	kPluginMsg_HandleNotify,             // 33 PluginHandleNotifyParam
	kPluginMsg_GetTextForPacketListCell, // 34 PluginGetTextForPacketListCellParam
	kPluginMsg_MeasurePacketListCell,    // 35 PluginMeasurePacketListCellParam
	kPluginMsg_DrawPacketListCell,       // 36 PluginDrawPacketListCellParam
	kPluginMsg_ContextOptions,           // 37 PluginContextOptionsParam
	kPluginMsg_SetContextPrefs,          // 38 PluginContextPrefsParam
	kPluginMsg_GetContextPrefs           // 39 PluginContextPrefsParam
	kPluginMsg_ProcessTime               // 40 NULL
};

The ioParams parameter is a union whose contents are specific to each message and may be accompanied by additional information in the following PluginParamBlock.

typedef union PluginParamBlock
{
	PluginLoadParam                     uLoad;                     // kPluginMsg_Load
	PluginCreateContextParam            uCreateContext;            // kPluginMsg_CreateContext
	PluginDisposeContextParam           uDisposeContext;           // kPluginMsg_DisposeContext
	PluginProcessPacketParam            uProcessPacket;            // kPluginMsg_ProcessPacket
	PluginGetPacketStringParam          uGetPacketString;          // kPluginMsg_GetPacketString
	PluginApplyParam                    uApply;                    // kPluginMsg_Apply
	PluginSelectParam                   uSelect;                   // kPluginMsg_Select
	PluginResetParam                    uReset;                    // kPluginMsg_Reset
	PluginStartCaptureParam             uStartCapture;             // kPluginMsg_StartCapture
	PluginStopCaptureParam              uStopCapture;              // kPluginMsg_StopCapture
	PluginPacketsLoadedParam            uPacketsLoaded;            // kPluginMsg_PacketsLoaded
	PluginSummaryParam                  uSummary;                  // kPluginMsg_Summary
	PluginFilterParam                   uFilter;                   // kPluginMsg_Filter
	PluginNameTableUpdateParam          uNameTableUpdate           // kPluginMsg_NameTableUpdate
	PluginGetAdapterListParam           uAdapterList               // kPluginMsg_GetAdapterList
	PluginCreateNewAdapterParam         uCreateAdapter             // kPluginMsg_CreateNewAdapter
	PluginDeleteAdapterParam            uDeleteAdapter             // kPluginMsg_DeleteAdapter
	PluginAdapterAttribsParam           uAdapterAttribs            // kPluginMsg_SetAdapterAttribs, kPluginMsg_GetAdapterAttribs
	PluginDecodePacketParam             uDecodePacket;             // kPluginMsg_DecodePacket
	PluginAdapterPropertiesParam        uAdapterProperties;        // kPluginMsg_AdapterProperties
	PluginUserDecodeParam               uUserDecode;               // kPluginMsg_UserDecode
	PluginMediaSupportedParam           uMediaSupported;           // kPluginMsg_IsMediaSupported
	PluginProcessPluginMessageParam     uProcessPluginMessage;     // kPluginMsg_ProcessPluginMessage
	PluginHandleNotifyParam             uHandleNotify;             // kPluginMsg_HandleNotify
	PluginGetTextForPacketListCellParam uGetTextForPacketListCell; // kPluginMsg_GetTextForPacketListCell
	PluginMeasurePacketListCellParam    uMeasurePacketListCell;    // kPluginMsg_MeasurePacketListCell
	PluginDrawPacketListCellParam       uDrawPacketListCell;       // kPluginMsg_DrawPacketListCell
	PluginContextOptionsParam           uContextOptions;           // kPluginMsg_ContextOptions
	PluginContextPrefsParam             uContextPrefs;             // kPluginMsg_SetContextPrefs, kPluginMsg_GetContextPrefs
} PluginParamBlock;

kPluginMsg_Load

Peek sends this message to an analysis module when it is first loaded. The analysis module should return its API version, name, ID, attributes, supported and default actions, and supported ProtoSpecs. The analysis module should initialize whatever global data it may need on handling this message. See the description of the kPluginMsg_ReadPrefs message if you need to load preferences.

PluginLoadParam

This structure accompanies the kPluginMsg_Load message.

typedef struct PluginLoadParam
{
	UInt32           fAPIVersion;
	UInt32           fAppCapabilities;
	TCHAR*           fName;
	PluginID         fID;
	UInt16           fAttributes;
	UInt16           fSupportedActions;
	UInt16           fDefaultActions;
	UInt32           fSupportedCount;
	UInt32*          fSupportedProtoSpecs;
	ClientAppDataPtr fClientAppData;
	void*            fAppContextData;
	TCHAR*           fLoadErrorMessage;
	LCID             fLocaleId;
	UInt64           fAttributesEx;
 } PluginLoadParam;
Field In/Out Usage
fAPIVersion IN/OUT Peek's API version on input. Return the analysis module API version.
fAppCapabilities IN Peek application's capabilities (bit field). See below.
fName IN A pointer to a buffer preallocated by Peek (of maximum length kPluginNameMaxLength characters) into which the analysis module must copy its name.
fID OUT Return the analysis module's ID.
fAttributes OUT The analysis module's attributes (see Attributes).
fSupportedActions OUT Actions supported by the analysis module (see Actions).
fDefaultActions OUT Of the analysis module's supported actions (see Actions), which are enabled by default.
fSupportedCount OUT Return the number of supported ProtoSpecs, or zero to accept all ProtoSpecs, in the array pointed to by fSupportedProtoSpecs.
fSupportedProtoSpecs OUT A pointer to an array of supported ProtoSpecs, or NULL to accept all ProtoSpecs. The array must be allocated by the analysis module and outlive the scope of the kPluginMsg_Load handler (cannot be a local, stack-based array). Specifying a set of ProtoSpecs essentially acts as a protocol filter for the analysis module. Any packets that do not match the set of ProtoSpecs will not be sent in packet-based messages like kPluginMsg_ProcessPacket, kPluginMsg_GetPacketString, and kPluginMsg_DrawPacketListCell.
fClientAppData IN Reserved.
fAppContextData IN Analysis modules must retain this value for use in invoking Callbacks.
fLoadErrorMessage IN A pointer to a buffer preallocated by Peek (of maximum length kPluginLoadErrorMessageMaxLength characters) into which the analysis module should copy a message explaining why it could not load.
fLocaleId IN The Locale ID used by Peek. This can be used by the analysis module to determine which set of culture-specific resources to load. Also, if your analysis module is using multibyte ANSI strings and Peek is using Unicode (which is determined by the kAppCapability_Unicode flag being present in the fAppCapabilities field), then you must convert strings between the two character sets using this Locale ID.
fAttributesEx(12) OUT Extended attributes (see Attributes).

The following values are defined for the fAppCapabilities field.

enum
{
	kAppCapability_Unicode     = 0x00000001,
	kAppCapability_Pro         = 0x00000002,
	kAppCapability_RemoteAgent = 0x00000004,
	kAppCapability_Beta        = 0x00000008,
	kAppCapability_Demo        = 0x00000010,
	kAppCapability_Eval        = 0x00000020,
	kAppCapability_VoIP        = 0x00000040
};
Constant Description
kAppCapability_Unicode Peek was built with _UNICODE defined. All messages with accompanying parameter structures that include string fields will be in Unicode. Note that this does not affect callbacks; they will always accept wchar_t* parameters only.
kAppCapability_Pro Peek has Expert Analysis.
kAppCapability_RemoteAgent Peek supports Remote Engines.
kAppCapability_Beta Peek is a Beta Release.
kAppCapability_Demo Peek is a Demonstration Release.
kAppCapability_Eval Peek is an Evaluation Release.
kAppCapability_VoIP (11) Peek supports VoIP analysis.

kPluginMsg_Unload

Peek sends this message to an analysis module when it is unloaded. Free any additional memory and generally cleanup after the analysis module.

This message has no associated parameter structure.

kPluginMsg_CreateContext

Peek sends this message when a new context needs to be created for your analysis module. Each analysis module has one global context, one context for each open capture window, and one context for each open packet file window. This is the means by which analysis modules can, with relatively little work, support separate sets of statistics for each capture window and packet file window. Your analysis module should allocate memory for a context and return it to Peek. All subsequent context-related calls to your analysis module will include the appropriate analysis module context.

PluginCreateContextParam

This structure accompanies the kPluginMsg_CreateContext message.

typedef struct PluginCreateContextParam
{
	PluginContext*         fContextPtr;
	PluginCaptureContext   fCaptureContext;
	PluginContextData      fContextData;
	PluginContextFlags     fContextFlags;
} PluginCreateContextParam;
Field In/Out Usage
fContextPtr OUT Set this to the address of your newly allocated analysis module context.
fCaptureContext IN A value that the analysis module needs to store in its context structure, so that it can pass it back when it uses callbacks that require a capture context.
fContextData IN The HWND of the capture (or file) window. Because the global context has no associated capture window, this parameter will be NULL in that case.
fContextFlags IN Value indicating the type of context (see the enumeration below).

The following values are defined for the fContextFlags field.

enum
{
	kContextType_Global,
	kContextType_CaptureWindow,
	kContextType_FileWindow,
	kContextType_RemoteCaptureWindow,
	kContextType_RemoteFileWindow
};
Constant Description
kContextType_Global The Monitor context is being created.
kContextType_CaptureWindow A capture window is being created.
kContextType_FileWindow A packet file is being opened.
kContextType_RemoteCaptureWindow(11) A remote capture window is being created.
kContextType_RemoteFileWindow(11) A remote packet file is being opened.

kPluginMsg_DisposeContext

Peek sends this message to an analysis module when a context needs to be disposed. This happens when capture windows and packet file windows are closed. It also happens once just before the analysis module is unloaded (to dispose of the global context). Analysis modules should free the memory that was allocated in response to the kPluginMsg_CreateContext message.

PluginDisposeContextParam

This structure accompanies the kPluginMsg_DisposeContext message.

typedef struct PluginDisposeContextParam
{
	PluginContext fContext;
} PluginDisposeContextParam;
Field In/Out Usage
fContext IN The context pointer that your analysis module created in response to the kPluginMsg_CreateContext call.

kPluginMsg_ProcessPacket

This message is sent to an analysis module when Peek has a packet for it to process. This happens when Peek has captured a packet from the network or when a packet file is loaded. Analysis modules should handle the message as quickly as possible because any delay slows overall packet processing for Peek.

This message will only be sent if the analysis module has set the kPluginAttr_ProcessPackets attribute during handling of the kPluginMsg_Load message, and only for packets that match one of the ProtoSpecs the analysis module requested.

PluginProcessPacketParam

This structure accompanies the kPluginMsg_ProcessPacket message.

typedef struct PluginProcessPacketParam
{
	const PluginPacket* fPacket;
	const UInt8*        fPacketData;
	UInt64              fPacketNumber;
	UInt8               fMediaType;
	UInt8               fMediaSubType;
	UInt32              fProtoSpecMatched;
	PluginContext       fContext;
} PluginProcessPacketParam;
Field In/Out Usage
fPacket IN The packet to process. See PluginPacket for a detailed description.
fPacketData IN The actual packet data.
fPacketNumber IN The packet number in the packet list.
fMediaType IN The packet's media type. See Media Types for possible values.
fMediaSubType IN The packet's media subtype. See Media Subtypes for possible values.
fProtoSpecMatched IN The ProtoSpec instance ID of the packet that identifies the specific protocol. See ProtoSpecs for more information.
fContext IN The analysis module context your analysis module created in response to the kPluginMsg_CreateContext call.

kPluginMsg_GetPacketString, kPluginMsg_GetPacketAnalysis

These messages are sent to an analysis module when Peek needs to display text for a packet in the Summary or Expert columns of the packet list, respectively. The messages will only be sent if the analysis module has set the kPluginAttr_GetPacketString or kPluginAttr_ProvidesAnalysis attributes during handling of the kPluginMsg_Load message, and only for packets that match one of the ProtoSpecs the analysis module requested.

These messages are sent when a packet comes into view. Analysis modules should handle these messages as quickly as possible because any delay slows display of packets.

Peek calls each analysis module (that supports the ProtoSpec of the packet, of course) and uses the first non-empty string returned. Because all analysis modules are given the opportunity to provide strings for these columns, there may be contention. If this is undesirable, the analysis module may choose to supply its own custom column. See the SetPacketListColumnProc callback for more on that.

PluginGetPacketStringParam

This structure is accompanies both the kPluginMsg_GetPacketString and kPluginMag_GetPacketAnalysis messages.

typedef struct PluginGetPacketStringParam
{
	const PluginPacket* fPacket;
	const UInt8*        fPacketData;
	UInt64              fPacketNumber;
	UInt8               fMediaType;
	UInt8               fMediaSubType;
	UInt32              fProtoSpecMatched;
	TCHAR*              fString;
	PluginColor         fColor;
	PluginContext       fContext;
} PluginGetPacketStringParam;
Field In/Out Usage
fPacket IN The packet to process. See PluginPacket for a detailed description.
fPacketData IN The actual packet data.
fPacketNumber IN The packet number in the packet list.
fMediaType IN The packet's media type. See Media Types for possible values.
fMediaSubType IN The packet's media subtype. See Media Subtypes for possible values.
fProtoSpecMatched IN The ProtoSpec ID of the packet that identifies the specific protocol. See ProtoSpecs for more information.
fString OUT Return a string to be displayed in Peek's main packet list. Storage for the string has already been allocated by Peek and is limited to 256 characters (including null terminator).
fColor OUT The color to use when drawing the above string in the packet list.
fContext IN The analysis module context your analysis module created in response to the kPluginMsg_CreateContext call.

kPluginMsg_Apply

This message is passed when the user selects a packet in Peek's main packet list and chooses the Apply Analysis Module command. Typically, an analysis module will perform the same tasks as during the kPluginMsg_ProcessPacket but will not increment any summary statistics.

This message will only be sent if the analysis module has enabled the kPluginAttr_HandlesApply attribute during handling of the kPluginMsg_Load message.

The message is passed in three stages, indicated by the fCommand field in the accompanying PluginApplyParam structure:

  1. The analysis module initially receives the kApplyMsg_Start command. It may display a dialog and/or save additional information in the fPrivateData field of the PluginApplyParam structure. Analysis modules should return a non-zero value to cancel the operation or zero to continue.
  2. Each selected packet is then sent with the kApplyMsg_Packet command. Analysis modules should return zero if the packets is used, non-zero otherwise.
  3. Finally, the analysis module is sent the kApplyMsg_End command in order to clean up, including any data stored in fPrivateData.

PluginApplyParam

This structure is passed with the kPluginMsg_Apply message.

typedef struct PluginApplyParam
{
	const PluginPacket* fPacket;
	const UInt8*        fPacketData;
	UInt64              fPacketNumber;
	UInt8               fMediaType;
	UInt8               fMediaSubType;
	UInt32              fProtoSpecMatched;
	UInt16              fCommand;
	UInt32              fPrivateData;
	PluginContext       fContext;
} PluginApplyParam;
Field In/Out Usage
fPacket IN The packet to process. See PluginPacket for a detailed description.
fPacketData IN The actual packet data.
fPacketNumber IN The packet number in the packet list.
fMediaType IN The packet's media type. See Media Types for possible values.
fMediaSubType IN The packet's media subtype. See Media Subtypes for possible values.
fProtoSpecMatched IN The ProtoSpec instance ID of the packet that identifies the specific protocol. See ProtoSpecs for more information.
fCommand IN The command. See kPluginMsg_Apply for details.
fPrivateData IN/OUT  This field is for private use by the analysis module.
fContext IN The analysis module context your analysis module created in response to the kPluginMsg_CreateContext call.

The following values are defined for the fCommand field.

enum
{
	kApplyMsg_Start  = 1,
	kApplyMsg_End    = 2,
	kApplyMsg_Packet = 3
};

kPluginMsg_Select

This message is passed when the user chooses to use the analysis module in Peek's Select dialog.

This message will only be sent if the analysis module has enabled the kPluginAttr_HandlesSelection attribute during handling of the kPluginMsg_Load message.

The message is passed in three stages, indicated by the fCommand field in the accompanying PluginSelectParam structure:

  1. The analysis module initially receives the kSelectMsg_Start command. It may display a dialog and/or save additional information in the fPrivateData field of the PluginSelectParam structure. Analysis modules should return a non-zero value to cancel the operation or zero to continue.
  2. Every packet is then sent with the kSelectMsg_Packet command. Analysis modules should return zero if the packet should be selected, non-zero otherwise.
  3. Finally, the analysis module is sent the kSelectMsg_End command in order to clean up, including any data stored in fPrivateData.

PluginSelectParam

This structure is passed with the kPluginMsg_Select message.

typedef struct PluginSelectParam
{
	const PluginPacket* fPacket;
	const UInt8*        fPacketData;
	UInt64              fPacketNumber;
	UInt8               fMediaType;
	UInt8               fMediaSubType;
	UInt32              fProtoSpecMatched;
	UInt16              fCommand;
	UInt32              fPrivateData;
	PluginContext       fContext;
} PluginSelectParam;
Field In/Out Usage
fPacket IN The packet to process. See PluginPacket for a detailed description.
fPacketData IN The actual packet data.
fPacketNumber IN The packet number in the packet list.
fMediaType IN The packet's media type. See Media Types for possible values.
fMediaSubType IN The packet's media subtype. See Media Subtypes for possible values.
fProtoSpecMatched IN The ProtoSpec instance ID that this packet matched.
fCommand IN The command. See kPluginMsg_Select for details.
fPrivateData IN/OUT  This field is for private use by the analysis module.
fContext IN The analysis module context your analysis module created in response to the kPluginMsg_CreateContext call.

The following values are defined for the fCommand field.

enum
{
	kSelectMsg_Start  = 1,
	kSelectMsg_End    = 2,
	kSelectMsg_Packet = 3
};

kPluginMsg_Reset

This message is sent by Peek when a packet buffer is cleared. Your analysis module should clear out all accumulated statistics contained within its context.

PluginResetParam

This structure is passed with the kPluginMsg_Reset message.

typedef struct PluginResetParam
{
	PluginContext fContext;
	const TCHAR*  fPluginAdapterID;
} PluginResetParam;
Field In/Out Usage
fContext IN The analysis module context your analysis module created in response to the kPluginMsg_CreateContext call.
fPluginAdapterID IN When an analysis module is being used as the capture adapter, the ID of the adapter which is being reset.

kPluginMsg_StartCapture

This message is sent by Peek to notify analysis modules of when packet capture is started.

PluginStartCaptureParam

This structure is passed with the kPluginMsg_StartCapture message.

typedef struct PluginStartCaptureParam
{
	PluginContext fContext;
} PluginStartCaptureParam;
Field In/Out Usage
fContext IN The analysis module context your analysis module created in response to the kPluginMsg_CreateContext call.

kPluginMsg_StopCapture

This message is sent by Peek to notify analysis modules of when packet capture is stopped.

PluginStopCaptureParam

This structure is passed with the kPluginMsg_StopCapture message.

typedef struct PluginStopCaptureParam
{
	PluginContext fContext;
} PluginStopCaptureParam;
Field In/Out Usage
fContext IN The analysis module context your analysis module created in response to the kPluginMsg_CreateContext call.

kPluginMsg_PacketsLoaded

This message is sent by Peek when after a packet file has completed loading.

PluginPacketsLoadedParam

This structure is passed with the kPluginMsg_PacketsLoaded message.

typedef struct PluginPacketsLoadedParam
{
	PluginContext fContext;
} PluginPacketsLoadedParam;
Field In/Out Usage
fContext IN The analysis module context your analysis module created in response to the kPluginMsg_CreateContext call.

kPluginMsg_About

Peek sends this message to an analysis module when the user selects the analysis module in Peek's Analysis Module dialog and clicks the About button. The analysis module should display a dialog or message box with author information, the purpose of the analysis module and instructions on its use.

This message has no accompanying parameter data structure.

kPluginMsg_Options

Peek sends this message to an analysis module when the user selects the analysis module in Peek's Analysis Module dialog and clicks the Options button. Analysis modules should display a dialog box in which the user can set preferences supported by the analysis module.

Peek will only enable the Options button if the analysis module has the kPluginAttr_HasOptions attribute.

There is no accompanying parameter data structure for this message.

kPluginMsg_ReadPrefs

Peek sends this message to an analysis module right after it's loaded (during Peek launch). The analysis module can take this opportunity to load any user preferences specific to the analysis module. Use the PrefsGetValueProc and/or PrefsGetPrefsPathProc callbacks to retrieve your preferences.

This message has no accompanying parameter data structure.

kPluginMsg_WritePrefs

Peek sends this message to an analysis module right before it's unloaded (during Peek quit). The analysis module can take this opportunity to save any user preferences specific to the analysis module. Use the PrefsSetValueProc and/or PrefsGetPrefsPathProc callbacks to store your preferences.

This message has no accompanying parameter data structure.

kPluginMsg_Summary

This message is sent by Peek when it is time to update the values in the summary statistics. If your analysis module keeps track of any values for the summary statistics, it should use the SummaryModifyEntryProc and SummaryGetEntryProc callbacks as appropriate.

The message will only be passed if the analysis module has set the kPluginAttr_HandlesSummaries attribute during handling of the kPluginMsg_Load message.

PluginSummaryParam

This structure is passed with the kPluginMsg_Summary message.

typedef struct PluginSummaryParam
{
	PluginContext fContext;
} PluginSummaryParam;
Field In/Out Usage
fContext IN The analysis module context your analysis module created in response to the kPluginMsg_CreateContext call.

kPluginMsg_Filter

This message is passed when a packet is being evaluated by a filter that contains an analysis module filter node. Analysis modules should evaluate the packet passed in the associated PluginFilterParam parameter and determine if the packet should be accepted or rejected. If the packet should be accepted, your analysis module should return PLUGIN_RESULT_SUCCESS. If the packet should be rejected, return a value less than zero. You may specify a slice length for the packet by setting the value of the fBytesAccepted field to the number of bytes to slice to. You can use the constant PLUGIN_ACCEPT_WHOLE_PACKET to accept the entire packet without having to specify the packet's actual length. If this packet is accepted into a buffer which also has a slice length specified, slicing will occur at the smallest slice length specified.

This message will only be passed if the analysis module has set the kPluginAttr_Filters attribute during handling of the kPluginMsg_Load message.

It is very important to make the handling of this message as fast as possible to avoid degrading Peek's capture performance.

PluginFilterParam

This structure is passed with the kPluginMsg_Filter message.

typedef struct PluginFilterParam
{
	const PluginPacket* fPacket;
	const UInt8*        fPacketData;
	UInt8               fMediaType;
	UInt8               fMediaSubType;
	UInt16              fProtoSpecMatched;
	SInt16              fBytesAccepted;
	PluginContext       fContext;
} PluginFilterParam;
Field In/Out Usage
fPacket IN The packet to filter. See PluginPacket for a detailed description.
fPacketData IN The actual packet data.
fMediaType IN The packet's media type. See Media Types for possible values.
fMediaSubType IN The packet's media subtype. See Media Subtypes for possible values.
fProtoSpecMatched IN The ProtoSpec ID of the packet that identifies the specific protocol. See ProtoSpecs for more information.
fBytesAccepted OUT The number of bytes from the packet to accept. This allows the analysis module to specify separate slice lengths for each packet. If you don't want to slice this packet, set this to PLUGIN_ACCEPT_WHOLE_PACKET.
fContext IN The analysis module context your analysis module created in response to the kPluginMsg_CreateContext call.

kPluginMsg_FilterOptions

Peek sends this message when the user is configuring an advanced filter containing an analysis module node. In response to this message, an analysis module should present a dialog box that allows the user to adjust its filtering parameters.

Similar to the kPluginMsg_Filter message, an analysis module must set the kPluginAttr_Filters attribute during handling of the kPluginMsg_Load message.

This message has no accompanying parameter data structure.

kPluginMsg_NameTableUpdate

This message is sent by Peek when a change is made to the Name Table. Analysis modules should update any references or caches of name table entries. There are three types of name table changes: additions, edits, and deletions. Which one is being sent is indicated by the fCommand field in the PluginNameTableUpdateParam structure.

Analysis modules only receive name table notifications if the kPluginAttr_NameTableUpdates attribute was set during the handling of the kPluginMsg_Load message.

Although the associated PluginNameTableUpdateParam structure contains the fContext field, this message is not particular to any single context, and is not sent for each context. In fact, the fContext field always references the context created while handling the kPluginMsg_CreateContext message for the global context.

PluginNameTableUpdateParam

This structure is a parameter to the kPluginMsg_NameTableUpdate message.

typedef struct PluginNameTableUpdateParam
{
	PluginContext        fContext;
	PluginNameTableEntry fEntry;
	UInt16               fCommand;
} PluginNameTableUpdateParam
Field In/Out Usage
fContext IN The analysis module global context that your analysis module created in response to the kPluginMsg_CreateContext call.
fEntry IN The Name Table entry which was affected. See PluginNameTableEntry.
fCommand IN The Name Table Update command.

The fCommand field may contain the following values.

enum
{
	kNameTableUpdateMsg_Add,
	kNameTableUpdateMsg_Edit,
	kNameTableUpdateMsg_Delete
};

kPluginMsg_CreateNewAdapter

Peek sends this message to an analysis module to instruct the module to create a new capture adapter. This occurs when the user double-clicks the "New Remote Adapter" item under the module in the Adapter section of the Capture Options dialog.

The message will only be passed if the analysis module has set the kPluginAttr_PluginAdapter attribute during handling of the kPluginMsg_Load message.

PluginCreateNewAdapterParam

This structure is a parameter to the kPluginMsg_CreateNewAdapter message.

typedef struct PluginCreateNewAdapterParam
{
	TCHAR* fOutSelectedAdapterTag;
	UInt16 fInMaxLength;
} PluginCreateNewAdapterParam;
Field In/Out Usage
fOutSelectedAdapterTag OUT The adapter ID of the new adapter selection for the Select Adapter UI.
fInMaxLength IN The maximum length of the ID to put in fOutSelectedAdapterTag.

kPluginMsg_GetAdapterList

Peek sends this message to an analysis module to retrieve the current list of adapters available for this capture module.

The message will only be passed if the analysis module has set the kPluginAttr_PluginAdapter attribute during handling of the kPluginMsg_Load message.

PluginGetAdapterListParam

This structure is passed with the kPluginMsg_GetAdapterList message.

typedef struct PluginGetAdapterListParam
{
	const TCHAR* fOutXMLAdapterList;
	UInt32       fOutXMLStreamLength;
} PluginGetAdapterListParam;
Field In/Out Usage
fOutXMLAdapterList OUT The list of adapters available to this analysis module, expressed in XML. See the XML Adapter Tags section for a description of the XML format required. The analysis module is responsible for allocating a buffer and assigning this field to point to the buffer. The buffer must continue to exist after the analysis module has finished processing the associated kPluginMsg_GetAdapterList message. Therefore it is a good idea to make the buffer static/global.
fOutXMLStreamLength OUT Set this to the length, in characters, of the XML stream.

kPluginMsg_DeleteAdapter

Peek sends this message to an analysis module to instruct the module to delete an adapter from it's list. This occurs when the user right-click an adapter and chooses "Delete".

The message will only be passed if the analysis module has set the kPluginAttr_PluginAdapter attribute during handling of the kPluginMsg_Load message.

PluginDeleteAdapterParam

This structure is passed with the kPluginMsg_DeleteAdapter message.

typedef struct PluginDeleteAdapterParam
{
	const TCHAR* fInDeleteID;
} PluginDeleteAdapterParam;
Field In/Out Usage
fInDeleteID IN The adapter ID to delete, if such action is permitted.

kPluginMsg_SetAdapterAttribs

Peek sends this message to an analysis module to instruct the module to set the attributes of one of it's adapters.

kPluginMsg_GetAdapterAttribs

Peek sends this message to an analysis module to retrieve the attributes of one of it's adapters.

These messages will only be passed if the analysis module has set the kPluginAttr_PluginAdapter attribute during handling of the kPluginMsg_Load message.

PluginAdapterAttribsParam

This structure is passed with the kPluginMsg_SetAdapterAttribs and kPluginMsg_GetAdapterAttribs messages.

typedef struct PluginAdapterAttribsParam
{
	const TCHAR* fAdapterID;
	const TCHAR* fInParamTagStream;
	UInt32       fInParamTagStreamLen;
	const TCHAR* fOutParamTagStream;
	UInt32       fOutParamTagStreamLen;
} PluginAdapterAttribsParam;
Field In/Out Usage
fAdapterID IN The adapter ID which the message concerns.
fInParamTagStream IN The input XML stream of parameters to get/set. See the XML Adapter Tags section for a description of the XML format required.
fInParamTagStreamLen IN The length of the input XML stream.
fOutParamTagStream OUT For kPluginMsg_SetAdapterAttribs, the XML output stream of adapter parameters. This parameter is ignored for kPluginMsg_GetAdapterAttribs.
fOutParamTagStreamLen OUT The length of the output XML stream.

kPluginMsg_AdapterProperties

Peek sends this message to an analysis module to allow it to display properties for its adapters.

The message will only be passed if the analysis module has set the kPluginAttr_PluginAdapter attribute during handling of the kPluginMsg_Load message.

PluginAdapterPropertiesParam

This structure is passed with the kPluginMsg_AdapterProperties message.

typedef struct PluginAdapterPropertiesParam
{
	const TCHAR* fInAdapterID;
} PluginAdapterPropertiesParam;
Field In/Out Usage
fInAdapterID IN The adapter ID to display properties for.

kPluginMsg_DecodePacket

Peek sends this message to an analysis module to inform it that the application is about to decode a packet.

The message will only be passed if the analysis module has set the kPluginAttr_DecodePacket attribute during handling of the kPluginMsg_Load message.

PluginDecodePacketParam

This structure is passed with the kPluginMsg_DecodePacket message.

typedef struct PluginDecodePacketParam
{
	const PluginPacket* fPacket;
	const UInt8*        fPacketData;
	UInt64              fPacketNumber;
	UInt8               fMediaType;
	UInt8               fMediaSubType;
	UInt32              fProtoSpecMatched;
	PluginContext       fContext;
} PluginDecodePacketParam;
Field In/Out Usage
fPacket IN The packet to process. See PluginPacket for a detailed description.
fPacketData IN The actual packet data.
fPacketNumber IN The packet number in the packet list.
fMediaType IN The packet's media type. See Media Types for possible values.
fMediaSubType IN The packet's media subtype. See Media Subtypes for possible values.
fProtoSpecMatched IN The ProtoSpec instance ID of the packet that identifies the specific protocol. See ProtoSpecs for more information.
fContext IN The analysis module context your analysis module created in response to the kPluginMsg_CreateContext call.

kPluginMsg_UserDecode(11)

Peek sends this message to an analysis module to decode the packet specified.

PluginUserDecodeParam(11)

This structure is passed with the kPluginMsg_UserDecode message.

typedef struct PluginUserDecodeParam {
	const PluginPacket* fPacket;
	const UInt8*        fPacketData;
	UInt64              fPacketNumber;
	UInt8               fMediaType;
	UInt8               fMediaSubType;
	UInt32              fProtoSpecMatched;
	PluginContext       fContext;
	TCHAR*              fFunctionName;
	PluginContext       fDecodeContext;
	PluginContext       fDecodeState;
} PluginUserDecodeParam;
Field In/Out Usage
fPacket IN The packet to process. See PluginPacket for a detailed description.
fPacketData IN The actual packet data.
fPacketNumber IN The packet number in the packet list.
fMediaType IN The packet's media type. See Media Types for possible values.
fMediaSubType IN The packet's media subtype. See Media Subtypes for possible values.
fProtoSpecMatched IN The ProtoSpec instance ID of the packet that identifies the specific protocol. See ProtoSpecs for more information.
fContext IN The analysis module context.
fFunctionName IN The name of the function called from the .dcd file.
fDecodeContext IN opaque value passed into DecodeOpProc
fDecodeState IN opaque value passed into DecodeOpProc

kPluginMsg_DecodersLoaded(11)

Peek sends this message to an analysis module when the decoders have been loaded.

This message has no accompanying parameter structure.

kPluginMsg_IsMediaSupported

Peek sends this message to an analysis module to inquire if the analysis module supports the media being used for the capture or for the packet file. The analysis module should return PLUGIN_RESULT_SUCCESS if it supports the media, otherwise the analysis module is not loaded.

The message will only be passed if the analysis module has set the kPluginAttr_MediaSpecific attribute during handling of the kPluginMsg_Load message. Otherwise it is assumed that all medias are supported by the analysis module.

PluginMediaSupportedParam

This structure is passed with the kPluginMsg_IsMediaSupported message.

typedef struct PluginMediaSupportedParam
{
	UInt8 fMediaType;
	UInt8 fMediaSubType;
} PluginMediaSupportedParam;
Field In/Out Usage
fMediaType IN The media type for the capture or packet file. See Media Types for possible values.
fMediaSubType IN The media subtype for the capture or packet file. See Media Subtypes for possible values.

kPluginMsg_ProcessPluginMessage(11)

Peek sends this message to an analysis module when it receives a response from a SendPluginMessageProc call to a remote engine. The analysis module should return PLUGIN_RESULT_SUCCESS if it received the message.

The message will only be passed if the analysis module has set the kPluginAttr_ProcessPluginMessages attribute set during the handling of the kPluginMsg_Load message.

PluginProcessPluginMessageParam(11)

This structure is passed with the kPluginMsg_ProcessPluginMessage message.

typedef struct PluginProcessPluginMessageParam
{
	const UInt8*  fData;
	UInt32        fDataLen;
	UInt32        fResult;
	PluginContext fContext;
} PluginProcessPluginMessageParam;
Field In/Out Usage
fData IN Points to the received message buffer.
fDataLen IN Length of the data pointed to by fData.
fResult IN The HRESULT of the message from the server. For more information, see the Omni DAM SDK.
fContext IN The context of the plugin that made the SendPluginMessageProc call that this message is responding to.

kPluginMsg_HandleNotify(11)

Peek sends this message to an analysis module when Peek is handling a notification.

The message will only be passed if the analysis module set the kPluginAttr_HandlesNotify attribute during the handling of the kPluginMsg_Load message.

PluginHandleNotifyParam(11)

This structure is passed with the kPluginMsg_HandleNotify message.

typedef struct PluginHandleNotifyParam
{
	UInt64        fTimeStamp;
	UInt8         fSeverity;
	const TCHAR*  fShortMessage;
	const TCHAR*  fLongMessage;
	UInt32        fFlags;
	PluginContext fContext;
} PluginHandleNotifyParam;
Field In/Out Usage
fTimeStamp IN The time stamp of the notification.
fSeverity IN The severity level of the notification as one of the enumeration values below.
fShortMessage IN The abbreviated text describing the notification. It will be suitable as a subject line or summary. May be NULL.
fLongMessage IN The full text of the notification.
fFlags IN Reserved.
fContext IN The pointer to the context data created by the analysis module.

The fSeverity field may take one of the following severity levels:

enum
{
	kNotifySeverity_Informational,
	kNotifySeverity_Minor,
	kNotifySeverity_Major,
	kNotifySeverity_Severe
};

kPluginMsg_GetTextForPacketListCell(12)

Peek sends this message to an analysis module when Peek needs a textual representation for a custom packet list column cell. The textual representation is typically only requested when exporting the packets list, such as to a text file or to the Windows clipboard. This message is sent for each packet/row being exported.

The analysis module should return PLUGIN_RESULT_SUCCESS if a textual representation is supported, even if the cell is empty. If the column does not support a textual representation, then PLUGIN_RESULT_ERROR should be returned. Whichever value is returned, it must be consistent for all packets/rows because it is used to determine whether to include the cell in a packet/row's delimited output. If that is not consistent, then the resulting delimited text will be ragged.

This message will only be sent if the analysis module previously added a custom column by invoking the SetPacketListColumnProc callback.

PluginGetTextForPacketListCellParam(12)

This structure is passed with the kPluginMsg_GetTextForPacketListCell message.

typedef struct PluginGetTextForPacketListCellParam
{
	PluginContext                     fInContext;
	const PluginPacketProcessingInfo* fInPacketProcessingInfo;
	const PluginID*                   fInColumnID;
	TCHAR*                            fOutCellText;
	UInt32                            fInCellTextMaxLength;
} PluginGetTextForPacketListCellParam;
Field In/Out Usage
fInContext IN The pointer to the context data created by the analysis module.
fInPacketProcessingInfo IN Pointer to the packet data and metadata corresponding to the cell's row in the packet list view. See PluginPacketProcessingInfo.
fInColumnID IN Pointer to the ID of the cell's column (as it was specified in the initial call to SetPacketListColumnProc). If an analysis module adds more than one custom column to the packet list, this field is used to determine which of the columns is to be processed.
fOutCellText OUT Pointer to a Peek-allocated buffer into which the cell's text (if any) will be copied.
fInCellTextMaxLength IN The maximum length in characters of the buffer pointed to by fOutCellText.

kPluginMsg_MeasurePacketListCell(12)

Peek sends this message to an analysis module when the contents of a custom packet list column cell must be measured. This is typically only requested when the user double-clicks on the column header's divider to invoke an auto-size operation on the column. This message is sent for each packet/row being measured.

The analysis module should return PLUGIN_RESULT_SUCCESS if measurement of the column's cells is supported. If the column does not support auto-sizing, then PLUGIN_RESULT_ERROR should be returned, in which case the column will remain its current size.

An analysis module has the option of calculating the size itself or, if the column contains just a single line of text, letting Peek perform the measurement based on the cell's text.

  • If the analysis module chooses to calculate the size, it must set the fOutCellContentsSize dimensions (not including any padding/margin between the contents and the cell borders, as Peek will automatically incorporate whitespace for a consistent appearance across all cells) and set the fOutDefaultMeasure field to false.
  • If the analysis module wishes to allow Peek to perform the measurement for it, it must supply Peek with the cell's text in the fOutCellText buffer and set the fOutDefaultMeasure field true.

This message will only be sent if the analysis module previously added a custom column by invoking the SetPacketListColumnProc callback.

PluginMeasurePacketListCellParam(12)

This structure is passed with the kPluginMsg_MeasurePacketListCell message.

typedef struct PluginMeasurePacketListCellParam
{
	PluginContext                     fInContext;
	const PluginPacketProcessingInfo* fInPacketProcessingInfo;
	const PluginID*                   fInColumnID;
	TCHAR*                            fOutCellText;
	UInt32                            fInCellTextMaxLength;
	PluginDrawingHandle               fInDrawingHandle;
	UInt32                            fIoDrawingStates;
	PluginSize                        fOutCellContentSize;
	bool                              fOutDefaultMeasure;
} PluginGetTextForPacketListCellParam;
Field In/Out Usage
fInContext IN The pointer to the context data created by the analysis module.
fInPacketProcessingInfo IN Pointer to the packet data and metadata corresponding to the cell's row in the packet list view. See PluginPacketProcessingInfo.
fInColumnID IN Pointer to the ID of the cell's column (as it was specified in the initial call to SetPacketListColumnProc). If an analysis module adds more than one custom column to the packet list, this field is used to determine which of the columns is to be processed.
fOutCellText OUT Pointer to a Peek-allocated buffer into which the cell's text (if any) will be copied. This field is ignored by Peek if fOutDefaultMeasure is set to false.
fInCellTextMaxLength IN The maximum length in characters of the buffer pointed to by fOutCellText.
fInDrawingHandle IN The handle to the device context to be used for measurement.
fIoDrawingStates IN/OUT The visual states of the cell. See the enumeration below.
fOutCellContentSize OUT The dimensions of the cell's contents, which should not include padding/margins. This field is ignored by Peek if fOutDefaultMeasure is set to true.
fOutDefaultMeasure OUT Indicates whether Peek should perform the measurement of the cell's text as specified in fOutCellText.

The fIoDrawingStates field may take a combination of the following flags. kDrawingState_Selected and kDrawingState_Focused are not applied for this message because they are for appearances only should not have an impact on cell sizes. Should the analysis module choose to let Peek measure the cell's text (by setting fOutDefaultMeasure to true), kDrawingState_Italic can be set by the analysis module to force the italic font to be used for the calculation.

enum
{
	kDrawingState_Selected = 0x00000001,
	kDrawingState_Focused  = 0x00000002,
	kDrawingState_Italic   = 0x00000004
};

kPluginMsg_DrawPacketListCell(12)

Peek sends this message to an analysis module when the contents of a custom packet list column cell must be rendered. This message is sent for each packet/row being measured and should be handled as quickly as possible to prevent slowing down the refreshing of the packet list view.

An analysis module has the option of drawing the cell contents itself or, if the column contains just a single line of text, letting Peek render the cell's text.

  • If the analysis module chooses to draw the contents, it must set do so using the device context handle in the fInDrawingHandle and set the fOutDefaultDraw field to false.
  • If the analysis module wishes to have Peek perform the rendering, it must supply Peek with the cell's text in the fOutCellText buffer and set the fOutDefaultDraw field true. The analysis module may still customize the text's appearance by setting the cell's foreground and background colors, and by indicating whether the text should be italicized.

This message will only be sent if the analysis module previously added a custom column by invoking the SetPacketListColumnProc callback.

PluginDrawPacketListCellParam(12)

This structure is passed with the kPluginMsg_DrawPacketListCell message.

typedef struct PluginPacketListCellDrawingInfo
{
	PluginRect  fInBounds;
	PluginRect  fInContentRect;
	PluginColor fIoForeColor;
	PluginColor fIoBackColor;
} PluginPacketListCellDrawingInfo;
	
typedef struct PluginDrawPacketListCellParam
{
	PluginContext                     fInContext;
	const PluginPacketProcessingInfo* fInPacketProcessingInfo;
	const PluginID*                   fInColumnID;
	TCHAR*                            fOutCellText;
	UInt32                            fInCellTextMaxLength;
	PluginDrawingHandle               fInDrawingHandle;
	UInt32                            fIoDrawingStates;
	PluginPacketListCellDrawingInfo*  fInCellDrawingInfo;
	bool                              fOutDefaultDraw;
} PluginGetTextForPacketListCellParam;
Field In/Out Usage
fInContext IN The pointer to the context data created by the analysis module.
fInPacketProcessingInfo IN Pointer to the packet data and metadata corresponding to the cell's row in the packet list view.
fInColumnID IN Pointer to the ID of the cell's column (as it was specified in the initial call to SetPacketListColumnProc). If an analysis module adds more than one custom column to the packet list, this field is used to determine which of the columns is to be processed.
fOutCellText OUT Pointer to a Peek-allocated buffer into which the cell's text (if any) will be copied. This field is ignored by Peek if fOutDefaultMeasure is set to false.
fInCellTextMaxLength IN The maximum length in characters of the buffer pointed to by fOutCellText.
fInDrawingHandle IN The handle to the device context to be used for measurement.
fIoDrawingStates IN/OUT The visual states of the cell. See the enumeration below.
fInCellDrawingInfo->fInBounds IN The cell's bounding rectangle.
fInCellDrawingInfo->fInContentRect IN The cell's content rectangle, which is slightly inset from the bounding rectangle so as to provide some padding/margin whitespace between the cell border and the cell's contents. It is not advisable to draw outside of this rectangle.
fInCellDrawingInfo->fIoForeColor IN/OUT The cell's foreground (text) color. This will be supplied by Peek based on the packet list view's current display format settings and whether the packet/row is highlighted. The analysis module may change this field to force Peek to use a special color if fOutDefaultDraw is set to true.
fInCellDrawingInfo->fIoBackColor IN/OUT The cell's background color. This will be supplied by Peek based on the packet list view's current display format settings and whether the packet/row is highlighted. The analysis module may change this field to force Peek to use a special color if fOutDefaultDraw is set to true.
fOutDefaultDraw OUT Indicates whether Peek should perform the rendering of the cell's text specified in fOutCellText.

The fIoDrawingStates field may take a combination of the following flags. kDrawingState_Selected and kDrawingState_Focused are applied according to whether the packet/row is highlighted and/or focused. Should the analysis module choose to let Peek measure the cell's text (by setting fOutDefaultDraw to true), kDrawingState_Italic can be set by the analysis module to force the italic font to be used for drawing the text.

enum
{
	kDrawingState_Selected = 0x00000001,
	kDrawingState_Focused  = 0x00000002,
	kDrawingState_Italic   = 0x00000004
};

kPluginMsg_ContextOptions(12)

Peek sends this message to an analysis module when its options are to be configured for a particular file/capture context. Specifically, when the user is viewing the Analysis Modules page of the Capture Options dialog, highlights an analysis module, and then clicks the Options... button. Analysis modules typically present a modal dialog to the user in response and return the configuration back to Peek as XML.

An analysis module must set the kPluginAttr_HasContextOptions attribute during handling of the kPluginMsg_Load message in order to receive this message.

This message is sent in two situations:

  • The capture is about to be created and the user is editing capture options beforehand. In this case, the analysis module context has not yet been associated with the capture (kPluginMsg_CreateContext has not yet been sent and the fContext field will be NULL). The analysis module will present an options dialog and then return the resulting configuration XML to Peek via the fOutNewPrefs field. At a later time, once the capture has been created, the configuration XML will be handed back sometime later along with the kPluginMsg_SetContextPrefs message once so that the associated context options can be properly applied.
  • The capture has already been created and the user is editing capture options afterward. There will be an analysis module context associated with the capture (in the fContext field). The analysis module must apply the configuration changes to its context directly, as no subsequent kPluginMsg_SetContextPrefs message will be sent. The configuration XML should still be returned to Peek via the fOutNewPrefs field though.

PluginContextOptionsParam

This structure is passed with the kPluginMsg_ContextOptions message.

typedef struct PluginContextOptionsParam
{
	const wchar_t*  fInOldPrefs;
	UInt32          fInOldPrefsLength;
	wchar_t*        fOutNewPrefs;
	UInt32          fOutNewPrefsLength;
	PluginContext   fContext;
} PluginContextOptionsParam;
Field In/Out Usage
fInOldPrefs IN A pointer to a Peek-allocated buffer containing the XML of the previously configured options. The XML may be an empty string if the analysis module has not had its context options previously configured, or added to the capture template that was used when creating the capture.
fInOldPrefsLength IN The length in characters of the XML in fInOldPrefs.
fOutNewPrefs OUT A pointer to an analysis module-allocated buffer containing the XML of the newly configured options. This buffer must outlive the scope of the kPluginMsg_ContextOptions handler and therefore should be global/static.
fOutNewPrefsLength OUT The length in characters of the XML in fOutNewPrefs.
fContext IN Pointer to the context data created by the analysis module.

kPluginMsg_SetContextPrefs(12)

Peek sends this message to an analysis module when its options should be changed for a particular file/capture context. The analysis module must parse the incoming XML and apply the configuration.

kPluginMsg_GetContextPrefs(12)

Peek sends this message to an analysis module when to get its options for a particular file/capture context. The analysis module must create and return XML representing the configuration.

Both messages require that an analysis module sets the kPluginAttr_HasContextOptions attribute during handling of the kPluginMsg_Load message in order to be received.

PluginContextPrefsParam

This structure is passed with the kPluginMsg_SetContextPrefs and kPluginMsg_GetContextPrefs messages.

typedef struct PluginContextPrefsParam
{
	UInt32        fFlags;
	TCHAR*        fIoPrefs;
	UInt32        fIoPrefsLength;
	PluginContext fContext;
} PluginContextPrefsParam;
Field In/Out Usage
fFlags IN Reserved.
fIoPrefs IN/OUT A pointer to a buffer of XML text. For kPluginMsg_SetContextPrefs, this is a Peek-allocated, incoming buffer. For kPluginMsg_GetContextPrefs, this is an analysis module-allocated outgoing buffer.
fIoPrefsLength IN/OUT The length in characters of the XML text in fIoPrefs.
fOutNewPrefsLength OUT The length in characters of the XML in fOutNewPrefs.
fContext IN Pointer to the context data created by the analysis module.

kPluginMsg_ProcessTime(12)

Peek sends this message to an analysis module at one second intervals. These messages are sent even when plugins are disabled from the Performance tab.

This messages require that an analysis module sets the kPluginAttr_HandlesProcessTime attribute during handling of the kPluginMsg_Load message in order to be received.

PluginProcessTimeParam

This structure is passed with the kPluginMsg_ProcessTime message.

typedef struct PluginProcessTimeParam
{
	PluginContext fContext;
} PluginProcessTimeParam;
Field In/Out Usage
fContext IN Pointer to the context data created by the analysis module.

Callbacks

Peek exports a set of functions that analysis modules can use to access features of Peek, such as ProtoSpecs and the Name Table, or use as utility routines to aid in packet parsing, for example.

ProtoSpec Callbacks

Peek identifies protocols by placing them in a hierarchy in which each protocol has a unique, 16-bit unsigned identifier. You can view this hierarchy in the dialog used to set up protocol filters in Peek. However, this dialog doesn't show the integer ids that are needed in analysis modules.

IsDescendentOfProc

int
IsDescendentOfProc(
	UInt16        inSubProtocol,
	const UInt16* inParentArray,
	SInt16        inParentCount );
Remarks

Use this callback to determine if a ProtoSpec id is a subprotocol of any of a number of possible parent ProtoSpecs. See the section ProtoSpecs for a description of ProtoSpecs.

This is the only callback which is safe to call when handling a kPluginMsg_Filter message.

Return Value

The return value is the index of the parent matched in the array or -1 if there's no match.

GetProtocolNameProc

int
GetProtocolNameProc(
	UInt16   inProtocol,
	wchar_t* outString );
Remarks

Use this callback to look up the name of a protocol based on the ProtoSpec ID.

Return Value

Returns 0 if successful, non-zero otherwise.

GetProtocolLongNameProc

int
GetProtocolLongNameProc(
	UInt16   inProtocol,
	wchar_t* outString );
Remarks

Use this callback to look up the long name of a protocol based on the ProtoSpec ID.

Return Value

Returns 0 if successful, non-zero otherwise.

GetProtocolHierNameProc

int
GetProtocolHierNameProc(
	UInt16   inProtocol,
	wchar_t* outString );
Remarks

Use this callback to look up the hierarchical name of a protocol based on the ProtoSpec ID.

Return Value

Returns 0 if successful, non-zero otherwise.

GetProtocolParentProc

int
GetProtocolParentProc(
	UInt16  inProtocol,
	UInt16* outProtocolParent );
Remarks

Use this callback to look up the parent protocol of a protocol based on the ProtoSpec ID.

Return Value

Returns 0 if successful, non-zero otherwise.

GetProtocolColorProc

int
GetProtocolColorProc(
	UInt16       inProtocol,
	PluginColor* outColor );
Remarks

Use this callback to look up the color of a protocol based on the ProtoSpec ID.

Return Value

Returns 0 if successful, non-zero otherwise.

Name Table Callbacks

LookupNameProc

int
LookupNameProc(
	PluginNameTableEntry* ioEntry );
Remarks

Use this callback to retrieve a name from an address in Peek's name table. The ioEntry (see PluginNameTableEntry) parameter must contain the address on which to search in the fEntry and fEntryType fields. The entry type specified in fEntryType determines how much data Peek expects to find in address specified by the fEntry field. Clients using this callback are responsible for ensuring that the fName field points to ample storage (256 characters including the terminating null character) in which to receive the name upon successful lookup as well as deallocating that storage when no longer needed.

Return Value

If the address is found in the name table, the return value is 0 and ioEntry is populated with the resulting name and other name table information. If the entry is not found in the name table, the return value is non-zero.

LookupEntryProc

int
LookupEntryProc(
	PluginNameTableEntry* ioEntry );
Remarks

Use this callback to perform a reverse lookup (from name to address) in Peek's name table. Set the fName and fEntryType fields of ioEntry (see PluginNameTableEntry) for which to search. The fEntry field must point to enough storage to contain the resulting address, which depends on the entry type.

Return Value

Returns 0 if the name is found in the name table and ioEntry is populated with the resulting address and other name table information. If the name is not found in the name table, the return value is non-zero.

AddNameEntryProc

int
AddNameEntryProc(
	const PluginNameTableEntry* ioEntry,
	UInt16                      inOptions );
Remarks

Use this callback to add an entry to Peek's name table. Pass in a completely populated name table entry in ioEntry (see PluginNameTableEntry). If the group name specified in the fGroup field doesn't exist, it will be created. Pass NULL for fGroup if you wish the entry to be at the root level of the name table.

The inOptions parameter determines the actions Peek should take when a pre-existing matching entry is found. Options flags are defined below:

enum
{
	kSetEntryName_NoMatchAdd        = 0x0001,
	kSetEntryName_NoMatchSkip       = 0x0002,
	kSetEntryName_NameMatchAdd      = 0x0010,
	kSetEntryName_NameMatchReplace  = 0x0020,
	kSetEntryName_NameMatchSkip     = 0x0040,
	kSetEntryName_AddrMatchAdd      = 0x0100,
	kSetEntryName_AddrMatchReplace  = 0x0200,
	kSetEntryName_AddrMatchSkip     = 0x0400
};

Not all combinations are valid. Choose one from each of the following categories:

What to do in the case of no match
kSetEntryName_NoMatchAdd Add the entry.
kSetEntryName_NoMatchSkip Skip the entry.
What to do in the case of a name in the name table matching the name passed
kSetEntryName_NameMatchAdd Add the entry.
kSetEntryName_NameMatchReplace Replace the existing entry with this one.
kSetEntryName_NameMatchSkip Skip the entry.
What to do in the case of an entry in the name table matching the entry passed
kSetEntryName_AddrMatchAdd Add the entry.
kSetEntryName_AddrMatchReplace Replace the existing entry with this one.
kSetEntryName_AddrMatchSkip Skip the entry.
Return Value

Returns 0 if successful. Any other value indicates failure.

InvokeNameEditDialogProc

int
InvokeNameEditDialogProc(
	PluginNameTableEntry* inEntry );
Remarks

This callback is used to invoke the name edit dialog. The inEntry parameter (see PluginNameTableEntry) should be populated to the best of the client's knowledge to give the user a head start on filling in fields in the dialog. If the user chooses the OK button in the dialog, the entry is added to the name table.

Return Value

Returns 0 if the name edit dialog was successfully invoked, regardless of the user's course of action thereafter. Any other value indicates failure.

ResolveAddressProc

int
ResolveAddressProc(
	UInt8* inAddress,
	UInt16 inAddressType );
Remarks

This callback queues an attempt to resolve the given address to a name. Resolving address occurs asynchronously, so this call returns immediately. The function may be called repeatedly to queue any number of address resolutions. The Name Resolver dialog is displayed until all outstanding attempts are completed.

The following are used for the inAddressType field:

enum
{
	kEntryType_EthernetAddr,  // 6-byte entry.
	kEntryType_AppleTalkAddr, // 4-byte entry (socket ignored).
	kEntryType_IPAddr,        // 4-byte entry.
	kEntryType_DECnetAddr,    // 6-byte entry.
	kEntryType_IPv6Addr,      // 16-byte entry.
	kEntryType_IPPort,        // 2-byte entry.
	kEntryType_ProtoSpec,     // 2-byte entry.
	kEntryType_NWPort,        // 2-byte entry.
	kEntryType_WirelessAddr,  // 6-byte entry.
	kEntryType_IPXAddr,       // 10-byte entry.
	kEntryType_WANDLCIAddr,   // 2-byte (10-bit) entry
	kEntryType_TokenRingAddr  // 6-byte entry.
};

This callback was introduced after the initial release of API version 5, and is only found in Peek versions 4.6 or higher.

Return Value

Returns 0 upon successfully queuing up the resolve request. Returns non-zero otherwise.

Packet Buffer Callbacks

InsertPacketProc

int
InsertPacketProc(
	const PluginPacket* inPacket,
	const UInt8*        inPacketData,
	UInt8               inMediaType,
	UInt8               inMediaSubtype,
	UInt32              inReserved );
Remarks

Use this callback to insert a packet into the packet list.

COM must be initialized on the thread that is calling this routine for the Peek capture to disk feature to operate properly.

Return Value

Returns 0 if successful, non-zero otherwise.

GetPacketCountProc

int 
GetPacketCountProc(
	PluginAppContext     inAppContext, 
	PluginCaptureContext inCaptureContext, 
	UInt32*              outCount );
Remarks

Use this callback to obtain the current packet count for a particular capture, specified by the inCaptureContext parameter. The current count is returned in outCount. The count is the number of packets currently in the buffer, which may be different than the number of packets that have been captured.

Return Value

Returns 0 if successful, non-zero otherwise.

GetFirstPacketIndexProc

int
GetFirstPacketIndexProc(
	PluginAppContext     inAppContext, 
	PluginCaptureContext inCaptureContext, 
	UInt32*              outIndex );
Remarks

Use this callback to obtain the first index of the first packet for a particular capture, specified by the inCaptureContext parameter. The current index is returned in outIndex. This value is used in conjunction with the total packet count to obtain packets using GetPacketProc callback.

Return Value

Returns 0 if successful, non-zero otherwise.

GetPacketProc

int
GetPacketProc(
	PluginAppContext     inAppContext, 
	PluginCaptureContext inCaptureContext, 
	UInt32               inIndex,
	UInt64*              outPacketNumber,
	const PluginPacket** outPacket,
	const UInt8**        outPacketData );
Remarks

This function is reserved for Savvius use.

Return Value

Returns 0 if successful, non-zero otherwise.

Packet List View Callbacks

SelectPacketsProc

int
SelectPacketsProc(
	PluginAppContext     inAppContext,
	PluginCaptureContext inCaptureContext,
	UInt32               inPacketCount,
	UInt64*              inPacketArray,
	UInt32               inFlags );
Remarks

Use this callback to select packets in a Capture Window. The packets to select are listed in the inPacketArray parameter.

For possible values for the inFlags parameter, see the Remarks section for the SelectPacketsExProc callback.

Return Value

Returns 0 if successful. Any other value indicates failure.

SelectPacketsExProc

int
SelectPacketsExProc(
	PluginAppContext     inAppContext,
	PluginCaptureContext inCaptureContext,
	const UInt8*         inSrcAddr,
	UInt16               inSrcAddrType,
	const UInt8*         inDestAddr,
	UInt16               inDestAddrType,
	UInt16               inSrcPort,
	UInt16               inDestPort,
	UInt16               inPortTypes,
	bool                 inBothDirections,
	UInt32               inFlags );
Remarks

Use this callback to select packets in a Capture Window. The packets to select are based on the criteria specified by the parameters.

The following are used for the inSrcAddrType, inDstAddrType and inPortTypes fields:

enum
{
	kEntryType_EthernetAddr,  // 6-byte entry.
	kEntryType_AppleTalkAddr, // 4-byte entry (socket ignored).
	kEntryType_IPAddr,        // 4-byte entry.
	kEntryType_DECnetAddr,    // 6-byte entry.
	kEntryType_IPv6Addr,      // 16-byte entry.
	kEntryType_IPPort,        // 2-byte entry.
	kEntryType_ProtoSpec,     // 2-byte entry.
	kEntryType_NWPort,        // 2-byte entry.
	kEntryType_WirelessAddr,  // 6-byte entry.
	kEntryType_IPXAddr,       // 10-byte entry.
	kEntryType_WANDLCIAddr,   // 2-byte (10-bit) entry
	kEntryType_TokenRingAddr  // 6-byte entry.
};

The tables below show possible values for the inFlags member. Note that a flag and an action should be logically OR'ed together into the flags field. For example, specifying kSelectPacketsFlag_ReplaceSelection | kSelectPacketsAction_HideSelected will replace the current packet selection with the selection criteria you specify, and then automatically hide the selected packets.

Flag Meaning
kSelectPacketsFlag_ReplaceSelection Replace the current selection with the specified selection.
kSelectPacketsFlag_AddToSelection Add the specified selection to the current selection.
Action Meaning
kSelectPacketsAction_PromptUser Prompt the user with a dialog asking to hide selected or hide unselected packets.
kSelectPacketsAction_HideSelected Automatically hide selected packets prior to performing the specified selection.
kSelectPacketsAction_HideUnselected Automatically hide unselected packets prior to performing the specified selection.
Return Value

Returns 0 if successful, non-zero otherwise.

ClaimPacketStringProc

int
ClaimPacketStringProc(
	PluginAppContext     inAppContext,
	PluginCaptureContext inCaptureContext,
	UInt64               inPacketNumber,
	bool                 inExpert );
Remarks

This callback is used to claim a string for a particular packet based on the packet number of that packet.

Return Value

Returns 0 if successful, non-zero otherwise.

SetPacketListColumnProc

int
SetPacketListColumnProc(
	PluginAppContext     inAppContext,
	PluginCaptureContext inCaptureContext,
	const PluginID*      inColumnID,
	const wchar_t*       inColumnName,
	const wchar_t*       inHeaderText,
	bool                 inDefaultVisibility,
	UInt16               inDefaultWidth,
	UInt8                inAlignment );
		
Remarks

This function adds a custom column to the packet list view. Columns are associated with capture/file contexts, specified through the inCaptureContext parameter, and remain valid for the duration of the context. Thus, this callback must be invoked whenever a column is to be associated with a new context (probably while handling kPluginMsg_CreateContext). A single analysis module may add any number of columns through multiple invocations of this callback, but each must be identified by a globally unique ID passed in inColumnID. The ID will be used to store user settings for the column (shown/hidden, width, etc.) and therefore should be constant (i.e. it mustn't be randomly generated on the fly) in order for those settings to be reapplied in subsequently created contexts.

The column's name and header text are specified through inColumnName and inHeaderText, respectively. The header text will be displayed at the top of the column, while the column's name will be displayed in the context menu and options dialog that allow the user to show/hide and reorder columns. inDefaultVisibility and inDefaultWidth specify whether the column is initially shown/hidden and its initial width. The user may change these settings, but should he decide to revert them then they will be reset to these default values.

inAlignment decides whether the column is left or right justified, or centered according to these enumeration values:

enum PluginColumnAlignment
{
	kPluginColumnAlignment_Left,
	kPluginColumnAlignment_Right,
	kPluginColumnAlignment_Center
};

After the column becomes visible in the packet list view, its owning analysis module will start receiving the following messages: kPluginMsg_GetTextForPacketListCell, kPluginMsg_MeasurePacketListCell, and kPluginMsg_DrawPacketListCell.

Return Value

Returns PLUGIN_RESULT_SUCCESS if successful, non-zero otherwise.

Preferences Callbacks

PrefsGetValueProc

int
PrefsGetValueProc(
	PluginAppContext     inAppContext,
	PluginCaptureContext inCaptureContext,
	const wchar_t*       inName,
	const void*          outData,
	UInt32*              ioLength );
Remarks

This callback is used to retrieve a user preference value. It should normally be called in response to a kPluginMsg_ReadPrefs message.

Return Value

Returns 0 if successful, non-zero otherwise.

PrefsSetValueProc

int
PrefsSetValueProc(
	PluginAppContext     inAppContext,
	PluginCaptureContext inCaptureContext,
	const wchar_t*       inName,
	const void*          inData,
	UInt32               inLength );
Remarks

This callback is used to store a user preference value. It should normally be called in response to a kPluginMsg_WritePrefs message.

Return Value

Returns 0 if successful, non-zero otherwise.

PrefsGetPrefsPathProc

int
PrefsGetPrefsPathProc(
	wchar_t* outString );
Remarks

This callback retrieves the registry key path of where an analysis module's preferences are stored. This callback can be used if an analysis module chooses to use its own registry accessing routines instead of the PrefsGetValueProc and PrefsSetValueProc callbacks.

This callback was introduced after the initial release of API version 5, and is only found in Peek versions 4.6 or higher.

Return Value

Returns 0 if successful, non-zero otherwise.

Summary Statistics Callbacks

SummaryModifyEntryProc

int
SummaryModifyEntryProc(
	PluginAppContext     inAppContext,
	PluginCaptureContext inCaptureContext,
	const wchar_t*       inLabel,
	const wchar_t*       inGroupName,
	UInt32               inType,
	void*                inData );
Remarks

Use this callback to add or modify a summary entry. The inType parameter should consist of various flags indicating the type, format, and whether the statistic can be charted.

The type flags are as follows:

Summary Type Displayed As
kPluginSummaryType_Date Date (seconds since Jan 1 1904).
kPluginSummaryType_Time Time (seconds since Jan 1 1904).
kPluginSummaryType_Duration Elapsed time in Seconds.
kPluginSummaryType_PacketCount Count of packets.
kPluginSummaryType_ByteCount Count of bytes.
kPluginSummaryType_BothCount Both packet and byte counts (see ByteCountPair).
kPluginSummaryType_OtherCount A counter other than packets or bytes.

In addition, you must specify a size for the entry. The size should be logical OR'ed with the type (eg, kPluginSummaryType_Duration | kPluginSummarySize_UInt32). The size specified must be one of the following:

Summary Size Size
kPluginSummarySize_UInt8 1 byte.
kPluginSummarySize_UInt16 2 bytes.
kPluginSummarySize_UInt32 4 bytes.
kPluginSummarySize_UInt64 8 bytes.
kPluginSummarySize_ByteCountPair 16 bytes (8 bytes of byte count, 8 bytes of packet count).

There are also a series of optional flags which are used to give Peek some hints about how the data should be handled. Peek versions 4.1 and higher have the ability to graph and/or create alarms based on any summary statistic, including those created by your analysis module. In order for these features to work correctly, you may need to give Peek some hints about your data by setting these flags:

Summary Flag Description
kPluginSummaryFlag_Ungraphable Indicates that the specified summary entry cannot be graphed. Setting this flag will cause Peek to disallow creating graphs and alarms based on this entry, so you are strongly advised to NOT use this flag unless absolutely necessary.
kPluginSummaryFlag_IsOverTime Indicates that the specified summary entry represents some data calculated over time (e.g., utilization in bits per second).
kPluginSummarySize_IsSampled Indicates that the specified summary entry is sampled. This should be used for statistics which may potentially go DOWN (e.g., the number of currently active connections).
Return Value

Returns 0 if successful, non-zero otherwise.

SummaryGetEntryProc

int
SummaryGetEntryProc(
	PluginAppContext     inAppContext,
	PluginCaptureContext inCaptureContext,
	const wchar_t*       inName,
	const wchar_t*       inGroup,
	UInt32*              outType,
	void**               outData,
	UInt8*               outSource );
Remarks

Use this callback to retrieve a summary entry. For the values for outType and format of outData, see SummaryModifyEntryProc. The outSource parameter is unused, but a valid UInt8 pointer must still be supplied.

Return Value

Returns 0 if the statistic was successfully found, and outType will hold flags describing the type of data pointed to by outData. Any other value indicates failure, most likely because the statistic specified by inName cannot be found.

Packet Parsing Callbacks

PacketGetLayerProc

const UInt8*
PacketGetLayerProc(
	UInt8               inLayerType,
	UInt8               inMediaType,
	UInt8               inMediaSubtype,
	const PluginPacket* inPacket,
	const UInt8*        inPacketData,
	UInt16*             ioBytesLeft );
Remarks

This callback is used to obtain a pointer to a particular layer of a packet. The inLayerType parameter consists of flags telling Peek which portion of the packet to locate. Values must be one of the following:

Layer Type Description
kPacketLayerType_Header Start of header (first byte of header).
kPacketLayerType_Data End of header (first byte following header).

In addition, you must specify a layer. The layer should be logically OR'ed with the layer type (e.g., kPacketLayerType_Header | kPacketLayer_IP). The packet layer must be one of the following:

Packet Layer Description
kPacketLayer_Physical Physical layer.
kPacketLayer_IP IP layer.
kPacketLayer_UDP UDP layer.
kPacketLayer_TCP TCP layer.
kPacketLayer_ICMP ICMP layer.
Return Value

A pointer to the specified layer of the packet will be returned (or NULL on error), and ioBytesLeft will be set to the number of bytes remaining in the packet (counting from the returned pointer).

PacketGetAddressProc

int
PacketGetAddressProc(
	PluginAppContext     inAppContext,
	PluginCaptureContext inCaptureContext,
	UInt8                inAddressSelector,
	UInt8                inMediaType,
	UInt8                inSubType,
	const PluginPacket*  inPacket,
	const UInt8*         inPacketData,
	UInt64               inPacketNumber,
	UInt8*               outAddress,
	UInt16*              outAddressType );
Remarks

This callback copies an address from a packet into a buffer. Which address is copied from the packet is specified by the following values for the inAddressSelector parameter.

enum
{
	kAddressType_SrcPhysical,
	kAddressType_DestPhysical,
	kAddressType_SrcLogical,
	kAddressType_DestLogical,
	kAddressType_BSSID,
	kAddressType_Receiver,
	kAddressType_Transmitter,
	kAddressType_Address1,
	kAddressType_Address2,
	kAddressType_Address3,
	kAddressType_Address4
};

Address selectors kAddressType_SrcPhysical through kAddressType_DestLogical apply to both LAN and wireless packets. The remaining address selectors apply to wireless packets only.

The outAddress parameter must point to a buffer of sufficient space to hold the address when it is copied.

This callback is particularly useful for certain wireless control packets that don't have both a destination address specified in the packet. In those cases, Peek is able to deduce the destination address by traversing the packet list backwards to look for the sender in the packet to which the control packet is replying.

This callback was introduced after the initial release of API version 5, and is only found in Peek versions 4.6 or higher.

Return Value

If the address was successfully extracted from the packet, the return value is 0 and the buffer pointed to by outAddress will contain the address and outAddressType will indicate the type of address (see PluginNameTableEntry for address types). Any other value indicates failure.

PacketGetDataLayerProc

UInt8*
PacketGetDataLayerProc
( 
	UInt32              inProtoSpec, 
	UInt8               inMediaType, 
	UInt8               inSubType, 
	const PluginPacket* inPacket,
	const UInt8*        inPacketData, 
	UInt16*             ioBytesLeft, 
	UInt32*             outSourceProtoSpec );
Remarks

Use this callback to look up the start of the payload of the packet given a protocol ID.

Return Value

Returns a pointer in the packet data where the payload for that protocol layer starts.

PacketGetHeaderLayerProc

UInt8*
PacketGetHeaderLayerProc
( 
	UInt32              inProtoSpec, 
	UInt8               inMediaType, 
	UInt8               inSubType, 
	const PluginPacket* inPacket,
	const UInt8*        inPacketData, 
	UInt16*             ioBytesLeft, 
	UInt32*             outSourceProtoSpec );
Remarks

Use this callback to look up the start of the header of the packet given a protocol ID.

Return Value

Returns a pointer in the packet data where the header for that protocol layer starts.

Packet Decoding Callbacks

DecodeOpProc

int
DecodeOpProc(
	PluginAppContext      inAppContext,
	PluginCaptureContext  inCaptureContext,
	int                   inOp,
	UInt32                inValue,
	UInt32                inGlobal,
	UInt8                 inStyleValue,
	UInt8                 inStyleLabel,
	const wchar_t*        inString,
	const wchar_t*        inSummary );
Remarks

Use this callback to decode the operator inOp. The results are set in inString and inSummary.

Return Value

If successful the callback returns 0.

AddUserDecodeProc

int
AddUserDecodeProc(
	const wchar_t*  inFuncName );
Remarks

Use this callback to register a new callback function.

Return Value

If successful the callback returns 0.

Other Callbacks

AddTabProc

int
AddTabProc(
	PluginAppContext     inAppContext,
	PluginCaptureContext inCaptureContext,
	const wchar_t*       inTabName,
	const wchar_t*       inWindowClass,
	void**               outTabWnd );
Remarks

This callback is identical in purpose to AddTabWithGroupProc, except that the default group name will be used.

Return Value

If successful the callback returns 0 and the outTabWnd parameter contains either a window handle or an interface pointer, depending on the type of class name specified in the inWindowClass parameter. All other values indicate failure.

AddTabWithGroupProc

int
AddTabWithGroupProc(
	PluginAppContext     inAppContext,
	PluginCaptureContext inCaptureContext,
	const wchar_t*       inTabName,
	const wchar_t*       inGroupName,
	const wchar_t*       inWindowClass,
	void**               outTabWnd );
Remarks

Use this callback to add a custom tab to the capture window UI. The tab will be titled with the string specified in the inTabName parameter and will be placed in the group specified by inGroupName. The inWindowClass parameter specifies either the Win32 window class name (registered with the system using the RegisterClass Win32 function) or an ActiveX control ProgID. The window or ActiveX control will be created by Peek and added to the capture window UI before returning.

Return Value

If successful the callback returns 0 and the outTabWnd parameter contains either a window handle or an interface pointer, depending on the type of class name specified in the inWindowClass parameter. All other values indicate failure.

MakeFilterProc

int
MakeFilterProc(
	const UInt8* inSrcAddr,
	UInt16       inSrcAddrType,
	const UInt8* inDestAddr,
	UInt16       inDestAddrType,
	UInt16       inSrcPort,
	UInt16       inDestPort,
	UInt16       inPortTypes,
	bool         inBothDirections );
Remarks

This callback is used to invoke the Edit Filter dialog. Many of the parameters correspond to input fields in this dialog. If a parameter is not used in the filter, zero or NULL can be used to indicate that. If the user chooses the OK button in the dialog, the filter is created (but not activated), otherwise the filter is aborted.

The following are used for the inSrcAddrType, inDstAddrType and inPortTypes fields:

enum
{
	kEntryType_EthernetAddr,  // 6-byte entry.
	kEntryType_AppleTalkAddr, // 4-byte entry (socket ignored).
	kEntryType_IPAddr,        // 4-byte entry.
	kEntryType_DECnetAddr,    // 6-byte entry.
	kEntryType_IPv6Addr,      // 16-byte entry.
	kEntryType_IPPort,        // 2-byte entry.
	kEntryType_ProtoSpec,     // 2-byte entry.
	kEntryType_NWPort,        // 2-byte entry.
	kEntryType_WirelessAddr,  // 6-byte entry.
	kEntryType_IPXAddr,       // 10-byte entry.
	kEntryType_WANDLCIAddr,   // 2-byte (10-bit) entry
	kEntryType_TokenRingAddr  // 6-byte entry.
};

This callback was introduced after the initial release of API version 5, and is only found in Peek builds 4.6 or higher.

Return Value

Returns 0 if the Edit Filter dialog was successfully invoked, regardless of the user's course of action thereafter. Any other value indicates failure.

NotifyProc

int
NotifyProc(
	PluginAppContext     inAppContext,
	PluginCaptureContext inCaptureContext,
	UInt64               inTimeStamp,
	UInt8                inSeverity,
	const wchar_t*       inShortString,
	const wchar_t*       inLongString );
Remarks

Use this callback to trigger a Notification within Peek. Peek will log the message, or send a page or email, depending on the settings in the Peek's Notification dialog. inShortString is used in the log and the subject of an email, inLongString is used in the body of the email.

Return Values

Returns 0 if successful, non-zero otherwise, for example if the user has turned off notifications for the analysis module.

SendPacketProc

int
SendPacketProc(
	const UInt8* inPacketData,
	UInt16*      inPacketLength );
Remarks

Use this callback to send a packet, using the current send adapter.

Return Value

Returns 0 if successful, non-zero otherwise.

GetAppResourcePathProc

int
GetAppResourcePathProc(
	wchar_t* outAppResourcePath );
Remarks

Use this callback to retrieve the path to the language specific resource folder.

Return Value

Returns 0 if successful, non-zero otherwise.

SendPluginMessageProc

int
SendPluginMessageProc(
	PluginAppContext     inAppContext, 
	PluginCaptureContext inCaptureContext, 
	UInt8*               inParamData,
	UInt32               inParamDataLen );
Remarks

Use this callback to send messages to remote plugins on remote engines. This callback will only work if the fContextFlag value was set to kRemoteCaptureWindow when the context was created. The message to be sent is pointed to by inParamData, and the length is specified by inParamDataLen. Once this message is sent, the remote engine may reply with its own message, which any plugin that has set the kPluginAttr_ProcessPluginMessages or the context will receive. For more information on remote engine plugins, see the Omni DAM SDK.

Return Value

Returns 0 if successful, non-zero otherwise.

SaveContextProc

int
SaveContextProc(
	PluginAppContext     inAppContext, 
	PluginCaptureContext inCaptureContext );
Remarks

Use this callback to have Peek send a kPluginMsg_GetContextPrefs to the inCaptureContext context.

Do not call this function when handling a kPluginMsg_ContextOptions message.

Return Value

Returns 0 if successful, non-zero otherwise.

Appendix

Data Types

Basic Types

Basic types are defined in the header file AGTypes.h. These types are used in the SDK to allow an analysis modules core functionality to be completely cross-platform compatible. The typedefs also enhance readability of code by making the size and signed/unsigned property of types apparent.

Basic Type Typedef
unsigned char UInt8
signed char SInt8
unsigned short UInt16
signed short SInt16
unsigned long UInt32
signed long SInt32
signed __int64 SInt64
unsigned __int64 UInt64

Media Types

enum
{
	kPluginPacketMediaType_802_3,       // Ethernet, Wireless Ethernet
	kPluginPacketMediaType_802_5,       // Token Ring
	kPluginPacketMediaType_Fddi,        // FDDI
	kPluginPacketMediaType_Wan,         // WAN
	kPluginPacketMediaType_LocalTalk,   // LocalTalk
	kPluginPacketMediaType_Dix,         // DEC/Intel/Xerox (DIX) Ethernet
	kPluginPacketMediaType_ArcnetRaw,   // ARCNET (raw)
	kPluginPacketMediaType_Arcnet878_2, // ARCNET (878.2)
	kPluginPacketMediaType_Atm,         // ATM
	kPluginPacketMediaType_WirelessWan, // Wireless WAN
	kPluginPacketMediaType_Irda,        // Infrared (IrDA)
	kPluginPacketMediaType_Bpc,         // Broadcast architecture
	kPluginPacketMediaType_CoWan,       // Connection-oriented WAN
	kPluginPacketMediaType_1394         // IEEE 1394
};

Media Subtypes

enum
{
	kPluginPacketMediaSubType_Native,         // Native media specified by the media type.
	kPluginPacketMediaSubType_802_11_b,       // Wireless LAN network using 802.11b.
	kPluginPacketMediaSubType_802_11_a,       // Wireless LAN network using 802.11a.
	kPluginPacketMediaSubType_802_11_gen,     // Wireless LAN network using one or more 802.11 specifications.
	kPluginPacketMediaSubType_wan_ppp,        // PPP.
	kPluginPacketMediaSubType_wan_frameRelay, // Frame relay.
	kPluginPacketMediaSubType_wan_x25,        // X.25.
	kPluginPacketMediaSubType_wan_x25e,       // X.25 mod 128.
	kPluginPacketMediaSubType_wan_ipars,      // IPARS.
	kPluginPacketMediaSubType_wan_u200,       // U200.
	kPluginPacketMediaSubType_wan_Q931        // Q.931.
};

ProtoSpecs

Peek identifies protocols by placing them in a hierarchy in which each item has a unique identifier. You can view this hierarchy in the dialog used to set up protocol filters in Peek. However, this dialog doesn't show the integer IDs that are needed in analysis modules.

Data Structures

PluginPacket

typedef struct PluginPacket
{
	UInt64       fTimeStamp;
	UInt32       fProtoSpec;
	UInt32       fFlags;
	UInt32       fStatus;
	UInt16       fPacketLength;
	UInt16       fSliceLength;
	const UInt8* fMediaSpecInfoBlock;
} PluginPacket;

This is the definition of a packet used during processing of the messages kPluginMsg_ProcessPacket and kPluginMsg_GetPacketString, among others. Each field in the packet header is described below:

Field Usage
fTimeStamp Timestamp in nanoseconds from midnight Jan. 1, 1601 UTC.
fProtoSpec The ProtoSpec instance ID of the packet that identifies the specific protocol. See ProtoSpecs for more information.
fFlags Packet flags. See the definitions below.
fStatus Packet status. See the definitions below.
fPacketLength The packet length of the packet on the network.
fSliceLength The sliced length of the packet. Zero if the packet is not sliced.
fMediaSpecInfoBlock A pointer a MediaSpecificPrivateHeader structure that that immediately precedes another media-specific structure containing additional media-specific information for this particular packet. This value may be NULL.

The following values are defined for the fFlags field:

enum
{
	kPluginPacketFlag_Control        = 0x01, // Control vs. data packet.
	kPluginPacketFlag_CRC            = 0x02, // Checksum error.
	kPluginPacketFlag_Frame          = 0x04, // Frame error.
	kPluginPacketFlag_RouteInfo      = 0x08, // Has routing info (Token Ring).
	kPluginPacketFlag_Oversize       = 0x10, // Oversize error.
	kPluginPacketFlag_Runt           = 0x20, // Runt error.
	kPluginPacketFlag_Trigger        = 0x40, // Trigger packet.
	kPluginPacketFlag_SNAP           = 0x80, // SNAP packet.    
	kPluginPacketFlag_DroppedPackets = 0x100 // One or more packets were dropped prior to this packet.    
};

The following values are defined for the fStatus field:

enum
{
	kPluginPacketStatus_Truncated       = 0x02,  // Truncated packet.
	kPluginPacketStatus_Encrypted       = 0x04,  // Originally encrypted (e.g., WEP).
	kPluginPacketStatus_DecryptionError = 0x08,  // Decryption error (e.g., WEP ICV).
	kPluginPacketStatus_Sliced          = 0x20,  // Sliced packet.
	kPluginPacketStatus_ShortPreamble   = 0x40   // Short preamble.
};

PluginPacketMetadata(12)

This is a more complete version of the PluginPacket structure.

typedef struct PluginPacketMetadata
{
	UInt64       fTimeStamp;
	UInt32       fProtoSpec;
	UInt32       fFlags;
	UInt32       fStatus;
	UInt16       fPacketLength;
	UInt16       fSliceLength;
	const UInt8* fMediaSpecInfoBlock;
	UInt64       fPacketNumber;
	UInt32       fMatchedProtoSpec;
	UInt8        fMediaType;
	UInt8        fMediaSubType;
} PluginPacketMetaData;
Field Usage
fTimeStamp Timestamp in nanoseconds from midnight Jan. 1, 1601 UTC.
fProtoSpec The ProtoSpec instance ID of the packet that identifies the specific protocol. See ProtoSpecs for more information.
fFlags Packet flags. See the definitions in PluginPacket.
fStatus Packet status. See the definitions in PluginPacket.
fPacketLength The packet length of the packet on the network.
fSliceLength The sliced length of the packet; zero if the packet is not sliced.
fMediaSpecInfoBlock A pointer a MediaSpecificPrivateHeader structure, which precedes media specific information for this particular packet. This value may be NULL.
fPacketNumber The number of the packet.
fMatchedProtoSpec The ProtoSpec that is of interest to the analysis module (as specified during handling of the kPluginMsg_Load message). This may differ from fProtoSpec if, for example, the analysis module wishes to receive all TCP packets and the current packet is an HTTP packet. This field will contain the TCP ProtoSpec ID while fProtoSpec will contain the HTTP ProtoSpec ID. See ProtoSpecs for more information.
fMediaType One of the Media Types enumerations.
fMediaSubType One of the Media Subtypes enumerations.

PluginPacketProcessingInfo(12)

This structure contains both the packet metadata and a pointer raw packet data.

typedef struct PluginPacketProcessingInfo
{
	PluginPacketMetadata fPacketMetadata;
	const UInt8*         fPacketData;
} PluginPacketProcessingInfo;
Field Usage
fPacketMetadata A PluginPacketMetadata structure containing all of the metadata fields associated with a packet.
fPacketData Pointer to the raw packet data.

MediaSpecificPrivateHeader

The MediaSpecificPrivateHeader structure is defined as follows (see PacketHeaders.h in the SDK folder):

typedef struct MediaSpecificPrivateHeader
{
	UInt32 nSize; /* size of the whole information block, which is this struct the one that follows */
	UInt32 nType; /* type identifier for the structure immediately following this one */
};

The following values are defined for the nType field:

#define kMediaSpecificHdrType_Invalid    0 /* not a valid type */
#define kMediaSpecificHdrType_Wireless   1 /* Obsolete */
#define kMediaSpecificHdrType_WirelessEx 2 /* The next header is a WirelessPrivateHeader */
#define kMediaSpecificHdrType_FullDuplex 3 /* The next header is a FullDuplexPrivateHeader */
#define kMediaSpecificHdrType_Wan        4 /* The next header is a WideAreaNetworkHeader */

WirelessPrivateHeader

The WirelessPrivateHeader is defined as follows (see PacketHeaders.h in the SDK folder):

typedef struct Wireless80211PrivateHeader
{
	UInt8 DataRate; /* Data rate in 500 Kbps units. */
	UInt8 Channel; /* 802.11 channel [1-255] */
	UInt8 SignalStrength; /* Signal strength 0-100% */
	UInt8 NoiseStrength; /* Noise strength 0-100% */
	SInt16 SignaldBm; /* signal strength dBm */
	SInt16 NoisedBm; /* Noise dBm */
};

The following values are of note for dBm measurements:

#define PEEK_NULL_DBM -32767 /* -32767 dBm is the smallest we can ever have in a SHORT */
#define PEEK_MIN_DBM -100 /* -100dBm is 0.1pW, which is about the smallest reasonable value one would expect */
#define PEEK_MAX_DBM -5 /* -5dBm is 320uW, which is about the largest reasonable value one would expect */

FullDuplexPrivateHeader

The FullDuplexPrivateHeader is defined as follows (see PacketHeaders.h in the SDK folder):

typedef struct FullDuplexPrivateHeader
{
	UInt32 Channel; /* Channel number */
};

The following values are of note for Channel:

#define PEEK_INVALID_DUPLEX_CHANNEL 0

WideAreaNetworkHeader

The WideAreaNetworkHeader is defined as follows (see PacketHeaders.h in the SDK folder):

typedef struct WideAreaNetworkHeader
{
	UInt8 Direction; /* "To DCE" or "To DTE" */
	UInt8 Protocol; /* Frame relay, PPP, ... */
};

The following values are of note for Direction:

#define PEEK_WAN_DIRECTION_INVALID 0
#define PEEK_WAN_DIRECTION_DTE 1
#define PEEK_WAN_DIRECTION_DCE 2

The following values are of note for Protocol:

#define PEEK_WAN_PROT_INVALID 0x00 /* Not a valid protocol */
#define PEEK_WAN_PROT_0800    0x08 /* TCP/IP */
#define PEEK_WAN_PROT_FRLY    0x23 /* Frame relay */
#define PEEK_WAN_PROT_PPP     0x10 /* PPP/LCP (also used for HDLC) */
#define PEEK_WAN_PROT_X25     0x25 /* X.25 */
#define PEEK_WAN_PROT_X25E    0x29 /* X.25 mod 128 */
#define PEEK_WAN_PROT_Q931    0x31 /* Q.931 */
#define PEEK_WAN_PROT_SNA     0x40 /* SNA */
#define PEEK_WAN_PROT_SS7     0x70 /* SS7 */
#define PEEK_WAN_PROT_IPARS   0x50 /* IPARS */
#define PEEK_WAN_PROT_U200    0x60 /* U200 */

PluginNameTableEntry

typedef struct PluginNameTableEntry
{
	UInt8*      fEntry;
	TCHAR*      fName;
	TCHAR*      fGroup;
	PluginColor fColor;
	UInt16      fEntryType;
	UInt8       fHostType;
} PluginNameTableEntry;

The following are used for the fEntryType field:

enum
{
	kEntryType_EthernetAddr,  // 6-byte entry.
	kEntryType_AppleTalkAddr, // 4-byte entry (socket ignored).
	kEntryType_IPAddr,        // 4-byte entry.
	kEntryType_DECnetAddr,    // 6-byte entry.
	kEntryType_IPv6Addr,      // 16-byte entry.
	kEntryType_IPPort,        // 2-byte entry.
	kEntryType_ProtoSpec,     // 2-byte entry.
	kEntryType_NWPort,        // 2-byte entry.
	kEntryType_WirelessAddr,  // 6-byte entry.
	kEntryType_IPXAddr,       // 10-byte entry.
	kEntryType_WANDLCIAddr,   // 2-byte (10-bit) entry
	kEntryType_TokenRingAddr  // 6-byte entry.
};

The following are used for the fHostType field:

enum
{
	kHostType_Unknown,
	kHostType_Workstation,
	kHostType_Server,
	kHostType_Router,
	kHostType_Switch,
	kHostType_Repeater,
	kHostType_Printer,
	kHostType_AccessPoint
};

ByteCountPair

typedef struct ByteCountPair
{
	UInt64 fBytes;
	UInt64 fCount;
} ByteCountPair;

This structure is used in the summary statistics entries. See SummaryModifyEntryProc.

ClientAppDataPtr

typedef void* ClientAppDataPtr;

This type definition is used in PluginLoadParam.

XML Adapter Tags

These tags are used for the capture adapter calls which require XML data.

#define kAdapterTag_StartCaptureText _T("StartCaptureText")
#define kAdapterTag_StopCaptureText  _T("StopCaptureText")
#define kAdapterEle_Group            _T("Group")
#define kAdapterEle_Adapter          _T("Adapter")
#define kAdapterTag_Name             _T("Name")
#define kAdapterTag_ID               _T("ID")
#define kAdapterTag_Speed            _T("LinkSpeed")
#define kAdapterTag_DefaultSpeed     _T("DefaultLinkSpeed")
#define kAdapterTag_MediaType        _T("MediaType")
#define kAdapterTag_MediaSubType     _T("MediaSubType")
#define kAdapterTag_MediaDesc        _T("MediaDesc")
#define kAdapterTag_Deletable        _T("Deletable")
#define kAdapterVal_False            _T("false")
#define kAdapterVal_True             _T("true")
#define kAdapterTag_Address          _T("Address")
#define kAdapterTag_PluginID         _T("PluginID")
#define kAdapterTag_Device           _T("Device")		
#define kAdapterTag_Properties       _T("Properties")
#define kAdapterTag_Continuous       _T("Continuous")

These tags are used for wireless adapters.

#define kAdapterTag_CurrentSetting _T("Setting")	
#define kAdapterTag_Channel        _T("Channel")	
#define kAdapterTag_ChannelNumber  _T("ChannelNumber")	
#define kAdapterTag_ChannelFreq    _T("ChannelFreq")	
#define kAdapterTag_ChannelBand    _T("ChannelBand")	
#define kAdapterTag_ESSID          _T("ESSID")		
#define kAdapterTag_BSSID          _T("BSSID")		
#define kAdapterTag_ChannelScan    _T("Scanning")	
#define kAdapterTag_Enabled        _T("Enabled")
#define kAdapterTag_Duration       _T("Duration")
#define kAdapterTag_WEPKeys        _T("WEP")		
#define kAdapterTag_Key            _T("Key")
#define kAdapterTag_KeyNum         _T("KeyNum")

Here's an example of an XML stream, as prepared in response to a kPluginMsg_GetAdapterList message:

<?xml version="1.0" encoding="UTF-8"?>
<RemotePluginSampleAdapters StartCaptureText="Start Remote Capture" StopCaptureText="Stop Remote Capture">
	<Group Name="Probe #1" Deletable="true" ID="0x00000001">
		<Adapter Name="Adapter #1 : 0" ID="0x00010000" LinkSpeed="0x00a7d8c0" Address="00:00:00:00:00"
			MediaType="IEEE 802.11b" MediaSubType="1" Device="Remote Sample Plugin Adapter"
			Properties="true"/>
		<Adapter Name="Adapter #1 : 1" ID="0x00010001" LinkSpeed="0x00a7d8c0" Address="00:00:00:00:00"
			MediaType="IEEE 802.11b" MediaSubType="1" Device="Remote Sample Plugin Adapter"
			Properties="true"/>
	</Group>
</RemotePluginSampleAdapters>

Here's an example of an XML stream, as prepared for a kPluginMsg_GetAdapterAttribs message to get Link Speed:

<?xml version="1.0" encoding="UTF-8"?>
<Adapter>
	<LinkSpeed/>
</Adapter>

Here's an example of an XML stream, as prepared for a kPluginMsg_GetAdapterAttribs message to get wireless settings:

<?xml version="1.0" encoding="UTF-8"?>
<GetWirelessSettings>
	<Setting/>
	<Channel/>
	<ESSID/>
	<BSSID/>
	<Scanning/>
	<WEP/>
</GetWirelessSettings>

Here's an example of an XML stream, as prepared for a kPluginMsg_SetAdapterAttribs message to set wireless settings:

<?xml version="1.0" encoding="UTF-8"?>
<SetWirelessSettings>
	<Setting>Channel</Setting>
	<Channel>2</Channel>
	<ESSID/>
	<BSSID/>
	<Scanning>
		<Channel Enabled="true" Duration="500">1</Channel>
		<Channel Enabled="true" Duration="500">2</Channel>
		<Channel Enabled="true" Duration="500">3</Channel>
		<Channel Enabled="true" Duration="500">4</Channel>
		<Channel Enabled="true" Duration="500">5</Channel>
		<Channel Enabled="true" Duration="500">6</Channel>
		<Channel Enabled="true" Duration="500">7</Channel>
		<Channel Enabled="true" Duration="500">8</Channel>
		<Channel Enabled="true" Duration="500">9</Channel>
		<Channel Enabled="true" Duration="500">10</Channel>
		<Channel Enabled="true" Duration="500">11</Channel>
		<Channel Enabled="true" Duration="500">12</Channel>
		<Channel Enabled="true" Duration="500">13</Channel>
		<Channel Enabled="true" Duration="500">14</Channel>
	</Scanning>
	<WEP Name="sample wep key">
		<Key KeyNum="1">0102030405</Key>
		<Key KeyNum="3">060708090A</Key>
	</WEP>
</SetWirelessSettings>

Context Preferences

Context Preferences is a set of messages, data structures and callbacks that provide plugins with a way to manage unique preferences for each context. Prior to Omnipeek 5.0 plugins where given the option to display, save and restore a single set of peferences. Context Preferences allows plugins to display, save and restore a unique set of preferences for each context.

When at least one plugin supports Context Preferences, Peek will display an Analysis Modules tab in the Capture Options dialog. This tab contains the list of plugins that support Context Preferences, an About... button and an Options... button (simlar to the Analysis Modules tab on Peek's Options dialog). When the Options... button is clicked, Peek sends the selected plugin a kPluginMsg_ContextOptions message with a pointer to a PluginContextOptionsParams in the ioParams parameter. The plugin should display its Context Options dialog. If the user clicks OK then the plugin should set fOutNewPrefs and fOutNewPrefsLength and return PLUGIN_RESULT_SUCCESS. The preferences must be an XML formatted NULL terminated Unicode string. Peek will make of copy of the new preferences.

typedef struct PluginContextOptionsParam
{
	const wchar_t*  fInOldPrefs;
	UInt32          fInOldPrefsLength;
	wchar_t*        fOutNewPrefs;
	UInt32          fOutNewPrefsLength;
	PluginContext   fContext;
} PluginContextOptionsParam;

When the Capture Options dialog is displayed during the creation of a new Capture Window the context has not been created, so fContext will be set to NULL. The fInOldPrefs and fInOldPrefsLengths will be set to Peek's copy of the preferences. If fInOldPrefs is NULL or fInOldPrefsLengths is zero, then default preference values should be used.

When a new Capture Window is being created Peek will send the plugin a kPluginMsg_CreateContext message. The plugin should initialize the preferences for the new context to appropriate defaults. If the user configured Context Preferences for the plugin, then Peek will send the plugin a kPluginMsg_SetContextPrefs message with a copy of the preferences set from the kPluginMsg_ContextOptions message.

While the Capture is open the user may invoke the plugin's Context Options dialog via the Capture Options dialog. Peek will send the plugin a kPluginMsg_ContextOptions message. And fContext will contain the plugin's handle to the context. The fInOldPrefs and fInOldPrefsLength will be set to Peek's copy of the Context Preferences. If fInOldPrefs is NULL or fInOldPrefsLengths is zero, then default preference values should be used. It is the responsibility of the plugin to enforce Context Preference modifications policy while the Capture Window is capturing. If the plugin's policy is to not allow the user to modify the preferences while the Capture Window is capturing, then the appropriate controls of the Context Options dialog should be disabled.

When the user creates a Capture Template from an open Capture Windows. Peek will save the plugin's Context Preferences in the Capture Template File (CTF). If the user did not configure Context Preferences then there will not be an entry in the Plugins entry of the CTF for the plugin.

When opening a Capture Template file, Peek will send the plugina kPluginMsg_CreateContext message. If the CTF contains Context Preferences for the plugin, then Peek will send the plugin a kPluginMsg_SetContextPrefs message.

The plugin may create a Tab that allows the user to modify the Context Preferences of a context. To ensure that Peek maintains an up to date copy of the Context Preferences the plugin should call SetContextPrefsProc when the user modifies them. Peek will send the plugin a kPluginMsg_GetContextPrefs, the plugin returns the new Context Preferences and then Peek returns from SetContextPrefsProc.

The Plugin Wizard can create a plugin that implements Context Preferences that support the model presented here. An alternative model is for the Options dialog, displayed in response to the kPluginMsg_Options, could be used to manage global preferences that are shared by all plugins. The the Context Preferences Options dialog can be used to manage a completely different set of per context preferences.

The plugin must set the kPluginAttrEx_HasContextOptions flag in the fAttributesEx field of the ioParams parameter before returning from the kPluginMsg_Load message the receive the Context Preference's messages.