3.1.4.9.1 RpcStartDocPrinter (Opnum 17)

  • Article

RpcStartDocPrinter notifies the print server that a document is being spooled for printing.

 DWORD RpcStartDocPrinter(
   [in] PRINTER_HANDLE hPrinter,
   [in] DOC_INFO_CONTAINER* pDocInfoContainer,
   [out] DWORD* pJobId
 );

hPrinter: A handle to a printer object or port 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). The printer handle MUST NOT be in use for printing another document at the time of this call.

pDocInfoContainer: A parameter specified in DOC_INFO_CONTAINER Parameters (section 3.1.4.1.8.2).

pJobId: A pointer to a variable that receives a nonzero print job identifier. The job MUST be created with an identifier that is unique for this printer.

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). This method SHOULD assume that the handle to the printer or port object can be used without further access checks.

  • Perform the validation steps that are specified in DOC_INFO_CONTAINER Parameters.

  • The server MUST verify that RpcStartDocPrinter does not get called twice for a given printer or port object without an intervening call to RpcEndDocPrinter (section 3.1.4.9.7). If that verification fails, return ERROR_INVALID_HANDLE.

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:

  • Create the job object and associate it with a job queue.

    • If hPrinter is a printer object handle, associate the job with the job queue of that printer object.

    • If hPrinter is a port object handle, select an arbitrary printer object associated with that port object and associate the job with the job queue of that printer object.

  • Associate a data type with the print job.

    • If the pDatatype member of the DOC_INFO_1 structure that is pointed to by the pDocInfo1 pointer in the DOC_INFO_CONTAINER and pointed to by pDocInfoContainer is non-NULL, then use the data type specified in pDatatype as the data type for the print job.

    • If the pDatatype member of the DOC_INFO_1 structure is NULL, hPrinter is a printer object handle, and the data type contained in the context for hPrinter is non-NULL, then use the data type specified by the context for hPrinter for the print job.

    • If the pDatatype member of the DOC_INFO_1 structure is NULL and the context for hPrinter does not contain a data type, then use the printer's default data type for the print job.

  • Write the ID of the created job in the variable that is pointed to by the pJobId parameter.

  • If any clients that have registered for notification of the job object creation, a notification MUST be broadcast to them.

  • Return the status of the operation.