CM_Get_Device_Interface_ListA 함수(cfgmgr32.h)

  • 아티클

CM_Get_Device_Interface_List 함수는 지정된 디바이스 인터페이스 클래스에 속하는 디바이스 인터페이스 인스턴스 목록을 검색합니다.

구문

CMAPI CONFIGRET CM_Get_Device_Interface_ListA(
  [in]           LPGUID      InterfaceClassGuid,
  [in, optional] DEVINSTID_A pDeviceID,
  [out]          PZZSTR      Buffer,
  [in]           ULONG       BufferLen,
  [in]           ULONG       ulFlags
);

매개 변수

[in] InterfaceClassGuid

디바이스 인터페이스 클래스를 식별하는 GUID를 제공합니다.

[in, optional] pDeviceID

디바이스 instance ID를 나타내는 NULL로 끝나는 문자열에 대한 호출자 제공 포인터입니다. 지정된 경우 함수는 지정된 클래스에 대해 디바이스에서 지원하는 디바이스 인터페이스를 검색합니다. 이 값이 NULL이거나 길이가 0인 문자열을 가리키는 경우 함수는 지정된 클래스에 속하는 모든 인터페이스를 검색합니다.

[out] Buffer

인터페이스 instance 기호 링크 이름을 나타내는 여러 NULL로 끝나는 유니코드 문자열을 수신하는 버퍼에 대한 호출자 제공 포인터입니다.

[in] BufferLen

버퍼가 가리키는 버퍼의 길이를 문자 단위로 지정하는 호출자 제공 값입니다. CM_Get_Device_Interface_List_Size 호출하여 필요한 버퍼 크기를 확인합니다.

[in] ulFlags

다음 호출자 제공 플래그 중 하나를 포함합니다.

CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES

함수는 지정된 GUID 및 디바이스 instance ID(있는 경우)와 일치하는 모든 디바이스와 연결된 디바이스 인터페이스를 포함하는 목록을 제공합니다.

CM_GET_DEVICE_INTERFACE_LIST_PRESENT

함수는 현재 활성 상태이고 지정된 GUID 및 디바이스 instance ID(있는 경우)와 일치하는 디바이스와 연결된 디바이스 인터페이스가 포함된 목록을 제공합니다.

반환 값

작업이 성공하면 함수는 CR_SUCCESS 반환합니다. 그렇지 않으면 Cfgmgr32.h에 정의된 대로 CR_ 접두사를 사용하여 오류 코드 중 하나를 반환합니다.

다음 표에는 이 함수가 반환할 수 있는 몇 가지 일반적인 오류 코드가 포함되어 있습니다.

반환 코드 설명
CR_BUFFER_SMALL
 버퍼 버퍼가 너무 작아서 요청된 디바이스 인터페이스 목록을 보관할 수 없습니다.

설명

목록의 크기를 가져오기 위해 CM_Get_Device_Interface_List_Size 호출하고 CM_Get_Device_Interface_List 호출하여 목록을 가져오는 사이에 새 디바이스 인터페이스를 시스템에 추가하여 반환된 크기가 더 이상 유효하지 않게 만들 수 있습니다.  호출자는 해당 조건에 견고해야 하며 CM_Get_Device_Interface_List CR_BUFFER_SMALL 반환하는 경우 크기와 목록을 가져오려고 다시 시도해야 합니다.

예제

이 코드 조각은 주의 섹션에 설명된 대로 크기 및 목록을 가져오는 재시도를 보여 줍니다.

    CONFIGRET cr = CR_SUCCESS;
    PWSTR DeviceInterfaceList = NULL;
    ULONG DeviceInterfaceListLength = 0;

    do {
        cr = CM_Get_Device_Interface_List_Size(&DeviceInterfaceListLength,
                                               (LPGUID)&GUID_DEVINTERFACE_VOLUME,
                                               NULL,
                                               CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES);

        if (cr != CR_SUCCESS)
        {
            break;
        }

        if (DeviceInterfaceList != NULL) {
            HeapFree(GetProcessHeap(),
                     0,
                     DeviceInterfaceList);
        }

        DeviceInterfaceList = (PWSTR)HeapAlloc(GetProcessHeap(),
                                               HEAP_ZERO_MEMORY,
                                               DeviceInterfaceListLength * sizeof(WCHAR));

        if (DeviceInterfaceList == NULL)
        {
            cr = CR_OUT_OF_MEMORY;
            break;
        }

        cr = CM_Get_Device_Interface_List((LPGUID)&GUID_DEVINTERFACE_VOLUME,
                                          NULL,
                                          DeviceInterfaceList,
                                          DeviceInterfaceListLength,
                                          CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES);
    } while (cr == CR_BUFFER_SMALL);

    if (cr != CR_SUCCESS)
    {
        goto Exit;
    }

참고

cfgmgr32.h 헤더는 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 CM_Get_Device_Interface_List 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Microsoft Windows 2000 이상 버전의 Windows에서 사용할 수 있습니다.
대상 플랫폼 유니버설
헤더 cfgmgr32.h(Cfgmgr32.h 포함)
라이브러리 Cfgmgr32.lib
DLL CfgMgr32.dll

추가 정보

CM_Get_Device_Interface_List_Size