Функция StartXpsPrintJob1 (xpsprint.h)
[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. Допустимые значения включают, но не ограничиваются, значения, приведенные в следующей таблице.
| Код возврата | Описание |
|---|---|
|
Метод выполнен успешно. |
|
printerName или xpsOMPackageTarget имеет значение NULL. |
|
Недостаточно памяти для создания нового объекта IXpsPrintJob . |
Комментарии
StartXpsPrintJob1 — это асинхронная функция, поэтому она может возвращать данные до создания или запуска задания печати.
Не используйте интерфейсы, возвращаемые в xpsPrintJob и xpsOMPackageTarget , пока не будет успешно возвращен метод StartXpsPrintJob1 .
После того как вызывающий объект начнет отправлять данные, рекомендуется отслеживать события хода выполнения, которые передаются в progressEvent. Когда событие подается, вызывающий объект должен вызвать IXpsPrintJob::GetJobStatus , чтобы получить текущее состояние задания печати.
Когда задание печати завершается успешно или нет, событие, передаваемое в completionEvent , сообщается только один раз. Чтобы предотвратить потерю данных, для вызывающего объекта рекомендуется отслеживать событие завершения и гарантировать, что ни поток, ни приложение, создающее задание печати, не будут завершены до получения сигнала о событии завершения.
Состояние задания не хранится и не помещаются в очередь в очередь в очереди. Так как при обработке задания не ожидается считывание состояния после получения сигналов о событиях, вызывающий объект может пропустить некоторые изменения состояния в зависимости от задержки между временем получения приложением уведомления об изменениях и временем вызова IXpsPrintJob::GetJobStatus. Чтобы получать последующие уведомления, приложение должно сбросить событие хода выполнения после получения уведомления.
Если вызов StartXpsPrintJob1 завершается сбоем, диспетчер очереди печати печати обновляет состояние задания, сообщает о событиях завершения и выполнения и возвращает код ошибки. Чтобы получить состояние неудачного задания печати, вызовите IXpsPrintJob::GetJobStatus.
StartXpsPrintJob1 вызывает DuplicateHandle при завершенииEvent и progressEvent , чтобы убедиться, что они остаются действительными в течение всего времени существования задания. Так как очередь печати печати использует повторяющийся дескриптор для событий, вызывающий объект может закрыть эти дескрипторы в любой момент, не влияя на выполнение задания. Однако мы рекомендуем, чтобы вызывающий объект закрывал эти дескрипторы только после того, как событие completionEvent было показано и вызывающий объект наблюдал за ним.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | 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 |