IoGetDeviceProperty 함수(wdm.h)

아티클
02/27/2024

IoGetDeviceProperty 루틴은 구성 정보 및 해당 PDO의 이름과 같은 디바이스에 대한 정보를 검색합니다.

구문

NTSTATUS IoGetDeviceProperty(
  [in]            PDEVICE_OBJECT           DeviceObject,
  [in]            DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]            ULONG                    BufferLength,
  [out, optional] PVOID                    PropertyBuffer,
  [out]           PULONG                   ResultLength
);

매개 변수

[in] DeviceObject

쿼리 중인 디바이스에 대한 PDO(물리적 디바이스 개체)에 대한 포인터입니다.

[in] DeviceProperty

요청되는 디바이스 속성을 지정합니다. 다음 DEVICE_REGISTRY_PROPERTY 열거형 값 중 하나여야 합니다.

DevicePropertyAddress

버스에서 디바이스의 주소를 요청합니다. PropertyBuffer는 ULONG을 가리킵니다.

이 주소의 해석은 버스별로 다릅니다. 이 루틴의 호출자는 주소를 해석할 수 있도록 DevicePropertyBusTypeGuid 또는 DevicePropertyLegacyBusType을 요청하기 위해 루틴을 다시 호출해야 합니다. 주소 값 0xFFFFFFFF 기본 버스 드라이버가 디바이스에 대한 버스 주소를 제공하지 않았음을 나타냅니다.

다음 목록에서는 특정 버스 드라이버가 자식 디바이스의 PropertyBuffer 에 저장하는 정보를 설명합니다.

버스	Description
1394	주소가 휘발성이므로 주소를 제공하지 않습니다. 기본값은 0xFFFFFFFF.
Eisa	슬롯 번호(0-F)입니다.
IDE	IDE 디바이스의 경우 주소에 대상 ID 및 LUN이 포함됩니다. IDE 채널의 경우 주소는 0 또는 1(0 = 기본 채널 및 1 = 보조 채널)입니다.
ISApnp	주소를 제공하지 않습니다. 기본값은 0xFFFFFFFF.
PC 카드(PCMCIA)	소켓 번호(일반적으로 0x00 또는 0x40)입니다.
PCI	상위 단어의 디바이스 번호와 낮은 단어의 함수 번호입니다.
SCSI	대상 ID입니다.
USB	포트 번호.

DevicePropertyBootConfiguration

원시 형식으로 펌웨어에 의해 디바이스에 할당된 하드웨어 리소스를 요청합니다. PropertyBuffer는CM_RESOURCE_LIST 구조를 가리킵니다.

DevicePropertyBootConfigurationTranslated

펌웨어에 의해 디바이스에 할당된 하드웨어 리소스(변환된 형식)입니다. PropertyBuffer는CM_RESOURCE_LIST 구조를 가리킵니다.

DevicePropertyBusNumber

디바이스가 연결된 버스의 레거시 버스 번호를 요청합니다. PropertyBuffer는 ULONG을 가리킵니다.

DevicePropertyBusTypeGuid

디바이스가 연결된 버스에 대한 GUID를 요청합니다. 시스템 정의 버스 유형 GUID는 Wdmguid.h 헤더 파일에 나열됩니다. PropertyBuffer 는 이진 형식의 GUID를 포함하는 16바이트 구조체인 GUID를 가리킵니다.

DevicePropertyClassGuid

디바이스의 설정 클래스에 대한 GUID를 요청합니다. PropertyBuffer는 NULL로 끝나는 WCHAR 배열을 가리킵니다. 이 루틴은 다음과 같이 문자열 형식으로 GUID를 반환합니다. 여기서 각 "c"는 16진수 문자를 나타냅니다. {cccccccc-cccc-cccc-cccc}

DevicePropertyClassName

디바이스의 설정 클래스 이름을 텍스트 형식으로 요청합니다. PropertyBuffer는 NULL로 끝나는 WCHAR 문자열을 가리킵니다.

DevicePropertyCompatibleIDs

디바이스에서 보고한 호환 ID 를 요청합니다. PropertyBuffer는 REG_MULTI_SZ 값을 가리킵니다.

DevicePropertyDeviceDescription

일반적으로 제조업체에서 정의한 "Microsoft PS/2 포트 마우스"와 같이 디바이스를 설명하는 문자열을 요청합니다. PropertyBuffer는 NULL로 끝나는 WCHAR 문자열을 가리킵니다.

DevicePropertyDriverKeyName

드라이버별 레지스트리 키의 이름을 요청합니다. PropertyBuffer는 NULL로 끝나는 WCHAR 문자열을 가리킵니다.

DevicePropertyEnumeratorName

디바이스의 열거자 이름(예: "PCI" 또는 "root")을 요청합니다. PropertyBuffer는 NULL로 끝나는 WCHAR 문자열을 가리킵니다.

DevicePropertyFriendlyName

일반적으로 클래스 설치 관리자가 정의한 두 개의 유사한 디바이스를 구분하는 데 사용할 수 있는 문자열을 요청합니다. PropertyBuffer는 NULL로 끝나는 WCHAR 문자열을 가리킵니다.

DevicePropertyHardwareID

