Функция 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

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