Функция GetPrinter

Статья
06/12/2023

Функция GetPrinter извлекает сведения об указанном принтере.

Синтаксис

BOOL GetPrinter(
  _In_  HANDLE  hPrinter,
  _In_  DWORD   Level,
  _Out_ LPBYTE  pPrinter,
  _In_  DWORD   cbBuf,
  _Out_ LPDWORD pcbNeeded
);

Параметры

hPrinter [in]

Дескриптор принтера, для которого функция извлекает сведения. Используйте функцию OpenPrinter или AddPrinter для получения дескриптора принтера.

Level [in]

Уровень или тип структуры, который функция сохраняет в буфере, на который указывает pPrinter.

Это значение может быть 1, 2, 3, 4, 5, 6, 7, 8 или 9.

pPrinter [out]

Указатель на буфер, который получает структуру, содержащую сведения о указанном принтере. Буфер должен быть достаточно большим, чтобы получать структуру и любые строки или другие данные, на которые указывают члены структуры. Если буфер слишком мал, параметр pcbNeeded возвращает требуемый размер буфера.

Тип структуры определяется значением Level.

Level	Структура
1	Структура PRINTER_INFO_1 , содержащая общие сведения о принтере.
2	Структура PRINTER_INFO_2 , содержащая подробные сведения о принтере.
3	Структура PRINTER_INFO_3 , содержащая сведения о безопасности принтера.
4	Структура PRINTER_INFO_4 , содержащая минимальные сведения о принтере, включая имя принтера, имя сервера и удаленный или локальный принтер.
5	Структура PRINTER_INFO_5 , содержащая сведения о принтере, такие как атрибуты принтера и параметры времени ожидания.
6	Структура PRINTER_INFO_6 , указывающая значение состояния принтера.
7	Структура PRINTER_INFO_7 , указывающая, опубликован ли принтер в службе каталогов.
8	Структура PRINTER_INFO_8 , указывающая глобальные параметры принтера по умолчанию.
9	Структура PRINTER_INFO_9 , указывающая параметры принтера по умолчанию для каждого пользователя.

cbBuf [in]

Размер (в байтах) буфера, на который указывает pPrinter.

pcbNeeded [ out]

Указатель на переменную, которую функция устанавливает для размера в байтах сведений о принтере. Если cbBuf меньше этого значения, getPrinter завершается ошибкой, а значение представляет требуемый размер буфера. Если cbBuf равно или больше этого значения, GetPrinter завершается успешно, а значение представляет количество байтов, хранящихся в буфере.

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

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

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

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

Элемент pDevMode в структурах PRINTER_INFO_2, PRINTER_INFO_8 и PRINTER_INFO_9 может иметь значение NULL. В этом случае принтер становится непригодным для использования, пока драйвер не будет успешно переустановлен.

Для PRINTER_INFO_2 и PRINTER_INFO_3 структур, содержащих указатель на дескриптор безопасности, функция получает только те компоненты дескриптора безопасности, на чтение которых у вызывающего объекта есть разрешение. Чтобы получить определенные компоненты дескриптора безопасности, необходимо указать необходимые права доступа при вызове функции OpenPrinter для получения дескриптора принтера. В следующей таблице показаны права доступа, необходимые для чтения различных компонентов дескриптора безопасности.

Право доступа	Компонент дескриптора безопасности
READ_CONTROL	Владелец Основная группа Список управления доступом на уровне пользователей (DACL)
ACCESS_SYSTEM_SECURITY	Системный список управления доступом (SACL)

Если указать уровень 7, член dwActionPRINTER_INFO_7 возвращает одно из следующих значений, чтобы указать, опубликован ли принтер в службе каталогов.

Значение dwAction	Значение
DSPRINT_PUBLISH	Принтер опубликован. Элемент pszObjectGUID содержит GUID объекта очереди печати служб каталогов, связанного с принтером.
DSPRINT_UNPUBLISH	Принтер не опубликован.
DSPRINT_PENDING	Указывает, что система пытается завершить операцию публикации или отмены публикации. Если вызову SetPrinter не удается опубликовать или отменить публикацию принтера, система предпринимает дальнейшие попытки завершить операцию в фоновом режиме.

Начиная с Windows Vista данные принтера, возвращаемые GetPrinter , извлекаются из локального кэша, когда hPrinter ссылается на принтер, размещенный на сервере печати, и имеется по крайней мере одно открытое подключение к серверу печати. Во всех остальных конфигурациях данные принтера запрашиваются с сервера печати.

Требования

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

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

Вывод на печать
Функции API очереди печати принтера
AbortPrinter
AddPrinter
ClosePrinter
DeletePrinter
EnumPrinters
PRINTER_INFO_1
PRINTER_INFO_2
PRINTER_INFO_3
PRINTER_INFO_4
PRINTER_INFO_5
PRINTER_INFO_7
PRINTER_INFO_8
PRINTER_INFO_9
OpenPrinter
SetPrinter