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

Статья
12/22/2023

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

Начинает печать потока документов XPS на принтер.

Синтаксис

HRESULT StartXpsPrintJob(
  [in]  LPCWSTR            printerName,
  [in]  LPCWSTR            jobName,
  [in]  LPCWSTR            outputFileName,
  [in]  HANDLE             progressEvent,
  [in]  HANDLE             completionEvent,
  [in]  UINT8              *printablePagesOn,
  [in]  UINT32             printablePagesOnCount,
  [out] IXpsPrintJob       **xpsPrintJob,
  [out] IXpsPrintJobStream **documentStream,
  [out] IXpsPrintJobStream **printTicketStream
);

Параметры

[in] printerName

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

[in] jobName

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

[in] outputFileName

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

[in] progressEvent

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

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

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

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

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

[in] completionEvent

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

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

[in] printablePagesOn

Параметр ссылается на массив UINT8, элементы которого определяют подмножество страниц документа для печати. Как показано в следующей таблице, значение каждого элемента указывает, должна ли быть напечатана страница.

Значение элемента массива	Значение
0	Не печатайте страницу.
Ненулевая	Печать страницы.

События хода выполнения будут сигнализироваться только для страниц, предназначенных для печати.

Элементы в массиве представляют все страницы, предназначенные для печати, во всех документах пакета XPS. Например, если пакет содержит два документа, каждый из которых содержит по три страницы, массив, показанный в следующей таблице, обозначает печать страниц 0 и 2 из документа 1 и страниц 0 и 2 из документа 2.

Индекс элемента	Значение элемента	Печати?	Номер документа	Номер страницы
5	1	Да	2	2
4	0	Нет	2	1
3	1	Да	2	0
2	1	Да	1	2
1	0	Нет	1	1
0	1	Да	1	0

Если параметр printablePagesOn имеет значение NULL, будут напечатаны все страницы в пакете.

Если printablePagesOn содержит больше элементов, чем страниц в пакете, лишние элементы будут игнорироваться.

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

[in] printablePagesOnCount

Количество элементов в массиве, на которые ссылается printablePagesOn. Если printablePagesOn имеет значение NULL, этот параметр игнорируется.

[out] xpsPrintJob

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

[out] documentStream

Указатель на интерфейс IXpsPrintJobStream , в который вызывающий объект записывает документ XPS для печати этим заданием печати.

[out] printTicketStream

Указатель на интерфейс IXpsPrintJobStream , используемый вызывающим объектом для записи билета печати на уровне задания, который будет связан с этим заданием. Если для этого параметра задано значение NULL, будут использоваться билеты на печать (если таковые существуют) из документа XPS, записанного в documentStream .

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

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

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

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

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

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

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

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

Интерфейсы IXpsPrintJobStream , возвращаемые в documentStream и printTicketStream , являются потоками только для записи, которые не допускают поиск, но могут быть закрыты. Вызывающий объект записывает документ XPS и содержимое билета на печать в эти потоки, а затем вызывает метод Close после записи всех данных. Вызовы метода Write потоков являются потокобезопасны; Однако если такие вызовы выполняются из разных потоков, они не гарантированно будут зафиксированы в потоке в ожидаемом порядке.

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

Требования


Минимальная версия клиента	Windows 7 [только классические приложения]
Минимальная версия сервера	Windows Server 2008 R2 [только классические приложения]
Целевая платформа	Windows
Header	xpsprint.h
Библиотека	XpsPrint.lib
DLL	XpsPrint.dll

См. также

Документы

StartXpsPrintJob1

XPS

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

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

Синтаксис

Параметры

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

Комментарии

Требования

См. также

Обратная связь

Дополнительные ресурсы