Описание библиотеки SetupAPI.dll

Для получения списка аппаратуры и отслеживания аппаратных изменений, как и в предыдущем случае, возможностей.NET недостаточно, и будут использоваться функции из библиотеки SetupAPI.dll.

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

Основными функциями библиотеки SetupAPI.dll являются:

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

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

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

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

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

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

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

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 – не используется, должен быть нулем.