Функция OpenPrinter2

Статья
06/13/2023

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

Синтаксис

BOOL OpenPrinter2(
  _In_  LPCTSTR            pPrinterName,
  _Out_ LPHANDLE           phPrinter,
  _In_  LPPRINTER_DEFAULTS pDefault,
  _In_  PPRINTER_OPTIONS   pOptions
);

Параметры

pPrinterName [in]

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

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

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

phPrinter [out]

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

pDefault [in]

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

pOptions [in]

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

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

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

Если функция выполняется неудачно, возвращается нулевое значение. Для получения дополнительных сведений об ошибке вызовите Метод GetLastError.

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

Версия ANSI этой функции не реализована и возвращает ERROR_NOT_SUPPORTED.

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

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

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

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

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

Если pPrinterName является локальным принтером, OpenPrinter2 игнорирует все значения dwFlags , на которые указывает структура PRINTER_OPTIONS с помощью pOptions, за исключением PRINTER_OPTION_CLIENT_CHANGE. Если последний передается, OpenPrinter2 вернет ERROR_ACCESS_DENIED. Соответственно, при открытии локального принтера OpenPrinter2 не дает никаких преимуществ по сравнению с OpenPrinter.

Windows Vista: Данные принтера, возвращаемые OpenPrinter2 , извлекаются из локального кэша, если флаг PRINTER_OPTION_NO_CACHE не установлен в поле dwFlagsструктуры PRINTER_OPTIONS , на которую ссылается pOptions.

Примеры

В этом примере OpenPrinter2 завершается сбоем, когда PRINTER_ACCESS_MANAGE_LIMITED передается в структуру PRINTER_DEFAULTS , а пользователь не имеет соответствующего разрешения.

// Specify the limited management permission.
PRINTER_DEFAULTS defaults = {};
defaults.DesiredAccess = PRINTER_ACCESS_MANAGE_LIMITED;

// Open a printer to which the user has no administrative rights.
HANDLE printer = nullptr;
assert(!OpenPrinter2(L QueueWithNoAdminRights , // Queue name
                     &printer,                  // Printer handle
                     &defaults,                 // Printer defaults
                     nullptr));                 // Printer options

assert(GetLastError() == ERROR_ACCESS_DENIED);

if (printer)
{
    ClosePrinter(printer);
}

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

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Заголовок	Winspool.h (включая Windows.h)
Библиотека	Winspool.lib
DLL	Spoolss.dll
Имя в кодировке Юникод и ANSI	OpenPrinter2W (Юникод) и OpenPrinter2A (ANSI)

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

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