Функция DrvDocumentEvent (winddiui.h)
Функция DrvDocumentEvent в библиотеке DLL интерфейса принтера может обрабатывать определенные события, связанные с печатью документа.
Синтаксис
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 , предоставляемую вызывающим элементом функции StartDoc . |
| 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 диспетчер очереди может интерпретировать значение DOCUMENTEVENT_SUCCESS, возвращаемое DrvDocumentEvent , двумя способами, в зависимости от того, изменил ли драйвер определенные элементы структуры DOCEVENT_FILTER . (Параметр pvOut указывает на эту структуру.) Когда диспетчер очереди выделяет память для структуры этого типа, он инициализирует два члена этой структуры, cElementsReturned и cElementsNeeded, для известных значений. После возврата DrvDocumentEvent диспетчер очереди очереди определяет, были ли изменены значения этих элементов, и использует эти сведения для интерпретации возвращаемого значения DrvDocumentEvent . Эта ситуация представлена в следующей таблице.
| Возвращаемое значение | Состояние cElementsReturned, cElementsNeeded | Значение |
|---|---|---|
| DOCUMENTEVENT_SUCCESS | Драйвер не вносил изменений ни в один из членов. | Очередь очереди интерпретирует это возвращаемое значение как эквивалент DOCUMENTEVENT_UNSUPPORTED. Диспетчеру очереди не удается получить фильтр событий из драйвера, поэтому он сохраняется при вызове DrvDocumentEvent для всех событий. |
| DOCUMENTEVENT_SUCCESS | Драйвер написал одному или обоим членам. | Очередь очереди принимает это возвращаемое значение без интерпретации. Если драйвер записывает данные только в один из cElementsNeeded и cElementsReturned, диспетчер очереди считает, что без изменений элемент имеет нулевое значение. Диспетчер очереди отфильтровывает все события, перечисленные в элементе aDocEventCallDOCEVENT_FILTER. |
| DOCUMENTEVENT_UNSUPPORTED | Неприменимо | Драйвер не поддерживает DOCUMENTEVENT_QUERYFILTER. Диспетчеру очереди не удается получить фильтр событий из драйвера, поэтому он сохраняется при вызове DrvDocumentEvent для всех событий. |
| DOCUMENTEVENT_FAILURE | Неприменимо | Драйвер поддерживает DOCUMENTEVENT_QUERYFILTER, но столкнулся с внутренней ошибкой. Диспетчеру очереди не удается получить фильтр событий из драйвера, поэтому он сохраняется при вызове DrvDocumentEvent для всех событий. |
Если имя escape-кода не имеет суффикса или имеет суффикс PRE, клиент GDI вызывает DrvDocumentEvent непосредственно перед вызовом подсистемы отрисовки GDI в режиме ядра. Если имя escape-кода имеет суффикс POST, клиент GDI вызывает DrvDocumentEvent сразу после возврата подсистемы отрисовки GDI в режиме ядра.
Если escape-код, указанный в параметре iEsc , DOCUMENTEVENT_CREATEDCPRE, применяются следующие правила:
Если задание отправляется непосредственно на принтер без очереди, pvIn --> pszDevice указывает на имя принтера. (Дополнительные сведения см. в разделе структура DOCEVENT_CREATEDCPRE .)
Если задание выполняется, pvIn --> pszDevice указывает на имя порта принтера.
Функция DrvDocumentEvent выполняется в контексте вызывающего объекта пользовательского режима клиентской функции GDI. Если функция spooling EMF отключена, функция может отображать пользовательский интерфейс. Например, функция DrvDocumentEvent для драйвера FAX может отображать диалоговое окно для пользователя перед обработкой функции StartDoc GDI.
При запуске 32-разрядного приложения в 64-разрядной версии Windows действуют следующие ограничения:
Единственной функцией GDI, которую должен вызывать DrvDocumentEvent , является ExtEscape, и следует использовать только закрытые escape-экраны.
Вызовы DrvDocumentEvent к другим функциям GDI могут привести к неопределенному поведению.
Требования
| Требование | Значение |
|---|---|
| Целевая платформа | Персональный компьютер |
| Верхняя часть | winddiui.h (включая Winddiui.h) |