Функция 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 [только классические приложения]
Заголовок
Winspool.h (include Windows.h)
Имя в кодировке Юникод и ANSI
DocumentEventW (Юникод) и DocumentEventA (ANSI)

См. также раздел

Вывод на печать

Функции API очереди печати принтера

пакет средств разработки драйверов Windows