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
Note
This is a blocking or synchronous function and might not return immediately. How quickly this function returns depends on run-time factors such as network status, print server configuration, and printer driver implementation factors that are difficult to predict when writing an application. Calling this function from a thread that manages interaction with the user interface could make the application appear to be unresponsive.
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.
| Access permission | Security descriptor component |
|---|---|
| WRITE_OWNER | Owner Primary group |
| WRITE_DAC | Discretionary access-control list (DACL) |
| ACCESS_SYSTEM_SECURITY | System access-control list (SACL) |
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.
| Value | Description |
|---|---|
| DSPRINT_PUBLISH |
Publishes the directory service data. |
| DSPRINT_REPUBLISH |
The directory service data for the printer is unpublished and then published again, refreshing all properties in the published printer. Re-publishing also changes the GUID of the published printer. Use this value if you suspect the printer's published data has been corrupted. |
| DSPRINT_UNPUBLISH |
Unpublishes the directory service data. |
| DSPRINT_UPDATE |
Updates the directory service data. This is the same as DSPRINT_PUBLISH, except that SetPrinter fails with ERROR_FILE_NOT_FOUND if the printer is not already published. Use DSPRINT_UPDATE to update published properties but not force publishing. Printer drivers should always use DSPRINT_UPDATE rather than DSPRINT_PUBLISH. |
DSPRINT_PENDING is not a valid dwAction value for SetPrinter.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client |
Windows 2000 Professional [desktop apps only] |
| Minimum supported server |
Windows 2000 Server [desktop apps only] |
| Header |
|
| Library |
|
| DLL |
|
| Unicode and ANSI names |
SetPrinterW (Unicode) and SetPrinterA (ANSI) |