DrvDocumentEvent 函数 (winddiui.h)
打印机接口 DLL 的 DrvDocumentEvent 函数可以处理与打印文档相关的某些事件。
语法
int DrvDocumentEvent(
HANDLE hPrinter,
HDC hdc,
int iEsc,
ULONG cbIn,
[in] PVOID pvIn,
ULONG cbOut,
[out] PVOID pvOut
);
参数
hPrinter
调用方提供的打印机句柄。
hdc
由 CreateDC 生成的调用方提供的设备上下文句柄 如果 iEsc 设置为 DOCUMENTEVENT_CREATEDCPRE，则为零。 有关在 64 位版本的 Windows 上从 32 位应用程序打印的限制，请参阅下面的 “备注 ”部分。
iEsc
调用方提供的转义代码标识要处理的事件。
有关在 64 位版本的 Windows 上从 32 位应用程序打印的限制，请参阅下面的 “备注 ”部分。
此参数可以是以下整数常量之一：
| iEsc 常量 | 事件 |
|---|---|
| DOCUMENTEVENT_ABORTDOC | GDI 即将处理对其 AbortDoc 函数的调用。 |
| DOCUMENTEVENT_CREATEDCPOST | GDI 刚刚处理了对其 CreateDC 或 CreateIC 函数的调用。 除非之前调用 DrvDocumentEvent 且 iEsc 设置为 DOCUMENTEVENT_CREATEDCPRE，否则不应使用此转义代码。 |
| DOCUMENTEVENT_CREATEDCPRE | GDI 即将处理对其 CreateDC 或 CreateIC 函数的调用。 |
| DOCUMENTEVENT_DELETEDC | GDI 即将处理对其 DeleteDC 函数的调用。 |
| DOCUMENTEVENT_ENDDOCPOST | GDI 刚刚处理了对其 EndDoc 函数的调用。 |
| DOCUMENTEVENT_ENDDOCPRE或DOCUMENTEVENT_ENDDOC | GDI 即将处理对其 EndDoc 函数的调用。 |
| DOCUMENTEVENT_ENDPAGE | GDI 即将处理对其 EndPage 函数的调用。 |
| DOCUMENTEVENT_ESCAPE | GDI 即将处理对其 ExtEscape 函数的调用。 |
| DOCUMENTEVENT_QUERYFILTER | DOCUMENTEVENT_QUERYFILTER 事件表示后台处理程序有机会在驱动程序中查询驱动程序，以获取驱动程序将响应的 DOCUMENTEVENT_XXX 事件的列表。 此事件是在调用通过 DOCUMENTEVENT_CREATEDCPRE 事件的 DrvDocumentEvent 之前发出的。 |
| DOCUMENTEVENT_RESETDCPOST | GDI 刚刚处理了对其 ResetDC 函数的调用。 除非以前调用 过 DrvDocumentEvent 且 iEsc 设置为 DOCUMENTEVENT_RESETDCPRE，否则不应使用此转义代码。 |
| DOCUMENTEVENT_RESETDCPRE | GDI 即将处理对其 ResetDC 函数的调用。 |
| DOCUMENTEVENT_STARTDOCPOST | GDI 刚刚处理了对其 StartDoc 函数的调用。 |
| DOCUMENTEVENT_STARTDOCPRE或DOCUMENTEVENT_STARTDOC | GDI 即将处理对其 StartDoc 函数的调用。 |
| DOCUMENTEVENT_STARTPAGE | GDI 即将处理对其 StartPage 函数的调用。 |
cbIn
pvIn 指向的缓冲区的调用方提供的大小（以字节为单位）。
[in] pvIn
调用方提供的指针，其用法取决于为 iEsc 提供的值，如下所示：
| iEsc 常量 | pvIn 内容 |
|---|---|
| DOCUMENTEVENT_ABORTDOC | 未使用。 |
| DOCUMENTEVENT_CREATEDCPOST | pvIn 包含指向在上一次对此函数的调用中 pvOut 参数中指定的 DEVMODEW 结构的指针的地址，iEsc 参数已设置为DOCUMENTEVENT_CREATEDCPRE。 |
| DOCUMENTEVENT_CREATEDCPRE | pvIn 指向 DOCEVENT_CREATEDCPRE 结构。 |
| DOCUMENTEVENT_DELETEDC | 未使用。 |
| DOCUMENTEVENT_ENDDOCPOST | 未使用。 |
| DOCUMENTEVENT_ENDDOCPRE或DOCUMENTEVENT_ENDDOC | 未使用。 |
| DOCUMENTEVENT_ENDPAGE | 未使用。 |
| DOCUMENTEVENT_ESCAPE | pvIn 指向 DOCEVENT_ESCAPE 结构。 |
| DOCUMENTEVENT_QUERYFILTER | 与 DOCUMENTEVENT_CREATEDCPRE 相同。 |
| DOCUMENTEVENT_RESETDCPOST | pvIn 包含指向在上一次对此函数的调用中 pvOut 参数中指定的 DEVMODEW 结构的指针的地址，其 iEsc 参数已设置为DOCUMENTEVENT_RESETDCPRE。 |
| DOCUMENTEVENT_RESETDCPRE | pvIn 包含由 ResetDC 函数的调用方提供的 DEVMODEW 结构的指针的地址。 |
| DOCUMENTEVENT_STARTDOCPOST | pvIn 指向指定 StartDoc 函数返回的打印作业标识符的 LONG。 |
| DOCUMENTEVENT_STARTDOCPRE或DOCUMENTEVENT_STARTDOC | pvIn 包含指向由 StartDoc 函数的调用方提供的 DOCINFO 结构的指针的地址。 |
| DOCUMENTEVENT_STARTPAGE | 未使用。 |
cbOut
如果 iEsc 为 DOCUMENTEVENT_ESCAPE
用作 ExtEscape 函数的 cbOutput 参数的函数提供的值。
如果 iEsc 为 DOCUMENTEVENT_QUERYFILTER
pvOut 指向的缓冲区指针的调用方提供的大小（以字节为单位）。
对于所有其他 iEsc 值
未使用。
[out] pvOut
函数提供的指向输出缓冲区的指针，其用法取决于为 iEsc 提供的值，如下所示：
| iEsc 常量 | pvOut 内容 |
|---|---|
| DOCUMENTEVENT_CREATEDCPRE | 指向驱动程序提供的 DEVMODEW 结构的指针，GDI 使用该结构，而不是 CreateDC 调用方提供的 DEVMODEW 结构。 (如果 为 NULL，GDI 将使用调用方提供的 structure.) |
| DOCUMENTEVENT_ESCAPE | 用作 ExtEscape 函数的 lpszOutData 参数的缓冲区指针。 |
| DOCUMENTEVENT_QUERYFILTER | 调用方提供的指向包含 DOCEVENT_FILTER 结构的缓冲区的指针。 |
| DOCUMENTEVENT_RESETDCPRE | 指向驱动程序提供的 DEVMODEW 结构的指针，GDI 使用该结构，而不是 ResetDC 函数调用方提供的 DEVMODEW 结构。 (如果 为 NULL，GDI 将使用调用方提供的 structure.) |
| 所有其他 iEsc 值 | 未使用。 |
返回值
函数的返回值取决于为 iEsc 提供的转义。 对于某些转义代码，不使用返回值 (查看) 的第二个值列表。 如果函数提供返回值，则它必须是下列值之一：
| 返回代码 | 说明 |
|---|---|
| DOCUMENTEVENT_FAILURE | 驱动程序支持 由 iEsc 标识的转义代码，但发生故障。 |
| DOCUMENTEVENT_SUCCESS | 驱动程序已成功处理 由 iEsc 标识的转义代码。 |
| DOCUMENTEVENT_UNSUPPORTED | 驱动程序不支持 iEsc 标识的转义代码。 |
注解
打印机接口 DLL 可以选择提供 DrvDocumentEvent 函数，以执行与呈现文档相关的 GDI 调用的预处理或后处理。 当应用程序调用 GDI 客户端时，从用户模式 GDI 客户端调用 DrvDocumentEvent 函数。
对于 DOCUMENTEVENT_QUERYFILTER 的 iEsc 值，后台处理程序可以通过两种方式解释 DrvDocumentEvent 返回的DOCUMENTEVENT_SUCCESS值，具体取决于驱动程序是否修改了 DOCEVENT_FILTER 结构的某些成员。 (pvOut 参数指向此 structure。) 当后台处理程序为此类型的结构分配内存时，它会将此结构的两个成员 cElementsReturned 和 cElementsNeeded 初始化为已知值。 DrvDocumentEvent 返回后，后台处理程序将确定这些成员的值是否已更改，并使用该信息来解释 DrvDocumentEvent 返回值。 下表总结了这种情况。
| 返回值 | cElementsReturned、cElementsNeeded 的状态 | 含义 |
|---|---|---|
| DOCUMENTEVENT_SUCCESS | 驱动程序未对任一成员进行更改。 | 后台处理程序将此返回值解释为等效于DOCUMENTEVENT_UNSUPPORTED。 后台处理程序无法从驱动程序中检索事件筛选器，因此它会保留对所有事件调用 DrvDocumentEvent 。 |
| DOCUMENTEVENT_SUCCESS | 驱动程序写入一个或两个成员。 | 后台处理程序接受此返回值，无需解释。 如果驱动程序只写入 cElementsNeeded 和 cElementsReturned 中的一个，则后台处理程序会将未更改的成员视为值为零。 后台处理程序筛选出DOCEVENT_FILTER的 aDocEventCall 成员中列出的所有事件。 |
| DOCUMENTEVENT_UNSUPPORTED | 不适用 | 驱动程序不支持DOCUMENTEVENT_QUERYFILTER。 后台处理程序无法从驱动程序中检索事件筛选器，因此它会保留对所有事件调用 DrvDocumentEvent 。 |
| DOCUMENTEVENT_FAILURE | 不适用 | 驱动程序支持DOCUMENTEVENT_QUERYFILTER，但遇到内部错误。 后台处理程序无法从驱动程序中检索事件筛选器，因此它会保留对所有事件调用 DrvDocumentEvent 。 |
如果转义代码名称没有后缀或带有 PRE 后缀，则 GDI 客户端会在调用内核模式 GDI 呈现引擎之前调用 DrvDocumentEvent 。 如果转义代码名称后缀为 POST，则 GDI 客户端会在内核模式 GDI 呈现引擎返回后调用 DrvDocumentEvent 。
如果 iEsc 参数中提供的转义代码DOCUMENTEVENT_CREATEDCPRE，则以下规则适用：
如果作业直接发送到打印机而不后台打印， 则 pvIn --> pszDevice 指向打印机名称。 (有关详细信息，请参阅 DOCEVENT_CREATEDCPRE 结构。)
如果作业正在假脱机， 则 pvIn --> pszDevice 指向打印机端口名称。
DrvDocumentEvent 函数在 GDI 客户端函数的用户模式调用方上下文中执行。 禁用 EMF 假脱机时，函数可以显示用户界面。 例如，FAX 驱动程序的 DrvDocumentEvent 函数可能会在处理 GDI 的 StartDoc 函数之前向用户显示一个对话框。
在 64 位版本的 Windows 上运行 32 位应用程序时，以下限制适用：
DrvDocumentEvent 应调用的唯一 GDI 函数是 ExtEscape，并且只应使用专用转义。
对其他 GDI 函数的 DrvDocumentEvent 调用可能会产生未定义的行为。
要求
| 要求 | 值 |
|---|---|
| 目标平台 | 桌面 |
| 标头 | winddiui.h (包括 Winddiui.h) |