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

События документа драйвера XPS

  • Статья

Внимание

Современная платформа печати — это предпочтительный способ взаимодействия с принтерами Windows. Рекомендуется использовать драйвер класса "Входящие" Microsoft IPP вместе с приложениями поддержки печати (PSA), чтобы настроить возможности печати в Windows 10 и 11 для разработки устройств принтера.

Дополнительные сведения см. в статье "Современная платформа печати" и руководство по проектированию приложений поддержки печати.

Поддержка печати Microsoft Windows Presentation Foundation (WPF) отправляет события уведомлений о драйверах печати XPSDrv во время spooling документа аналогично тому, как поддержка печати GDI отправляет уведомления драйверам печати GDI. Поддержка печати WPF также использует ту же функцию DrvDocumentEvent DDI, которую использует поддержка печати GDI, но новые события были определены для поддержки событий обработки документов XPS. Поддержка печати GDI продолжит выдавать обработчики событий DrvDocumentEvent драйверам печати на основе GDI и драйверам печати XPSDrv для печати приложений Microsoft Win32.

Обзор обработчика событий DrvDocumentEvent

При необходимости драйверы печати XPSDrv могут экспортировать обработчик событий DrvDocumentEvent из модуля конфигурации для перехвата функций обработки документов. Новые события, связанные с документом XPS, определяются символьным именем, начинающимся с "DOCUMENTEVENT_XPS_".

Поддержка печати WPF вызывает функцию DrvDocumentEvent драйвера печати XPSDrv, пока она распечатывает документ для печати. Каждый вызов выполняется на другом шаге процесса. Шаг обработки каждого вызова определяется значением аргумента iEsc . Содержимое буферов, на которые ссылаются аргументы pvIn и pvOut , зависят от шага обработки.

В следующих подразделах в этом разделе описываются только события обработки документов XPS, которые поддерживают поддержку печати WPF.

Описание обработчика событий DrvDocumentEvent

Обработчик событий DrvDocumentEvent имеет следующий формат вызова. Определения кода и параметров в этом разделе предназначены только для получения сведений.

INT
  DrvDocumentEvent(
    HANDLE  hPrinter,
    HDC  hdc,
    int  iEsc,
    ULONG  cbIn,
    PVOID  pvIn,
    ULONG  cbOut,
    PVOID  pvOut
    );

Параметры

hPrinter
Дескриптор принтера, который предоставляет поддержка печати WPF.

hdc
Вызывающий маркер контекста устройства, создаваемый вызовом CreateDC . Этот параметр равен нулю, если для iEsc задано значение DOCUMENTEVENT_CREATEDCPRE.

При печати документа система будет использовать одинаковые значения событий для документов XPS и GDI. Драйвер должен знать об этом сходстве и определять тип задания на основе hdc. hdc равен INVALID_HANDLE_VALUE для всех событий DOCUMENTEVENT_XPS_Xxx. Эта проверка определяет правильную интерпретацию значений событий DrvDocumentEvent на основе вызывающего приложения. Эта проверка применима только к драйверам печати XPSDrv.

iEsc
Вызывающий код escape-кода, определяющий событие для обработки. Этот параметр может быть одной из следующих целочисленных констант.

DOCUMENTEVENT_QUERYFILTER
Поддержка печати WPF отправляет это событие, чтобы запросить драйвер печати для списка событий обработки документов XPS, на которые будет отвечать драйвер. Это событие выдано перед любыми другими событиями, связанными с документом XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
Поддержка печати WPF отправляет это событие перед добавлением FixedDocumentSequence в файл spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
Поддержка печати WPF отправляет это событие после добавления FixedDocumentSequence в файл spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
Поддержка печати WPF отправляет это событие перед добавлением FixedDocument в файл spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
Поддержка печати WPF отправляет это событие после добавления FixedDocument в файл spool XPS.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
WPF ожидает добавления PrintTicket в фиксированный уровень заданий.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST
WPF должен освободить данные, возвращаемые драйвером для соответствующего события DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE .

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
WPF будет добавлять PrintTicket в ФиксированныйDocument (уровень документа).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST
WPF должен освободить данные, возвращаемые драйвером для соответствующего события DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
WPF собирался добавить PrintTicket в ФиксированныйPage (уровень страницы).

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST
WPF освобождает данные, возвращаемые драйвером для соответствующего события DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE.

DOCUMENTEVENT_XPS_CANCELJOB
Поддержка печати WPF отправляет это событие перед вызовом действия отмены задания.

DOCUMENTEVENT_XPS_COMMITJOB
WPF закончил запись даты в текущий файл.

cbIn
Размер в байтах буфера, на который ссылается параметр pvln . Это значение предоставляется поддержкой печати WPF и чтением обработчиком событий.

pvIn
Указатель, предоставленный вызывающим. Использование этого параметра зависит от значения iEsc , как описано в следующем списке. (Для DOCUMENTEVENT_XPS_События XXX , которые не отображаются в этом списке, pvIn не используется.)

