Библиотека SetupAPI.dll

SetupAPI это системный компонент, содержащий функции для установки драйвера устройства, и связывающий пользовательское приложение с устройством.

В дальнейшем рассмотрим некоторые функции из двух групп SetupAPI: Device Installation Functions и PnP Configuration Manager Functions. Первая группа включает функции установки устройств в Microsoft Windows, вторая – дополняет её функциями конфигурирования устройств (CM_xxx).

Функция SetupDiGetClassDevs возвращает дескриптор (манипулятор или handle) класса устройства, заданного в качестве параметра. Имеет следующий формат:

hDevInfoSet: = SetupDiGetClassDevs (ClassGuid, Enumerator, hwndParent, Flags),

где hDevInfoSet – имя дескриптора класса;

ClassGuid – идентификатор класса;

Enumerator – системный компонент, определяющий PnP-идентификатор устройства;

hwndParent – дескриптор родительского окна;

Flags – флаг управления функцией. Может принимать пять значений, мы будем использовать флаг по умолчанию DIGCF_DEFAULT = 2.

Жесткие диски и USB-накопители имеют глобальный уникальный идентификатор класса ClassGuid = {4d36e967-e325-11ce-bfc1-08002be10318}.

Функция SetupDiEnumDeviceInfo возвращает структуру c информацией об очередном устройстве указанного класса. Если функция вернула значение TRUE, то информация извлечена успешно, а если FALSE, то в большинстве случаев это означает что мы пришли к концу списка.

SetupDiEnumDeviceInfo (hDeviceInfoSet, MemberIndex, DeviceInfoData),

где hDeviceInfoSet – дескриптор класса устройств;

MemberIndex – порядковый номер в списке устройств указанного класса;

DeviceInfoData – возвращаемая структура с информацией об устройстве.

Функция SetupDiGetDeviceRegistryProperty позволяет получить PnP свойства устройства.

SetupDiGetDeviceRegistryProperty (hDeviceInfoSet, DeviceInfoData, Property, PropertyRegDataType, PropertyBuffer, PropertyBufferSize, RequiredSize),

где hDeviceInfoSet – дескриптор класса устройств;

DeviceInfoData – указатель на структуру с информацией об устройстве;

Property – параметр, указывающий какое именно свойство требуется получить. Для получения строки с описанием устройства необходимо указать константу или SPDRP_DEVICEDESC (0x00000000) или SPDRP_FRIENDLYNAME (0х0000000С). Для получения идентификатора оборудования (HardwareID) необходимо указать константу SPDRP_HARDWAREID (0x00000001);

PropertyRegDataType – указатель на переменную, в которую помещается тип возвращаемых функцией данных;

PropertyBuffer – указатель на буфер, в который возвращается значение указанного свойства. Если этот параметр указа как null и PropertyBufferSize указан как 0, то функция возвращает в RequiredSize необходимый размер буфера;

PropertyBufferSize – размер буфера для получения значения свойства;

RequiredSize – дополнительный параметр для получения размера буфера, если не используется, то null.

Функция SetupDiDestroyDeviceInfoList удаляет всю информацию об устройствах указанного класса, и очищаем память. В качестве параметра этой функции указывается дескриптор класса устройств(hDeviceInfoSet), который предварительно был получен функцией SetupDiGetClassDevs.

Функция CM_Get_Parent получает дескриптор родительской ветки в дереве устройств локальной машины.

CM_Get_Parent (pdnDevInst, dnDevInst, ulFlags),

где pdnDevInst – возвращаемый указатель на идентификатор родительского устройства;

dnDevInst – идентификатор устройства;

ulFlags – не используется, должен быть нулём.

Функция CM_Get_Device_ID_Size возвращает размер строки идентификатора устройства.

CM_Get_Device_ID_Size (pulLen, dnDevInst, ulFlags),

где pulLen – указатель на переменную для записи длины строки;

dnDevInst – идентификатор устройства;

ulFlags – не используется, должен быть нулем.

Функция CM_Get_Device_ID возвращает текстовый идентификатор экземпляра устройства ID.

CM_Get_Device_ID (dnDevInst, Buffer, BufferLen, ulFlags),

где dnDevInst – дескриптор устройства;

Buffer – указатель на буфер для записи строки идентификатора устройства;

BufferLen – длина строки идентификатора устройства;

ulFlags – не используется, должен быть нулем.

Функция CM_Request_Device_Eject выполняет безопасное извлечение устройства, а если это не возможно, то возвращает информацию об ошибке.

CM_Request_Device_Eject (dnDevInst, pVetoType, pszVetoName, ulNameLength, ulFlags),

где dnDevInst – дескриптор устройства;

pVetoType – дополнительный параметр для возвращения кода ошибки, если отказано в извлечении устройства;

pszVetoName – дополнительный параметр для возвращения текстового описания ошибки, в случае отказа в извлечении устройства;

ulNameLength – максимальная длина текстового описания ошибки;

ulFlags – не используется, должен быть нулем.

Функция CM_Locate_DevNode позволяет получить дескриптор устройства по строке идентификатора.

CM_Locate_DevNode (pdnDevInst, pDeviceID, ulFlags),

pdnDevInst – указатель на возвращаемый дескриптор устройства;

pDeviceID – указатель на строку идентификатора устройства;

ulFlags – флаг управления функцией. Может принимать четыре значения, мы будем использовать CM_LOCATE_DEVNODE_NORMAL = 0.

Функция CM_Get_DevNode_Status позволяет получить статус устройства, по которому можно определить, можно ли извлечь данное устройство. Если в статусе (pulStatus) возвращается флаг DN_REMOVABLE (0х4000), то устройство можно извлечь.

CM_Get_DevNode_Status (pulStatus, pulProblemNumber, dnDevInst, ulFlags),

где pulStatus – указатель на переменную со статусом устройства;

pulProblemNumber – указатель на переменную с номером ошибки;

dnDevInst – идентификатор устройства, у которого необходимо проверить статус;

ulFlags – не используется, должен быть нулем.