3.1.4.2.18 RpcSetPrinterDataEx (Opnum 77)

  • Article

RpcSetPrinterDataEx sets the configuration data for a printer or print server.<298> This method is similar to RpcSetPrinterData (section 3.1.4.2.8) but additionally allows the caller to specify the registry key under which to store the data.

 DWORD RpcSetPrinterDataEx(
   [in] PRINTER_HANDLE hPrinter,
   [in, string] const wchar_t* pKeyName,
   [in, string] const wchar_t* pValueName,
   [in] DWORD Type,
   [in, size_is(cbData)] BYTE* pData,
   [in] DWORD cbData
 );

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 set. 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, and the server MUST ignore this parameter.

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

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

For printer objects, a value name is an arbitrary string defined by the printer driver associated with the printer object. The value name "ChangeID" is reserved by the protocol and MUST NOT be used in a call to RpcSetPrinterDataEx.<299>

Type: A code that indicates the type of data that is pointed to by the pData parameter. The value SHOULD be one of the possible type codes defined by type values in section 2.2.3.9. For rules governing registry type values, see section 2.2.4.15.

pData: A pointer to an array of bytes that contain the printer configuration data. The type of the data in the buffer is specified by the Type parameter.

cbData: The size, in bytes, of the pData array. This value SHOULD NOT be zero.

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 the hPrinter parameter 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) with the "read-write" column selected. If this verification fails, return ERROR_INVALID_PARAMETER.

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

  • Additional validation SHOULD<300> be performed.

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, store the data that is provided by pData with the type that is supplied by Type in the printer data value that is identified by pKeyName and pValueName.

  • If hPrinter is a handle to a server object, store the data that is provided by pData with the type that is supplied by Type in the server data value that is identified by the pValueName parameter.

  • Return the status of the operation.