DOCUMENTEVENT_QUERYFILTER
pvIn указывает на структуру PDOCEVENT_FILTER (так же, как и для DOCUMENTEVENT_QUERYFILTER).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE
pvIn указывает на структуру PrintPropertiesCollection (см. Winspool.h), содержащую три свойства:

  • EscapeCode, который является значением EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode — это значение события.

  • JobIdentifier, являющийся значением EPrintPropertyType::kPropertyTypeInt32 (ULONG). JobIdentifier — это идентификатор, необходимый для вызова GetJob() и SetJob().

  • JobName, который является значением EPrintPropertyType:: kPropertyTypeString (UNICODE).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST
То же самое, что и для DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE
pvIn указывает на структуру PrintPropertiesCollection (см. Winspool.h), содержащую два свойства:

  • EscapeCode, который является значением EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode — это значение события.

  • DocumentNumber, который является значением EPrintPropertyType::kPropertyTypeInt32 (ULONG).

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST
То же самое, что и для DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE
pvIn указывает на структуру PrintPropertiesCollection (см. Winspool.h), содержащую два свойства:

  • EscapeCode, который является значением EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PageNumber, являющийся значением EPrintPropertyType::kPropertyTypeInt32 (ULONG).

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPOST
То же самое, что и для DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
pvIn указывает на структуру PrintPropertiesCollection (см. Winspool.h), содержащую четыре свойства:

  • EscapeCode, который является EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode — это значение события.

  • JobIdentifier, являющийся значением EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • JobName, который является значением EPrintPropertyType:: kPropertyTypeString (UNICODE).

  • PrintTicket, который является значением EPrintPropertyType:: kPropertyTypeByte.

Необходимо выделить структуру PrintPropertiesCollection и ее свойства для события PRE и освободить его в соответствующем событии POST. Вы можете задать для pvOut значение NULL , чтобы указать, что вы поддерживаете событие, но не заинтересованы в изменении PrintTicket для данного документа или страницы. Подключаемый модуль никогда не должен выгружаться между событиями PRE и POST.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
pvIn является тем же указателем, что и pvOut из DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE

Драйвер должен освободить pvIn.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
pvIn указывает на структуру PrintPropertiesCollection (см. Winspool.h), содержащую три свойства:

  • EscapeCode, который является значением EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode — это значение события.

  • DocumentNumber, который является значением EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PrintTicket, который является значением EPrintPropertyType:: kPropertyTypeByte.

Необходимо выделить структуру PrintPropertiesCollection и ее свойства для события PRE и освободить его в соответствующем событии POST. Вы можете задать для pvOut значение NULL , чтобы указать, что вы поддерживаете событие, но не заинтересованы в изменении PrintTicket для данного документа или страницы. Подключаемый модуль никогда не должен выгружаться между событиями PRE и POST.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
pvIn является тем же указателем, что и pvOut из DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE.

Драйвер должен освободить pvIn.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
pvIn указывает на структуру PrintPropertiesCollection (см. Winspool.h), содержащую три свойства:

  • EscapeCode, который является значением EPrintPropertyType::kPropertyTypeInt32 (ULONG). EscapeCode — это значение события.

  • PageNumber, который является EPrintPropertyType::kPropertyTypeInt32 (ULONG).

  • PrintTicket, который является EPrintPropertyType:: kPropertyTypeByte.

Необходимо выделить структуру PrintPropertiesCollection и ее свойства для события PRE и освободить его в соответствующем событии POST. Вы можете задать для pvOut значение NULL , чтобы указать, что вы поддерживаете событие, но не заинтересованы в изменении PrintTicket для данного документа или страницы. Подключаемый модуль никогда не должен выгружаться между событиями PRE и POST.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
pvIn является тем же указателем, что и pvOut из DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE.

Драйвер должен освободить pvIn.

DOCUMENTEVENT_XPS_CANCELJOB
pvIn имеет значение NULL.

cbOut
Если параметр iEsc содержит DOCUMENTEVENT_QUERYFILTER, функция печати WPF предоставляет размер буфера, на который ссылается параметр pvOut в параметре cbOut. Для всех остальных значений iEsc cbOut не используется.

pvOut
Указатель на буфер, который предоставляет поддержка печати WPF. Размер буфера и содержимое зависят от значения параметра iEsc . В следующем списке описывается содержимое буфера pvOut для каждого значения iEsc .

DOCUMENTEVENT_QUERYFILTER
Вызывающий указатель на буфер, содержащий DOCEVENT_FILTER структуру.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE
Указатель на структуру PrintPropertiesCollection (см. Winspool.h), которая содержит свойство PrintTicket типа EPrintPropertyType::kPropertyTypeBuffer. Это свойство всегда присутствует. Если параметр PrintTicket недоступен, значение PrintPropertyValue.propertyBlob.pBuf равно NULL.

