Функция WritePrinter

Статья
06/13/2023

Функция WritePrinter уведомляет диспетчер очереди печати о том, что данные должны быть записаны на указанный принтер.

Примечание

WritePrinter поддерживает только GDI-печать и не должна использоваться для печати XPS. Если задание печати использует путь печати XPS или OpenXPS, используйте API печати XPS. Отправка заданий печати XPS или OpenXPS в очередь с помощью WritePrinter не поддерживается и может привести к неопределенным результатам.

Синтаксис

BOOL WritePrinter(
  _In_  HANDLE  hPrinter,
  _In_  LPVOID  pBuf,
  _In_  DWORD   cbBuf,
  _Out_ LPDWORD pcWritten
);

Параметры

hPrinter [in]: Дескриптор принтера. Используйте функцию OpenPrinter или AddPrinter для получения дескриптора принтера.
pBuf [in]: Указатель на массив байтов, содержащий данные, которые должны быть записаны на принтер.
cbBuf [in]: Размер массива в байтах.
pcWritten [out]: Указатель на значение, которое получает количество байтов данных, записанных на принтер.

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

Если функция выполняется успешно, возвращаемое значение будет ненулевым.

Если функция выполняется неудачно, возвращается нулевое значение.

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

Последовательность задания печати выглядит следующим образом:

Чтобы начать задание печати, вызовите StartDocPrinter.
Чтобы начать каждую страницу, вызовите StartPagePrinter.
Чтобы записать данные на страницу, вызовите WritePrinter.
Чтобы завершить каждую страницу, вызовите EndPagePrinter.
Повторите 2, 3 и 4 для необходимого количества страниц.
Чтобы завершить задание печати, вызовите Метод EndDocPrinter.

Когда документ высокого уровня (например, файл Adobe PDF или Microsoft Word) или другие данные принтера (например, PCL, PS или HPGL) отправляются непосредственно на принтер, параметры печати, определенные в документе, берут приоритет над параметрами печати Windows. Выходные данные, когда значение элемента pDatatypeструктуры DOC_INFO_1 , переданное в параметре pDocInfo вызова StartDocPrinter , равно "RAW", должно полностью описывать параметры задания печати в стиле DEVMODE на языке, понятном оборудованием.

В версиях Windows, предшествующих Windows XP, если размер страницы в хранимом файле превышает приблизительно 350 МБ, она может не печатать и не отправлять сообщение об ошибке. Например, это может произойти при печати больших EMF-файлов. Ограничение на размер страницы в версиях Windows до Windows XP зависит от многих факторов, включая объем доступной виртуальной памяти, объем памяти, выделяемой вызывающими процессами, и объем фрагментации в куче процесса. В Windows XP и более поздних версиях Windows EMF-файлы должны иметь размер не более 2 ГБ. Если writePrinter используется для записи данных, отличных от EMF, таких как PDL, готовый к принтеру, размер файла ограничивается только доступным местом на диске.

Примеры

Пример программы, использующий эту функцию, см. в разделе Практическое руководство. Печать с помощью API печати GDI.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Заголовок	Winspool.h (включая Windows.h)
Библиотека	Winspool.lib
DLL	Spoolss.dll

См. также раздел

Вывод на печать
Функции API очереди печати принтера
EndDocPrinter
EndPagePrinter
OpenPrinter
StartDocPrinter
StartPagePrinter
WritePrinter