EnumPrinterData 函数
EnumPrinterData 函数枚举指定打印机的配置数据。
若要在单个调用中检索配置数据,请使用 EnumPrinterDataEx 函数。
语法
DWORD EnumPrinterData(
_In_ HANDLE hPrinter,
_In_ DWORD dwIndex,
_Out_ LPTSTR pValueName,
_In_ DWORD cbValueName,
_Out_ LPDWORD pcbValueName,
_Out_ LPDWORD pType,
_Out_ LPBYTE pData,
_In_ DWORD cbData,
_Out_ LPDWORD pcbData
);
参数
-
hPrinter [in]
-
要获取其配置数据的打印机的句柄。 使用 OpenPrinter 或 AddPrinter 函数检索打印机句柄。
-
dwIndex [in]
-
指定要检索的配置数据值的索引值。
对于指定的打印机句柄,首次调用 EnumPrinterData 时,将此参数设置为零。 然后,对于涉及同一打印机的后续调用,将参数递增 1,直到函数返回ERROR_NO_MORE_ITEMS。 有关详细信息,请参阅以下“备注”部分。
如果使用 cbValueName 和 cbData 参数的说明中提到的技术来获取足够的缓冲区大小值,请在指定打印机句柄的第一次调用 EnumPrinterData 时将这两个参数设置为零, 则 dwIndex 的值对于该调用并不重要。 在下一次调用 EnumPrinterData 时,将 dwIndex 设置为零,以启动实际枚举过程。
配置数据值不排序。 新值将具有任意索引。 这意味着 EnumPrinterData 函数可以按任意顺序返回值。
-
pValueName [out]
-
指向缓冲区的指针,该缓冲区接收配置数据值的名称,包括终止 null 字符。
-
cbValueName [in]
-
pValueName 指向的缓冲区的大小(以字节为单位)。
如果希望操作系统提供足够的缓冲区大小,请在指定打印机句柄的第一次调用 EnumPrinterData 时将此参数和 cbData 参数都设置为零。 当函数返回时, 由正确值名称指向的变量 将包含足以成功枚举打印机的所有配置数据值名称的缓冲区大小。
-
rvalueName [out]
-
指向变量的指针,该变量接收 pValueName 指向的缓冲区中存储的字节数。
-
pType [out]
-
指向变量的指针,该变量接收指示存储在指定值中的数据类型的代码。 有关可能的类型代码的列表,请参阅 注册表值类型。 如果不需要类型代码,则 pType 参数可以为 NULL 。
-
pData [out]
-
指向接收配置数据值的缓冲区的指针。
如果不需要配置数据值,此参数可以为 NULL 。
-
cbData [in]
-
pData 指向的缓冲区的大小(以字节为单位)。
如果希望操作系统提供足够的缓冲区大小,请将此参数和 cbValueName 参数都设置为零,以便首次调用指定的打印机句柄 的 EnumPrinterData 。 当函数返回时, 由data 指向的变量将包含一个缓冲区大小,该缓冲区大小足以成功枚举打印机的所有配置数据值名称。
-
sqlData [out]
-
指向变量的指针,该变量接收 pData 指向的缓冲区中存储的字节数。
如果 pData 为 NULL,此参数可以为 NULL。
返回值
如果函数成功,则返回值为 ERROR_SUCCESS。
如果函数失败,则返回值为系统错误代码。
当指定打印机句柄没有更多要检索的配置数据值时,函数将返回ERROR_NO_MORE_ITEMS。
备注
注意
这是一个阻塞或同步函数,可能不会立即返回。 此函数的返回速度取决于运行时因素,例如网络状态、打印服务器配置以及编写应用程序时难以预测的打印机驱动程序实现因素。 从管理与用户界面交互的线程调用此函数可能会使应用程序看起来无响应。
EnumPrinterData 检索 SetPrinterData 函数的打印机配置数据集。 打印机的配置数据由一组命名值和类型值组成。 每次调用 EnumPrinterData 函数时,都会获取其中一个值及其名称和类型代码。 连续多次调用 EnumPrinterData 函数以获取打印机的所有配置数据值。
打印机配置数据存储在注册表中。 枚举打印机配置数据时,应避免调用可能会更改该数据的注册表函数。
如果希望操作系统提供足够的缓冲区大小,请先调用 EnumPrinterData ,同时将 cbValueName 和 cbData 参数都设置为零,如前面 Parameters 部分所述。 dwIndex 的值对于此调用无关紧要。 当函数返回时,*gpValueName 和 *bdata 将包含足够大的缓冲区大小,以枚举打印机的所有配置数据值名称和值。 在下一次调用中,分配值名称和数据缓冲区,将 cbValueName 和 cbData 设置为已分配缓冲区的大小(以字节为单位),并将 dwIndex 设置为零。 此后,继续调用 EnumPrinterData 函数,每次递增 dwIndex 一次,直到该函数返回ERROR_NO_MORE_ITEMS。
要求
要求 | 值 |
---|---|
最低受支持的客户端 |
Windows 2000 Professional [仅限桌面应用] |
最低受支持的服务器 |
Windows 2000 Server [仅限桌面应用] |
标头 |
|
库 |
|
DLL |
|
Unicode 和 ANSI 名称 |
EnumPrinterDataW (Unicode) 和 EnumPrinterDataA (ANSI) |