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.
BOOL SetPrinter(
HANDLE hPrinter, // handle to printer object
DWORD Level, // structure level
LPBYTE pPrinter, // pointer to array containing printer data
DWORD Command // printer-state command
);
Windows 95: This value can be 0, 1, 2, or 5.
Windows NT: This value can be 0, 1, 2, 3, 4, 5, or 7.
| 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. |
| 1 | A PRINTER_INFO_1 structure containing general printer information. |
| 2 | A PRINTER_INFO_2 structure containing detailed information about the printer. |
| 3 | Windows NT: A PRINTER_INFO_3 structure containing the printer's security information. |
| 4 | Windows NT: 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. |
| 7 | Windows NT 5.0 and later: A PRINTER_INFO_7 structure. The dwAction member of this structure indicates whether SetPrinter should publish, unpublish, or update the printer's data in the directory service. |
If the Level parameter is nonzero, Command must be 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, Command can be one of the following values to set the state of the printer.
| Value | Meaning |
|---|---|
| PRINTER_CONTROL_PAUSE | Pauses the printer. |
| PRINTER_CONTROL_PURGE | Deletes all print jobs in the printer. |
| PRINTER_CONTROL_RESUME | Resumes a paused printer. |
| PRINTER_CONTROL_SET_STATUS | Sets the printer status. The pPrinter parameter points to a DWORD that specifies the new printer status. |
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
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.
Windows NT: 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 function to retrieve a handle to the printer. The following table shows the access rights required to modify the various security descriptor components.
| Access right | Security Descriptor Component |
|---|---|
| WRITE_OWNER | Owner Primary proup |
| 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.
Windows NT 5.0 and later: 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 | Publish the directory service data. |
| DSPRINT_UNPUBLISH | Unpublish the directory service data. |
| DSPRINT_UPDATE | Update 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. |
Windows 95: SetPrinter does not update the pShareName member in the PRINTER_INFO_2 structure.
You cannot call SetPrinter from a Windows 95 computer to set the data for a Windows NT printer using the printer's UNC name.
Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in winspool.h.
Import Library: Use winspool.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.
Printing and Print Spooler Overview, Printing and Print Spooler Functions, AddPrinter, GetPrinter, OpenPrinter, PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_4, PRINTER_INFO_5, PRINTER_INFO_7, SetPrinterDataEx