FindFirstPrinterChangeNotification
The FindFirstPrinterChangeNotification
function creates a change notification object and returns a handle to the
object. You can then use this handle in a call to one of the wait functions to
monitor changes to the printer or print server.
The FindFirstPrinterChangeNotification
call specifies the type of changes to be monitored. You can specify a set of
conditions to monitor for changes, a set of printer information fields to
monitor, or both.
A wait
operation on the change notification handle succeeds when one of the specified
changes occurs in the specified printer or print server. You then call the FindNextPrinterChangeNotification function to retrieve
information about the change, and to reset the change notification object for
use in the next wait operation.
HANDLE FindFirstPrinterChangeNotification(
|
HANDLE hPrinter, |
// handle to
printer or print server to monitor for changes |
|
DWORD fdwFlags, |
// flags that
specify the conditions to monitor |
|
DWORD fdwOptions, |
// reserved, must
be zero |
|
LPVOID pPrinterNotifyOptions |
// pointer to
structure specifying printer information to monitor |
|
); |
|
Parameters
hPrinter
Handle to the
printer or print server that you want to monitor. This handle is obtained by
calling the OpenPrinter
function.
fdwFlags
A set of bit
flags that specify the conditions that will cause the change notification
object to enter a signaled state. A change notification occurs when one or more
of the specified conditions are met. The fdwFlags parameter can be zero
if pPrinterNotifyOptions is non-NULL.
You can set
one or more of the following change notification constants:
|
Value |
Meaning |
|
|
PRINTER_CHANGE_FORM |
|
|
|
|
Notify of
any changes to a form. You can set this general flag or one or more of the
following specific flags: |
|
|
PRINTER_CHANGE_JOB |
|
|
|
|
Notify of
any changes to a job. You can set this general flag or one or more of the
following specific flags: |
|
|
PRINTER_CHANGE_PORT |
|
|
|
|
Notify of
any changes to a port. You can set this general flag or one or more of the
following specific flags: |
|
|
PRINTER_CHANGE_PRINT_PROCESSOR |
|
|
|
|
Notify of
any changes to a print processor. You can set this general flag or one or
more of the following specific flags: PRINTER_CHANGE_ADD_PRINT_PROCESSOR
PRINTER_CHANGE_DELETE_PRINT_PROCESSOR |
|
|
PRINTER_CHANGE_PRINTER |
|
|
|
|
Notify of
any changes to a printer. You can set this general flag or one or more of the
following specific flags: |
|
|
PRINTER_CHANGE_PRINTER_DRIVER |
|
|
|
|
Notify of
any changes to a printer driver. You can set this general flag or one or more
of the following specific flags: |
|
|
PRINTER_CHANGE_ALL |
|
|
|
|
Notify if
any of the preceding changes occur. |
|
For
descriptions of the more specific flags in the preceding table, see the FindNextPrinterChangeNotification function.
fdwOptions
Reserved;
must be zero.
pPrinterNotifyOptions
Pointer to a PRINTER_NOTIFY_OPTIONS structure. The pTypes
member of this structure points to an array of one or more PRINTER_NOTIFY_OPTIONS_TYPE
structures, each of which specifies a printer information field to monitor. A
change notification occurs when one or more of the specified fields changes.
When a change occurs, the FindNextPrinterChangeNotification function can
retrieve the new printer information. This parameter can be NULL if fdwFlags
is nonzero.
For a list of
fields that can be monitored, see PRINTER_NOTIFY_OPTIONS_TYPE.
Return Values
If the
function succeeds, the return value is a handle to a change notification object
associated with the specified printer or print server.
If the
function fails, the return value is INVALID_HANDLE_VALUE. To get extended error
information, call GetLastError.
Remarks
To monitor a
printer or print server, call the FindFirstPrinterChangeNotification function,
then use the returned change notification object handle in a call to one of the
wait functions. A
wait operation on a change notification object is satisfied when the change
notification object enters the signaled state. The system signals the object
when one or more of the changes specified by fdwFlags or pPrinterNotifyOptions
occurs in the monitored printer or print server.
When you call
FindFirstPrinterChangeNotification, either fdwFlags must be
nonzero or pPrinterNotifyOptions must be non-NULL. If both are
specified, notifications will occur for both.
When a wait
operation on a printer change notification object is satisfied, call the FindNextPrinterChangeNotification function to determine the
cause of the notification. For a condition specified by fdwFlags, FindNextPrinterChangeNotification
reports the condition or conditions that changed. For a printer information
field specified by pPrinterNotifyOptions , FindNextPrinterChangeNotification
reports the field or fields that changed as well as the new information for
these fields. FindNextPrinterChangeNotification also resets the change
notification object to the nonsignaled state so you can use it in another wait
operation to continue monitoring the printer or print server.
Do not call
the FindNextPrinterChangeNotification function if the change
notification object is not in the signaled state. If the wait function returns
the value WAIT_TIMEOUT, the change object is not in the signaled state. Call
the FindNextPrinterChangeNotification function only if the wait function
succeeds without timing out.
When you no
longer need the change notification object, close it by calling the FindClosePrinterChangeNotification function.
The three Find*PrinterChangeNotification
functions, in combination with the wait functions, provide an asynchronous
and resource-efficient alternative to the WaitForPrinterChange function.
See Also