Функция DeviceCapabilitiesA (wingdi.h)

Статья
03/08/2023

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

Синтаксис

int DeviceCapabilitiesA(
  [in]  LPCSTR         pDevice,
  [in]  LPCSTR         pPort,
  [in]  WORD           fwCapability,
  [out] LPSTR          pOutput,
  [in]  const DEVMODEA *pDevMode
);

Параметры

[in] pDevice

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

[in] pPort

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

[in] fwCapability

Возможности для запроса. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
DC_BINNAMES	Извлекает имена бумажных контейнеров принтера. Буфер pOutput получает массив строковых буферов. Каждый строковый буфер имеет длину 24 символа и содержит имя бумажной корзины. Возвращаемое значение указывает количество записей в массиве. Строки имен заканчиваются нулевым значением, если только имя не содержит 24 символа. Если pOutput имеет значение NULL, возвращаемое значение — это необходимое количество записей в ячейке.
DC_BINS	Извлекает список доступных бумажных ячеек. Буфер pOutput получает массив значений WORD , указывающих доступные источники бумаги для принтера. Возвращаемое значение указывает количество записей в массиве. Список возможных значений массива см. в описании элемента dmDefaultSource структуры DEVMODE . Если pOutput имеет значение NULL, возвращаемое значение указывает необходимое количество записей в массиве.
DC_COLLATE	Если принтер поддерживает сортировку, возвращаемое значение равно 1; в противном случае возвращаемое значение равно нулю. Параметр pOutput не используется.
DC_COLORDEVICE	Если принтер поддерживает цветную печать, возвращаемое значение равно 1; в противном случае возвращаемое значение равно нулю. Параметр pOutput не используется.
DC_COPIES	Возвращает количество копий, которые устройство может распечатать.
DC_DRIVER	Возвращает номер версии драйвера принтера.
DC_DUPLEX	Если принтер поддерживает двустороннюю печать, возвращается значение 1; в противном случае возвращаемое значение равно нулю. Параметр pOutput не используется.
DC_ENUMRESOLUTIONS	Возвращает список разрешений, поддерживаемых принтером. Буфер pOutput получает массив значений LONG . Для каждого поддерживаемого разрешения массив содержит пару значений LONG , указывающих размеры x и y разрешения в точках на дюйм. Возвращаемое значение указывает количество поддерживаемых разрешений. Если pOutput имеет значение NULL, возвращаемое значение указывает количество поддерживаемых разрешений.
DC_EXTRA	Возвращает количество байтов, необходимых для конкретного устройства части структуры DEVMODE для драйвера принтера.
DC_FIELDS	Возвращает элемент dmFields структуры DEVMODE драйвера принтера. Элемент dmFields указывает, какие элементы в аппаратно-независимой части структуры поддерживаются драйвером принтера.
DC_FILEDEPENDENCIES	Извлекает имена всех дополнительных файлов, которые необходимо загрузить при установке драйвера. Буфер pOutput получает массив строковых буферов. Каждый буфер строки содержит 64 символа и содержит имя файла. Возвращаемое значение указывает количество записей в массиве. Строки имен заканчиваются нулевым значением, если только имя не содержит 64 символа. Если pOutput имеет значение NULL, возвращаемым значением является количество файлов.
DC_MAXEXTENT	Возвращает максимальный размер бумаги, который могут указывать члены dmPaperLength и dmPaperWidth структуры DEVMODE драйвера принтера. LOWORD возвращаемого значения содержит максимальное значение dmPaperWidth , а HIWORD — максимальное значение dmPaperLength .
DC_MEDIAREADY	Извлекает имена бумажных форм, которые в настоящее время доступны для использования. Буфер pOutput получает массив строковых буферов. Каждый строковый буфер имеет длину 64 символа и содержит имя бумажной формы. Возвращаемое значение указывает количество записей в массиве. Строки имен заканчиваются нулевым значением, если только имя не содержит 64 символа. Если pOutput имеет значение NULL, возвращаемое значение равно количеству бумажных форм.
DC_MEDIATYPENAMES	Извлекает имена поддерживаемых типов мультимедиа. Буфер pOutput получает массив строковых буферов. Каждый строковый буфер длиной 64 символа содержит имя поддерживаемого типа мультимедиа. Возвращаемое значение указывает количество записей в массиве. Строки завершаются нулевым значением, если имя не содержит 64 символа. Если pOutput имеет значение NULL, возвращаемое значение — это необходимое количество имен типов мультимедиа.
DC_MEDIATYPES	Получает список поддерживаемых типов мультимедиа. Буфер pOutput получает массив значений DWORD, указывающих поддерживаемые типы мультимедиа. Возвращаемое значение указывает количество записей в массиве. Список возможных значений массива см. в описании элемента dmMediaType структуры DEVMODE . Если pOutput имеет значение NULL, возвращаемое значение указывает необходимое количество записей в массиве.
DC_MINEXTENT	Возвращает минимальный размер бумаги, который могут указывать члены dmPaperLength и dmPaperWidth структуры DEVMODE драйвера принтера. LOWORD возвращаемого значения содержит минимальное значение dmPaperWidth , а HIWORD — минимальное значение dmPaperLength .
DC_ORIENTATION	Возвращает связь между книжной и альбомной ориентацией для устройства с точки зрения количества градусов поворота книжной ориентации против часовой стрелки для создания альбомной ориентации. Может возвращаться одно из следующих значений: 0 Нет альбомной ориентации. 90 Портрет поворачивается на 90 градусов, чтобы создать пейзаж. 270 Портрет повернут на 270 градусов для создания ландшафта.
DC_NUP	Извлекает массив целых чисел, указывающих, что принтер может печатать несколько страниц документа на каждую печатаемую страницу. Буфер pOutput получает массив значений DWORD . Каждое значение представляет поддерживаемое количество страниц документа на каждую печатаемую страницу. Возвращаемое значение указывает количество записей в массиве. Если pOutput имеет значение NULL, возвращаемое значение указывает необходимое количество записей в массиве.
DC_PAPERNAMES	Возвращает список поддерживаемых названий документов (например, Letter или Legal). Буфер pOutput получает массив строковых буферов. Каждый строковый буфер имеет длину 64 символа и содержит имя бумажной формы. Возвращаемое значение указывает количество записей в массиве. Строки имен заканчиваются нулевым значением, если только имя не содержит 64 символа. Если pOutput имеет значение NULL, возвращаемое значение равно количеству бумажных форм.
DC_PAPERS	Извлекает список поддерживаемых размеров бумаги. Буфер pOutput получает массив значений WORD , указывающих доступные размеры бумаги для принтера. Возвращаемое значение указывает количество записей в массиве. Список возможных значений массива см. в описании элемента dmPaperSize структуры DEVMODE . Если pOutput имеет значение NULL, возвращаемое значение указывает необходимое количество записей в массиве.
DC_PAPERSIZE	Извлекает размеры в десятых миллиметрах каждого поддерживаемого размера бумаги. Буфер pOutput получает массив структур POINT . Каждая структура содержит ширину (x-измерение) и длину (размерность y) размера бумаги, как если бы бумага находилась в DMORIENT_PORTRAIT ориентации. Возвращаемое значение указывает количество записей в массиве.
DC_PERSONALITY	Возвращает список языков описания принтера, поддерживаемых принтером. Буфер pOutput получает массив строковых буферов. Каждый буфер содержит 32 символа и содержит имя языка описания принтера. Возвращаемое значение указывает количество записей в массиве. Строки имен завершаются null, если только имя не имеет длину 32 символа. Если pOutput имеет значение NULL, возвращаемое значение указывает необходимое количество записей массива.
DC_PRINTERMEM	Возвращаемое значение — это объем доступной памяти принтера в килобайтах. Параметр pOutput не используется.
DC_PRINTRATE	Возвращаемое значение указывает скорость печати принтера. Значение, возвращаемое для DC_PRINTRATEUNIT , указывает единицы DC_PRINTRATE значения. Параметр pOutput не используется.
DC_PRINTRATEPPM	Возвращаемое значение указывает скорость печати принтера в страницах в минуту. Параметр pOutput не используется.
DC_PRINTRATEUNIT	Возвращаемое значение является одним из следующих значений, которые указывают единицы скорости печати для значения, возвращаемого для флага DC_PRINTRATE . Параметр pOutput не используется. PRINTRATEUNIT_CPS Число символов в секунду. PRINTRATEUNIT_IPM Дюймы в минуту. PRINTRATEUNIT_LPM Количество строк в минуту. PRINTRATEUNIT_PPM Страниц в минуту.
DC_SIZE	Возвращает элемент dmSize структуры DEVMODE драйвера принтера.
DC_STAPLE	Если принтер поддерживает скрепку, возвращаемое значение не равно нулю; в противном случае возвращаемое значение равно нулю. Параметр pOutput не используется.
DC_TRUETYPE	Извлекает возможности драйвера использовать шрифты TrueType. Для DC_TRUETYPE параметр pOutput должен иметь значение NULL. Возвращаемое значение может быть одним или несколькими из следующих значений: DCTT_BITMAP Устройство может печатать шрифты TrueType в виде графики. DCTT_DOWNLOAD Устройство может скачивать шрифты TrueType. DCTT_SUBDEV Устройство может заменять шрифты устройства шрифтами TrueType.
DC_VERSION	Возвращает версию спецификации, которой соответствует драйвер принтера.

