DataParsers

Data Parsers

IRPMon is capable of collecting data associated with certain types of (iRP) requests. For example, if a driver sends a requests querying device hardware IDs, the IRPMon driver captures both the IRP requesta and its completion. When the target device completes the request, it allocates a block of memory and fills it with requested hardware IDs. IRPMon copies this block to the IRP completion event record.

When the IRP completion request is displayed in detail in the IRPMon application, the user can view the hardware IDs in hexadecimal format. Since the IDs are reported as wide character strings separated by a null characters reading them is not too hard for the user.

However, some requests, such as IRP_MJ_PNP:IRP_MN_QUERY_CAPABILITIES report data in more complicated format which is hard to read from the hexadecimal output for most of users. To countermeasure this inconvenience, data parsers were introduced. Their task is to display data associated with requests in a human readable manner.

A data parser is implemented as a dynamic link library (DLL) exporting the following routine:

DWORD cdecl DataParserInit(PIRPMON_DATA_PARSER Parser);

The routine is invoked by the IRPMon application when the parser DLL is loaded (which usually happens during the application startup). The routine must initialize the parser for regular operation and write necessary information into the IRPMON_DATA_PARSER structure given by the application. If the initialization succeeds, it must return zero. Failures are reported by nonzero values that are intrepreted by the application as Windows error codes.

The IRPMON_DATA_PARSER structure contains the following members:

• Name. Name of the parser. It is displayed by the IRPMon application and server no other purpose.
• Majorversion, MinorVersion, BuildNumber. Version of the parser. Values are parser-defined and the application just displays them in its interface.
• Priority. Defines order in which the parsers are called for an incomming request. Higher values mean ealrier calls.
• ParseRoutine. Address of a routine responsible for parsing data associated with an incomming request.
• FreeRoutine. Address of a routine that is called by the application to free resources allocated by the Parseroutine. Each call to the parse routine is followed by a call to the free routine. The free routine is optional (FreeRoutine field can be NULL).

typedef struct _IRPMON_DATA_PARSER { const wchar_t *Name; DP_PARSE_ROUTINE *ParseRoutine; DP_FREE_ROUTINE *FreeRoutine; DWORD MajorVersion; DWORD MinorVersion; DWORD BuildVersion; DWORD Priority; } IRPMON_DATA_PARSER, *PIRPMON_DATA_PARSER;

The parse and free routines need to have the following signatures:

typedef struct _DP_REQUEST_EXTRA_INFO { PWCHAR DriverName; PWCHAR DeviceName; PWCHAR FileName; } DP_REQUEST_EXTRA_INFO, *PDP_REQUEST_EXTRA_INFO;

DWORD cdecl ParseRoutine(const REQUEST_HEADER *Request, const DP_REQUEST_EXTRA_INFO *ExtraInfo, PBOOLEAN Handled, wchar_t ***Names, wchar_t ***Values, size_t *RowCount); void cdecl FreeRoutine(wchar_t **Names, wchar_t **Values, size_t Count);

The incomming request and some extra information (driver name, device name, file name) are reported in the first two arguments. Data associated with the request directly follow its headers (where their amount is also stored).

By setting the Handled parameter to a nonzero value the routine signals it successfully processed the request and the Names, Values and RowCount parameters contain valid data.

• RowCount contain number of elements in the Names and Values arrays
• Names describes individual values,
• values store individual values extracted from the request data.

If no description is available for the parsed data values, the Names array address can be set to NULL. The IRPMon application handles this case correctly.

The IRPMon application displays the parsed data in the following manner:

Names[0] : Values[0] Names[1] : values[1] . . . Names[RowCount - 1] : Values[RowCount - 1]

Each name-value pair is displayed on a single line.

If the parser does not handle given request, it must set the Handled parameter to zero (FALSE). The IRPMon application then ignores values of the last three parameters and does not call the free routine. Similar behavior is applied if the parse routine returns a nonzero value. In that case, howerver, the application may display an error message.

The free routine is invoked for every successful call to the parse routine and the application passes values of the last three parameters (modified by the parse routine) as its arguments. Hence, the parser has a chance to free memory allocated to hold the parsed data information.

Dynamic link libraries for data parsers need to be stored in the same directory as IRPMon´s executable. During its initialization, the application loads every DLL that exports the DataParserInit symbol and treats it as a data parser.