FindNextPrinterChangeNotification 函数

  • 项目

FindNextPrinterChangeNotification 函数检索与打印机或打印服务器关联的更改通知对象的最新更改通知信息。 满足更改通知对象上的等待操作时调用此函数。

函数还会将更改通知对象重置为未发出信号的状态。 然后，可以在另一个等待操作中使用 对象继续监视打印机或打印服务器。 下次打印机或打印服务器发生一组指定的更改之一时，操作系统会将对象设置为信号状态。 FindFirstPrinterChangeNotification 函数创建更改通知对象并指定要监视的更改集。

语法

BOOL FindNextPrinterChangeNotification(
  _In_      HANDLE hChange,
  _Out_opt_ PDWORD pdwChange,
  _In_opt_  LPVOID pPrinterNotifyOptions,
  _Out_opt_ LPVOID *ppPrinterNotifyInfo
);

参数

hChange [in]

与打印机或打印服务器关联的更改通知对象的句柄。 可以通过调用 FindFirstPrinterChangeNotification 函数来获取此类句柄。 操作系统在检测到对象的更改通知筛选器中指定的更改之一时，将此更改通知对象设置为信号状态。

pdwChange [out， optional]

指向变量的指针，该变量的位设置为指示导致最新通知而发生的更改。 可能设置的位标志对应于 FindFirstPrinterChangeNotification 调用的 fdwFilter 参数中指定的位标志。 系统设置以下一个或多个位标志。

值 含义
PRINTER_CHANGE_ADD_FORM
 已将窗体添加到服务器。
PRINTER_CHANGE_ADD_JOB
 打印作业已发送到打印机。
PRINTER_CHANGE_ADD_PORT
 已将端口或监视器添加到服务器。
PRINTER_CHANGE_ADD_PRINT_PROCESSOR
 已将打印处理器添加到服务器。
PRINTER_CHANGE_ADD_PRINTER
 已将打印机添加到服务器。
PRINTER_CHANGE_ADD_PRINTER_DRIVER
 已将打印机驱动程序添加到服务器。
PRINTER_CHANGE_CONFIGURE_PORT
 服务器上配置了端口。
PRINTER_CHANGE_DELETE_FORM
 已从服务器中删除窗体。
PRINTER_CHANGE_DELETE_JOB
 作业已删除。
PRINTER_CHANGE_DELETE_PORT
 已从服务器中删除端口或监视器。
PRINTER_CHANGE_DELETE_PRINT_PROCESSOR
 已从服务器中删除打印处理器。
PRINTER_CHANGE_DELETE_PRINTER
 已删除打印机。
PRINTER_CHANGE_DELETE_PRINTER_DRIVER
 已从服务器中删除打印机驱动程序。
PRINTER_CHANGE_FAILED_CONNECTION_PRINTER
 打印机连接失败。
PRINTER_CHANGE_SET_FORM
 在服务器上设置了窗体。
PRINTER_CHANGE_SET_JOB
 作业已设置。
PRINTER_CHANGE_SET_PRINTER
 打印机已设置。
PRINTER_CHANGE_SET_PRINTER_DRIVER
 已设置打印机驱动程序。
PRINTER_CHANGE_WRITE_JOB
 作业数据已写入。
PRINTER_CHANGE_TIMEOUT
 作业超时。
PRINTER_CHANGE_SERVER
 Windows 7：服务器上发生更改。

pPrinterNotifyOptions [in， optional]

指向 PRINTER_NOTIFY_OPTIONS 结构的指针。 将此结构的 Flags 成员设置为 PRINTER_NOTIFY_OPTIONS_REFRESH，使函数返回所有受监视打印机信息字段的当前数据。 函数忽略 结构的所有其他成员。 此参数可以为 NULL。

ppPrinterNotifyInfo [out， optional]

指向指针变量的指针，该变量接收指向系统分配的只读缓冲区的指针。 使用完缓冲区后，调用 FreePrinterNotifyInfo 函数以释放缓冲区。 如果不需要任何信息，此参数可以为 NULL 。

