Функция GetPrinterDataEx

Статья
06/13/2023

Функция GetPrinterDataEx извлекает данные конфигурации для указанного принтера или сервера печати. GetPrinterDataEx может извлекать значения, сохраненные функцией SetPrinterData . Кроме того, GetPrinterDataEx может извлекать значения, которые функция SetPrinterDataEx хранит в указанном ключе.

Синтаксис

DWORD GetPrinterDataEx(
  _In_  HANDLE  hPrinter,
  _In_  LPCTSTR pKeyName,
  _In_  LPCTSTR pValueName,
  _Out_ LPDWORD pType,
  _Out_ LPBYTE  pData,
  _In_  DWORD   nSize,
  _Out_ LPDWORD pcbNeeded
);

Параметры

hPrinter [in]

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

pKeyName [in]

Указатель на строку, завершающуюся значением NULL, которая указывает ключ, содержащий извлекаемое значение. Используйте символ обратной косой черты ( \ ) в качестве разделителя, чтобы указать путь, имеющий один или несколько подразделов.

Если hPrinter является дескриптором принтера, а pKeyName имеет значение NULL или пустую строку, GetPrinterDataEx возвращает ERROR_INVALID_PARAMETER.

Если hPrinter является дескриптором сервера печати, pKeyName игнорируется.

pValueName [in]

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

Для принтеров эта строка указывает имя значения в разделе pKeyName .

Для серверов печати эта строка является одной из предопределенных строк, перечисленных в следующем разделе Примечаний.

pType [out]

Указатель на переменную, которая получает тип данных, хранящихся в значении. Функция возвращает тип, указанный в вызове SetPrinterDataEx при хранении данных. Этот параметр может иметь значение NULL , если вам не нужны сведения. GetPrinterDataEx передает pType в качестве параметра lpdwType вызова функции RegQueryValueEx .

pData [out]

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

nSize [in]

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

pcbNeeded [ out]

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

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

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

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

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

GetPrinterDataEx извлекает данные конфигурации принтера, которые были заданы функциями SetPrinterDataEx и SetPrinterData .

Вызов Метода GetPrinterDataEx с параметром pKeyName , равным PrinterDriverData, эквивалентен вызову функции GetPrinterData .

Если hPrinter является дескриптором сервера печати, pValueName может указать одно из следующих предопределенных значений.

Значение	Комментарии
SPLREG_ALLOW_USER_MANAGEFORMS	Windows XP с пакетом обновления 2 (SP2) и более поздних версий Windows Server 2003 с пакетом обновления 1 (SP1) и более поздних версий
SPLREG_ARCHITECTURE
SPLREG_BEEP_ENABLED
SPLREG_DEFAULT_SPOOL_DIRECTORY
SPLREG_DNS_MACHINE_NAME
SPLREG_DS_PRESENT	При успешном возвращении pData содержит 0x0001, если компьютер находится в домене DS, в противном случае — значение 0.
SPLREG_DS_PRESENT_FOR_USER	При успешном возвращении pData содержит 0x0001, если пользователь вошел в домен DS, в противном случае — значение 0.
SPLREG_EVENT_LOG
SPLREG_MAJOR_VERSION
SPLREG_MINOR_VERSION
SPLREG_NET_POPUP	Не поддерживается в Windows Server 2003 и более поздних версиях
SPLREG_NET_POPUP_TO_COMPUTER	При успешном возвращении pData содержит значение 1, если уведомления о задании должны отправляться на клиентский компьютер, или 0, если уведомления о заданиях должны отправляться пользователю. Не поддерживается в Windows Server 2003 и более поздних версиях
SPLREG_OS_VERSION	Windows XP и более поздних версий.
SPLREG_OS_VERSIONEX
SPLREG_PORT_THREAD_PRIORITY_DEFAULT
SPLREG_PORT_THREAD_PRIORITY
SPLREG_PRINT_DRIVER_ISOLATION_GROUPS	Windows 7 и более поздние версии
SPLREG_PRINT_DRIVER_ISOLATION_TIME_BEFORE_RECYCLE	Windows 7 и более поздние версии
SPLREG_PRINT_DRIVER_ISOLATION_MAX_OBJECTS_BEFORE_RECYCLE	Windows 7 и более поздние версии
SPLREG_PRINT_DRIVER_ISOLATION_IDLE_TIMEOUT	Windows 7 и более поздние версии
SPLREG_PRINT_DRIVER_ISOLATION_EXECUTION_POLICY	Windows 7 и более поздние версии
SPLREG_PRINT_DRIVER_ISOLATION_OVERRIDE_POLICY	Windows 7 и более поздние версии
SPLREG_REMOTE_FAX	При успешном возвращении pData содержит 0x0001, поддерживает ли служба ФАКС удаленных клиентов, в противном случае — значение 0.
SPLREG_RETRY_POPUP	При успешном возвращении pData содержит 1, если сервер настроен на повторную попытку всплывающих окон для всех заданий, или 0, если сервер не повторяет всплывающие окна для всех заданий. Не поддерживается в Windows Server 2003 и более поздних версиях
SPLREG_SCHEDULER_THREAD_PRIORITY
SPLREG_SCHEDULER_THREAD_PRIORITY_DEFAULT
SPLREG_WEBSHAREMGMT	Windows Server 2003 и более поздние версии

