FindFirstPrinterChangeNotification 函数

  • 项目

FindFirstPrinterChangeNotification 函数创建更改通知对象，并返回对象的句柄。 然后，可以在调用某个等待函数时使用此句柄来监视对打印机或打印服务器的更改。

FindFirstPrinterChangeNotification 调用指定要监视的更改类型。 可以指定要监视更改的一组条件和/或一组要监视的打印机信息字段。

当指定更改之一在指定的打印机或打印服务器中发生时，更改通知句柄上的等待操作会成功。 然后调用 FindNextPrinterChangeNotification 函数来检索有关更改的信息，并重置更改通知对象以用于下一个等待操作。

语法

HANDLE FindFirstPrinterChangeNotification(
  _In_     HANDLE hPrinter,
           DWORD  fdwFilter,
           DWORD  fdwOptions,
  _In_opt_ LPVOID pPrinterNotifyOptions
);

参数

hPrinter [in]

要监视的打印机或打印服务器的句柄。 使用 OpenPrinter 或 AddPrinter 函数检索打印机句柄。

fdwFilter

导致更改通知对象进入信号状态的条件。 满足一个或多个指定条件时，会发生更改通知。 如果 pPrinterNotifyOptions 为非 NULL，fdwFilter 参数可以为零。

此参数可使用以下一个或多个值。

值 含义
PRINTER_CHANGE_FORM
 通知窗体的任何更改。 可以设置此常规标志或以下一个或多个特定标志：
PRINTER_CHANGE_ADD_FORM
PRINTER_CHANGE_SET_FORM
PRINTER_CHANGE_DELETE_FORM
PRINTER_CHANGE_JOB
 通知作业的任何更改。 可以设置此常规标志或以下一个或多个特定标志：
PRINTER_CHANGE_ADD_JOB
PRINTER_CHANGE_SET_JOB
PRINTER_CHANGE_DELETE_JOB
PRINTER_CHANGE_WRITE_JOB
PRINTER_CHANGE_PORT
 通知端口的任何更改。 可以设置此常规标志或以下一个或多个特定标志：
PRINTER_CHANGE_ADD_PORT
PRINTER_CHANGE_CONFIGURE_PORT
PRINTER_CHANGE_DELETE_PORT
PRINTER_CHANGE_PRINT_PROCESSOR
 通知打印处理器的任何更改。 可以设置此常规标志或以下一个或多个特定标志：
PRINTER_CHANGE_ADD_PRINT_PROCESSOR
PRINTER_CHANGE_DELETE_PRINT_PROCESSOR
PRINTER_CHANGE_PRINTER
 通知打印机的任何更改。 可以设置此常规标志或以下一个或多个特定标志：
PRINTER_CHANGE_ADD_PRINTER
PRINTER_CHANGE_SET_PRINTER
PRINTER_CHANGE_DELETE_PRINTER
PRINTER_CHANGE_FAILED_CONNECTION_PRINTER
PRINTER_CHANGE_PRINTER_DRIVER
 通知打印机驱动程序的任何更改。 可以设置此常规标志或以下一个或多个特定标志：
PRINTER_CHANGE_ADD_PRINTER_DRIVER
PRINTER_CHANGE_SET_PRINTER_DRIVER
PRINTER_CHANGE_DELETE_PRINTER_DRIVER
PRINTER_CHANGE_ALL
 如果发生上述任何更改，请通知。
PRINTER_CHANGE_SERVER
 Windows 7：通知服务器的任何更改。
通过设置PRINTER_CHANGE_ALL值监视的更改中不包含 此 标志。

有关上表中更具体的标志的说明，请参阅 FindNextPrinterChangeNotification 函数。

fdwOptions

确定通知将适用于的打印机类别的标志。

值 含义
PRINTER_NOTIFY_CATEGORY_ALL
0x001000
 FindNextPrinterChangeNotification 返回 2D 和 3D 打印机的通知。
PRINTER_NOTIFY_CATEGORY_3D
0x002000
 FindNextPrinterChangeNotification 仅返回 3D 打印机的通知。

当此标志设置为零 (0) 时， FindFirstPrinterChangeNotification 将仅适用于 2D 打印机。 这是默认值。