[out] pOutput

Указатель на массив. Формат массива зависит от параметра fwCapability . Ознакомьтесь с каждой из приведенных выше возможностей, чтобы узнать, что возвращается, если pOutput имеет значение NULL.

[in] pDevMode

Указатель на структуру DEVMODE . Если этот параметр имеет значение NULL, DeviceCapabilities получает текущие значения инициализации по умолчанию для указанного драйвера принтера. В противном случае функция извлекает значения, содержащиеся в структуре, на которую указывает pDevMode .

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

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

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

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

Структура DEVMODE, на которую указывает параметр pDevMode , можно получить, вызвав функцию DocumentProperties .

Если драйвер принтера поддерживает пользовательские возможности устройства, драйвер должен вызывать функцию SetPrinterData для каждой пользовательской возможности. Функция SetPrinterData добавляет соответствующие данные принтера в систему печати, что позволяет 32-разрядным приложениям получать доступ к пользовательским возможностям в 64-разрядных установках Windows.

Для каждой пользовательской возможности необходимо сначала добавить данные принтера, описывающие тип возможности. Для этого при вызове SetPrinterData задайте для строки pValueNameзначение CustomDeviceCapabilityType_Xxx, где "Xxx" — шестнадцатеричное представление возможности. Например, у вас может быть "CustomDeviceCapabilityType_1234". Заданные данные реестра должны иметь тип REG_DWORD и задать для них одно из следующих значений:

0, если настраиваемая возможность имеет значение DWORD
1, если настраиваемая возможность является буфером байтов
2, если настраиваемая возможность представляет собой массив элементов

Если настраиваемая возможность представляет собой массив элементов, необходимо повторно вызвать SetPinterData , чтобы предоставить сведения о размере элемента в массиве. Для этого при вызове SetPinterData указанная строка pValueName должна быть "CustomDeviceCapabilitySize_Xxx", где Xxx — шестнадцатеричное представление возможности. Например, у вас может быть "CustomDeviceCapabilitySize_1234". Заданные данные реестра должны относиться к типу REG_DWORD , а для его значения необходимо задать размер элемента в массиве в байтах.

Примечание

Заголовок wingdi.h определяет DeviceCapabilities в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	wingdi.h (включая Windows.h)
Библиотека	WinSpool.lib
DLL	Winspool.drv