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


Функция OpenPrinter

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

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

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

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

Комментарии

Не вызывайте этот метод в DllMain.

Примечание

Дескриптор, полученный для удаленного принтера путем вызова 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