3.1.4.14.2 RpcIppCreateJobOnPrinter (Opnum 119)

  • Article

RpcIppCreateJobOnPrinter calls the IPP printer handler to issue create-job message if the printer supports it or, otherwise, cache the attributes. <404> See [RFC8011], section 4.2.4.

 HRESULT
 RpcIppCreateJobOnPrinter(
   [in] PRINTER_HANDLE hPrinter,
   [in] DWORD jobId,
   [in, string, unique] const wchar_t* pdlFormat,
   [in] DWORD jobAttributeGroupBufferSize,
   [in, size_is(jobAttributeGroupBufferSize)] BYTE* jobAttributeGroupBuffer,
   [out, ref] DWORD* ippResponseBufferSize,
   [out, size_is(, *ippResponseBufferSize), ref] BYTE** ippResponseBuffer
 );

hPrinter: A PRINTER_HANDLE (section 2.2.1.1.4) 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).

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

pdlFormat: Pointer to a null-terminated string of 16-bit Unicode characters representing the format of the PDL. Supported PDL formats depend on the printer. For the list of possible values for this parameter, see [RFC8011], section 5.1.10.

jobAttributeGroupBufferSize: The size, in bytes, of the buffer pointed to by the jobAttributeGroupBuffer.

jobAttributeGroupBuffer: A pointer to a buffer containing a serialized IPP attribute group (see [RFC8010], section 4.2.1).

ippResponseBufferSize: A pointer to a variable that receives the number of bytes in the buffer pointed to by the ippResponseBuffer parameter on a successful return from this call.

ippResponseBuffer: On a successful return from this call, this parameter is a pointer to the buffer containing the serialized IPP response from the printer (see [RFC8010], section 3.1.1) or the response generated by the server in case the job is not yet active, and the attributes have been cached.

Return Values: This method MUST return zero or an HRESULT success value (see [MS-ERREF], section 2.1) to indicate successful completion, or an HRESULT error value to indicate failure.

On 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 ippResponseBuffer and ippResponseBufferSize parameters are not null.

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

  • Allocate and initialize a buffer with a serialized IPP response to be returned to the client via the ippResponseBuffer parameter.

  • Update the value pointed to by ippResponseBufferSize with the number of bytes allocated for the buffer pointed to by the ippResponseBuffer parameter.

  • Return the status of the operation.

On successful completion of this call, the client SHOULD free the buffer specified by the ippResponseBuffer parameter.