SetPrinter

BOOL SetPrinter(
  HANDLE hPrinter,   /* handle of printer object                  */
  DWORD  dwLevel,    /* structure level                           */
  LPBYTE lpbPrinter, /* address of array containing printer data  */
  DWORD  dwCommand   /* printer-state command                     */
);

Sets the specified printer by pausing printing, resuming printing, or clearing all print jobs. It can also be used to set printer data.

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

hPrinter	Identifies the printer.
dwLevel	Specifies the version of the structure to which lpbPrinter points. This value must be 0, 1, 2, or 3.
lpbPrinter	Points to an array of bytes that may contain printer data. If dwLevel is 0, this pointer must be NULL; if dwLevel is 1, the array contains a PRINTER_INFO_1 structure. If dwLevel is 2, the array contains a PRINTER_INFO_2 structure. If dwLevel is 3, the array contains a PRINTER_INFO_3 structure.
dwCommand	Specifies the new printer state. This parameter can be zero or one of the values listed in the following table. If it is zero, the printer retains its original state and the printer data is reconfigured by using the structure to which lpbPrinter points. Valid values for the dwCommand parameter are:

	PRINTER_CONTROL_PAUSE	Pauses the printer.
	PRINTER_CONTROL_PURGE	Deletes all print jobs in the printer.
	PRINTER_CONTROL_RESUME	Resumes a paused printer.

The handle hPrinter is obtained 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_1, PRINTER_INFO_2, or PRINTER_INFO_3 structure, modify the members of that structure as necessary, and then call the SetPrinter function.

The following fields of a PRINTER_INFO_2 or PRINTER_INFO_3 structure will be ignored on a call to the SetPrinter function: pServerName, pPrinterName, 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.

Note that there are limits to using the SetPrinter function on a Windows 95 client to perform remote administrative tasks on a remote print server. ( SetPrinter operates on data structures that reside on a remote print server when the network path name, for example a UNC name, to that server is used in the OpenPrinter call that must be made before the SetPrinter call.) For example, the SetPrinter function cannot be used on a standard Windows 95 client to change the printer port on a remote server, regardless of what the server platform is (Windows 95, Windows NT, or some other server platform). The fundamental reason, for the specific example of changing the remote printer port, is that the standard Windows 95 client does not support the RPC protocol.

In other cases, limits to the remote administration capability of the SetPrinter function on the Windows 95 client are determined by the type of server platform. A remote administration task may be carried out on one type of remote platform, for example a Windows 95 server, but not on another type, say a Windows NT server. (This is similar to the way the remote capability of the SetJob function is limited by the type of server platform.) The optimum match of client platform type to server platform is to use Windows NT for both, because Windows NT clients and servers can communicate using the RPC protocol.