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 指向一个 LONG，该 LONG 指定由 StartDoc 函数返回的打印作业标识符。 |
| 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 调用方提供的结构。 （如果 NULL，GDI 将使用调用方提供的结构。 |
| DOCUMENTEVENT_ESCAPE | 用作 ExtEscape 函数的 lpszOutData 参数的缓冲区指针。 |
| DOCUMENTEVENT_QUERYFILTER | 调用方提供的指向包含 DOCEVENT_FILTER 结构的缓冲区的指针。 |
| DOCUMENTEVENT_RESETDCPRE | 指向驱动程序提供的 DEVMODEW 结构的指针，GDI 使用该结构，而不是由 ResetDC 函数调用方提供的结构。 （如果 NULL，GDI 将使用调用方提供的结构。 |
| 所有其他 iEsc 值 | 未使用。 |
返回值
函数的返回值取决于为 iEsc提供的转义。 对于某些转义代码，不使用返回值（请参阅第二个值列表）。 如果函数提供返回值，则它必须是下列值之一：
| 返回代码 | 描述 |
|---|---|
| DOCUMENTEVENT_FAILURE | 驱动程序支持由 iEsc标识的转义代码，但发生了故障。 |
| DOCUMENTEVENT_SUCCESS | 驱动程序已成功处理由 iEsc标识的转义代码。 |
| DOCUMENTEVENT_UNSUPPORTED | 驱动程序不支持由 iEsc标识的转义代码。 |
言论
打印机接口 DLL 可以选择提供 DrvDocumentEvent 函数来执行与呈现文档关联的 GDI 调用的预处理或后处理。 当应用程序调用 GDI 客户端时，从用户模式 GDI 客户端调用 DrvDocumentEvent 函数。
对于 iEsc 值DOCUMENTEVENT_QUERYFILTER，后台处理程序可以通过两种方式解释 DrvDocumentEvent 返回的DOCUMENTEVENT_SUCCESS值，具体取决于驱动程序是否修改了 DOCEVENT_FILTER 结构的某些成员。 （pvOut 参数指向此结构。当后台处理程序为此类型的结构分配内存时，它会将此结构的两个成员（cElementsReturned 和 cElementsNeeded）初始化为已知值。 DrvDocumentEvent 返回后，后台处理程序将确定这些成员的值是否已更改，并使用该信息解释 drvDocumentEvent 返回值。 下表总结了这种情况。
| 返回值 | cElementsReturned、cElementsNeeded 的状态 | 意义 |
|---|---|---|
| DOCUMENTEVENT_SUCCESS | 驱动程序未对任一成员进行更改。 | 后台处理程序将此返回值解释为等效于DOCUMENTEVENT_UNSUPPORTED。 后台处理程序无法从驱动程序中检索事件筛选器，因此它会保留对所有事件的调用 DrvDocumentEvent。 |
| DOCUMENTEVENT_SUCCESS | 驱动程序写信给一个或两个成员。 | 后台处理程序接受此返回值而不解释。 如果驱动程序只写信给 cElementsNeeded 和 cElementsReturned中的一个，则后台处理程序会将未更改的成员视为值为零。 后台处理程序筛选掉 aDocEventCall 成员 DOCEVENT_FILTER中列出的所有事件。 |
| 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 后台处理程序后，该函数可以显示用户界面。 例如，在处理 GDI 的 StartDoc 函数之前，传真驱动程序的 DrvDocumentEvent 函数可能会向用户显示对话框。
在 64 位版本的 Windows 上运行 32 位应用程序时，以下限制适用：
DrvDocumentEvent 应调用的唯一 GDI 函数是 ExtEscape，只应使用专用转义。
DrvDocumentEvent 调用其他 GDI 函数可能会产生未定义的行为。
要求
| 要求 | 价值 |
|---|---|
| 目标平台 | 桌面 |
| 标头 | winddiui.h （包括 Winddiui.h） |