3.1.4.1.9 INFO Structures Query Parameters

  • Article

Unless noted otherwise, methods that return one or more of the INFO structures (sections 2.2.1.3 to 2.2.1.11) use a common API pattern, in which the caller passes in the following parameters:

  • Level: The desired information level of the INFO structures, if this parameter is present in the method signature.

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

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

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

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

  • pcReturned: This parameter is a pointer to a variable into which the server copies the number of INFO structures written to the buffer, if the buffer was large enough to hold them.

The individual method sections use the following documentation conventions:

  • BUFFER TYPE: The type of INFO structures returned, which is one of the following:

    • _DATATYPES_INFO_1

    • _DRIVER_INFO

    • _FORM_INFO

    • _JOB_INFO

    • _MONITOR_INFO

    • _PORT_INFO

    • _PRINTER_INFO

    • _PRINTPROCESSOR_INFO_1

  • Level: The valid levels of INFO structures.

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

  • The server MUST verify that Level is valid, and if that verification fails, the server MUST return ERROR_INVALID_LEVEL.

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

  • If the value of cbBuf is zero, the server MUST ignore the pointer to the buffer that was passed in. If the value of cbBuf is not zero, the server MUST verify that the pointer to the buffer that was passed in is a pointer, and 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 INFO structures of a type specified by TYPE that describe the objects enumerated according to method-specific enumeration steps.

  • For methods capable of returning more than one INFO structure, the server MUST store the number of INFO structures that it writes to BUFFER in 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.