CM_Get_Device_Interface_ListA関数 (cfgmgr32.h)

[アーティクル]
08/22/2023

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

デバイスインスタンス 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 ヘッダーは、CM_Get_Device_Interface_Listを別名として定義します。これは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイルエラーまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

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

こちらもご覧ください

CM_Get_Device_Interface_List_Size

Share via