DrvPrinterEvent 函数 (winddiui.h)

打印机接口 DLL 的 DrvPrinterEvent 函数由打印后台处理程序在处理可能需要打印机驱动程序操作的打印机特定事件时调用。

语法

BOOL DrvPrinterEvent(
  [in] LPWSTR pPrinterName,
       int    DriverEvent,
       DWORD  Flags,
       LPARAM lParam
);

参数

[in] pPrinterName

调用方提供的指向以 NULL 结尾的打印机名称字符串的指针。 字符串格式可以是 \Machine\PrinterName （用于指定远程打印机）或 PrinterName （用于指定本地打印机）。

DriverEvent

调用方提供的事件代码标识事件。 定义了以下事件代码：

事件代码	定义
PRINTER_EVENT_ADD_CONNECTION	后台处理程序刚刚完成了对其 AddPrinterConnection 函数的调用的处理，该函数允许客户端用户连接到以前创建的远程打印机。
PRINTER_EVENT_ATTRIBUTES_CHANGED	打印机的属性位已更改。 为了响应应用程序对 SetPrinter 函数的调用，后台处理程序调用打印机驱动程序的 DrvPrinterEvent 函数，并在调用中传递事件代码。 使用此事件代码时， lParam 参数指向描述新旧属性 的 PRINTER_EVENT_ATTRIBUTES_INFO 结构。
PRINTER_EVENT_CACHE_DELETE	后台处理程序正在删除客户端的文件缓存。
PRINTER_EVENT_CACHE_REFRESH	后台处理程序正在更新客户端的缓存文件。
PRINTER_EVENT_CONFIGURATION_CHANGE	保留。
PRINTER_EVENT_CONFIGURATION_UPDATE	打印机配置已更改。 使用此事件代码时， lParam 参数指向包含根据 Bidi 通知架构设置格式的通知的 Unicode 字符串。
PRINTER_EVENT_DELETE_CONNECTION	后台处理程序刚刚完成对其 DeletePrinterConnection 函数的调用的处理，该函数允许客户端用户删除打印机连接。
PRINTER_EVENT_DELETE	后台处理程序刚刚完成对其 DeletePrinter 函数的调用的处理，该函数允许管理员删除打印机实例。
PRINTER_EVENT_INITIALIZE	后台处理程序刚刚完成对其 AddPrinter 函数的调用，该函数允许管理员在服务器上提供打印机，或者其 SetPrinter 函数，该函数允许管理员修改打印机的状态。 在客户端呈现连接中，客户端计算机刚刚添加了 GUID 打印机。 PRINTER_EVENT_INITIALIZE 事件为 Windows Vista 和早期版本上的 DrvPrinterEvent 调用指定 NULL lParam 参数值。 对于 Windows 7 及更高版本，lParam 参数是用户令牌句柄。 打印驱动程序可以使用返回的令牌句柄来查询用户数据或模拟用户。

Flags

调用方提供的位标志，定义如下：

值	定义
PRINTER_EVENT_FLAG_NO_UI	如果设置，函数 不得 显示用户界面。 在安装打印处理器、打印监视器或打印机驱动程序期间，允许使用用户界面的唯一方法是使用 VendorSetup 指令。 有关详细信息 ，请参阅打印机 INF 文件条目 和 自定义打印机设置操作 。

注意

VendorSetup 指令已弃用，不应由你开发的任何新的 v3 或 v4 驱动程序使用。 有关 VendorSetup 的此信息仅供参考，或用于维护已使用此 INF 指令的现有 v3 驱动程序。

lParam

除非 DriverEvent 参数设置为 PRINTER_EVENT_ATTRIBUTES_CHANGED，否则不使用。 在本例中， lParam 包含PRINTER_EVENT_ATTRIBUTES_INFO结构的地址。 (请参阅上述 DriverEvent 参数的说明。) 对于 DriverEvent 参数的所有其他值， lParam 参数为 NULL。

返回值

如果操作成功，函数应返回 TRUE;否则，它应返回 FALSE。 但是，目前唯一检查函数的返回值的时间是，后台处理程序在处理 AddPrinter 函数期间调用了 DrvPrinterEvent，DriverEvent 设置为 PRINTER_EVENT_INITIALIZE。 在这种情况下 ，如果 DrvPrinterEvent 返回 FALSE ，则后台处理程序不会创建打印机，而是导致 AddPrinter 失败。

注解

所有 打印机接口 DLL 都必须提供 DrvPrinterEvent 函数，并且该函数必须支持PRINTER_EVENT_INITIALIZE事件代码。 对所有其他事件代码的支持是可选的。

处理PRINTER_EVENT_INITIALIZE事件时存储的注册表设置应通过调用 SetPrinterData 存储在 HKEY_LOCAL_MACHINE 键下。 对于PRINTER_EVENT_INITIALIZE和PRINTER_EVENT_DELETE事件代码，后台处理程序验证调用方是否具有管理权限，并在模拟调用方时调用 DrvPrinterEvent 。

相比之下，如果需要在处理PRINTER_EVENT_ADD_CONNECTION事件时将设置存储在注册表中，打印机接口 DLL 应在HKEY_CURRENT_USER键下写入这些设置，以便按用户存储这些设置。 然后，如果具有漫游配置文件的用户登录到另一个系统，则连接会跟随该用户。 仅当用户首次建立连接时，才调用 DrvPrinterEvent 函数，而不是当用户随后使用漫游配置文件登录到其他系统时调用。

对于PRINTER_EVENT_ADD_CONNECTION和PRINTER_EVENT_DELETE_CONNECTION事件代码， DrvPrinterEvent 函数的执行上下文是调用应用程序， (通常是 Print Folder) ，函数可以显示用户界面。 对于所有其他事件代码，执行上下文是打印后台处理程序，无法显示用户界面。

在建立连接时可能显示用户界面的驱动程序的一个示例是 FAX 驱动程序，它可以提示用户输入用户的姓名和电话号码 (FAX 发件人) ，并保存信息，直到删除连接。

可能存储在客户端缓存中的文件类型的一个示例是包含太多无法写入注册表的信息的大型字体指标文件。 当 DrvPrinterEvent 函数的事件代码PRINTER_EVENT_CACHE_REFRESH时，打印机接口 DLL 可以从服务器重新加载文件，以确保缓存是最新的。

要求

要求	值
目标平台	桌面
标头	winddiui.h (包括 Winddiui.h)