3.1.4.2.19 RpcGetPrinterDataEx (Opnum 78)

  • Article

RpcGetPrinterDataEx retrieves configuration data for the specified printer or print server.<301> This method is similar to RpcGetPrinterData (section 3.1.4.2.7), but it also allows the caller to specify the registry key from which to retrieve the data.

 DWORD RpcGetPrinterDataEx(
   [in] PRINTER_HANDLE hPrinter,
   [in, string] const wchar_t* pKeyName,
   [in, string] const 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).

pKeyName: A pointer to a string that specifies the key under which the value is to be queried. A key name is an arbitrary string defined by the printer driver associated with the printer object. For rules governing key names, see section 2.2.4.7.

If hPrinter is a handle to a server object, the key name can be NULL.

pValueName: A pointer to a string that identifies the 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). If the value name is not one of the predefined strings, it is an arbitrary string defined by the printer driver associated with the printer object. See RpcGetPrinterData for further details on the interpretation of this value.

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).

  • If hPrinter is a handle to a printer object, the server MUST verify that the pKeyName parameter points to a string that complies with the rules for key names specified in section 2.2.4.7.

  • 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 perform the validation steps that are specified in section 3.1.4.1.2.

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

  • If hPrinter is a handle to 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 pcbNeeded parameter) does not exceed 0xFFFFFFFF bytes. If this verification fails, the server SHOULD return ERROR_NOT_ENOUGH_MEMORY.<302>

  • If hPrinter is a handle to a printer object with a printer driver version of 0x00000004, the server SHOULD verify that that the pValueName parameter points to a string value that is supported for the printer object. If this verification fails, the server SHOULD return ERROR_NOT_SUPPORTED.<303>

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:

  • If the hPrinter parameter is a handle to a printer object, with the data identified by pKeyName and pValueName, perform the processing and response steps that are specified in section 3.1.4.1.2.

  • If hPrinter is a handle to a server object, with the data that is identified by pValueName, perform the processing and response steps that are specified in section 3.1.4.1.2.

  • Return the status of the operation.