pPrinterNotifyOptions [in， optional]

指向 PRINTER_NOTIFY_OPTIONS 结构的指针。 此结构的 pTypes 成员是一个或多个 PRINTER_NOTIFY_OPTIONS_TYPE 结构的数组，每个结构都指定要监视的打印机信息字段。 当一个或多个指定字段发生更改时，会发生更改通知。 发生更改时， FindNextPrinterChangeNotification 函数可以检索新的打印机信息。 如果 fdwFilter 为非零值，此参数可以为 NULL。

有关可监视的字段的列表，请参阅 PRINTER_NOTIFY_OPTIONS_TYPE。

返回值

如果函数成功，则返回值是与指定打印机或打印服务器关联的更改通知对象的句柄。

如果函数失败，则返回值为 INVALID_HANDLE_VALUE。

备注

注意

这是一个阻塞或同步函数，可能不会立即返回。 此函数的返回速度取决于运行时因素，例如网络状态、打印服务器配置以及编写应用程序时难以预测的打印机驱动程序实现因素。 从管理与用户界面交互的线程调用此函数可能会使应用程序看起来无响应。

若要监视打印机或打印服务器，请调用 FindFirstPrinterChangeNotification 函数，然后在调用某个 等待函数时使用返回的更改通知对象句柄。 更改通知对象进入信号状态时，满足更改通知对象的等待操作。 当受监视的打印机或打印服务器中发生 fdwFilter 或 pPrinterNotifyOptions 指定的一个或多个更改时，系统会向对象发出信号。

调用 FindFirstPrinterChangeNotification 时， fdwFilter 必须为非零或 pPrinterNotifyOptions 必须为非 NULL。 如果同时指定了两者，则两者都会发出通知。

当满足打印机更改通知对象上的等待操作时，调用 FindNextPrinterChangeNotification 函数以确定通知的原因。 对于 由 fdwFilter 指定的条件， FindNextPrinterChangeNotification 报告一个或多个已更改的条件。 对于 由 pPrinterNotifyOptions 指定的打印机信息字段， FindNextPrinterChangeNotification 报告已更改的字段以及这些字段的新信息。 FindNextPrinterChangeNotification 还会将更改通知对象重置为未签名状态，以便可以在另一个等待操作中使用它来继续监视打印机或打印服务器。

有一个例外，如果更改通知对象未处于信号状态，请不要调用 FindNextPrinterChangeNotification 函数。 如果 wait 函数返回值WAIT_TIMEOUT，则更改对象不处于信号状态。 仅当 wait 函数成功且不超时时，才调用 FindNextPrinterChangeNotification 函数。当使用 pPrinterNotifyOptions 参数中设置的 PRINTER_NOTIFY_OPTIONS_REFRESH 位调用 FindNextPrinterChangeNotification 时，例外。

如果不再需要更改通知对象，请通过调用 FindClosePrinterChangeNotification 函数将其关闭。

FindFirstPrinterChangeNotification 的调用方必须确保传入 FindFirstPrinterChangeNotification 的打印机句柄在调用 FindClosePrinterChangeNotification 之前保持有效。 如果在打印机更改通知句柄之前关闭打印机句柄，则无法传递其他通知。

FindFirstPrinterChangeNotification 不会将 3D 打印机的更改通知发送到服务器句柄。

注意

在具有 Service Pack 2 (SP2) 及更高版本的 Windows XP 中，Internet 连接防火墙 (ICF) 默认阻止打印机端口，但可以启用文件和打印共享的例外。 如果用户与另一台计算机建立打印机连接，并且未启用该异常，则用户将不会收到来自服务器的打印机更改通知。 计算机管理员必须启用例外。

要求

要求 值
最低受支持的客户端
 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器
 Windows 2000 Server [仅限桌面应用]
标头
Winspool.h (包括 Windows.h)
库
Winspool.lib
DLL
Spoolss.dll

另请参阅

打印

打印后台处理程序 API 函数

FindClosePrinterChangeNotification

FindNextPrinterChangeNotification

OpenPrinter

PRINTER_NOTIFY_OPTIONS

PRINTER_NOTIFY_OPTIONS_TYPE