Свойство содержит XML PrintTicket, из которого Microsoft Windows Presentation Foundation (WPF) будет использовать PrintTicket вместо того, который предоставляет вызывающий объект XPSDocumentWriter . (Если pvOut имеет значение NULL или свойство отсутствует или данные свойства равно NULL, WPF использует вызываемую функцию PrintTicket.)

После обработки этого события WPF вызовет DocumentEvent с DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST драйвера для выпуска pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE
Указатель на структуру PrintPropertiesCollection (см. Winspool.h), содержащую свойство PrintTicket типа EPrintPropertyType::P ropertyTypeBuffer. Это свойство всегда присутствует. Если параметр PrintTicket недоступен, значение PrintPropertyValue.propertyBlob.pBuf равно NULL.

Свойство содержит XML PrintTicket, из которого WPF будет использовать PrintTicket вместо того, который предоставляет вызывающий объект XPSDocumentWriter . (Если pvOut имеет значение NULL или свойство отсутствует или данные свойства равно NULL, WPF использует вызываемую функцию PrintTicket.)

После обработки этого события WPF вызовет DocumentEvent с DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST драйвера для выпуска pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOS
NULL

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE
Указатель на структуру PrintPropertiesCollection (см. Winspool.h), которая содержит свойство PrintTicket типа EPrintPropertyType:: PropertyTypeBuffer. Это свойство всегда присутствует. Если параметр PrintTicket недоступен, значение PrintPropertyValue.propertyBlob.pBuf равно NULL.

Свойство содержит XML PrintTicket, из которого WPF будет использовать PrintTicket вместо того, который предоставляет вызывающий объект XPSDocumentWriter . (Если pvOut имеет значение NULL или свойство отсутствует или данные свойства равно NULL, WPF использует вызываемую функцию PrintTicket.)

После обработки этого события WPF вызовет DocumentEvent с DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST драйвера для выпуска pvOut.

DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOS
NULL

Возвращаемое значение

DrvDocumentEvent возвращает одно из следующих значений:

DOCUMENTEVENT_SUCCESS
Драйвер успешно обрабатывал код escape-кода, который был идентифицирован iEsc .

DOCUMENTEVENT_FAILURE
Драйвер поддерживает escape-код, который был идентифицирован iEsc , но произошел сбой.

DOCUMENTEVENT_UNSUPPORTED
Драйвер не поддерживает код escape-кода, который был идентифицирован iEsc .

Структуры событий документа XPS и значения кода событий

В следующем примере кода показаны структуры и константы, используемые новыми событиями документа XPS.

//
// structures used in XPS Document events
//
 
typedef enum
    {
        kPropertyTypeString = 1,
        kPropertyTypeInt32,
        kPropertyTypeInt64,
        kPropertyTypeByte,
        kPropertyTypeTime,
        kPropertyTypeDevMode,
        kPropertyTypeSD,
        kPropertyTypeNotificationReply,
        kPropertyTypeNotificationOptions,

    } EPrintPropertyType;

    typedef struct
    {
        EPrintPropertyType       ePropertyType;
        union
        {
            BYTE                 propertyByte;
            PWSTR                propertyString;
            LONG                 propertyInt32;
            LONGLONG             propertyInt64;
            struct {
                DWORD  cbBuf;
                LPVOID pBuf;
            }                    propertyBlob;
        } value;

    }PrintPropertyValue;

    typedef struct
    {
        WCHAR*                  propertyName;
        PrintPropertyValue      propertyValue;

    }PrintNamedProperty;

    typedef struct
    {
        ULONG                   numberOfProperties;
        PrintNamedProperty*     propertiesCollection;

    }PrintPropertiesCollection;

Структуры в предыдущем примере кода определяются в Winspool.h.

В Winddiui.h определены следующие коды escape-кода.

//
 // Escape code for XPS Document events
//
#define DOCUMENTEVENT_QUERYFILTER                                     14
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE                 1
// DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRE must have same value as //DOCUMENTEVENT_CREATEDCPRE for Winspool.drv to query the driver for supported events and reset the cached events.
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRE                         2
#define DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRE        3                           
#define DOCUMENTEVENT_XPS_ADDFIXEDPAGEPOST                            4
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPOST                        5
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST                13
// DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPOST must have same value as //DOCUMENTEVENT_STARTDOCPOST for Winspool.drv to signal the tray balloon that //the document is completed
#define DOCUMENTEVENT_XPS_CANCELJOB                                   6
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPRE      7
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPRE              8
#define DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPRE                  9
#define DOCUMENTEVENT_XPS_ADDFIXEDPAGEPRINTTICKETPOST                 10
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTPRINTTICKETPOST             11
#define DOCUMENTEVENT_XPS_ADDFIXEDDOCUMENTSEQUENCEPRINTTICKETPOST     12