FindFirstPrinterChangeNotification function

Warning  

Starting with Windows 10, the APIs which support third-party print providers are deprecated. Microsoft does not recommend any investment into third-party print providers. Additionally, on Windows 8 and newer products where the v4 print driver model is available, third-party print providers may not create or manage queues which use v4 print drivers.

 

A print provider's FindFirstPrinterChangeNotification function informs the provider that an application has requested notification when a specified set of events occur on a specified print queue.

Syntax


BOOL FindFirstPrinterChangeNotification(
   HANDLE hPrinter,
   DWORD  fdwFlags,
   DWORD  fdwOptions,
   HANDLE hNotify,
   PDWORD pfdwStatus,
   PVOID  pPrinterNotifyOptions,
   PVOID  pPrinterNotifyInit
);

Parameters

hPrinter

Caller-supplied printer handle, identifying the printer for which event notification is being requested. This handle must have been previously obtained from OpenPrinter (described in the Microsoft Windows SDK documentation).

fdwFlags

One or more caller-supplied PRINTER_CHANGE-prefixed flags. For more information, see the description of FindFirstPrinterChangeNotification in the Windows SDK documentation.

fdwOptions

Not used.

hNotify

Caller-supplied notification handle. This handle must be saved and used as input to ReplyPrinterChangeNotification and PartialReplyPrinterChangeNotification.

pfdwStatus

Caller-supplied pointer to a location to receive provider-specified flags. The following flags are defined.

PRINTER_NOTIFY_STATUS_ENDPOINT

If set, the print provider supplies print change notifications, by either the polling or the change notification method. (The notification method is identified by the PRINTER_NOTIFY_STATUS_POLL flag.)

PRINTER_NOTIFY_STATUS_POLL

If set, the print application must poll to detect printer changes.

If clear, the print provider notifies the spooler of changes by calling RefreshPrinterChangeNotification.

(See the following Remarks section.)

PRINTER_NOTIFY_STATUS_INFO

Not used.

pPrinterNotifyOptions

Caller-supplied pointer to a PRINTER_NOTIFY_OPTIONS structure (described in the Windows SDK documentation).

pPrinterNotifyInit

Not used.

Return value

If the operation succeeds, the function should return TRUE. Otherwise the function should return FALSE.

Remarks

When the spooler calls a print provider's FindFirstPrinterChangeNotification function, fdwFlags identifies the printer events for which notification is being requested. Additionally, pPrinterNotifyOptions identifies the types of information that the print provider should send to the spooler when one of the specified events occurs.

For a list of the types of notifications an application can request, and for a list of the types of information that can be used to describe an event, see the Windows SDK documentation's description of FindFirstPrinterChangeNotification. Types of events for which an application might request notification include adding or deleting a print job or form. Types of information an application might request include job or form parameters.

If the print provider does not request polling (that is, it does not set PRINTER_NOTIFY_STATUS_POLL in pfdwStatus), it must notify the spooler when events identified by pfwFlags occur. The print provider must supply the types of information identified by pPrinterNotifyOptions, by calling PartialReplyPrinterChangeNotification or ReplyPrinterChangeNotification.

If the provider does request polling (that is, it sets PRINTER_NOTIFY_STATUS_POLL), it should not call ReplyPrinterChangeNotification. Instead, the spooler signals the application at regular intervals.

Both polled and nonpolled print provider must return the current state of all requested information types whenever its RefreshPrinterChangeNotification function is called.

For additional information, see Supporting Printer Change Notifications.

Requirements

Target platform

Desktop

Header

Winspool.h (include Winspool.h)

Library

WinSpool.lib

DLL

WinSpool.drv

See also

PartialReplyPrinterChangeNotification
ReplyPrinterChangeNotification
RefreshPrinterChangeNotification

 

 

Send comments about this topic to Microsoft

Show: