<div class="content" name="RpcSetJob" uuid="f978bd2c-e99a-43ff-ba08-02e892948dac"><p>RpcSetJob pauses, resumes, cancels, or restarts a <span><a href="831cd729-be7c-451e-b729-bd8d84ce4d24#gt_12a6e569-e97c-4761-92f0-e397f8d5125f" data-linktype="relative-path">print job</a></span>.
It also sets print job parameters, such as the job priority and the document
name.</p><dl>
<dd>
<div><pre> DWORD RpcSetJob(
   [in] PRINTER_HANDLE hPrinter,
   [in] DWORD JobId,
   [in, unique] JOB_CONTAINER* pJobContainer,
   [in] DWORD Command
 );
</pre></div>
</dd></dl><p><b>hPrinter: </b>A <span><a href="9c5d49b8-6920-47b0-9466-87ba910e6071" data-linktype="relative-path">PRINTER_HANDLE (section 2.2.1.1.4)</a></span>
to a printer object, job object, or server object that was opened by <span><a href="bd0bb8d5-26fd-4705-81f5-614d32b9f38f" data-linktype="relative-path">RpcAddPrinter (section 3.1.4.2.3)</a></span>,
<span><a href="3af45717-308f-4b4f-8428-430d12856110" data-linktype="relative-path">RpcAddPrinterEx (section 3.1.4.2.15)</a></span>,
<span><a href="989357e2-446e-4872-bb38-1dce21e1313f" data-linktype="relative-path">RpcOpenPrinter (section 3.1.4.2.2)</a></span>,
or <span><a href="0e81ce18-72b1-46c3-8584-a205393b04ff" data-linktype="relative-path">RpcOpenPrinterEx (section 3.1.4.2.14)</a></span>.</p><p><b>JobId: </b>The identifier of the print job. This
value MUST NOT be zero.</p><p><b>pJobContainer: </b>An optional pointer to a <span><a href="0cd5f47b-5421-4b19-9ed0-5a29d63f3c2a" data-linktype="relative-path">JOB_CONTAINER (section 2.2.1.2.5)</a></span>
that specifies the parameters to set on the job object.</p><dl>
<dd>
<p>If the value of the <i>Command</i> parameter is
zero, this pointer MUST be specified.</p>
</dd></dl><p><b>Command: </b>A <span><a href="c22b303e-b62c-4d36-8336-e9b42322f125" data-linktype="relative-path">Job Control
Value (section 2.2.4.6)</a></span> that specifies an action. This
value MUST be one of the following job control actions:</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Name/value</p>
   </th>
   <th>
   <p>Description</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0x00000000</td>
  <td>Perform no additional action.</td>
 </tr><tr>
  <td>JOB_CONTROL_PAUSE 0x00000001</td>
  <td>Pause the print job.</td>
 </tr><tr>
  <td>JOB_CONTROL_RESUME 0x00000002</td>
  <td>Resume a paused print job.</td>
 </tr><tr>
  <td>JOB_CONTROL_CANCEL 0x00000003</td>
  <td>Delete a print job.&lt;321&gt;</td>
 </tr><tr>
  <td>JOB_CONTROL_RESTART 0x00000004</td>
  <td>Restart a print job.</td>
 </tr><tr>
  <td>JOB_CONTROL_DELETE 0x00000005</td>
  <td>Delete a print job.&lt;322&gt;</td>
 </tr><tr>
  <td>JOB_CONTROL_SENT_TO_PRINTER 0x00000006</td>
  <td>Used by port monitors to signal that a print job has been sent to the printer. This value SHOULD NOT be used remotely.</td>
 </tr><tr>
  <td>JOB_CONTROL_LAST_PAGE_EJECTED 0x00000007</td>
  <td>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.</td>
 </tr><tr>
  <td>JOB_CONTROL_RETAIN 0x00000008</td>
  <td>Keep the print job in the print queue after it prints.</td>
 </tr><tr>
  <td>JOB_CONTROL_RELEASE 0x00000009</td>
  <td>Release the print job, undoing the effect of a JOB_CONTROL_RETAIN action.</td>
 </tr></tbody></table>
