DocumentProperties 函数

  • 项目

DocumentProperties 函数检索或修改打印机初始化信息，或显示指定打印机的打印机配置属性表。

语法

LONG DocumentProperties(
  _In_  HWND     hWnd,
  _In_  HANDLE   hPrinter,
  _In_  LPTSTR   pDeviceName,
  _Out_ PDEVMODE pDevModeOutput,
  _In_  PDEVMODE pDevModeInput,
  _In_  DWORD    fMode
);

参数

hWnd [in]

打印机配置属性表的父窗口的句柄。

hPrinter [in]

打印机对象的句柄。 使用 OpenPrinter 或 AddPrinter 函数检索打印机句柄。

pDeviceName [in]

指向以 null 结尾的字符串的指针，该字符串指定显示打印机配置属性表的设备的名称。

pDevModeOutput [out]

指向 DEVMODE 结构的指针，该结构接收用户指定的打印机配置数据。

pDevModeInput [in]

指向操作系统用于初始化属性表控件的 DEVMODE 结构的指针。

仅当在 fMode 参数中设置了DM_IN_BUFFER标志时，才使用此参数。 如果未设置 DM_IN_BUFFER ，操作系统将使用打印机的默认 DEVMODE。

fMode [in]

函数执行的操作。 如果此参数为零， DocumentProperties 函数将返回打印机驱动程序的 DEVMODE 数据结构所需的字节数。 否则，请使用以下一个或多个常量来构造此参数的值：但请注意，若要更改打印设置，应用程序必须至少指定一个输入值和一个输出值。

值 含义
DM_IN_BUFFER
 输入值。 在提示、复制或更新之前，函数会将打印机驱动程序的当前打印设置与 pDevModeInput 参数指定的 DEVMODE 结构中的设置合并。 函数仅更新 由 DEVMODE 结构的 dmFields 成员指定的那些成员的结构。 此值也定义为 DM_MODIFY。 如果合并期间发生冲突，pDevModeInput 指定的 DEVMODE 结构中的设置将替代打印机驱动程序的当前打印设置。
DM_IN_PROMPT
 输入值。 函数显示打印机驱动程序的打印设置属性表，然后将打印机的 DEVMODE 数据结构中的设置更改为用户指定的值。 此值也定义为 DM_PROMPT。
DM_OUT_BUFFER
 输出值。 函数将打印机驱动程序的当前打印设置（包括专用数据）写入 pDevModeOutput 参数指定的 DEVMODE 数据结构。 调用方必须分配足够大的缓冲区才能包含信息。 如果位 DM_OUT_BUFFER 集是明确的，则 pDevModeOutput 参数可以为 NULL。 此值也定义为 DM_COPY。

返回值

如果 fMode 参数为零，则返回值是包含打印机驱动程序初始化数据所需的缓冲区大小。 请注意，如果打印机驱动程序将专用数据追加到结构，则此缓冲区可能大于 DEVMODE 结构。

如果函数显示属性表，则返回值为 IDOK 或 IDCANCEL，具体取决于用户选择的按钮。

如果函数未显示属性表并且成功，则返回值为 IDOK。

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

备注

注意

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

可以通过调用 GetPrinter 函数来获取 pDeviceName 参数指向的字符串。

打印机驱动程序实际使用的 DEVMODE 结构包含上面定义的与设备无关的部件 () 后跟特定于驱动程序的部件，该部件的大小和内容因每个驱动程序和驱动程序版本而异。 由于此驱动程序依赖性，应用程序在为其分配缓冲区之前查询驱动程序以获取 DEVMODE 结构的正确大小非常重要。

若要对应用程序的本地打印设置进行更改，应用程序应执行以下步骤：

  1. 通过调用 DocumentProperties 并在 fMode 参数中指定零，获取完整 DEVMODE 结构所需的字节数。
  2. 为完整的 DEVMODE 结构分配内存。
  3. 通过调用 DocumentProperties 获取当前打印机设置。 将指向步骤 2 中分配的 DEVMODE 结构的指针作为 pDevModeOutput 参数传递，并指定 DM_OUT_BUFFER 值。
  4. 修改返回的 DEVMODE 结构的相应成员，并通过在 DEVMODE 的 dmFields 成员中设置相应的位来指示哪些成员已更改。
  5. 调用 DocumentProperties 并将修改后的 DEVMODE 结构作为 pDevModeInput 和 pDevModeOutput 参数传递回来，并指定使用 OR 运算符) 组合的DM_IN_BUFFER值和DM_OUT_BUFFER值 (。第三次调用 DocumentProperties 返回的 DEVMODE 结构可用作对 CreateDC 函数的调用中的参数。

若要使用当前打印机设置创建打印机设备上下文的句柄，只需调用 DocumentProperties 两次，如上所述。 第一次调用获取完整 DEVMODE 的大小，第二次调用使用当前打印机设置初始化 DEVMODE 。 将初始化的 DEVMODE 传递给 CreateDC 以获取打印机设备上下文的句柄。

要求

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

另请参阅

打印

打印后台处理程序 API 函数

AdvancedDocumentProperties

CreateDC

DEVMODE

GetPrinter

OpenPrinter