WdfDeviceRetrieveDeviceInterfaceString 함수(wdfdevice.h)

[KMDF 및 UMDF에 적용]

WdfDeviceRetrieveDeviceInterfaceString 메서드는 드라이버가 지정된 디바이스에 등록한 디바이스 인터페이스에 운영 체제가 할당한 기호 링크 이름을 검색합니다.

구문

NTSTATUS WdfDeviceRetrieveDeviceInterfaceString(
  [in]           WDFDEVICE        Device,
  [in]           const GUID       *InterfaceClassGUID,
  [in, optional] PCUNICODE_STRING ReferenceString,
  [in]           WDFSTRING        String
);

매개 변수

[in] Device

프레임워크 디바이스 개체에 대한 핸들입니다.

[in] InterfaceClassGUID

디바이스 인터페이스 클래스를 식별하는 GUID에 대한 포인터입니다.

[in, optional] ReferenceString

디바이스 인터페이스에 대한 참조 문자열을 설명하는 UNICODE_STRING 구조체에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 드라이버가 WdfDeviceCreateDeviceInterface를 호출할 때 참조 문자열을 지정하지 않은 경우 NULL일 수 있습니다.

[in] String

프레임워크 문자열 개체에 대한 핸들입니다. 프레임워크는 기호 링크 이름의 유니코드 문자열을 문자열 개체에 할당합니다.

반환 값

WdfDeviceRetrieveDeviceInterfaceString 은 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 메서드는 다음 값 중 하나를 반환할 수 있습니다.

반환 코드	설명
STATUS_INVALID_DEVICE_REQUEST	WdfDeviceRetrieveDeviceInterfaceString 은 IRQL = PASSIVE_LEVEL 호출되지 않았습니다.
STATUS_INVALID_PARAMETER	잘못된 매개 변수가 지정되었습니다.
STATUS_INVALID_DEVICE_REQUEST	지정된 디바이스 개체가 WdfControlDeviceInitAllocate에 의해 초기화되었습니다.
STATUS_OBJECT_NAME_NOT_FOUND	지정된 GUID 및 참조 문자열과 일치하는 디바이스 인터페이스를 찾을 수 없습니다.
STATUS_INVALID_DEVICE_STATE	드라이버가 WdfDeviceCreateDeviceInterface 라고 했지만 시스템에서 아직 디바이스 인터페이스에 기호 링크 이름을 할당하지 않았습니다.

 

WdfDeviceRetrieveDeviceInterfaceString 은 다른 NTSTATUS 값도 반환할 수 있습니다.

드라이버가 잘못된 개체 핸들을 제공하는 경우 버그 검사 발생합니다.

설명

디바이스 인터페이스에 대한 자세한 내용은 디바이스 인터페이스 사용을 참조하세요.

예제

다음 코드 예제에서는 문자열 개체를 만든 다음 지정된 디바이스 인터페이스의 기호 링크 이름을 검색합니다.

NTSTATUS status;
WDFSTRING string;

status = WdfStringCreate(
                         NULL,
                         WDF_NO_OBJECT_ATTRIBUTES,
                         &string
                         );
if (NT_SUCCESS(status)) {
    status = WdfDeviceRetrieveDeviceInterfaceString(
                         Device,
                         &GUID_DEVINTERFACE_DDI_TEST1,
                         NULL,
                         string
                         );
    if (!NT_SUCCESS(status)) {
        return status;
    }
}

요구 사항

요구 사항	값
대상 플랫폼	유니버설
최소 KMDF 버전	1.0
최소 UMDF 버전	2.0
머리글	wdfdevice.h(Wdf.h 포함)
라이브러리	Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF)
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

추가 정보

UNICODE_STRING

WdfControlDeviceInitAllocate

WdfDeviceCreateDeviceInterface

WdfStringCreate