Функция GetPrinter
Функция 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 [только классические приложения] |
| Заголовок |
|
| Библиотека |
|
| DLL |
|
| Имя в кодировке Юникод и ANSI |
GetPrinterW (Юникод) и GetPrinterA (ANSI) |