3.1.4.1.2 Dynamically Typed Query Parameters

  • Article

Unless notified otherwise, methods returning one or more dynamically-typed values use a common API pattern, in which the caller passes in the following parameters:

  • BUFFER: A buffer into which the server copies the requested dynamically-typed values. The term "BUFFER" is used here as a placeholder. Each method section defines which of its parameters is the pointer to the buffer.

  • pType: An optional pointer to a variable that receives a code that indicates the type of data that is stored in the specified value. For a list of possible type values, see section 2.2.3.9.

  • nSize or cbData: The size, in bytes, of the buffer. This value can be larger than the required size for the requested dynamically-typed values.

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

For methods capable of returning more than one dynamically-typed value, the caller also passes in:

  • pcReturned: A pointer to a variable into which the server copies the number of dynamically-typed values that were written to the buffer, if the buffer was large enough to hold them. If the buffer is not large enough to hold these dynamically typed values, the client SHOULD ignore the value that the server can return through pcReturned.

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

  • The server MUST verify that the value of the buffer size parameter is not smaller than the number of bytes required to hold the dynamically-typed values to be written to the buffer. If that verification fails, the server MUST write the number of bytes required into the variable that is pointed to by pcbNeeded and return ERROR_MORE_DATA.

  • If the value of the buffer size 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 dynamically-typed values enumerated according to method-specific enumeration steps.

  • If pType is not a NULL pointer, the server MUST write the type of the data returned in BUFFER to the variable pointed to by pType.

  • For methods capable of returning more than one dynamically-typed value, the server MUST store the number of values that were 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.