EnumPrinters 函数

  • 项目

EnumPrinters 函数枚举可用的打印机、打印服务器、域或打印提供程序。

语法

BOOL EnumPrinters(
  _In_  DWORD   Flags,
  _In_  LPTSTR  Name,
  _In_  DWORD   Level,
  _Out_ LPBYTE  pPrinterEnum,
  _In_  DWORD   cbBuf,
  _Out_ LPDWORD pcbNeeded,
  _Out_ LPDWORD pcReturned
);

parameters

Flags [in]

函数应枚举的打印对象的类型。 此值可以是以下一个或多个值。

值 含义
PRINTER_ENUM_LOCAL
 如果未同时传递PRINTER_ENUM_NAME标志，函数将忽略 Name 参数，并枚举本地安装的打印机。 如果同时传递了PRINTER_ENUM_NAME，函数将枚举 Name 上的本地打印机。
PRINTER_ENUM_NAME
 函数枚举由 Name 标识的打印机。 这可以是服务器、域或打印提供程序。 如果 Name 为 NULL，则该函数枚举可用的打印提供程序。
PRINTER_ENUM_SHARED
 函数枚举具有共享属性的打印机。 不能单独使用;使用 OR 操作与其他PRINTER_ENUM类型合并。
PRINTER_ENUM_CONNECTIONS
 函数枚举用户以前连接的打印机列表。
PRINTER_ENUM_NETWORK
 函数枚举计算机域中的网络打印机。 仅当 Level 为 1 时，此值才有效。
PRINTER_ENUM_REMOTE
 函数枚举计算机域中的网络打印机和打印服务器。 仅当 Level 为 1 时，此值才有效。
PRINTER_ENUM_CATEGORY_3D
 函数仅枚举 3D 打印机。
PRINTER_ENUM_CATEGORY_ALL
 函数枚举所有打印设备，包括 3D 打印机。

如果 Level 为 4，则只能使用 PRINTER_ENUM_CONNECTIONS 和 PRINTER_ENUM_LOCAL 常量。

注意

默认情况下不枚举 3D 打印设备。 必须同时包含 PRINTER_ENUM_CATEGORY_3D 和 PRINTER_ENUM_LOCAL 才能仅枚举 3D 打印机。 若要包含 3D 打印机以及所有其他本地打印机，请使用 PRINTER_ENUM_CATEGORY_ALL 和 PRINTER_ENUM_LOCAL。

Name [in]

如果 Level 为 1， Flags 包含PRINTER_ENUM_NAME， Name 为非 NULL，则 Name 是指向以 null 结尾的字符串的指针，该字符串指定要枚举的对象的名称。 此字符串可以是服务器、域或打印提供程序的名称。

如果 Level 为 1， Flags 包含PRINTER_ENUM_NAME， Name 为 NULL，则函数枚举可用的打印提供程序。

如果 Level 为 1， Flags 包含PRINTER_ENUM_REMOTE， Name 为 NULL，则函数枚举用户域中的打印机。

如果 Level 为 2 或 5，则 Name 是指向以 null 结尾的字符串的指针，该字符串指定要枚举其打印机的服务器的名称。 如果此字符串为 NULL，则该函数将枚举本地计算机上安装的打印机。

如果 Level 为 4， 则 Name 应为 NULL。 函数始终在本地计算机上查询。

当 Name 为 NULL 时，将 Flags 设置为 PRINTER_ENUM_LOCAL |PRINTER_ENUM_CONNECTIONS枚举本地计算机上安装的打印机。 这些打印机包括物理连接到本地计算机的打印机，以及它与它有网络连接的远程打印机。

当 Name 不为 NULL 时，将 Flags 设置为 PRINTER_ENUM_LOCAL |PRINTER_ENUM_NAME枚举安装在服务器 名称上的本地打印机。

级别 [in]

pPrinterEnum 指向的数据结构的类型。 有效值为 1、2、4 和 5，分别对应于 PRINTER_INFO_1、 PRINTER_INFO_2 、 PRINTER_INFO_4和 PRINTER_INFO_5 数据结构。

此值可以是 1、2、4 或 5。

pPrinterEnum [out]

指向接收PRINTER_INFO_1、PRINTER_INFO_2、PRINTER_INFO_4或PRINTER_INFO_5结构的数组的缓冲区的指针。 每个结构都包含描述可用打印对象的数据。

如果 Level 为 1，则数组包含 PRINTER_INFO_1 结构。 如果 Level 为 2，则数组包含 PRINTER_INFO_2 结构。 如果 Level 为 4，则数组包含 PRINTER_INFO_4 结构。 如果 Level 为 5，则数组包含 PRINTER_INFO_5 结构。

缓冲区必须足够大，才能接收数据结构数组以及结构成员指向的任何字符串或其他数据。 如果缓冲区太小， 则板Needed 参数将返回所需的缓冲区大小。

