Функция DocumentEvent
Функция DocumentEvent — это обработчик событий, связанных с печатью документа.
Синтаксис
HRESULT DocumentEvent(
_In_ HANDLE hPrinter,
_In_ HDC hdc,
INT iEsc,
ULONG cbIn,
_In_ PVOID pvIn,
ULONG cbOut,
_Out_ PVOID pvOut
);
Параметры
-
hPrinter [in]
-
Дескриптор объекта принтера. Используйте функцию OpenPrinter или AddPrinter для получения дескриптора принтера.
-
hdc [in]
-
Дескриптор контекста устройства, созданный вызовом CreateDC. Значение равно нулю, если для iEsc задано значение DOCUMENTEVENT_CREATEDCPRE. Ограничения на печать из 32-разрядного приложения в 64-разрядной версии Windows см. в примечаниях.
-
iEsc
-
Escape-код, определяющий обрабатываемое событие. Этот параметр может быть одной из следующих целых констант.
Постоянно Событие - DOCUMENTEVENT_ABORTDOC
GDI будет обрабатывать вызов функции AbortDoc . - DOCUMENTEVENT_CREATEDCPOST
GDI только что обработал вызов функции CreateDC или CreateIC .
Этот escape-код не следует использовать, если не было предыдущего вызова DocumentEvent с 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 , который передает событие DOCUMENTEVENT_CREATEDCPRE. - DOCUMENTEVENT_RESETDCPOST
GDI только что обработал вызов функции ResetDC .
Этот escape-код не следует использовать, если не было предыдущего вызова DocumentEvent с iEsc , для которого задано значение DOCUMENTEVENT_RESETDCPRE.- DOCUMENTEVENT_RESETDCPRE
GDI будет обрабатывать вызов функции ResetDC . - DOCUMENTEVENT_STARTDOCPOST
GDI только что обработал вызов функции StartDoc . - DOCUMENTEVENT_STARTDOCPRE или DOCUMENTEVENT_STARTDOC
GDI будет обрабатывать вызов функции StartDoc . - DOCUMENTEVENT_STARTPAGE
GDI обработает вызов функции StartPage . -
Cbin
-
Размер буфера в байтах, на который указывает pvIn.
-
pvIn [in]
-
Указатель на буфер. Содержимое буфера зависит от значения iEsc, как показано в следующей таблице.
Постоянно Содержимое pvin - DOCUMENTEVENT_ABORTDOC
Не используется. - DOCUMENTEVENT_CREATEDCPOST
PvIn содержит адрес указателя на структуру DEVMODE , указанную в параметре pvOut в предыдущем вызове этой функции, для которой для параметра iEsc задано значение DOCUMENTEVENT_CREATEDCPRE. - DOCUMENTEVENT_CREATEDCPRE
PvIn указывает на структуру DOCEVENT_CREATEDCPRE, которая описана в пакете средств разработки драйверов Windows. - DOCUMENTEVENT_DELETEDC
Не используется. - DOCUMENTEVENT_ENDDOCPOST
Не используется. - DOCUMENTEVENT_ENDDOCPRE или DOCUMENTEVENT_ENDDOC
Не используется. - DOCUMENTEVENT_ENDPAGE
Не используется. - DOCUMENTEVENT_ESCAPE
PvIn указывает на структуру DOCEVENT_ESCAPE, которая описана в пакете средств разработки драйверов Windows. - DOCUMENTEVENT_QUERYFILTER
То же, что и для DOCUMENTEVENT_CREATEDCPRE. - DOCUMENTEVENT_RESETDCPOST
PvIn содержит адрес указателя на структуру DEVMODE , указанную в параметре pvOut в предыдущем вызове этой функции, для которой для параметра iEsc задано значение DOCUMENTEVENT_RESETDCPRE. - DOCUMENTEVENT_RESETDCPRE
PvIn содержит адрес указателя на структуру DEVMODE , предоставляемую вызывающим элементом ResetDC. - DOCUMENTEVENT_STARTDOCPOST
pvIn указывает на LONG, указывающее идентификатор задания печати, возвращаемый StartDoc. - DOCUMENTEVENT_STARTDOCPRE или DOCUMENTEVENT_STARTDOC
PvIn содержит адрес указателя на структуру DOCINFO , предоставляемую вызывающим элементом StartDoc. - DOCUMENTEVENT_STARTPAGE
Не используется. - *cbOut*
-
Значение Значение IDOCUMENTEVENT_QUERYFILTER Размер в байтах указателя буфера на pvOut. DOCUMENTEVENT_ESCAPE Значение, используемое в качестве параметра cbOutput для ExtEscape. Для всех остальных значений IEsc не используется. -
pvOut [out]
-
Указатель на буфер. Содержимое буфера зависит от значения, предоставленного для iEsc, как показано в следующей таблице.
Постоянно Содержимое pvOut - DOCUMENTEVENT_CREATEDCPRE
Указатель на предоставленную драйвером структуру DEVMODE , которую GDI использует вместо той, которую предоставляет вызывающий объект CreateDC . (Если значение NULL, GDI использует предоставленную вызывающим объектом структуру.) - DOCUMENTEVENT_ESCAPE
Указатель на буфер, используемый в качестве параметра lpszOutData для ExtEscape. - DOCUMENTEVENT_QUERYFILTER
Указатель на буфер, содержащий структуру DOCEVENT_FILTER, которая описана в пакете средств разработки драйверов Windows. - DOCUMENTEVENT_RESETDCPRE
Указатель на предоставленную драйвером структуру DEVMODE , которая GDI использует вместо той, которую предоставляет вызывающий объект ResetDC . (Если значение NULL, GDI использует предоставленную вызывающим объектом структуру.)
Возвращаемое значение
Возвращаемое значение функции зависит от escape-файла, предоставленного для iEsc. Для некоторых escape-кодов возвращаемое значение не используется (см. ниже). Если функция предоставляет возвращаемое значение, оно должно быть одним из следующих значений.
| Возвращаемое значение | Значение |
|---|---|
| DOCUMENTEVENT_FAILURE | Драйвер поддерживает escape-код, определенный iEsc, но произошел сбой. |
| DOCUMENTEVENT_SUCCESS | Драйвер успешно обработал escape-код, определенный iEsc. |
| DOCUMENTEVENT_UNSUPPORTED | Драйвер не поддерживает escape-код, определенный iEsc. |
В следующем списке указывается, какие escape-коды требуют возвращаемого значения и которые не имеют значения, а также объясняет смысл DOCUMENTEVENT_SUCCESS, DOCUMENTEVENT_FAILURE и DOCUMENTEVENT_UNSUPPORTED кодов возврата.
| Возвращаемое значение | Значение |
|---|---|
| DOCUMENTEVENT_ABORTDOC | Возвращаемое значение не используется и не должно быть прочитано. |
| DOCUMENTEVENT_CREATEDCPOST | Возвращаемое значение не используется и не должно быть прочитано. |
| DOCUMENTEVENT_CREATEDCPRE | DOCUMENTEVENT_FAILURE — GDI не создает контекст устройства или контекст информации и предоставляет возвращаемое значение 0 для CreateDC или CreateIC. |
| DOCUMENTEVENT_DELETEDC | Возвращаемое значение не используется и не должно быть прочитано. |
| DOCUMENTEVENT_ENDDOCPOST | Возвращаемое значение не используется и не должно быть прочитано. |
| DOCUMENTEVENT_ENDDOCPRE или DOCUMENTEVENT_ENDDOC | Возвращаемое значение не используется и не должно быть прочитано. |
| DOCUMENTEVENT_ENDPAGE | Возвращаемое значение не используется и не должно быть прочитано. |
| DOCUMENTEVENT_ESCAPE | Возвращаемое значение не используется и не должно быть прочитано. |
| DOCUMENTEVENT_QUERYFILTER | См. заметки. |
| DOCUMENTEVENT_RESETDCPOST | Возвращаемое значение не используется и не должно быть прочитано. |
| DOCUMENTEVENT_RESETDCPRE | DOCUMENTEVENT_FAILURE — GDI не сбрасывает контекст устройства и предоставляет возвращаемое значение 0 для ResetDC. |
| DOCUMENTEVENT_STARTDOCPOST | DOCUMENTEVENT_FAILURE — GDI вызывает AbortDoc , чтобы остановить документ, а затем предоставляет возвращаемое значение SP_ERROR для StartDoc. |
| DOCUMENTEVENT_STARTDOCPRE или DOCUMENTEVENT_STARTDOC | DOCUMENTEVENT_FAILURE — GDI не запускает документ и предоставляет возвращаемое значение SP_ERROR для StartDoc. |
| DOCUMENTEVENT_STARTPAGE | DOCUMENTEVENT_FAILURE — GDI не запускает страницу и предоставляет возвращаемое значение SP_ERROR для StartPage. |
Remarks
Для значения iEsc DOCUMENTEVENT_QUERYFILTER обработчик может интерпретировать DOCUMENTEVENT_SUCCESS значение, возвращаемое DocumentEvent двумя способами, в зависимости от того, изменил ли драйвер определенные члены структуры DOCEVENT_FILTER (который задокументирован в пакете средств разработки драйверов Windows). (Параметр pvOut указывает на эту структуру.) Когда spooler выделяет память для структуры этого типа, она инициализирует два члена этой структуры cElementsReturned и cElementsNeeded для известных значений. После возврата DocumentEvent средство spooler определяет, изменились ли значения этих элементов, и использует эти сведения для интерпретации возвращаемого значения DocumentEvent . В следующей таблице приведены сведения об этой ситуации.
| Возвращаемое значение | Состояние cElementsReturned и cElementsNeeded | Значение |
|---|---|---|
| DOCUMENTEVENT_SUCCESS |
Драйвер не изменился ни на один из участников. |
Средство очереди интерпретирует это возвращаемое значение как эквивалентное DOCUMENTEVENT_UNSUPPORTED. Не удается получить фильтр событий из драйвера, поэтому он сохраняется при вызове DocumentEvent для всех событий. |
| DOCUMENTEVENT_SUCCESS |
Водитель написал одному или обоим членам. |
Spooler принимает это возвращаемое значение без интерпретации. Если драйвер написал только один из cElementsNeeded и cElementsReturned, то spooler считает, что без изменений член имеет нулевое значение. Spooler фильтрует все события, перечисленные в члене DOCEVENT_FILTER aDocEventCall (который описан в пакете средств разработки драйверов Windows). |
| DOCUMENTEVENT_UNSUPPORTED |
Неприменимо |
Драйвер не поддерживает DOCUMENTEVENT_QUERYFILTER. Не удается получить фильтр событий из драйвера, поэтому он сохраняется при вызове DocumentEvent для всех событий. |
| DOCUMENTEVENT_FAILURE |
Неприменимо |
Драйвер поддерживает DOCUMENTEVENT_QUERYFILTER, но возникла внутренняя ошибка. Не удается получить фильтр событий из драйвера, поэтому он сохраняется при вызове DocumentEvent для всех событий. |
Если escape-код, предоставленный в параметре iEsc , DOCUMENTEVENT_CREATEDCPRE, применяются следующие правила:
- Если задание отправляется непосредственно на принтер без очистки, pvIn-pszDevice> указывает на имя принтера. (Дополнительные сведения см. в документации по структуре DOCEVENT_CREATEDCPRE в пакете средств разработки драйверов Windows.)
- Если задание копируется, pvIn-pszDevice> указывает на имя порта принтера.
Примечание
Следующие ограничения применяются при запуске 32-разрядного приложения в 64-разрядной версии Windows. Единственная функция GDI, вызываемая DocumentEvent , — ExtEscape, и следует использовать только частные экраны. Вызовы DocumentEvent к другим функциям GDI могут привести к неопределенному поведению.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента |
Windows Vista [только классические приложения] |
| Минимальная версия сервера |
Windows Server 2008 [только классические приложения] |
| Заголовок |
|
| Имя в кодировке Юникод и ANSI |
DocumentEventW (Юникод) и DocumentEventA (ANSI) |