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

Статья
03/14/2023

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

Синтаксис

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 (описано в документации по Microsoft Windows SDK).
DOCUMENTEVENT_STARTDOCPOST	pvIn указывает на значение LONG, указывающее идентификатор задания печати, возвращаемый startDoc (описано в документации по Windows SDK).
DOCUMENTEVENT_STARTDOCPRE или DOCUMENTEVENT_STARTDOC	pvIn содержит адрес указателя на структуру DOCINFO, предоставляемую вызывающим элементом StartDoc (как описано в документации windows SDK).
DOCUMENTEVENT_STARTPAGE	Не используется.

cbOut

Если iEsc DOCUMENTEVENT_ESCAPE:

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

Если iEsc DOCUMENTEVENT_QUERYFILTER:

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

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

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

pvOut

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

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, экспортируемый библиотеками DLL интерфейса принтера пользовательского режима. Сведения о событиях документа и способах их обработки см. в описании DDI DrvDocumentEvent .

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

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

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

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