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,      // information level
  LPBYTE pPrinter,  // printer data buffer
  DWORD Command     // printer-state command
);

Parameters

hPrinter

[in] Handle to the printer. Use the OpenPrinter, OpenPrinter2, or AddPrinter function to retrieve a printer handle.

Level

[in] Specifies 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.

Windows 95/98/Me: This value can be 0, 2, or 5.

Windows NT/2000/XP/Vista: This value can be 0, 2, 3, 4, 5, 6, 7, 8, or 9.

pPrinter

[in] 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	Windows NT/2000/XP/Vista: A PRINTER_INFO_3 structure containing the printer's security information.
4	Windows NT/2000/XP/Vista: 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	Windows 2000/XP/Vista: A PRINTER_INFO_6 structure specifying the status value of a printer.
7	Windows 2000/XP/Vista: 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	Windows 2000/XP/Vista: A PRINTER_INFO_8 structure specifying the global default printer settings.
9	Windows 2000/XP/Vista: A PRINTER_INFO_9 structure specifying the per-user default printer settings.

Command

[in] Specifies the action performed by the SetPrinter function.

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 is a pointer to a DWORD that specifies the new printer status.

Return Values

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

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Windows 2000/XP/Vista: 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. For more information, see Printer Output.

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.

Windows NT/2000/XP/Vista: 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.

Windows XP SP2/Vista: 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.

Windows 2000/XP/Vista: 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.

Windows 95/98/Me: SetPrinter does not update the pShareName member in the PRINTER_INFO_2 structure.

You cannot call SetPrinter from a Windows 95/98/Me computer to set the data for a Windows NT/2000/XP/Vista printer using the printer's UNC name.

Requirements

  Windows NT/2000/XP/Vista: Included in Windows NT 3.1 and later.
  Windows 95/98/Me: Included in Windows 95 and later.
  Header: Declared in Winspool.h; include Windows.h.
  Library: Use Winspool.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP.

See Also

Printing and Print Spooler Overview, Printing and Print Spooler 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