3.1.4.2.7 RpcGetPrinterData (Opnum 26)

  • Article

RpcGetPrinterData retrieves printer configuration data for a printer or print server.

 DWORD RpcGetPrinterData(
   [in] PRINTER_HANDLE hPrinter,
   [in, string] wchar_t* pValueName,
   [out] DWORD* pType,
   [out, size_is(nSize)] BYTE* pData,
   [in] DWORD nSize,
   [out] DWORD* pcbNeeded
 );

hPrinter: A handle to a printer object or server object that was opened by RpcAddPrinter (section 3.1.4.2.3), RpcAddPrinterEx (section 3.1.4.2.15), RpcOpenPrinter (section 3.1.4.2.2), or RpcOpenPrinterEx (section 3.1.4.2.14).

pValueName: A pointer to a string that identifies the configuration data to get. For rules governing value names, see section 2.2.4.18.

For print servers, the value name is one of the predefined strings listed in Server Handle Key Values (section 2.2.3.10).

For printer objects, the value name MAY be one of the predefined strings listed in Printer Data Values (section 2.2.3.11). Also, the value name "ChangeID"<266> is reserved by the protocol and has a special meaning. It identifies a read-only value that specifies that a change identifier is returned in the buffer pointed to by pData. This identifier is a DWORD that is set by the print server to a new, unique value each time printer information changes. The client SHOULD use the change identifier to decide if it has stale information about a printer object, in which case it SHOULD call this method or RpcGetPrinter (section 3.1.4.2.6) to update its view of the printer object. Only the fact that the pData buffer value changes is significant; the change identifier value itself is arbitrary. If the value name is not one of these predefined strings, it is an arbitrary string defined by the printer driver associated with the printer object or by client applications.

pType: A parameter specified in Dynamically Typed Query Parameters (section 3.1.4.1.2).

pData: A pointer to BUFFER as specified in Dynamically Typed Query Parameters.

This parameter can be NULL if nSize equals zero

nSize: A parameter specified in Dynamically Typed Query Parameters.

pcbNeeded: A parameter specified in Dynamically Typed Query Parameters.

Return Values: This method MUST return zero (ERROR_SUCCESS) to indicate successful completion or a nonzero Windows error code to indicate failure [MS-ERREF].

Upon receiving this message, the server validates parameters as follows:

  • The server MUST perform the validation steps that are specified in PRINTER_HANDLE Parameters (section 3.1.4.1.11).

  • The server MUST perform the validation steps that are specified in Dynamically Typed Query Parameters.

  • For server objects, the server MUST verify that the pValueName parameter points to a string that is one of the predefined value names listed in Server Handle Key Values (section 2.2.3.10). If this verification fails, return ERROR_INVALID_PARAMETER.

  • For printer objects, the server MUST verify that, if the pValueName parameter points to a string that is one of the predefined value names listed in Printer Data Values (section 2.2.3.11), the print server supports retrieving the value for this printer according to the rules in section 2.2.3.11. If this verification fails, return ERROR_NOT_SUPPORTED.

  • For printer objects, the server MAY verify that the pValueName parameter points to a string that complies with the rules specified in section 2.2.4.18.

  • The server MUST NOT perform access checks on the hPrinter object.

If parameter validation fails, the server MUST fail the operation immediately and return a nonzero error response to the client. Otherwise, the server MUST process the message and compose a response to the client as follows:

  • With the data identified by pValueName, perform the processing and response steps<267> specified in Dynamically Typed Query Parameters.

  • Return the status of the operation.