Функция EnumPrinters

Статья
06/13/2023

Функция EnumPrinters перечисляет доступные принтеры, серверы печати, домены или поставщики печати.

Синтаксис

BOOL EnumPrinters(
  _In_  DWORD   Flags,
  _In_  LPTSTR  Name,
  _In_  DWORD   Level,
  _Out_ LPBYTE  pPrinterEnum,
  _In_  DWORD   cbBuf,
  _Out_ LPDWORD pcbNeeded,
  _Out_ LPDWORD pcReturned
);

Параметры

Флаги [в]

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

Значение	Значение
PRINTER_ENUM_LOCAL	Если флаг PRINTER_ENUM_NAME также не передается, функция игнорирует параметр Name и перечисляет локально установленные принтеры. Если PRINTER_ENUM_NAME также передается, функция перечисляет локальные принтеры по имени.
PRINTER_ENUM_NAME	Функция перечисляет принтер, определенный по имени. Это может быть сервер, домен или поставщик печати. Если параметр Name имеет значение NULL, функция перечисляет доступных поставщиков печати.
PRINTER_ENUM_SHARED	Функция перечисляет принтеры с общим атрибутом . Не может использоваться в изоляции; используйте операцию OR для объединения с другим типом PRINTER_ENUM.
PRINTER_ENUM_CONNECTIONS	Функция перечисляет список принтеров, к которым пользователь установил предыдущие подключения.
PRINTER_ENUM_NETWORK	Функция перечисляет сетевые принтеры в домене компьютера. Это значение допустимо, только если уровень равен 1.
PRINTER_ENUM_REMOTE	Функция перечисляет сетевые принтеры и серверы печати в домене компьютера. Это значение допустимо, только если уровень равен 1.
PRINTER_ENUM_CATEGORY_3D	Функция перечисляет только трехмерные принтеры.
PRINTER_ENUM_CATEGORY_ALL	Функция перечисляет все устройства печати, включая трехмерные принтеры.

Если уровень равен 4, можно использовать только константы PRINTER_ENUM_CONNECTIONS и PRINTER_ENUM_LOCAL.

Примечание

Устройства трехмерной печати по умолчанию не перечисляются. Для перечисления только трехмерных принтеров необходимо включить как PRINTER_ENUM_CATEGORY_3D , так и PRINTER_ENUM_LOCAL . Чтобы включить трехмерные принтеры, наряду со всеми другими локальными принтерами, используйте PRINTER_ENUM_CATEGORY_ALL и PRINTER_ENUM_LOCAL.

Имя [in]

Если значение Level равно 1, Флаги содержат PRINTER_ENUM_NAME, а Name не равно NULL, то Name — это указатель на строку, завершающуюся null, которая указывает имя перечисляемого объекта. Эта строка может быть именем сервера, домена или поставщика печати.

Если level имеет значение 1, Флаги содержат PRINTER_ENUM_NAME, а Name имеет значение NULL, функция перечисляет доступных поставщиков печати.

Если параметр Level имеет значение 1, флаги содержат PRINTER_ENUM_REMOTE, а Name имеет значение NULL, функция перечисляет принтеры в домене пользователя.

Если значение параметра Level равно 2 или 5, Name — это указатель на строку, завершающуюся null, которая указывает имя сервера, принтеры которого должны быть перечислены. Если эта строка имеет значение NULL, функция перечисляет принтеры, установленные на локальном компьютере.

Если уровень равен 4, имя должно иметь значение NULL. Функция всегда выполняет запросы на локальном компьютере.

Если имя имеет значение NULL, установите для параметра Флаги значение PRINTER_ENUM_LOCAL | PRINTER_ENUM_CONNECTIONS перечисляет принтеры, установленные на локальном компьютере. К этим принтерам относятся принтеры, которые физически подключены к локальному компьютеру, а также удаленные принтеры, к которым у него есть сетевое подключение.

Если имя не равно NULL, установите для флагов значение PRINTER_ENUM_LOCAL | PRINTER_ENUM_NAME перечисляет локальные принтеры, установленные на сервере Имя.

Level [in]

Тип структур данных, на которые указывает pPrinterEnum. Допустимые значения: 1, 2, 4 и 5, которые соответствуют PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4 и PRINTER_INFO_5 структурам данных.

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

pPrinterEnum [out]

Указатель на буфер, получающий массив структур PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4 или PRINTER_INFO_5 . Каждая структура содержит данные, описывающие доступный объект печати.

Если уровень равен 1, массив содержит PRINTER_INFO_1 структуры. Если значение Level равно 2, массив содержит PRINTER_INFO_2 структуры. Если значение Level равно 4, массив содержит PRINTER_INFO_4 структуры. Если уровень равен 5, массив содержит PRINTER_INFO_5 структуры.

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

