CM_Get_Device_Interface_ListW関数 (cfgmgr32.h)

[アーティクル]
02/23/2024

CM_Get_Device_Interface_List関数は、指定されたデバイスインターフェイスクラスに属するデバイスインターフェイスインスタンスの一覧を取得します。

構文

CMAPI CONFIGRET CM_Get_Device_Interface_ListW(
  [in]           LPGUID      InterfaceClassGuid,
  [in, optional] DEVINSTID_W pDeviceID,
  [out]          PZZWSTR     Buffer,
  [in]           ULONG       BufferLen,
  [in]           ULONG       ulFlags
);

パラメーター

[in] InterfaceClassGuid

デバイスインターフェイスクラスを識別する GUID を提供します。

[in, optional] pDeviceID

デバイスインスタンス ID を表す NULL で終わる文字列への呼び出し元指定ポインター。指定した場合、関数は、指定したクラスのデバイスでサポートされているデバイスインターフェイスを取得します。この値が NULL の場合、または長さ 0 の文字列を指している場合、関数は指定されたクラスに属するすべてのインターフェイスを取得します。

[out] Buffer

インターフェイスインスタンスのシンボリックリンク名を表す複数の NULL で終わる Unicode 文字列を受け取るバッファーへの呼び出し元指定ポインター。

[in] BufferLen

Buffer が指すバッファーの長さを文字数で指定する呼び出し元から指定された値。 CM_Get_Device_Interface_List_Sizeを呼び出して、必要なバッファーサイズを決定します。

[in] ulFlags

呼び出し元から指定された次のいずれかのフラグが含まれています。

CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES

関数は、指定された GUID とデバイスインスタンス ID (存在する場合) に一致するすべてのデバイスに関連付けられているデバイスインターフェイスを含む一覧を提供します。

CM_GET_DEVICE_INTERFACE_LIST_PRESENT

関数は、現在アクティブなデバイスに関連付けられているデバイスインターフェイスと、指定された GUID とデバイスインスタンス 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 ヘッダーは、unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとしてCM_Get_Device_Interface_Listを定義します。エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Microsoft Windows 2000 以降のバージョンの Windows で使用できます。
対象プラットフォーム	ユニバーサル
Header	cfgmgr32.h (Cfgmgr32.h を含む)
Library	Cfgmgr32.lib
[DLL]	CfgMgr32.dll

こちらもご覧ください

CM_Get_Device_Interface_List_Size