IPrintOemUI2::D ocumentEvent 方法 (prcomoem.h)
方法 IPrintOemUI2::DocumentEvent
允许 UI 插件替换核心驱动程序 UI 模块的默认 DrvDocumentEvent DDI 实现。
语法
HRESULT DocumentEvent(
HANDLE hPrinter,
HDC hdc,
INT iEsc,
ULONG cbIn,
PVOID pvIn,
ULONG cbOut,
PVOID pvOut,
PINT piResult
);
参数
hPrinter
调用方提供的打印机句柄。
hdc
调用方提供的设备上下文句柄,由 CreateDC 调用生成。 如果DOCUMENTEVENT_CREATEDCPRE iEsc ,则为零。
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 指向的缓冲区的调用方提供的大小(以字节为单位)。
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 结构的指针的地址, (如 Microsoft Windows SDK 文档) 中所述。 |
DOCUMENTEVENT_STARTDOCPOST | pvIn 指向一个 LONG,指定 StartDoc (返回的打印作业标识符,如 Windows SDK 文档) 中所述。 |
DOCUMENTEVENT_STARTDOCPRE 或 DOCUMENTEVENT_STARTDOC |
pvIn 包含指向 StartDoc 调用方提供的 DOCINFO 结构的指针的地址, (Windows SDK 文档) 中所述。 |
DOCUMENTEVENT_STARTPAGE | 未使用。 |
cbOut
如果 iEsc 是DOCUMENTEVENT_ESCAPE:
用作 ExtEscape 的 cbOutput 参数的函数提供的值。
如果 iEsc 是DOCUMENTEVENT_QUERYFILTER:
pvOut 指向的缓冲区指针的调用方提供的大小(以字节为单位)。
对于所有其他 iEsc 值:
未使用。
pvOut
函数提供的指向输出缓冲区的指针,其用法取决于为 iEsc 提供的值,如下所示。 Windows SDK 文档中介绍了 CreateDC、ExtEscape 和 ResetDC。
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 值 | 未使用。 |
piResult
指向接收以下值之一的内存位置的指针:
返回值 | 定义 |
---|---|
DOCUMENTEVENT_FAILURE | 驱动程序支持 由 iEsc 标识的转义代码,但发生故障。 |
DOCUMENTEVENT_SUCCESS | 驱动程序已成功处理 由 iEsc 标识的转义代码。 有关详细信息,另请参阅“备注”部分。 |
DOCUMENTEVENT_UNSUPPORTED | 驱动程序不支持 iEsc 标识的转义代码。 |
返回值
此方法应返回以下值之一。 有关详细信息,请参阅备注部分。
返回代码 | 说明 |
---|---|
|
UI 插件实现此方法。 |
|
UI 插件不实现此方法。 |
注解
用户界面插件的 IPrintOemUI2::DocumentEvent
方法执行的操作类型与用户模式打印机接口 DLL 导出的 DrvDocumentEvent DDI 相同。 有关文档事件及其处理方式的信息,请参阅 DrvDocumentEvent DDI 的说明。
如果提供用户界面插件,打印机驱动程序的 DrvDocumentEvent DDI 将调用 IPrintOemUI2::DocumentEvent
方法。 DrvDocumentEvent DDI 对指定的事件执行自己的处理,然后调用 IPrintOemUI2::DocumentEvent
方法来处理事件的其他处理。
当此方法使用 DOCUMENTEVENT_QUERYFILTER 的 iEsc 参数的值调用,并使用 *piResult == DOCUMENTEVENT_SUCCESS 返回时,后台处理程序可以通过两种方式之一解释此值,具体取决于 DOCEVENT_FILTER 结构的某些成员是否更改了值。 有关详细信息,请参阅 DrvDocumentEvent 的“备注”部分。
触发 DOCUMENTEVENT_QUERYFILTER 事件时,核心驱动程序会按照安装插件的顺序调用插件,直到其中一个插件返回S_OK,或者直到调用所有插件且没有一个插件S_OK返回。 这样,最多允许一个插件处理DOCUMENTEVENT_QUERYFILTER事件,并且它指定的筛选器将应用于插件链中的所有插件。
对于实现 IPrintOemUI2 接口但不需要支持 IPrintOemUI2::DocumentEvent
该方法的插件编写器,此方法应返回 iEsc 的所有值的E_NOTIMPL。 如果确实需要实现此方法,它应返回 iEsc 的所有值的S_OK。 这向核心驱动程序发出信号,表明此方法已处理相关事件。 核心驱动程序使用此方法放置在 piResult 中的值作为 DrvDocumentEvent DDI 的返回值。
要求
要求 | 值 |
---|---|
目标平台 | 桌面 |
标头 | prcomoem.h (包括 Prcomoem.h) |