디바이스를 식별하는 디바이스에서 제공하는 하드웨어 ID를 요청합니다. PropertyBuffer는 REG_MULTI_SZ 값을 가리킵니다.

DevicePropertyInstallState

디바이스의 설치 상태를 요청합니다. 설치 상태는 DEVICE_INSTALL_STATE 열거형 값으로 반환됩니다.

DevicePropertyLegacyBusType

PCIBus 또는 PCMCIABus와 같은 버스 유형을 요청합니다. PropertyBuffer는INTERFACE_TYPE 열거형 값을 가리킵니다.

DevicePropertyLocationInformation

버스에서 디바이스의 위치에 대한 정보를 요청합니다. 이 정보의 해석은 버스에 따라 다릅니다. PropertyBuffer는 NULL로 끝나는 WCHAR 문자열을 가리킵니다.

DevicePropertyManufacturer

디바이스 제조업체를 식별하는 문자열을 요청합니다. PropertyBuffer는 NULL로 끝나는 WCHAR 문자열을 가리킵니다.

DevicePropertyPhysicalDeviceObjectName

이 디바이스의 PDO 이름을 요청합니다. PropertyBuffer는 NULL로 끝나는 WCHAR 문자열을 가리킵니다.

DevicePropertyRemovalPolicy

디바이스의 현재 제거 정책을 요청합니다. 운영 체제는 이 값을 힌트로 사용하여 디바이스가 일반적으로 제거되는 방식을 결정합니다. PropertyBuffer 매개 변수는 DEVICE_REMOVAL_POLICY 열거형 값을 가리킵니다.

DevicePropertyUINumber

사용자 인터페이스에 표시할 수 있는 디바이스와 연결된 번호를 요청합니다. PropertyBuffer는 ULONG 값을 가리킵니다.

이 번호는 일반적으로 보드의 슬롯 옆에 인쇄된 숫자 또는 사용자가 물리적 디바이스를 더 쉽게 찾을 수 있도록 하는 다른 번호와 같이 사용자가 인식하는 슬롯 번호입니다. 디바이스가 UI 번호 규칙이 없는 버스에 있거나 디바이스의 버스 드라이버가 UI 번호를 확인할 수 없는 경우 이 값은 0xFFFFFFFF.

[in] BufferLength

호출자가 제공한 PropertyBuffer의 크기(바이트)를 지정합니다.

[out, optional] PropertyBuffer

속성 정보를 수신하기 위해 호출자가 제공한 버퍼에 대한 포인터입니다. 버퍼는 페이징 가능한 메모리에서 할당할 수 있습니다. 버퍼의 형식은 DeviceProperty 에 의해 결정됩니다(위 참조).

[out] ResultLength

PropertyBuffer에서 반환된 속성 정보의 크기를 수신하는 ULONG에 대한 포인터입니다. IoGetDeviceProperty가 STATUS_BUFFER_TOO_SMALL 반환하는 경우 이 매개 변수를 필요한 버퍼 길이로 설정합니다.

반환 값

IoGetDeviceProperty 는 호출이 성공하면 STATUS_SUCCESS 반환합니다. 가능한 오류 반환 값은 다음과 같습니다.

반환 코드	설명
STATUS_BUFFER_TOO_SMALL	PropertyBuffer의 버퍼가 너무 작습니다. ResultLength 는 필요한 버퍼 길이를 가리킵니다.
STATUS_INVALID_PARAMETER_2	지정된 DeviceProperty 는 이 루틴에서 처리하는 속성 중 하나가 아닙니다.
STATUS_INVALID_DEVICE_REQUEST	지정된 DeviceObject 가 유효한 PDO 포인터가 아님을 나타내는 것일 수 있습니다.

설명

IoGetDeviceProperty 는 레지스트리에서 디바이스 설정 정보를 검색합니다. 레지스트리에 직접 액세스하는 대신 이 루틴을 사용하여 플랫폼 간 차이와 레지스트리 구조의 가능한 변경으로부터 드라이버를 격리합니다.

많은 DeviceProperty 요청의 경우 IoGetDeviceProperty 를 두 번 이상 호출하여 필요한 BufferLength를 확인할 수 있습니다. 첫 번째 호출은 최적 추측 값을 사용해야 합니다. 반환 상태 STATUS_BUFFER_TOO_SMALL 경우 드라이버는 현재 버퍼를 해제하고 ResultLength에서 반환된 크기의 버퍼를 할당한 다음 IoGetDeviceProperty를 다시 호출해야 합니다. 일부 설정 속성은 동적이므로 필요한 크기가 반환되고 드라이버가 이 루틴을 다시 호출하는 시간 사이에 데이터 크기가 변경됩니다. 따라서 드라이버는 반환 상태 STATUS_BUFFER_TOO_SMALL 않을 때까지 실행되는 루프 내에서 IoGetDeviceProperty를 호출해야 합니다.

레거시 버스 및 PnP 버스에서 디바이스를 지원하는 함수 드라이버는 DevicePropertyBusNumber, DevicePropertyBusTypeGuid 및 DevicePropertyLegacyBusType 속성을 사용하여 버스를 구분할 수 있습니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000부터 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)