缓冲区包含 一个PRINTER_NOTIFY_INFO 结构，该结构包含 PRINTER_NOTIFY_INFO_DATA 结构的数组。 数组的每个元素都包含有关 FindFirstPrinterChangeNotification 调用的 pPrinterNotifyOptions 参数中指定的字段之一的信息。 通常， 函数仅为更改为导致最新通知的字段提供数据。 但是，如果 pPrinterNotifyOptions 参数指向的结构指定 PRINTER_NOTIFY_OPTIONS_REFRESH，则函数会为所有受监视字段提供数据。

如果在 PRINTER_NOTIFY_INFO 结构的 Flags 成员中设置了 PRINTER_NOTIFY_INFO_DISCARDED 位，则会发生溢出或错误，并且通知可能已丢失。 在这种情况下，在进行第二次指定PRINTER_NOTIFY_OPTIONS_REFRESH的 FindNextPrinterChangeNotification 调用之前，不会发送其他通知。

返回值

如果函数成功，则返回值为非零值。

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

注解

注意

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

在满足 FindFirstPrinterChangeNotification 创建的通知对象的等待操作后，调用 FindNextPrinterChangeNotification 函数。 调用 FindNextPrinterChangeNotification 可让你获取有关满足等待操作的更改的信息，并重置通知对象，以便在下一次更改发生时发出信号。

有一个例外，如果更改通知对象未处于信号状态，请不要调用 FindNextPrinterChangeNotification 函数。 如果 wait 函数 返回值WAIT_TIMEOUT，则 change 对象不处于信号状态。 仅当 wait 函数成功且不超时时，才调用 FindNextPrinterChangeNotification 函数。例外情况是使用 pPrinterNotifyOptions 参数中设置的 PRINTER_NOTIFY_OPTIONS_REFRESH 位调用 FindNextPrinterChangeNotification 时。 请注意，即使设置了此标志，仍可以在 ppPrinterNotifyInfo 参数中设置PRINTER_NOTIFY_INFO_DISCARDED标志。

若要继续监视打印机或打印服务器的更改，请重复调用等待 函数 之一 的循环，然后调用 FindNextPrinterChangeNotification 函数以检查更改并重置通知对象。

FindNextPrinterChangeNotification 可将对同一打印机信息字段的多个更改合并到单个通知中。 发生这种情况时， 函数通常会将字段的所有更改折叠为 ppPrinterNotifyInfo 中PRINTER_NOTIFY_INFO_DATA结构数组中的单个条目;单个条目仅报告最新信息。 但是，对于某些作业和打印机信息字段，该函数可以返回同一字段的多个数组条目。 在这种情况下，字段的最后一个数组条目报告当前数据，而前面的条目包含中间阶段的数据。

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

注意

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

示例

下面的代码示例演示了如何使用这些函数监视打印机状态。

// Get change notification handle for the printer   
chgObject = FindFirstPrinterChangeNotification( 
                hPrinter, 
                PRINTER_CHANGE_JOB, 
                0, 
                NULL); 

if (chgObject != INVALID_HANDLE_VALUE) {
    while (bKeepMonitoring) {
        // Wait for the change notification 
        WaitForSingleObject(chgObject, INFINITE);

        fcnreturn = FindNextPrinterChangeNotification(
                        chgObject, 
                        pdwChange, 
                        NULL, 
                        NULL);

        if (fcnreturn) {
            // Check value of *pdwChange and 
            //  deal with the indicated change 
        }
        // Insert some mechanism to stop monitoring
        //  such as: 
        //
        // if (something happens) {
        //     bKeepMonitoring = false; 
        // }
        //
    }
    // Close Printer Change Notification handle when finished. 
    FindClosePrinterChangeNotification(chgObject);
} else {
    // Unable to open printer change notification handle 
    dwStatus = GetLastError();
}

要求

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

另请参阅

打印

打印后台处理程序 API 函数

FindClosePrinterChangeNotification

FindFirstPrinterChangeNotification

PRINTER_NOTIFY_INFO

PRINTER_NOTIFY_INFO_DATA

PRINTER_NOTIFY_OPTIONS