The SetPrinter function sets the state of the specified printer by pausing printing, resuming printing, or clearing all print jobs. The function can also be used to set printer data.
BOOL SetPrinter(
|
HANDLE hPrinter, |
// handle of printer object |
|
DWORD Level, |
// structure level |
|
LPBYTE pPrinter, |
// address of array containing printer data |
|
DWORD Command |
// printer-state command |
|
); |
Windows NT: Specifies the type of data contained in pPrinter. This
parameter must be 0, 2, 3, 5, or 6. This parameter must be zero if Command
is not equal to zero.
If Level is 0, and 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.
Windows 95: If Level is 2, 3, 4, or 5, pPrinter points to an array that contains PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_4, or PRINTER_INFO_5 structures, respectively.
Windows NT: If Level is 2, 3, 5, or 6, pPrinter points to
an array that contains PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_5, or
PRINTER_INFO_6 structures, respectively.
|
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. |
If Command is any of the above values, Level must be zero.
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.
You can obtain the handle hPrinter is by calling the OpenPrinter function.
To modify the current printer settings, an application should call GetPrinter to retrieve the current settings into a PRINTER_INFO_2 structure, modify the members of that structure as necessary, and then call the SetPrinter function.
The SetPrinter function ignores the following members of a PRINTER_INFO_2 structure:
pServerName, AveragePPM, Status, and cJobs
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 the printer data structure contains a pointer to a security descriptor, only those components of the security descriptor that the caller has permission to write should be present. An application that wants to write particular security descriptor components must open the printer with sufficient access permission to modify those components. The following table shows the security descriptor components that can be modified for particular access permission values:
|
Access Permission |
Modifiable Security Descriptor Components |
|
WRITE_OWNER |
Owner, primary proup |
|
WRITE_DAC |
Discretionary access-control list (ACL) |
|
ACCESS_SYSTEM_SECURITY |
System ACL |
If the calling application lacks a required permission, SetPrinter fails. Those components of a security descriptor that an application does not wish 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 95: SetPrinter does not update the pShareName member in the PRINTER_INFO_2 structure.
Windows 95: SetPrinter is not supported when called against a Windows NT printer from a Windows 95 machine using the printer's UNC name.
AddPrinter, GetPrinter, OpenPrinter, PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_4, PRINTER_INFO_5, PRINTER_INFO_6