Функция EnumPrinterData

Статья
06/12/2023

Функция EnumPrinterData перечисляет данные конфигурации для указанного принтера.

Чтобы получить данные конфигурации в одном вызове, используйте функцию EnumPrinterDataEx .

Синтаксис

DWORD EnumPrinterData(
  _In_  HANDLE  hPrinter,
  _In_  DWORD   dwIndex,
  _Out_ LPTSTR  pValueName,
  _In_  DWORD   cbValueName,
  _Out_ LPDWORD pcbValueName,
  _Out_ LPDWORD pType,
  _Out_ LPBYTE  pData,
  _In_  DWORD   cbData,
  _Out_ LPDWORD pcbData
);

Параметры

hPrinter [in]

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

dwIndex [in]

Значение индекса, указывающее извлекаемое значение данных конфигурации.

Задайте этому параметру нулевое значение для первого вызова EnumPrinterData для указанного дескриптора принтера. Затем приращение параметра на единицу для последующих вызовов с использованием того же принтера, пока функция не вернет ERROR_NO_MORE_ITEMS. Дополнительные сведения см. в следующем разделе Примечаний.

Если вы используете метод, упомянутый в описаниях параметров cbValueName и cbData , для получения адекватных значений размера буфера. При первом вызове EnumPrinterData для указанного дескриптора принтера значение dwIndex не имеет значения. Задайте dwIndex равным нулю в следующем вызове EnumPrinterData , чтобы запустить фактический процесс перечисления.

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

pValueName [out]

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

cbValueName [in]

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

Если вы хотите, чтобы операционная система предоставляла достаточный размер буфера, задайте для этого параметра и параметра cbData значение 0 для первого вызова EnumPrinterData для указанного дескриптора принтера. При возврате функции переменная, на которую указывает pcbValueName , будет содержать размер буфера, достаточный для успешного перечисления всех имен значений данных конфигурации принтера.

pcbValueName [out]

Указатель на переменную, которая получает количество байтов, хранящихся в буфере, на который указывает pValueName.

pType [out]

Указатель на переменную, получающую код, указывающий тип данных, хранящихся в указанном значении. Список возможных кодов типов см. в разделе Типы значений реестра. Параметр pType может иметь значение NULL , если код типа не требуется.

pData [out]

Указатель на буфер, получающий значение данных конфигурации.

Этот параметр может иметь значение NULL , если значение данных конфигурации не требуется.

cbData [in]

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

Если вы хотите, чтобы операционная система предоставляла достаточный размер буфера, задайте для этого параметра и параметра cbValueName значение 0 для первого вызова EnumPrinterData для указанного дескриптора принтера. При возврате функции переменная, на которую указывает pcbData , будет содержать размер буфера, достаточный для успешного перечисления всех имен значений данных конфигурации принтера.

pcbData [out]

Указатель на переменную, получающую количество байтов, хранящихся в буфере, на который указывает pData.

Этот параметр может иметь значение NULL, если pData имеет значение NULL.

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

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

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

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

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

EnumPrinterData извлекает данные конфигурации принтера, заданные функцией SetPrinterData . Данные конфигурации принтера состоят из набора именованных и типизированных значений. Функция EnumPrinterData получает одно из этих значений, а также его имя и код типа при каждом вызове. Несколько раз последовательно вызывайте функцию EnumPrinterData , чтобы получить все значения данных конфигурации принтера.

Данные конфигурации принтера хранятся в реестре. При перечислении данных конфигурации принтера следует избегать вызова функций реестра, которые могут изменить эти данные.

Если вы хотите, чтобы операционная система предоставляла достаточный размер буфера, сначала вызовите EnumPrinterData с параметрами cbValueName и cbData , равными нулю, как указано ранее в разделе Параметры. Значение dwIndex не имеет значения для этого вызова. При возврате функции *pcbValueName и *pcbData будут содержать буферы размеров, достаточно больших для перечисления всех имен и значений значений данных конфигурации принтера. При следующем вызове выделите имена значений и буферы данных, задайте для cbValueName и cbData размеры выделенных буферов в байтах, а dwIndex — нулевое значение. После этого продолжайте вызывать функцию EnumPrinterData , каждый раз приращение dwIndex на единицу, пока функция не вернет ERROR_NO_MORE_ITEMS.

Требования

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

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

Вывод на печать
Функции API очереди печати принтера
DeletePrinterData
EnumPrinterDataEx
GetPrinterData
OpenPrinter
SetPrinter
SetPrinterData