SetPrinter function

The SetPrinter function sets the data for a specified printer or sets the state of the specified printer by pausing printing, resuming printing, or clearing all print jobs.

Syntax

BOOL SetPrinter(
  _In_ HANDLE hPrinter,
  _In_ DWORD  Level,
  _In_ LPBYTE pPrinter,
  _In_ DWORD  Command
);

Parameters

hPrinter [in]

A handle to the printer. Use the OpenPrinter, OpenPrinter2, or AddPrinter function to retrieve a printer handle.

Level [in]

The type of data that the function stores into the buffer pointed to by pPrinter. If the Command parameter is not equal to zero, the Level parameter must be zero.

This value can be 0, 2, 3, 4, 5, 6, 7, 8, or 9.

pPrinter [in]

A pointer to a buffer containing data to set for the printer, or containing information for the command specified by the Command parameter. The type of data in the buffer is determined by the value of Level.

Level	Structure
0	If the Command parameter is PRINTER_CONTROL_SET_STATUS, pPrinter must contain a DWORD value that specifies the new printer status to set. For a list of the possible status values, see the Status member of the PRINTER_INFO_2 structure. Note that PRINTER_STATUS_PAUSED and PRINTER_STATUS_PENDING_DELETION are not valid status values to set. If Level is 0, but the Command parameter is not PRINTER_CONTROL_SET_STATUS, pPrinter must be NULL.
2	A PRINTER_INFO_2 structure containing detailed information about the printer.
3	A PRINTER_INFO_3 structure containing the printer's security information.
4	A PRINTER_INFO_4 structure containing minimal printer information, including the name of the printer, the name of the server, and whether the printer is remote or local.
5	A PRINTER_INFO_5 structure containing printer information such as printer attributes and time-out settings.
6	A PRINTER_INFO_6 structure specifying the status value of a printer.
7	A PRINTER_INFO_7 structure. The dwAction member of this structure indicates whether SetPrinter should publish, unpublish, re-publish, or update the printer's data in the directory service.
8	A PRINTER_INFO_8 structure specifying the global default printer settings.
9	A PRINTER_INFO_9 structure specifying the per-user default printer settings.

Command [in]

The action to perform.

If the Level parameter is nonzero, set the value of this parameter to zero. In this case, the printer retains its current state and the function reconfigures the printer data as specified by the Level and pPrinter parameters.

If the Level parameter is zero, set the value of this parameter to one of the following values.

Value	Meaning
PRINTER_CONTROL_PAUSE	Pause the printer.
PRINTER_CONTROL_PURGE	Delete all print jobs in the printer.
PRINTER_CONTROL_RESUME	Resume a paused printer.
PRINTER_CONTROL_SET_STATUS	Set the printer status. Set the pPrinter parameter to a pointer to a DWORD value that specifies the new printer status.

Return value

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

If Level is 7 and the publish action failed, SetPrinter returns ERROR_IO_PENDING and attempts to complete the action in the background. If Level is 7 and the update action failed, SetPrinter returns ERROR_FILE_NOT_FOUND.

Remarks

You cannot use SetPrinter to change the default printer.

To modify the current printer settings, call the GetPrinter function to retrieve the current settings into a PRINTER_INFO_2 structure, modify the members of that structure as necessary, and then call SetPrinter.

The SetPrinter function ignores the pServerName, AveragePPM, Status, and cJobs members of a PRINTER_INFO_2 structure.

Pausing a printer suspends scheduling of all print jobs for that printer, except for the one print job that may be currently printing. Print jobs can be submitted to a paused printer, but no jobs will be scheduled to print on that printer until printing is resumed. If a printer is cleared, all print jobs for that printer are deleted, except for the current print job.

If you use SetPrinter to modify the default DEVMODE structure for a printer (globally setting the printer defaults), you must first call the DocumentProperties function to validate the DEVMODE structure.

For the PRINTER_INFO_2 and PRINTER_INFO_3 structures that contain a pointer to a security descriptor, the function can set only those components of the security descriptor that the caller has permission to modify. To set particular security descriptor components, you must specify the necessary access rights when you call the OpenPrinter or OpenPrinter2 function to retrieve a handle to the printer. The following table shows the access rights required to modify the various security descriptor components.

If the security descriptor contains a component that the caller does not have the access right to modify, SetPrinter fails. Those components of a security descriptor that you don't want to modify should be NULL or not be present, as appropriate. If you do not want to modify the security descriptor, and are calling SetPrinter with a PRINTER_INFO_2 structure, set the pSecurityDescriptor member of that structure to NULL.

The Internet Connection Firewall (ICF) blocks printer ports by default, but an exception for File and Print Sharing can be enabled. If SetPrinter is called by a machine admin, it enables the exception. If it is called by a non-admin and the exception has not already been enabled, the call fails.

You can use level 7 with the PRINTER_INFO_7 structure to publish, unpublish, or update directory service data for the printer. The directory service data for a printer includes all the data stored under the SPLDS_* keys by calls to the SetPrinterDataEx function for the printer. Before calling SetPrinter, set the pszObjectGUID member of PRINTER_INFO_7 to NULL and set the dwAction member to one of the following values.

DSPRINT_PENDING is not a valid dwAction value for SetPrinter.

Requirements

See also

Printing

Print Spooler API Functions

AddPrinter

GetPrinter

OpenPrinter

OpenPrinter2

PRINTER_INFO_2

PRINTER_INFO_3

PRINTER_INFO_4

PRINTER_INFO_5

PRINTER_INFO_6

PRINTER_INFO_7

PRINTER_INFO_8

PRINTER_INFO_9

SetPrinterDataEx