Следующие значения pValueName указывают на поведение печати пула при возникновении ошибки.

Значение	Комментарии
SPLREG_RESTART_JOB_ON_POOL_ERROR	Значение pData указывает время (в секундах) перезапуска задания на другом порту после возникновения ошибки. Этот параметр используется с SPLREG_RESTART_JOB_ON_POOL_ENABLED.
SPLREG_RESTART_JOB_ON_POOL_ENABLED	Ненулевое значение в pData указывает, что SPLREG_RESTART_JOB_ON_POOL_ERROR включен.

Время, указанное в SPLREG_RESTART_JOB_ON_POOL_ERROR , — это минимальное время. Фактическое время может быть больше в зависимости от следующих параметров монитора портов, которые являются значениями реестра в этом разделе реестра:

HKLM\SYSTEM\CurrentControlSet\Control\Print\Monitors\<MonitorName>\Ports

Вызовите функцию RegQueryValueEx , чтобы запросить эти значения.

Параметр монитора портов	Тип данных	Значение
StatusUpdateEnabled	REG_DWORD	Если значение не равно нулю, монитор портов может обновить очередь очереди, указав состояние порта.
StatusUpdateInterval	REG_DWORD	Указывает интервал в минутах, когда монитор портов обновляет очередь очереди с состоянием порта.

Если pKeyName является одним из предопределенных ключей службы каталогов (DS) (см . SetPrinter), а pValueName содержит запятую (','), то часть pValueName перед запятой является именем значения, а часть pValueName справа от запятой — идентификатором свойства DS. Создается подраздел с именем OID, и новое значение, состоящее из имени значения и идентификатора идентификатора, вводится под ключом OID. SetPrinterDataEx также добавляет имя значения и данные в ключ DS.

В Windows 7 и более поздних версиях Windows задания печати, отправляемые на сервер печати, по умолчанию отрисовываются на клиенте. Конфигурацию отрисовки на стороне клиента для принтера можно считать, задав для параметра pKeyName значение PrinterDriverData, а pValueName — значение параметра, указанное в следующей таблице.

Параметр	Тип данных	Описание
EMFDespoolingSetting	REG_DWORD	Значение 0 или, если это значение отсутствует в реестре, включает отрисовку заданий печати на стороне клиента по умолчанию. Значение 1 отключает отрисовку заданий печати на стороне клиента.
ForceClientSideRendering	REG_DWORD	Значение 0 или, если это значение отсутствует в реестре, приведет к отображению заданий печати на клиенте. Если задание печати не удается отобразить на клиенте, оно будет отрисовывается на сервере. Если задание печати не может быть отрисовывается на сервере, оно завершится ошибкой. Значение 1 будет отображать задания печати на клиенте. Если задание печати не удается отобразить на клиенте, оно завершится ошибкой.

Требования

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

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

Вывод на печать
Функции API очереди печати принтера
OpenPrinter
SetPrinterDataEx

Поделиться через