3.1.4.2.5 RpcSetPrinter (Opnum 7)

  • Article

RpcSetPrinter sets the data or state of a specified printer by pausing or resuming printing or by clearing all print jobs.

 DWORD RpcSetPrinter(
   [in] PRINTER_HANDLE hPrinter,
   [in] PRINTER_CONTAINER* pPrinterContainer,
   [in] DEVMODE_CONTAINER* pDevModeContainer,
   [in] SECURITY_CONTAINER* pSecurityContainer,
   [in] DWORD Command
 );

hPrinter: A handle to a printer 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).

pPrinterContainer: A parameter specified in PRINTER_CONTAINER Parameters (section 3.1.4.1.8.6). If the Command is 0, the Level member of the PRINTER_CONTAINER MUST be 0x00000000 or a number from 0x00000002 to 0x00000007. If the Command parameter is 1, 2, or 3, the Level member of the PRINTER_CONTAINER MUST be 0x00000000.

pDevModeContainer: A parameter specified in DEVMODE_CONTAINER Parameters (section 3.1.4.1.8.1).

pSecurityContainer: A parameter specified in SECURITY_CONTAINER Parameters (section 3.1.4.1.8.7).

Command: A value that specifies an action to perform. If this value is non-zero, it is one of the printer control values in the following table, and the Level member of the PRINTER_CONTAINER (section 2.2.1.2.9) structure that is pointed to by the pPrinterContainer parameter MUST be 0x00000000.

Name/value

Description

PRINTER_CONTROL_PAUSE

0x00000001

Pauses the printer object.

PRINTER_CONTROL_RESUME

0x00000002

Resumes a paused printer object.

PRINTER_CONTROL_PURGE

0x00000003

Deletes all print jobs queued for the printer object.

If this value is zero, the PrinterInfo member of the PRINTER_CONTAINER structure that is pointed to by the pPrinterContainer parameter MUST contain a pointer to a PRINTER_INFO (section 2.2.2.9) structure that this method can use. See section 2.2.1.10.1 for details.

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 specified in PRINTER_HANDLE Parameters (section 3.1.4.1.11).

  • Perform the validation steps specified in PRINTER_CONTAINER Parameters.

  • Verify that the information provided in the PRINTER_CONTAINER that is pointed to by the pPrinterContainer parameter is consistent with the value in Command, according to the following table:

    Command

    Level in PRINTER_CONTAINER

    0x00000000

    0x00000000 or a number from 0x00000002 to 0x00000007, inclusive.

    0x00000001

    0x00000000.

    0x00000002

    0x00000000.

    0x00000003

    0x00000000.

    If this verification fails, return ERROR_INVALID_LEVEL.

  • Perform the validation steps specified in DEVMODE_CONTAINER Parameters (section 3.1.4.1.8.1).

  • Perform the validation steps specified in SECURITY_CONTAINER Parameters (section 3.1.4.1.8.7).

  • If the Level member of the PRINTER_CONTAINER is 0x00000007 and the dwAction field in the PRINTER_INFO_7 structure that is pointed to by the pPrinterInfo7 member of the PRINTER_CONTAINER pointed to by pPrinterContainer is DSPRINT_UPDATE (0x00000002):

    • Verify that hPrinter specifies a printer object that is already published in the directory service. If hPrinter represents a printer that is not already published in the directory service, the server MUST fail the call by returning an HRESULT ([MS-ERREF] section 2.1) code of 0x80070002 with the same meaning as the ERROR_FILE_NOT_FOUND error specified in [MS-ERREF].

  • Additional validation SHOULD<261> be performed.

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:

  • If hPrinter specifies a server object, the server MUST only apply the SECURITY_CONTAINER parameter to set the print server's security descriptor, and MUST not perform the remaining processing steps that follow.

  • Perform PRINTER_CONTAINER parameter processing steps that are specified in PRINTER_CONTAINER Parameters.

  • Perform the operation from the following table that corresponds to the value of the Command parameter.

    Name/value

    Operation that is performed

    No command

    0x0000000

    Update the printer configuration using the settings in pPrinterContainer.<262>

    Pause the printer

    0x00000001

    Temporarily suspend sending data to the printer without changing the state of any jobs associated with the printer. Clients are allowed to continue adding data to the job.

    Resume the printer

    0x00000002

    Resume sending data to the printer without changing the state of any jobs associated with the printer.

    Purge the printer

    0x00000003

    Remove all jobs that are currently associated with the printer and mark them as having failed to print.

  • If hPrinter specifies a printer object that the print server has published in the Active Directory, and as a result of this call the print server has changed the printer driver associated with the printer or changed printer configuration information that the print server has published in the Active Directory, update the print queue object in the directory as specified in section 2.3.3.2 with attributes obtained from the print queue configuration and the printer driver as specified in section 2.3.3.1.<263> If the directory service operation fails, the print server MUST continue processing the current call and MUST NOT return the status of the directory service operation to the client.

  • If any clients registered for notifications of the printer object change, a notification MUST be broadcast to them.

  • Return the status of the operation.