Функция 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 представляет возможность для spooler запрашивать драйвер для списка событий 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. (If NULL, GDI использует структуру, предоставляемую вызывающим оператором.)
DOCUMENTEVENT_ESCAPE
 Указатель на буфер, используемый в качестве параметра lpszOutData для ExtEscape.
DOCUMENTEVENT_QUERYFILTER
 Указатель на буфер, содержащий структуру DOCEVENT_FILTER, которая задокументирована в комплекте средств разработки драйверов Windows.
DOCUMENTEVENT_RESETDCPRE
 Указатель на предоставленную драйвером структуру DEVMODE, которая GDI использует вместо той, которую предоставляет вызывающий объект ResetDC. (If 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.

Замечания

Для значения iEsc DOCUMENTEVENT_QUERYFILTER средство spooler может интерпретировать DOCUMENTEVENT_SUCCESS значение, возвращаемое DocumentEvent, двумя способами в зависимости от того, изменил ли драйвер определенные члены структуры DOCEVENT_FILTER (который документируется в пакете средств разработки драйверов Windows). (Параметр pvOut указывает на эту структуру.) Когда spooler выделяет память для структуры этого типа, она инициализирует два члена этой структуры cElementsReturned и cElementsNeeded для известных значений. После возврата DocumentEvent средство spooler определяет, изменились ли значения этих элементов, и использует эти сведения для интерпретации возвращаемого значения DocumentEvent. В следующей таблице приведены сведения об этой ситуации.

Возвращаемое значение Состояние cElementsReturned и cElementsNeeded Значение
DOCUMENTEVENT_SUCCESS
 Драйвер не изменился ни на один член.
 Средство spooler интерпретирует это возвращаемое значение как эквивалентное DOCUMENTEVENT_UNSUPPORTED. Spooler не может получить фильтр событий от драйвера, поэтому он сохраняется при вызове DocumentEvent для всех событий.
DOCUMENTEVENT_SUCCESS
 Драйвер написал одному или обоим членам.
 Spooler принимает это возвращаемое значение без интерпретации. Если драйвер написал только один из cElementsNeeded и cElementsReturned, spooler считает без изменений элемент иметь значение нуля.
Spooler фильтрует все события, перечисленные в элементе aDocEventCall DOCEVENT_FILTER (который задокументирован в комплекте средств разработки драйверов Windows).
DOCUMENTEVENT_UNSUPPORTED
 Нет данных
 Драйвер не поддерживает DOCUMENTEVENT_QUERYFILTER.
Spooler не может получить фильтр событий от драйвера, поэтому он сохраняется при вызове DocumentEvent для всех событий.
DOCUMENTEVENT_FAILURE
 Нет данных
 Драйвер поддерживает DOCUMENTEVENT_QUERYFILTER, но возникла внутренняя ошибка.
Spooler не может получить фильтр событий от драйвера, поэтому он сохраняется при вызове DocumentEvent для всех событий.

Если код escape, предоставленный в параметре iEsc , DOCUMENTEVENT_CREATEDCPRE, применяются следующие правила:

  • Если задание отправляется непосредственно на принтер без spooling, pvIn-pszDevice> указывает на имя принтера. (Дополнительные сведения см. в документации по структуре DOCEVENT_CREATEDCPRE в Пакет средств разработки драйверов Windows.)
  • Если задание копируется, pvIn-pszDevice> указывает на имя порта принтера.

Примечание.

Следующие ограничения применяются при запуске 32-разрядного приложения в 64-разрядной версии Windows. Единственная функция GDI, вызываемая DocumentEvent, — ExtEscape, и следует использовать только частные escape-каналы. Вызовы DocumentEvent к другим функциям GDI могут привести к неопределенному поведению.

Requirements

Требование Значение
Минимальная версия клиента
 Windows Vista [только классические приложения]
Минимальная версия сервера
 Windows Server 2008 [только классические приложения]
Верхний колонтитул
Winspool.h (включая Windows.h)
Имена Юникода и ANSI
 DocumentEventW (Юникод) и DocumentEventA (ANSI)

См. также