4.4 Enumerating Jobs and Modifying Job Settings

To enumerate print jobs on a server ("CORPSERV"), modify job settings, or change job priorities, the client ("TESTCLT") performs the following steps.

1. Open the printer using RpcOpenPrinter.

   • The client allocates and initializes a devmodeContainer structure (section 2.2.1.2.1).

   • The client calls RpcOpenPrinter.

      RpcOpenPrinter( L"\\\\CORPSERV\\My Printer", &hPrinter, L"RAW", &devmodeContainer, PRINTER_ACCESS_USE );
     

   • The server allocates a printer handle, writes it to hPrinter, and returns 0 (success).

2. Enumerate jobs scheduled for printing on the printer using RpcEnumJobs.

   • The client calls RpcEnumJobs with FirstJob set to 0 and NoJobs set to the maximum unsigned integer to return all jobs.

      RpcEnumJobs( hPrinter, 0, 0xFFFFFFFF, 1, NULL, 0, &countBytesNeeded, &jobsFound );
     

   • The server returns ERROR_INSUFFICIENT_BUFFER and sets countBytesNeeded to store _JOB_INFO_1 structures for all shared print queues.

   • The client allocates memory in jobInfo1[] with size set to countBytesNeeded.

   • The client calls RpcEnumJobs.

      RpcEnumJobs( hPrinter, 0, 0xFFFFFFFF, 1, jobInfo1, countBytesNeeded, &countBytesNeeded, &jobsFound );
     

   • The server writes _JOB_INFO_1 for all jobs on the print queue to the output buffer, writes the number of _JOB_INFO_1 structures to jobsFound, and returns 0 (success).

     Note: If the number of jobs on the print queue on the server has increased between the first and second call to RpcEnumJobs, the server returns ERROR_INSUFFICIENT_BUFFER from the second call as well. In that case, the server updates countBytesNeeded, and the client allocates more memory and repeats the call to RpcEnumJobs.

3. Modify job settings or job priority using RpcSetJob.

   • The client picks a job from the list of _JOB_INFO_1 structures that it requests to modify. For this example, we assume the JobId is 12 and we want to cancel the job.

   • The client allocates and zero-initializes a jobContainer structure (section 2.2.1.2.5).

   • To modify job settings, the client calls RpcSetJob with the Command parameter set to zero.

      RpcSetJob( hPrinter, 12, &jobContainer, 0 ); 
       
     

   • To control the processing of a job, such as to cancel it, the client calls RpcSetJob with a non-zero Command parameter.

      RpcSetJob( hPrinter, 12, &jobContainer, JOB_CONTROL_CANCEL );
     

   • The server modifies the specified print job and returns 0 (success).

4. The client closes the printer using RpcClosePrinter.

    RpcClosePrinter( &hPrinter );
   

   The server frees the memory associated with the print queue handle, sets hPrinter to NULL, and returns 0 (success).

Figure 8: Enumerating jobs and modifying job settings