Share via

3.1.4.1.7 String Query Parameters

  • Article

Unless noted otherwise, methods that return one or more string values use a common API pattern, in which the caller passes in the following parameters:

  • Level: The value 0x00000001, if this parameter is present in the method signature.

  • BUFFER: A buffer into which the server copies the requested string values. The term BUFFER is used here as a placeholder. Each method section defines which of its parameters is the pointer to the buffer. Methods capable of returning more than one string value MUST write the values to the buffer as a multisz.

  • cbBuf: The size, in bytes, of the buffer. This value can be larger than the required size for the requested string values.

  • pcbNeeded: A pointer to a variable into which the server copies the number of bytes between the start of the buffer and the last byte written by the server into the buffer, both inclusive, or the required size of the buffer, in bytes, if the value of the cbBuf parameter is smaller than the actual size of the data to return to the caller.

For methods that are capable of returning more than one string value, the following parameter interpretation applies:

  • If a pcReturned parameter is present in the method signature, it is a pointer to a variable into which the server copies the actual number of string values that are written to BUFFER, if the buffer is large enough to hold them.

  • If a pcReturned parameter is not present in the method signature, the caller MUST interpret the data returned in BUFFER as a multisz.

The individual method sections include the following parameter validation steps by reference:

  • The server MUST verify that the value of cbBuf is not smaller than the number of bytes required to hold the string values to be written to the buffer. If that verification fails, the server MUST write the number of bytes required to the variable pointed to by the pcbNeeded parameter and return ERROR_INSUFFICIENT_BUFFER.

  • If the value of the cbBuf parameter is not zero, the server MUST verify that a pointer to the buffer was passed in. If that verification fails, the server MUST return ERROR_INVALID_USER_BUFFER.

The individual method sections include the following processing and response steps by reference:

  • The server MUST populate BUFFER with string values enumerated according to method-specific enumeration steps. Multiple string values MUST be represented as a multisz.

  • For methods that are capable of returning more than one string value, if a pcReturned parameter is present in the method signature, the server MUST store the number of string values written to BUFFER into the variable pointed to by pcReturned.

  • The server MUST return zero for success, or a nonzero error code if the method was not successful.

Except for diagnostic purposes, the server state as visible to the client through this protocol MUST NOT change as a result of processing the method call.