cbBuf [in]

pPrinterEnum 指向的缓冲区的大小（以字节为单位）。

线路板 [out]

指向一个值的指针，该值接收在函数成功时复制的字节数;如果 cbBuf 太小，则接收所需的字节数。

pcReturned [out]

指向一个值的指针，该值接收函数在 pPrinterEnum 指向 的数组中返回的PRINTER_INFO_1、PRINTER_INFO_2 、PRINTER_INFO_4 或PRINTER_INFO_5结构的数量。

返回值

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

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

注解

请勿在 DllMain 中调用此方法。

注意

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

如果 EnumPrinters 返回指定 了PRINTER_ENUM_CONTAINER的PRINTER_INFO_1 结构，则表示存在打印机对象的层次结构。 应用程序可以通过再次调用 EnumPrinters ，将 Name 设置为 PRINTER_INFO_1 结构的 pName 成员的值来枚举层次结构。

EnumPrinters 函数不检索安全信息。 如果在 pPrinterEnum 指向的数组中返回PRINTER_INFO_2结构，则其 pSecurityDescriptor 成员将设置为 NULL。

若要获取有关默认打印机的信息，请调用 GetDefaultPrinter。

PRINTER_INFO_4结构提供了一种简单且极快的方法，用于检索本地计算机上安装的打印机的名称，以及用户已建立的远程连接。 使用PRINTER_INFO_4数据结构调用 EnumPrinters 时，该函数在注册表中查询指定信息，然后立即返回 。 这不同于使用其他级别的PRINTER_INFO_* 数据结构调用 EnumPrinters 的行为。 具体而言，当使用级别 2 (PRINTER_INFO_2) 数据结构调用 EnumPrinters 时，它会在每个远程连接上执行 OpenPrinter 调用。 如果远程连接已关闭，或者远程服务器不再存在，或者远程打印机不再存在，则函数必须等待 RPC 超时，从而导致 OpenPrinter 调用失败。 这可能需要一段时间。 通过传递 PRINTER_INFO_4 结构，应用程序可以检索最少的必需信息;如果需要更详细的信息，可以进行后续 EnumPrinters 级别 2 调用。

Windows Vista：当 Level 值为 4 时，从本地缓存检索 EnumPrinters 返回的打印机数据。

下表显示了当 Level 参数设置为 1 时各种 Flags 值的 EnumPrinters 输出。

在表的 “名称 参数”列中，应替换“打印提供程序”、“域”和“计算机”的相应名称。 例如，对于“打印提供程序”，可以使用网络打印提供程序的名称或本地打印提供程序的名称。 若要检索打印提供程序名称，请调用名称设置为 NULL 的 EnumPrinters。

Flags 参数 Name 参数 结果
PRINTER_ENUM_LOCAL (而不是PRINTER_ENUM_NAME) 忽略 Name 参数。
 所有本地打印机。
PRINTER_ENUM_NAME “打印提供程序”
 所有域名
PRINTER_ENUM_NAME “打印提供程序！域”
 计算机域中的所有打印机和打印服务器
PRINTER_ENUM_NAME “打印提供程序！！\\Machine”
 在 \\Machine 上共享的所有打印机
PRINTER_ENUM_NAME 空字符串“”
 所有本地打印机。
PRINTER_ENUM_NAME NULL
 计算机域中的所有打印提供程序
PRINTER_ENUM_CONNECTIONS 忽略 Name 参数。
 所有连接的远程打印机
PRINTER_ENUM_NETWORK 忽略 Name 参数。
 计算机域中的所有打印机
PRINTER_ENUM_REMOTE 空字符串“”
 计算机域中的所有打印机和打印服务器
PRINTER_ENUM_REMOTE “打印提供程序”
 与 PRINTER_ENUM_NAME 相同
PRINTER_ENUM_REMOTE “打印提供程序！域”
 计算机域中的所有打印机和打印服务器，而不考虑指定的 域 。
PRINTER_ENUM_CATEGORY_3D 忽略 Name 参数。
 仅枚举 3D 打印机。
PRINTER_ENUM_CATEGORY_ALL 忽略 Name 参数。
 枚举 3D 打印机以及所有其他打印机。

要求

要求 值
最低受支持的客户端
 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器
 Windows 2000 Server [仅限桌面应用]
标头
Winspool.h (包括 Windows.h)
库
Winspool.lib
DLL
Winspool.drv
Unicode 和 ANSI 名称
 EnumPrintersW (Unicode) 和 EnumPrintersA (ANSI)

另请参阅

打印

打印后台处理程序 API 函数

AddPrinter

DeletePrinter

GetPrinter

PRINTER_INFO_1

PRINTER_INFO_2

PRINTER_INFO_4

PRINTER_INFO_5

SetPrinter