3.1.4.12.4 RpcEnumJobNamedProperties (Opnum 113)

  • Article

RpcEnumJobNamedProperties enumerates the Job Named Properties (section 3.1.1) for the specified print job.<400>

 DWORD RpcEnumJobNamedProperties(
   [in] PRINTER_HANDLE hPrinter,
   [in] DWORD JobId,
   [out] DWORD* pcProperties,
   [out, size_is(,*pcProperties)] RPC_PrintNamedProperty** ppProperties
 );

hPrinter: A PRINTER_HANDLE (section 2.2.1.1.4) to a printer object, job 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).

JobId: The identifier of a print job. This value MUST NOT be zero.

pcProperties: On successful return from this call, this parameter is a pointer to the address of an array of RPC_PrintNamedProperty (section 2.2.1.14.2) structures returned. This pointer MUST NOT be NULL.

ppProperties: On successful return from this call, this parameter is a pointer to the address of an array of RPC_PrintNamedProperty structures returned. This pointer MUST NOT be NULL.

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 the following:

  • Perform the validation steps that are specified in PRINTER_HANDLE Parameters (section 3.1.4.1.11).

  • Verify that the value of the JobId parameter corresponds to a job in the list of jobs. If the object specified by the hPrinter parameter is a server object, search for a print job in each printer in the list of printers on the print server. If the object specified by the hPrinter parameter is a printer object, search for a print job only in the list of print jobs for the specified printer. If the object specified by the hPrinter parameter is a job object, compare the identifier of this print job with the specified JobId. If this verification fails, return ERROR_INVALID_PARAMETER.

  • Verify that the pcProperties and ppProperties pointers are not NULL. If this verification fails, return ERROR_INVALID_PARAMETER.

  • Verify that the buffer to contain the array of RPC_PrintNamedProperty structures can be successfully allocated. If this verification fails, return ERROR_NOT_ENOUGH_MEMORY.

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:

  • Allocate and initialize a buffer containing the array of RPC_PrintNamedProperty structures to be returned to the client via the ppProperties parameter.

  • Return the number of enumerated properties (the number of returned RPC_PrintNamedProperty structures) in the pcProperties parameter.

  • Return the status of the operation.

Upon a successful completion of this call the client SHOULD free the buffer specified by the ppProperties parameter.