Метод IPrintOemUI2::D ocumentEvent (prcomoem.h)

Статья
02/07/2025

Метод IPrintOemUI2::DocumentEvent позволяет подключаемым модулю пользовательского интерфейса заменить базовую реализацию модуля пользовательского интерфейса драйвера по умолчанию DrvDocumentEvent DDI.

Синтаксис

HRESULT DocumentEvent(
  HANDLE hPrinter,
  HDC    hdc,
  INT    iEsc,
  ULONG  cbIn,
  PVOID  pvIn,
  ULONG  cbOut,
  PVOID  pvOut,
  PINT   piResult
);

Параметры

hPrinter

Вызывающий дескриптор принтера.

hdc

Вызывающий дескриптор контекста устройства, созданный вызовом CreateDC. Это равно нулю, если iEsc DOCUMENTEVENT_CREATEDCPRE.

iEsc

Вызывающий код escape-кода, определяющий событие для обработки. Этот параметр может быть одной из следующих целочисленных констант:

Escape-код	Значение
DOCUMENTEVENT_ABORTDOC	GDI обработает вызов функции AbortDoc.
DOCUMENTEVENT_CREATEDCPOST	GDI только что обработал вызов CreateDC или функцию CreateIC. Этот escape-код не следует использовать, если не было предыдущего вызова 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, на которые будет отвечать драйвер. Это событие выдается непосредственно перед вызовом DrvDocumentEvent, который передает событие DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST	GDI только что обработал вызов функции ResetDC. Этот escape-код не следует использовать, если не было предыдущего вызова 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 содержит адрес указателя на структуру DEVMODEW, указанную в параметре pvOut в предыдущем вызове этой функции, для которой для параметра 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 содержит адрес указателя на структуру DEVMODEW, указанную в параметре pvOut в предыдущем вызове этой функции, для которой для параметра iEsc задано значение DOCUMENTEVENT_RESETDCPRE.
DOCUMENTEVENT_RESETDCPRE	pvIn содержит адрес указателя на структуру DEVMODEW, предоставляемую вызывающим ResetDC (описано в документации по пакету SDK для Microsoft Windows).
DOCUMENTEVENT_STARTDOCPOST	pvIn указывает на long, указывающее идентификатор задания печати, возвращенный StartDoc (описано в документации по пакету SDK для Windows).
DOCUMENTEVENT_STARTDOCPRE или DOCUMENTEVENT_STARTDOC	pvIn содержит адрес указателя на структуру DOCINFO, предоставляемую вызывающим элементом StartDoc (как описано в документации по пакету SDK для Windows).
DOCUMENTEVENT_STARTPAGE	Не используется.

cbOut

Если iEsc DOCUMENTEVENT_ESCAPE:

Предоставленное функцией значение, используемое в качестве параметра cbOutput для ExtEscape.

Если iEsc DOCUMENTEVENT_QUERYFILTER:

Предоставленный вызывающим объектом размер в байтах указателя буфера на pvOut.

Для всех остальных значений iEsc:

Не используется.

pvOut

Указатель на выходной буфер, используемый функцией, зависит от значения, предоставленного для iEsc, как показано ниже. CreateDC, ExtEscapeи ResetDC описаны в документации по пакету SDK для Windows.

Констант iEsc	pvOut Содержимое
DOCUMENTEVENT_CREATEDCPRE	Указатель на предоставленную драйвером структуру DEVMODEW, которая использует GDI вместо той, которую предоставляет вызывающий объект CreateDC. (Если null, GDI использует структуру, предоставляемую вызывающим пользователем.)
DOCUMENTEVENT_ESCAPE	Указатель буфера, используемый в качестве параметра lpszOutData для ExtEscape.
DOCUMENTEVENT_QUERYFILTER	Вызывающий указатель на буфер, содержащий DOCEVENT_FILTER структуру.
DOCUMENTEVENT_RESETDCPRE	Указатель на структуру DEVMODEW, предоставляемую драйвером, которая использует GDI вместо той, которую предоставляет вызывающий объект ResetDC. (Если null, GDI использует структуру, предоставляемую вызывающим пользователем.)
Все остальные значения iEsc	Не используется.

piResult

Указатель на расположение памяти, которое получает одно из следующих значений:

Возвращаемое значение	Определение
DOCUMENTEVENT_FAILURE	Драйвер поддерживает escape-код, определенный iEsc, но произошел сбой.
DOCUMENTEVENT_SUCCESS	Драйвер успешно обработал escape-код, определенный iEsc. Дополнительные сведения см. в разделе "Примечания".
DOCUMENTEVENT_UNSUPPORTED	Драйвер не поддерживает escape-код, определенный iEsc.

Возвращаемое значение

Этот метод должен возвращать одно из следующих значений. Дополнительные сведения см. в разделе "Примечания".

Возвращаемый код	Описание
S_OK	Подключаемый модуль пользовательского интерфейса реализует этот метод.
E_NOTIMPL	Подключаемый модуль пользовательского интерфейса не реализует этот метод.

Замечания

Метод IPrintOemUI2::DocumentEvent пользовательского интерфейса выполняет те же типы операций, что и DDI drvDocumentEvent DDI, экспортируемых библиотеками DLL интерфейса принтера в пользовательском режиме. Сведения о событиях документа и их обработке см. в описании DrvDocumentEvent DDI.

Если вы предоставляете подключаемый модуль пользовательского интерфейса, драйвер принтера DrvDocumentEvent DDI вызывает метод IPrintOemUI2::DocumentEvent. DDI DrvDocumentEvent выполняет собственную обработку указанного события, а затем вызывает метод IPrintOemUI2::DocumentEvent для обработки дополнительной обработки события.

При вызове этого метода со значением параметра iEsc DOCUMENTEVENT_QUERYFILTER и возвращается с помощью *piResult == DOCUMENTEVENT_SUCCESS, средство spooler может интерпретировать это значение двумя способами, в зависимости от того, изменились ли определенные члены структуры DOCEVENT_FILTER структуры. Дополнительные сведения см. в разделе "Примечания" для DrvDocumentEvent.

При срабатывании события DOCUMENTEVENT_QUERYFILTER основной драйвер вызывает подключаемые модули в том порядке, в котором они были установлены, пока один из них не возвращает S_OK, или до тех пор, пока все подключаемые модули не были вызваны, и ни один из них не вернул S_OK. Таким образом, хотя бы один подключаемый модуль может обрабатывать событие DOCUMENTEVENT_QUERYFILTER, а фильтр, который он указывает, применяется ко всем подключаемым модулям в цепочке подключаемых модулей.

Для подключаемого модуля записи, реализующего интерфейс IPrintOemUI2, но не требует поддержки метода IPrintOemUI2::DocumentEvent, этот метод должен возвращать E_NOTIMPL для всех значений iEsc. Если необходимо реализовать этот метод, он должен возвращать S_OK для всех значений iEsc. Это сигнализирует основному драйверу, что этот метод обрабатывает соответствующее событие. Основной драйвер использует значение, которое этот метод помещает в piResult в качестве возвращаемого значения для DrvDocumentEvent DDI.