22.214.171.124.1 RpcSetJob (Opnum 2)
RpcSetJob pauses, resumes, cancels, or restarts a print job. It also sets print job parameters, such as the job priority and the document name.
DWORD RpcSetJob( [in] PRINTER_HANDLE hPrinter, [in] DWORD JobId, [in, unique] JOB_CONTAINER* pJobContainer, [in] DWORD Command );
hPrinter: A PRINTER_HANDLE (section 126.96.36.199.4) to a printer object, job object, or server object that was opened by RpcAddPrinter (section 188.8.131.52.3), RpcAddPrinterEx (section 184.108.40.206.15), RpcOpenPrinter (section 220.127.116.11.2), or RpcOpenPrinterEx (section 18.104.22.168.14).
JobId: The identifier of the print job. This value MUST NOT be zero.
pJobContainer: An optional pointer to a JOB_CONTAINER (section 22.214.171.124.5) that specifies the parameters to set on the job object.
If the value of the Command parameter is zero, this pointer MUST be specified.
Command: A Job Control Value (section 126.96.36.199) that specifies an action. This value MUST be one of the following job control actions:
Perform no additional action.
Pause the print job.
Resume a paused print job.
Delete a print job.<305>
Restart a print job.
Delete a print job.<306>
Used by port monitors to signal that a print job has been sent to the printer. This value SHOULD NOT be used remotely.
Used by language monitors to signal that the last page of a print job has been ejected from the printer. This value SHOULD NOT be used remotely.
Keep the print job in the print queue after it prints.
Release the print job, undoing the effect of a JOB_CONTROL_RETAIN action.
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 for PRINTER_HANDLE parameters (section 188.8.131.52.11).
Verify that the value of the JobId parameter corresponds to a print job in the list of jobs. If this method is called with a job object handle, JobId MUST match the job identifier specified in the call to RpcOpenPrinter or RpcOpenPrinterEx.
If the pJobContainer parameter is specified, verify that it points to a valid JOB_CONTAINER as follows:
The Level member MUST be a value between 0x00000001 and 0x00000004, inclusive;
The JobInfo member MUST point to a JOB_INFO structure (section 184.108.40.206);
If the Level value specified in JOB_CONTAINER is 0x00000003, the JobId member of the contained JOB_INFO_3 structure (section 220.127.116.11.3) MUST match the JobId input parameter; otherwise, the JobId parameter MUST be ignored.
The members of the JOB_INFO structure MUST comply with the constraints specified for JOB_INFO members (section 18.104.22.168.3) with the exception of JobId for all levels except 0x00000003, PrinterName, ServerName, PrinterDriverName, Size, Submitted, Time, TotalPages, pDevMode, and pSecurityDescriptor, which MUST be ignored, and pMachineName, which SHOULD be ignored.
If the Level value specified in JOB_CONTAINER is 0x00000001, 0x00000002, or 0x00000004, perform the validation steps that are specified in Datatype Name Parameters (section 22.214.171.124.1) on the pDataType member of the JOB_INFO structure.
If the Level value specified in JOB_CONTAINER is 0x00000002 or 0x00000004, and the print processor specified in the pPrintProcessor member of the JOB_INFO structure does not already exist in the system, the server SHOULD return ERROR_UNKNOWN_PRINTPROCESSOR to the client.
Verify that the Command parameter is a supported command.
Additional validation SHOULD<307> be performed.
If parameter validation fails, the server MUST fail the operation immediately and return to the client ERROR_INVALID_PARAMETER or another nonzero error specified in the preceding JOB_CONTAINER validation steps; otherwise, the server MUST process the message and respond to the client as follows:
Modify the job with a JobId that matches the JobId input parameter to reflect the required changes based on the value of Command:
(0x00000000): No additional action is performed.
Pausing the print job (0x00000001): Pause the current job specified by JobId and allow any succeeding job to print.
Resuming the print job (0x00000002): Resume the job specified by JobId.
Canceling the print job (0x00000003): Cancel the job specified by JobId.
Restarting the print job (0x00000004): Reinitialize the internal state of the job specified by JobId and re-schedule the job for printing.
Deleting the print job (0x00000005): Delete the job specified by JobId and any internal structures representing that job.
Last Page Ejected (0x00000007): MAY be set by language monitors associated with a port to signal that the physical printer ejected the last page of the job, but it is not sent over the wire.
Retain Job (0x00000008): Keep the print job in the print queue after printing is finished. It MAY then be restarted.
Release Job (0x00000009): Release a job previously retained. Remove the print job from the queue if it has finished printing and has not been restarted.
If any clients have registered for notification of a job object change, those clients SHOULD be sent notifications about the changes that the server performs.
Modify the print job with a JobId that matches the JobId input parameter by applying the information in the JOB_INFO structure that is contained in the JOB_CONTAINER specified by the pJobContainer parameter. The following modifications SHOULD be performed:
If the Level value specified in JOB_CONTAINER is 0x00000003, the contained JOB_INFO_3 structure specifies the order of print jobs in the job queue. The server SHOULD change the order of jobs so that the job with the identifier specified by the NextJobId member of JOB_INFO_3 follows immediately after the job with the identifier specified by the JobId member. In addition, the server SHOULD link the two jobs together, so they form an atomic entity and are scheduled such that no other job can intervene between them.
If the Level value specified in JOB_CONTAINER is 0x00000001, 0x00000002, or 0x00000004, the contained JOB_INFO_1 (section 126.96.36.199.1), JOB_INFO_2 (section 188.8.131.52.2), or JOB_INFO_4 (section 184.108.40.206.4) structure, respectively, specifies the new position of the print job in the job queue. The server SHOULD set the position of the job to the value specified by the Position member of the JOB_INFO structure, and the server SHOULD reorder the list of jobs to reflect the new positions.
Return the status of the operation.