Поделиться через

структура DOCEVENT_FILTER (winddiui.h)

  • Статья

Структура DOCEVENT_FILTER содержит список событий документа, на которые будет отвечать драйвер принтера. Полный список событий документа см. в разделе DrvDocumentEvent .

Синтаксис

typedef struct _DOCEVENT_FILTER {
  UINT  cbSize;
  UINT  cElementsAllocated;
  UINT  cElementsNeeded;
  UINT  cElementsReturned;
  DWORD aDocEventCall[ANYSIZE_ARRAY];
} DOCEVENT_FILTER, *PDOCEVENT_FILTER;

Члены

cbSize

Размер этой структуры в байтах, предоставленный диспетчером очереди. Диспетчер очереди инициализирует этот элемент в sizeof(DOCEVENT_FILTER).

cElementsAllocated

Предоставленное spooler количество элементов в элементе массива aDocEventCall . Очередь очереди инициализирует этот элемент DOCUMENTEVENT_LAST – 1. (Константу DOCUMENTEVENT_LAST определяется в файле заголовка Winddiui.h.)

cElementsNeeded

Предоставленное драйвером общее количество элементов, необходимых в элементе массива aDocEventCall . Очередь очереди инициализирует этот элемент для 0XFFFFFFFF. Дополнительные сведения см. в разделе "Примечания".

cElementsReturned

Указанное драйвером количество событий DOCUMENTEVENT_**XXX**, которые он помещал в элемент массива aDocEventCall . Очередь очереди инициализирует этот элемент для 0XFFFFFFFF. Дополнительные сведения см. в разделе "Примечания".

aDocEventCall[ANYSIZE_ARRAY]

Заполненный драйвером массив DWORD со списком всех событий DOCUMENTEVENT_XXX, на которые будет отвечать драйвер принтера. Диспетчер очереди инициализирует этот элемент значением 0.

Комментарии

Драйвер принтера перечисляет события, на которые он будет отвечать в структуре DOCEVENT_FILTER. Так как это ограничивает количество вызовов драйвера, необходимого для очереди очереди, производительность принтера повышается. Когда диспетчер очереди очереди выполняет вызов DDI DrvDocumentEvent с параметром iEsc , заданным DOCUMENTEVENT_QUERYFILTER, диспетчер очереди очереди выделяет буфер, содержащий структуру DOCEVENT_FILTER, включая его массив aDocEventCall . Объем памяти, выделенный для буфера:

sizeof(DOCEVENT_FILTER) + sizeof(DWORD) * (DOCUMENTEVENT_LAST - 2)

После выделения буфера, содержащего структуру DOCEVENT_FILTER, диспетчер очереди очереди инициализирует члены структуры следующими значениями:

Член Инициализировано в
cbSize 0
cElementsAllocated DOCUMENTEVENT_LAST - 1

Константу DOCUMENTEVENT_LAST определяется в файле winddiui.h.
cElementsNeeded 0XFFFFFFFF
cElementsReturned 0XFFFFFFFF
aDocEventCall 0

После того как диспетчер очереди инициализирует элементы структуры значениями, показанными в предыдущей таблице, он вызывает DrvDocumentEvent. Когда эта функция возвращается, диспетчер очереди очереди проверяет элементы cElementsNeeded и cElementsReturned , чтобы проверить, были ли изменены элементы. Если драйвер записывает данные в один из этих элементов, но не в другой, диспетчер очереди печати интерпретирует неписаный элемент как имеющий значение 0.

Если драйвер поддерживает DOCUMENTEVENT_QUERYFILTER:

  • Если массив aDocEventCall достаточно велик, чтобы содержать все события DOCUMENTEVENT_XXX, которые драйвер принтера планирует разместить в нем, драйвер принтера:

    • Заполняет массив этими событиями

    • Задает член cElementsReturned таким числом событий (которое должно быть меньше или равно cElementsAllocated).

    • Оставляет cElementsNeed без изменений

    • Возвращает DOCUMENTEVENT_SUCCESS

В этом случае очередь очереди использует первые значения cElementsReturned в массиве aDocEventCall .

Событие DOCUMENTEVENT_CREATEDCPRE обрабатывается особым образом. Когда spooler вызывает DrvDocumentEvent с параметром iEsc, для параметра iEsc задано значение DOCUMENTEVENT_CREATEDCPRE, он использует возвращаемое значение, чтобы определить, необходимы ли будущие вызовы этой функции. В отличие от других событий DOCUMENTEVENT_XXX драйвер принтера всегда принимает вызовы DrvDocumentEvent с DOCUMENTEVENT_CREATEDCPRE независимо от того, отфильтровывается это событие или нет.

  • Если массив aDocEventCall недостаточно велик, чтобы содержать все события DOCUMENTEVENT_XXX , которые драйвер принтера планирует разместить в нем, драйвер принтера должен:

    • Задайте для параметра cElementsNeeded значение количества событий, на которые он намерен отвечать (которое должно быть больше , чем cElementsAllocated).

    • Оставьте cElementsReturned без изменений

    • Возврат DOCUMENTEVENT_SUCCESS

В этом случае очередь очереди выделяет новый достаточно большой буфер, а затем выполняет еще один вызов DrvDocumentEvent с DOCUMENTEVENT_QUERYFILTER.

Если драйвер не поддерживает событие DOCUMENTEVENT_QUERYFILTER, он должен вернуть DOCUMENTEVENT_UNSUPPORTED. Если драйвер поддерживает DOCUMENTEVENT_QUERYFILTER, но при обработке этого события возникают внутренние ошибки, он должен вернуть DOCUMENTEVENT_FAILURE. В любом случае диспетчер очереди очереди не может получить фильтр событий из драйвера, поэтому он продолжает вызывать DrvDocumentEvent для всех событий.

Требования

Требование Значение
Заголовок winddiui.h (включая Winddiui.h)

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

DrvDocumentEvent