Функция 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. Ограничения на печать из 32-разрядного приложения в 64-разрядной версии Windows см. в разделе Примечания ниже.
iEsc
Вызывающий код escape-кода, определяющий событие для обработки.
Ограничения на печать из 32-разрядного приложения в 64-разрядной версии Windows см. в разделе Примечания ниже.
Этот параметр может быть одной из следующих целочисленных констант:
| константы iEsc | Событие |
|---|---|
| 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.
[in] 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. |
| DOCUMENTEVENT_STARTDOCPOST | pvIn указывает на long, указывающее идентификатор задания печати, возвращаемый функцией StartDoc. |
| DOCUMENTEVENT_STARTDOCPRE или DOCUMENTEVENT_STARTDOC | pvIn содержит адрес указателя на структуру DOCINFO, предоставляемую вызывающим функцией StartD oc. |
| DOCUMENTEVENT_STARTPAGE | Не используется. |
cbOut
Если iEsc DOCUMENTEVENT_ESCAPE
Предоставленное функцией значение, используемое в качестве параметра cbOutput для функции ExtEscape.
Если iEsc DOCUMENTEVENT_QUERYFILTER
Предоставленный вызывающим объектом размер в байтах указателя буфера на pvOut.
Для всех остальных значений iEsc
Не используется.
[out] pvOut
Указатель на выходной буфер, который зависит от значения, предоставленного для iEsc, следующим образом:
| константы 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 | Не используется. |
Возвращаемое значение
Возвращаемое значение функции зависит от escape-файла, предоставленного для iEsc. Для некоторых кодов escape-кода возвращаемое значение не используется (см. второй список значений). Если функция предоставляет возвращаемое значение, она должна быть одной из следующих:
| Возвращаемый код | Описание |
|---|---|
| DOCUMENTEVENT_FAILURE | Драйвер поддерживает escape-код, определенный iEsc, но произошел сбой. |
| DOCUMENTEVENT_SUCCESS | Драйвер успешно обработал escape-код, определенный iEsc. |
| DOCUMENTEVENT_UNSUPPORTED | Драйвер не поддерживает escape-код, определенный iEsc. |
Замечания
Библиотека DLL интерфейса принтера может при необходимости предоставить функцию DrvDocumentEvent для выполнения предварительной обработки или последующей обработки вызовов GDI, связанных с отрисовкой документа. Вызовы функции DrvDocumentEvent выполняются из клиента GDI в пользовательском режиме, когда приложение выполняет вызовы в клиент GDI.
Для значения iEsc DOCUMENTEVENT_QUERYFILTER средство spooler может интерпретировать значение DOCUMENTEVENT_SUCCESS, возвращаемое DrvDocumentEvent двумя способами в зависимости от того, изменил ли драйвер определенные члены структуры DOCEVENT_FILTER. (Параметр pvOut указывает на эту структуру.) Когда spooler выделяет память для структуры этого типа, он инициализирует два члена этой структуры, cElementsReturned и cElementsNeeded, к известным значениям. После drvDocumentEvent возвращается, средство spooler определяет, изменились ли значения этих элементов, и использует эти сведения для интерпретации значения DrvDocumentEvent возвращаемого значения. В следующей таблице приведены сведения об этой ситуации.
| Возвращаемое значение | Состояние cElementsReturned, cElementsNeeded | Значение |
|---|---|---|
| DOCUMENTEVENT_SUCCESS | Драйвер не изменился ни на один член. | Средство spooler интерпретирует это возвращаемое значение как эквивалентное DOCUMENTEVENT_UNSUPPORTED. Spooler не может получить фильтр событий от драйвера, поэтому он сохраняется при вызове DrvDocumentEvent для всех событий. |
| DOCUMENTEVENT_SUCCESS | Драйвер написал одному или обоим членам. | Spooler принимает это возвращаемое значение без интерпретации. Если драйвер написал только один из cElementsNeed и cElementsReturned, spooler считает без изменений элемент иметь значение нуля. Spooler фильтрует все события, перечисленные в aDocEventCall члена DOCEVENT_FILTER. |
| DOCUMENTEVENT_UNSUPPORTED | Неприменимо | Драйвер не поддерживает DOCUMENTEVENT_QUERYFILTER. Spooler не может получить фильтр событий от драйвера, поэтому он сохраняется при вызове DrvDocumentEvent для всех событий. |
| DOCUMENTEVENT_FAILURE | Неприменимо | Драйвер поддерживает DOCUMENTEVENT_QUERYFILTER, но возникла внутренняя ошибка. Spooler не может получить фильтр событий от драйвера, поэтому он сохраняется при вызове DrvDocumentEvent для всех событий. |
Если имя escape-кода не имеет суффикса или суффиксировано с помощью PRE, клиент GDI вызывает DrvDocumentEvent непосредственно перед вызовом обработчика отрисовки GDI в режиме ядра. Если имя escape-кода суффиксировано с помощью POST, клиент GDI вызывает DrvDocumentEvent сразу после возврата подсистемы отрисовки GDI в режиме ядра.
Если код escape-кода, предоставленный в параметре iEsc, DOCUMENTEVENT_CREATEDCPRE, применяются следующие правила:
Если задание отправляется непосредственно на принтер без spooling, pvIn -> pszDevice указывает на имя принтера. (Дополнительные сведения см. в структуре DOCEVENT_CREATEDCPRE.)
Если задание копируется, pvIn -> pszDevice указывает на имя порта принтера.
Функция DrvDocumentEvent выполняется в контексте вызывающего пользователя функции клиента GDI. При отключении spooling EMF функция может отображать пользовательский интерфейс. Например, функция DrvDocumentEvent драйвера ФАКСа может отобразить диалоговое окно пользователю перед обработкой функции GDI StartDoc.
Следующие ограничения применяются при запуске 32-разрядного приложения в 64-разрядной версии Windows:
Единственная функция GDI, которая DrvDocumentEvent должна вызываться ExtEscape, и следует использовать только частные escape-каналы.
drvDocumentEvent вызовы других функций GDI могут привести к неопределенному поведению.
Требования
| Требование | Ценность |
|---|---|
| целевая платформа | Настольный |
| заголовка | winddiui.h (include Winddiui.h) |