cbBuf [in]

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

pcbNeeded [ out]

Указатель на значение, которое получает количество байтов, скопированных при успешном выполнении функции, или количество байтов, необходимое, если cbBuf слишком мало.

pcReturned [out]

Указатель на значение, которое получает число PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4 или PRINTER_INFO_5 структур, возвращаемых функцией в массиве, на который указывает pPrinterEnum .

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

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

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

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

Если EnumPrinters возвращает PRINTER_INFO_1 структуру, в которой указан PRINTER_ENUM_CONTAINER, это означает, что существует иерархия объектов принтера. Приложение может перечислить иерархию, повторно вызвав EnumPrinters, установив для параметра Name значение элемента pNameструктуры PRINTER_INFO_1.

Функция EnumPrinters не извлекает сведения о безопасности. Если PRINTER_INFO_2 структуры возвращаются в массиве, на который указывает pPrinterEnum, их члены pSecurityDescriptor будут иметь значение NULL.

Чтобы получить сведения о принтере по умолчанию, вызовите GetDefaultPrinter.

Структура PRINTER_INFO_4 предоставляет простой и очень быстрый способ получения имен принтеров, установленных на локальном компьютере, а также удаленных подключений, установленных пользователем. При вызове EnumPrinters со структурой данных PRINTER_INFO_4 эта функция запрашивает указанные сведения в реестре, а затем немедленно возвращает данные. Это отличается от поведения EnumPrinters при вызове с другими уровнями структур данных PRINTER_INFO_* . В частности, при вызове EnumPrinters со структурой данных уровня 2 (PRINTER_INFO_2) он выполняет вызов OpenPrinter для каждого удаленного подключения. Если удаленное подключение не работает, удаленный сервер больше не существует или удаленный принтер больше не существует, функция должна дождаться истечения времени ожидания RPC и, следовательно, завершить вызов OpenPrinter . Это может занять некоторое время. Передача структуры PRINTER_INFO_4 позволяет приложению получить минимум необходимых сведений; Если требуются более подробные сведения, можно выполнить последующий вызов EnumPrinters уровня 2.

Windows Vista: Данные принтера, возвращаемые EnumPrinters , извлекаются из локального кэша, если значение уровня равно 4.

В следующей таблице показаны выходные данные EnumPrinters для различных значений Flags , если для параметра Level задано значение 1.

В столбце Параметр Name таблицы следует заменить соответствующее имя поставщиком печати, доменом и компьютером. Например, для параметра "Поставщик печати" можно использовать имя поставщика сетевой печати или имя локального поставщика печати. Чтобы получить имена поставщиков печати, вызовите EnumPrinters с параметром Name значение NULL.

Параметр Flags	Параметр Name	Результат
PRINTER_ENUM_LOCAL (а не PRINTER_ENUM_NAME)	Параметр Name игнорируется.	Все локальные принтеры.
PRINTER_ENUM_NAME	"Поставщик печати"	Все доменные имена
PRINTER_ENUM_NAME	"Поставщик печати! Домен"	Все принтеры и серверы печати в домене компьютера
PRINTER_ENUM_NAME	"Поставщик печати!! \\Machine"	Все принтеры, к которым предоставлен общий доступ на \\Machine
PRINTER_ENUM_NAME	Пустая строка "	Все локальные принтеры.
PRINTER_ENUM_NAME	NULL	Все поставщики печати в домене компьютера
PRINTER_ENUM_CONNECTIONS	Параметр Name игнорируется.	Все подключенные удаленные принтеры
PRINTER_ENUM_NETWORK	Параметр Name игнорируется.	Все принтеры в домене компьютера
PRINTER_ENUM_REMOTE	Пустая строка "	Все принтеры и серверы печати в домене компьютера
PRINTER_ENUM_REMOTE	"Поставщик печати"	То же, что и PRINTER_ENUM_NAME
PRINTER_ENUM_REMOTE	"Поставщик печати! Домен"	Все принтеры и серверы печати в домене компьютера, независимо от указанного домена .
PRINTER_ENUM_CATEGORY_3D	Параметр Name игнорируется.	Перечисляются только трехмерные принтеры.
PRINTER_ENUM_CATEGORY_ALL	Параметр Name игнорируется.	Перечисляются трехмерные принтеры, а также все остальные принтеры.

Требования

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

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

Вывод на печать
Функции API очереди печати принтера
AddPrinter
DeletePrinter
GetPrinter
PRINTER_INFO_1
PRINTER_INFO_2
PRINTER_INFO_4
PRINTER_INFO_5
SetPrinter