3.1.4.1.10 PRINTER_ENUM_VALUES Structures Query Parameters

  • Article

Unless noted otherwise, methods returning one or more PRINTER_ENUM_VALUES structures (section 2.2.2.11) use a common API pattern, in which the caller passes in the following parameters:

  • BUFFER: A buffer into which the server copies the requested PRINTER_ENUM_VALUES structures. The term "BUFFER" is used here as a placeholder; each method section defines which of its parameters contains a pointer to the buffer.

  • cbEnumValues: The size, in bytes, of BUFFER. The value of cbEnumValues can be larger than the required size for the requested PRINTER_ENUM_VALUES structures.

  • pcbEnumValues: 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 cbEnumValues is smaller than the size of the data to return to the caller.

For methods capable of returning more than one PRINTER_ENUM_VALUES structure, the caller also passes in:

  • pnEnumValues: A pointer to a variable into which the server copies the number of PRINTER_ENUM_VALUES structures written to the buffer if it is large enough to hold them.

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

  • The server MUST verify that the value of cbEnumValues is not smaller than the number of bytes required by the PRINTER_ENUM_VALUES structures to be written to the buffer. If that verification fails, the server MUST write the number of bytes required to the variable that is pointed to by pcbEnumValues and return ERROR_MORE_DATA.

  • If the value of cbEnumValues 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.

  • For a printer object with a printer driver version (cVersion in section 2.2.1.3.1) of 0x00000004, the server SHOULD verify that the size in bytes of the data to be returned to the client (the value to be returned via the pcbEnumValues parameter) does not exceed 0xFFFFFFFF bytes. If this verification fails, the server SHOULD<263> return ERROR_NOT_ENOUGH_MEMORY.

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

  • The server MUST populate BUFFER with PRINTER_ENUM_VALUES structures that describe the enumerated objects according to method-specific enumeration steps.

  • For methods capable of returning more than one PRINTER_ENUM_VALUES structure, the server MUST write the number of PRINTER_ENUM_VALUES structures that were written to BUFFER into the variable pointed to by the pnEnumValues parameter.

  • 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 because of processing the method call.