3.1.4.2.21 RpcEnumPrinterKey (Opnum 80)

  • Article

RpcEnumPrinterKey enumerates the subkeys of a specified key for a specified printer.<292>

 DWORD RpcEnumPrinterKey(
   [in] PRINTER_HANDLE hPrinter,
   [in, string] const wchar_t* pKeyName,
   [out, size_is(cbSubkey/sizeof(wchar_t))] 
     wchar_t* pSubkey,
   [in] DWORD cbSubkey,
   [out] DWORD* pcbSubkey
 );

hPrinter: A handle to a printer 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 containing the subkeys to enumerate. 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.

pSubkey: A pointer to BUFFER as specified in String Query Parameters (section 3.1.4.1.7).

This parameter can be NULL if cbSubkey equals zero.

cbSubkey: A value that is synonymous with the cbBuf parameter specified in String Query Parameters.

pcbSubkey: A value that is synonymous with the pcbNeeded parameter specified in String 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 MUST validate parameters as follows:

  • Perform the validation steps specified in PRINTER_HANDLE Parameters (section 3.1.4.1.11). This method SHOULD assume that the handle to the printer object can be used without further access checks.

  • Perform the validation steps specified in String Query Parameters, substituting ERROR_MORE_DATA [MS-ERREF] for ERROR_INSUFFICIENT_BUFFER.

  • Verify that the key specified in the string that is pointed to by the pKeyName parameter exists on the server. If it does not exist, the server MUST return ERROR_FILE_NOT_FOUND [MS-ERREF].

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:

  • Enumerate the key names that have the key specified in the string that is pointed to by the pKeyName parameter as an immediate parent. This method returns zero or more key names by storing them as multisz values in the BUFFER pointed to by pSubkey.

  • Using the enumerated objects, perform the processing and response steps that are specified in String Query Parameters.

  • Return the status of the operation.