Функция StartXpsPrintJob1 (xpsprint.h)

Статья
08/28/2023

[StartXpsPrintJob1 не поддерживается и в будущем может быть изменен или недоступен. ]

Создает задание печати для отправки содержимого документа XPS на принтер. Эта функция создает более эффективный путь печати, чем StartXpsPrintJob.

Синтаксис

HRESULT StartXpsPrintJob1(
  [in]            LPCWSTR             printerName,
  [in, optional]  LPCWSTR             jobName,
  [in, optional]  LPCWSTR             outputFileName,
  [in, optional]  HANDLE              progressEvent,
  [in, optional]  HANDLE              completionEvent,
  [out, optional] IXpsPrintJob        **xpsPrintJob,
  [out]           IXpsOMPackageTarget **printContentReceiver
);

Параметры

[in] printerName

Имя принтера, с которым будет связано это задание.

[in, optional] jobName

Указанное пользователем имя задания, связанное с этим заданием. Для этого параметра можно задать значение NULL , если задание не требует отдельного имени, указанного пользователем.

[in, optional] outputFileName

Имя файла или порта, в который должны быть перенаправлены выходные данные этого задания. Если задать это значение, выходные данные задания печати будут перенаправлены в указанный файл или порт. Чтобы отправить задание печати на принтер, указанный в параметре printerName, необходимо задать для этого параметра значение NULL.

[in, optional] progressEvent

Дескриптор события, который подается при изменении одного из следующих заданий печати:

Заданию печати назначается идентификатор задания.
Печать страницы завершена
Печать документа завершена
Задание печати отменено или завершено из-за ошибки

Примечание Это событие не будет передаваться до тех пор, пока приложение не начнет отправлять данные в задание печати.

API печати XPS не сбрасывает это событие, за что отвечает вызывающий объект.

Присвойте этому параметру значение NULL , если вы не хотите получать уведомления о ходе выполнения.

[in, optional] completionEvent

Дескриптор события, который подается по завершении задания печати. Это событие гарантированно будет сигнализироваться ровно один раз при вызове StartXpsPrintJob1 . API печати XPS не сбрасывает это событие, за что отвечает вызывающий объект.

Присвойте этому параметру значение NULL , если не хотите получать уведомления о завершении.

[out, optional] xpsPrintJob

Указатель на интерфейс IXpsPrintJob , представляющий задание печати, созданное StartXpsPrintJob1 . Чтобы получить состояние задания печати или отменить его, используйте интерфейс IXpsPrintJob . Присвойте этому параметру значение NULL , если он вам не нужен.

[out] printContentReceiver

Указатель на интерфейс IXpsOMPackageTarget , созданный этой функцией. Этот параметр является обязательным, и ему нельзя присвоить значение NULL.

Чтобы отправить содержимое документа в задание печати, созданное этой функцией, используйте интерфейс IXpsOMPackageWriter , созданный путем вызова метода CreateXpsOMPackageWriter интерфейса IXpsOMPackageTarget , возвращаемого в xpsOMPackageTarget.

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

Метод возвращает HRESULT. Допустимые значения включают, но не ограничиваются, значения, приведенные в следующей таблице.

Код возврата	Описание
S_OK	Метод выполнен успешно.
E_POINTER	printerName или xpsOMPackageTarget имеет значение NULL.
E_OUTOFMEMORY	Недостаточно памяти для создания нового объекта IXpsPrintJob .

После того как вызывающий объект начнет отправлять данные, рекомендуется отслеживать события хода выполнения, которые передаются в progressEvent. Когда событие подается, вызывающий объект должен вызвать IXpsPrintJob::GetJobStatus , чтобы получить текущее состояние задания печати.

Когда задание печати завершается успешно или нет, событие, передаваемое в completionEvent , сообщается только один раз. Чтобы предотвратить потерю данных, для вызывающего объекта рекомендуется отслеживать событие завершения и гарантировать, что ни поток, ни приложение, создающее задание печати, не будут завершены до получения сигнала о событии завершения.

Состояние задания не хранится и не помещаются в очередь в очередь в очереди. Так как при обработке задания не ожидается считывание состояния после получения сигналов о событиях, вызывающий объект может пропустить некоторые изменения состояния в зависимости от задержки между временем получения приложением уведомления об изменениях и временем вызова IXpsPrintJob::GetJobStatus. Чтобы получать последующие уведомления, приложение должно сбросить событие хода выполнения после получения уведомления.

Если вызов StartXpsPrintJob1 завершается сбоем, диспетчер очереди печати печати обновляет состояние задания, сообщает о событиях завершения и выполнения и возвращает код ошибки. Чтобы получить состояние неудачного задания печати, вызовите IXpsPrintJob::GetJobStatus.

StartXpsPrintJob1 вызывает DuplicateHandle при завершенииEvent и progressEvent , чтобы убедиться, что они остаются действительными в течение всего времени существования задания. Так как очередь печати печати использует повторяющийся дескриптор для событий, вызывающий объект может закрыть эти дескрипторы в любой момент, не влияя на выполнение задания. Однако мы рекомендуем, чтобы вызывающий объект закрывал эти дескрипторы только после того, как событие completionEvent было показано и вызывающий объект наблюдал за ним.

Примечание Когда приложение выполняет печать в файл, приложение отвечает за предоставление значения, передаваемого в параметре outputFileName для операций печати в файл. Для печати на принтер, использующий драйвер, который выводит на порт FILE:, вызывающий объект должен получить имя файла от пользователя, открыв диалоговое окно общего файла.

Требования

Требование	Значение
Минимальная версия клиента	Windows 7 с пакетом обновления 1 (SP1), Windows Vista и дополнением к обновлению платформы для Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 R2 с пакетом обновления 1 (SP1), Windows Server 2008 и дополнением к обновлению платформы для Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	xpsprint.h
Библиотека	XpsPrint.lib
DLL	XpsPrint.dll

См. также

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