3.1.4.3.1 RpcSetJob (Opnum 2)

  • Article

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 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 the print job. This value MUST NOT be zero.

pJobContainer: An optional pointer to a JOB_CONTAINER (section 2.2.1.2.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 2.2.4.6) that specifies an action. This value MUST be one of the following job control actions:

Name/value

Description

0x00000000

Perform no additional action.

JOB_CONTROL_PAUSE

0x00000001

Pause the print job.

JOB_CONTROL_RESUME

0x00000002

Resume a paused print job.

JOB_CONTROL_CANCEL

0x00000003

Delete a print job.<308>

JOB_CONTROL_RESTART

0x00000004

Restart a print job.

JOB_CONTROL_DELETE

0x00000005

Delete a print job.<309>

JOB_CONTROL_SENT_TO_PRINTER

0x00000006

Used by port monitors to signal that a print job has been sent to the printer. This value SHOULD NOT be used remotely.

JOB_CONTROL_LAST_PAGE_EJECTED

0x00000007

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.

JOB_CONTROL_RETAIN

0x00000008

Keep the print job in the print queue after it prints.

JOB_CONTROL_RELEASE

0x00000009

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 3.1.4.1.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 2.2.1.7);

    • If the Level value specified in JOB_CONTAINER is 0x00000003, the JobId member of the contained JOB_INFO_3 structure (section 2.2.1.7.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 2.2.1.3.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 3.1.4.1.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<310> 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.

    • Sent the print job to the printer (0x00000006): MAY be set by port monitors associated with a port to signal the job has been sent completely to the device, but it is not sent over the wire.

    • 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 2.2.1.7.1), JOB_INFO_2 (section 2.2.1.7.2), or JOB_INFO_4 (section 2.2.1.7.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.