Introduction to Virtual Device Drivers

Message Usage Macros

The following is a list of macros for using messages.

^{GET_MESSAGE_PTR}

GET_MESSAGE_PTR MsgIdentifier, Reg

Returns the address of the given message. The macro carries out no other processing.

 Return the message address in the given register.

MsgIdentifier

Message identifier of the message to retrieve.

Reg

Name of register that receives the message address.

A register name can also be given for the MsgIdentifier parameter. If a register name is given, the register value is checked at runtime to determine which table to look in for the message. Because this requires additional code to support, this register-based version of the macro should be avoided.

The overhead of the register-based version can be avoided by an alternate form of the GET_MESSAGE_PTR macro:

Get_Message_Ptr MsgIdentifier, Reg1, Reg2
This alternative form places into Reg1 a pointer to the message string whose identifier is MsgIdentifier + Reg2. No range checking is performed; the value MsgIdentifier + Reg2 must be of the same message type as MsgIdentifier. For example, if you have a series of three messages, declared contiguously:

VxD_MESSAGE_SEG

DECLARE_MESSAGE MsgFirst, <"First message">

DECLARE_MESSAGE MsgSecond, <"Second Message">

DECLARE_MESSAGE MsgThird, <"Third message">

VxD_MESSAGE_ENDS

then the line:

GET_MESSAGE_PTR MsgFirst, eax, esi

would load into the EAX register a pointer to MsgFirst, if ESI = 0, a pointer to MsgSecond if ESI = 1, and a pointer to MsgThird if ESI = 2. Any other value for ESI is an error and will load garbage or possibly even page fault.

^{LOCALIZED_SPRINTF}

LOCALIZED_SPRINTF pOutBuf, MsgIdentifier, Param1, Param2, ..., ParamX

Acts the same way as PUSH_SPRINTF___PUSH_SPRINTF'>PUSH_SPRINTF except that the generated string is placed in the buffer specified by pOutBuf instead of being pushed onto the stack. Uses EAX.

 No return value.

pOutBuf

Location of output buffer.

MsgIdentifier

Message identifier of the message to process.

Parm1, Parm2, through ParmX

Parameter values.

Currently, there is no way to determine the necessary output buffer size; you just have to hope that the generated message fits. This may be remedied in a future version of Windows.

^POP_SPRINTF

POP_SPRINTF

Pops a string off the stack. The string must have been previously pushed on the stack by the PUSH_SPRINTF macro. The address of the string is not longer valid and must not be used.

 No return value.

See also PUSH_SPRINTF

^PUSH_SPRINTF

PUSH_SPRINTF MsgIdentifier, Param1, Param2, ..., ParamX

Processes the given message and parameters to create a new string. Parameter placeholders in the original message are replaced in the new string with the corresponding parameter values. This macro places the new string on the stack.

 Returns the address of the new string in the EAX register.

MsgIdentifier

Message identifier of the message to process.

Parm1, Parm2, through ParmX

Parameter values. The number of parameters depends on the highest parameter number given in the parameter placeholders in the original message. For more information, see comments below.

A parameter placeholder consists of a percent sign (%), a parameter number, and a format character.

A parameter number can be any integer value in the range 0 to 9. This number identifies which parameter passed to the PUSH_SPRINTF macro replaces the given placeholder. This means the order in which parameter values are inserted is not determined order in which they are passed to the macro. Instead, the parameter number in the parameter placeholders determine where a given parameter is inserted and how often it is inserted.

The format character specifies the format of the parameter to be displayed. It can be one of these letters:

s	Null terminated string.
u	16-bit unsigned decimal integer in the range 0 to 999.
x	16-bit unsigned hexadecimal integer.

The parameter type must match the formatting specified by the corresponding parameter placeholder.

^{PUSHED_SPRINTF_LENGTH}

PUSHED_SPRINTF_LENGTH Reg

Returns the length, in bytes, of the string most recently pushed on the stack. This macro is not valid if any other item has been pushed on the stack since the most recent string. This macro is not valid and must not be used if the string has already been popped off the stack.

 Returns the string length in the given register. The length does not include the terminating null character.

Reg

Name of register that receives the string length.