</dd></dl><p><b>Return Values: </b>This method MUST return zero
(ERROR_SUCCESS) to indicate successful completion or a nonzero Windows error
code to indicate failure <span><a href="../ms-erref/1bc92ddf-b79e-413c-bbaa-99a5281a6c90" data-linktype="relative-path">[MS-ERREF]</a></span>.</p><p>Upon receiving this message, the server MUST validate
parameters as follows:</p><ul><li><p><span><span> 
</span></span>Perform the validation steps for <span><a href="10bfa8c2-d456-4ad0-912d-e674766a36c8" data-linktype="relative-path">PRINTER_HANDLE
parameters (section 3.1.4.1.11)</a></span>.</p>
</li><li><p><span><span> 
</span></span>Verify that the value of the <i>JobId</i> parameter corresponds
to a print job in the list of jobs. If this method is called with a job object
handle, <i>JobId</i> MUST match the job identifier specified in the call to
RpcOpenPrinter or RpcOpenPrinterEx.</p>
</li><li><p><span><span> 
</span></span>If the <i>pJobContainer</i> parameter is specified, verify that
it points to a valid JOB_CONTAINER as follows:</p>
<ul><li><p><span><span>  </span></span>The
<b>Level</b> member MUST be a value between 0x00000001 and 0x00000004,
inclusive;</p>
</li><li><p><span><span>  </span></span>The
<b>JobInfo</b> member MUST point to a <span><a href="87ea3e77-22fb-4914-b803-ef3b2619195a" data-linktype="relative-path">JOB_INFO
structure (section 2.2.1.7)</a></span>;</p>
</li><li><p><span><span>  </span></span>If
the <b>Level</b> value specified in JOB_CONTAINER is 0x00000003, the <b>JobId</b>
member of the contained <span><a href="1385aef9-d323-4e8d-9d28-5f2f011bd39c" data-linktype="relative-path">JOB_INFO_3
structure (section 2.2.1.7.3)</a></span> MUST match the <i>JobId</i>
input parameter; otherwise, the <i>JobId</i> parameter MUST be ignored.</p>
</li><li><p><span><span>  </span></span>The
members of the JOB_INFO structure MUST comply with the constraints specified
for <span><a href="94d1857e-c444-49b1-8fb4-83eac6696060" data-linktype="relative-path">JOB_INFO
members (section 2.2.1.3.3)</a></span> with the exception of <b>JobId</b>
for all levels except 0x00000003, <b>PrinterName</b>, <b>ServerName</b>, <b>PrinterDriverName</b>,
<b>Size</b>, <b>Submitted</b>, <b>Time</b>, <b>TotalPages</b>, <b>pDevMode</b>,
and <b>pSecurityDescriptor</b>, which MUST be ignored, and <b>pMachineName</b>,
which SHOULD be ignored.</p>
</li><li><p><span><span>  </span></span>If
the <b>Level</b> value specified in JOB_CONTAINER is 0x00000001, 0x00000002, or
0x00000004, perform the validation steps that are specified in <span><a href="c31e2dab-a809-474c-9864-0cbb61068903" data-linktype="relative-path">Datatype
Name Parameters (section 3.1.4.1.1)</a></span> on the <i>pDataType</i>
member of the JOB_INFO structure.</p>
</li><li><p><span><span>  </span></span>If
the <b>Level</b> value specified in JOB_CONTAINER is 0x00000002 or 0x00000004,
and the print processor specified in the <i>pPrintProcessor</i> member of the
JOB_INFO structure does not already exist in the system, the server SHOULD
return ERROR_UNKNOWN_PRINTPROCESSOR to the client.</p>
</li></ul></li><li><p><span><span> 
</span></span>Verify that the <i>Command</i> parameter is a supported command.</p>
</li><li><p><span><span> 
</span></span>Additional validation SHOULD<a id="Appendix_A_Target_323"></a><a aria-label="Product behavior note 323" href="e81cbc09-ab05-4a32-ae4a-8ec57b436c43#Appendix_A_323" data-linktype="relative-path">&lt;323&gt;</a> be
performed.</p>
</li></ul><p>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:</p><ul><li><p><span><span> 
</span></span>Modify the job with a <b>JobId</b> that matches the <i>JobId</i>
input parameter to reflect the required changes based on the value of <i>Command</i>:</p>
<ul><li><p><span><span>  </span></span>(0x00000000):
No additional action is performed.</p>
</li><li><p><span><span>  </span></span>Pausing
the print job (0x00000001): Pause the current job specified by <i>JobId</i> and
allow any succeeding job to print.</p>
</li><li><p><span><span>  </span></span>Resuming
the print job (0x00000002): Resume the job specified by <i>JobId</i>.</p>
</li><li><p><span><span>  </span></span>Canceling
the print job (0x00000003): Cancel the job specified by <i>JobId</i>.</p>
</li><li><p><span><span>  </span></span>Restarting
the print job (0x00000004): Reinitialize the internal state of the job
specified by <i>JobId</i> and re-schedule the job for printing.</p>
</li><li><p><span><span>  </span></span>Deleting
the print job (0x00000005): Delete the job specified by <i>JobId</i> and any
internal structures representing that job.</p>
</li><li><p><span><span>  </span></span>Sent
the print job to the printer (0x00000006): MAY be set by port monitors
associated with a <span><a href="831cd729-be7c-451e-b729-bd8d84ce4d24#gt_ac027425-6043-4ad3-be27-56a381b75d38" data-linktype="relative-path">port</a></span> to signal the
job has been sent completely to the <span><a href="831cd729-be7c-451e-b729-bd8d84ce4d24#gt_4712ded2-d927-4930-9450-29499f98cef4" data-linktype="relative-path">device</a></span>, but it is
not sent over the wire.</p>
</li><li><p><span><span>  </span></span>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.</p>
</li><li><p><span><span>  </span></span>Retain
Job (0x00000008): Keep the print job in the print queue after printing is
finished. It MAY then be restarted.</p>
</li><li><p><span><span>  </span></span>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.</p>
</li></ul></li><li><p><span><span> 
</span></span>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.</p>
</li><li><p><span><span> 
</span></span>Modify the print job with a <b>JobId</b> that matches the <i>JobId</i>
input parameter by applying the information in the JOB_INFO structure that is
contained in the JOB_CONTAINER specified by the <i>pJobContainer</i> parameter.
The following modifications SHOULD be performed:</p>
<ul><li><p><span><span>  </span></span>If
the <b>Level</b> 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 <b>NextJobId</b> member of JOB_INFO_3 follows immediately
after the job with the identifier specified by the <b>JobId</b> 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.</p>
</li><li><p><span><span>  </span></span>If
the <b>Level</b> value specified in JOB_CONTAINER is 0x00000001, 0x00000002, or
0x00000004, the contained <span><a href="794c1ba9-ba0a-4498-ba9c-2635563460dd" data-linktype="relative-path">JOB_INFO_1 (section 2.2.1.7.1)</a></span>,
<span><a href="5a48c6c9-fc5f-42ff-a5a7-f111fee58d1a" data-linktype="relative-path">JOB_INFO_2 (section 2.2.1.7.2)</a></span>,
or <span><a href="99086f6e-3db1-4034-ac6c-cd4a5a77f22c" data-linktype="relative-path">JOB_INFO_4 (section 2.2.1.7.4)</a></span>
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 <b>Position</b> member of the JOB_INFO structure, and the server SHOULD
reorder the list of jobs to reflect the new positions.</p>
</li></ul></li><li><p><span><span> 
</span></span>Return the status of the operation.</p>
</li></ul></div>