Функция OpenPrinter

Статья
06/12/2023

Функция OpenPrinter извлекает дескриптор на указанный принтер или сервер печати или другие типы дескрипторов в подсистеме печати.

Синтаксис

BOOL OpenPrinter(
  _In_  LPTSTR             pPrinterName,
  _Out_ LPHANDLE           phPrinter,
  _In_  LPPRINTER_DEFAULTS pDefault
);

Параметры

pPrinterName [in]

Указатель на строку со значением NULL, которая указывает имя принтера или сервера печати, объект принтера, XcvMonitor или XcvPort.

Для объекта принтера используйте: PrinterName, Job xxxx. Для XcvMonitor используйте: ServerName, XcvMonitor MonitorName. Для XcvPort используйте: ServerName, XcvPort PortName.

Значение NULL указывает на локальный сервер принтера.

phPrinter [out]

Указатель на переменную, которая получает дескриптор (не потокобезопасный) на открытый принтер или объект сервера печати.

Параметр phPrinter может возвращать дескриптор Xcv для использования с функцией XcvData. Дополнительные сведения о XcvData см. в разделе DDK.

pDefault [in]

Указатель на структуру PRINTER_DEFAULTS . Это значение может иметь значение NULL.

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

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

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

Дескриптор, полученный для удаленного принтера путем вызова OpenPrinter для удаленного принтера, обращается к принтеру через локальный кэш в службе очереди печати печати. Этот кэш не является точным в режиме реального времени. Чтобы получить точные данные, замените вызов OpenPrinter на OpenPrinter2 с параметром pOptions.dwFlags, для PRINTER_OPTION_NO_CACHE. Обратите внимание, что работает только OpenPrinter2W. Функция возвращает дескриптор принтера, который использует другие вызовы API печати и обходит локальный кэш. Этот метод блокируется во время ожидания сетевого взаимодействия с удаленным принтером, поэтому он может вернуться не сразу. Скорость возврата этой функции зависит от факторов времени выполнения, таких как состояние сети, конфигурация сервера печати и факторы реализации драйвера принтера, которые трудно предсказать при написании приложения. Вызов этой функции из потока, который управляет взаимодействием с пользовательским интерфейсом, может привести к тому, что приложение не отвечает.

Примечание

Дескриптор, полученный при вызове OpenPrinter для удаленного принтера, будет обращаться к принтеру через локальный кэш в службе очереди печати печати. Этот кэш, по умолчанию, не является точным в режиме реального времени. Если требуется получить точные данные, замените вызов OpenPrinterна OpenPrinter2 с параметром pOptions.dwFlags, для PRINTER_OPTION_NO_CACHE. Обратите внимание, что работает только OpenPrinter2W . При этом функция возвращает дескриптор принтера, который вызывает другие вызовы API печати для обхода локального кэша. Обратите внимание, что этот подход будет блокироваться во время ожидания кругового сетевого взаимодействия с удаленным принтером, поэтому он может вернуться не сразу. Скорость возврата этой функции зависит от факторов среды выполнения, таких как состояние сети, конфигурация сервера печати и реализация драйвера принтера. Факторы, которые трудно предсказать при написании приложения. Поэтому вызов этой функции из потока, который управляет взаимодействием с пользовательским интерфейсом, может привести к тому, что приложение не отвечает.

Дескриптор, на который указывает phPrinter , не является потокобезопасной. Если вызывающим абонентам необходимо использовать его одновременно в нескольких потоках, они должны предоставить настраиваемый доступ к дескриптору принтера с помощью функций синхронизации. Чтобы избежать написания пользовательского кода, приложение может открывать дескриптор принтера в каждом потоке по мере необходимости.

Параметр pDefault позволяет указать тип данных и значения режима устройства, используемые для печати документов, отправленных функцией StartDocPrinter . Однако эти значения можно переопределить с помощью функции SetJob после запуска документа.

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

Можно вызвать функцию OpenPrinter , чтобы открыть дескриптор на сервере печати или определить права доступа клиента к серверу печати. Для этого укажите имя сервера печати в параметре pPrinterName , присвойте элементам pDatatype и pDevMode структуры PRINTER_DEFAULTSзначение NULL, а для элемента DesiredAccess задайте значение маски доступа к серверу, например SERVER_ALL_ACCESS. Завершив работу с дескриптором, передайте его в функцию ClosePrinter , чтобы закрыть его.

Используйте элемент DesiredAccess структуры PRINTER_DEFAULTS , чтобы указать права доступа, необходимые для принтера. Права доступа могут быть одним из следующих. (Если pDefault имеет значение NULL, права доступа PRINTER_ACCESS_USE.)

Требуемое значение доступа	Значение
PRINTER_ACCESS_ADMINISTER	Для выполнения административных задач, например задач, предоставляемых SetPrinter.
PRINTER_ACCESS_USE	Для выполнения основных операций печати.
PRINTER_ALL_ACCESS	Для выполнения всех административных задач и базовых операций печати, за исключением SYNCHRONIZE (см. раздел Стандартные права доступа.
PRINTER_ACCESS_MANAGE_LIMITED	Для выполнения административных задач, например задач, предоставляемых SetPrinter и SetPrinterData. Это значение доступно начиная с Windows 8.1.
универсальные значения безопасности, такие как WRITE_DAC	Разрешение определенных прав доступа для управления. См. раздел Стандартные права доступа.

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

Примеры

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

Требования

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

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

Вывод на печать
Функции API очереди печати принтера
WritePrinter
ClosePrinter
PRINTER_DEFAULTS
Задание SetJob
SetPrinter
StartDocPrinter