126.96.36.199.5 RpcSetPrinter (Opnum 7)
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 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).
pPrinterContainer: A parameter specified in PRINTER_CONTAINER Parameters (section 22.214.171.124.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 126.96.36.199.8.1).
pSecurityContainer: A parameter specified in SECURITY_CONTAINER Parameters (section 188.8.131.52.8.7).
Command: A value that specifies an action to perform. If this value is non-zero, it MUST be one of the values in the following table, and the Level member of the PRINTER_CONTAINER (section 184.108.40.206.9) structure that is pointed to by the pPrinterContainer parameter MUST be 0x00000000.
Printer Control Name/Value
Pauses the printer object.
Resumes a paused printer object.
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 220.127.116.11) structure that this method can use. See section 18.104.22.168.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, as specified in [MS-ERREF].
Upon receiving this message, the server MUST validate parameters as follows:
Perform the validation steps specified in PRINTER_HANDLE Parameters (section 22.214.171.124.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:
Level in PRINTER_CONTAINER
MUST be 0x00000000 or a number from 0x00000002 to 0x00000007, inclusive.
MUST be 0x00000000.
MUST be 0x00000000.
MUST be 0x00000000.
If this verification fails, return ERROR_INVALID_LEVEL.
Perform the validation steps specified in DEVMODE_CONTAINER Parameters (section 126.96.36.199.8.1).
Perform the validation steps specified in SECURITY_CONTAINER Parameters (section 188.8.131.52.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 (see [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<322> 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.
Command parameter values
Operation that MUST be performed
Update the printer configuration using the settings in pPrinterContainer.<323>
Pause the printer
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
Resume sending data to the printer without changing the state of any jobs associated with the printer.
Purge the printer
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 described in section 184.108.40.206 with attributes obtained from the print queue configuration and the printer driver as described in section 220.127.116.11.<324> 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.