CM_Get_Device_ID_ListA関数 (cfgmgr32.h)

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

CM_Get_Device_ID_List関数は、ローカルコンピューターのデバイスインスタンスのデバイスインスタンス ID の一覧を取得します。

構文

CMAPI CONFIGRET CM_Get_Device_ID_ListA(
  [in, optional] PCSTR  pszFilter,
  [out]          PZZSTR Buffer,
  [in]           ULONG  BufferLen,
  [in]           ULONG  ulFlags
);

パラメーター

[in, optional] pszFilter

コンピューターのデバイスインスタンス識別子 (ID) のサブセットまたは NULL に設定されている文字列への呼び出し元指定ポインター。 ulFlags の次の説明を参照してください。

[out] Buffer

NULL で終わるデバイスインスタンス識別子文字列のセットを受け取るバッファーのアドレス。セットの末尾は、追加の NULL で終了します。必要なバッファーサイズは、 CM_Get_Device_ID_List_Sizeを呼び出すことによって取得する必要があります。

[in] BufferLen

Buffer で指定されたバッファーの呼び出し元から指定された長さ (文字数)。

[in] ulFlags

検索フィルターを指定する、呼び出し元から提供される次のいずれかのビットフラグ。

CM_GETIDLIST_FILTER_BUSRELATIONS

このフラグが設定されている場合、 pszFilter はデバイスインスタンス識別子を指定する必要があります。関数は、指定されたデバイスインスタンスのバス関係のデバイスインスタンス ID を返します。

CM_GETIDLIST_FILTER_CLASS (Windows 7 以降のバージョンの Windows)

このフラグが設定されている場合、 pszFilter にはデバイスセットアップクラス GUID を指定する文字列が含まれます。返されるリストには、(CM_DRP_CLASSGUID定数によって参照される) プロパティが指定されたデバイスセットアップクラス GUID と一致するデバイスインスタンスが含まれています。

CM_DRP_CLASSGUID定数は Cfgmgr32.h で定義されています。

CM_GETIDLIST_FILTER_PRESENT (Windows 7 以降のバージョンの Windows)

このフラグが設定されている場合、返されるリストには、システム上に現在存在するデバイスインスタンスのみが含まれます。この値は、CM_GETIDLIST_FILTER_CLASSなどの他 の ulFlags 値と組み合わせることができます。

CM_GETIDLIST_FILTER_TRANSPORTRELATIONS (Windows 7 以降のバージョンの Windows)

このフラグが設定されている場合、 pszFilter は複合デバイスノード (devnode) のデバイスインスタンス識別子を指定する必要があります。

関数は、指定された複合 devnode のトランスポート関係を表す devnode のデバイスインスタンス識別子を返します。

複合開発ノードとトランスポート関係の詳細については、次の 「解説 」セクションを参照してください。

CM_GETIDLIST_DONOTGENERATE

CM_GETIDLIST_FILTER_SERVICEでのみ使用されます。を設定し、デバイスツリーに指定されたサービスの devnode が含まれていない場合、このフラグを設定すると、関数がサービスの devnode を作成できなくなります。

CM_GETIDLIST_FILTER_EJECTRELATIONS

このフラグが設定されている場合、 pszFilter はデバイスインスタンス識別子を指定する必要があります。関数は、指定されたデバイスインスタンスの排出関係のデバイスインスタンス ID を返します。

CM_GETIDLIST_FILTER_ENUMERATOR

このフラグが設定されている場合、 pszFilter はデバイス列挙子の名前を指定し、必要に応じてデバイス ID を指定する必要があります。文字列形式は、ROOT や ROOT\<*PNP0500 などの EnumeratorName\DeviceID> です。

pszFilter が列挙子名のみを提供する場合、この関数は列挙子に関連付けられている各デバイスのインスタンスのデバイスインスタンス ID を返します。列挙子名は、 CM_Enumerate_Enumeratorsを呼び出すことによって取得できます。

pszFilter が列挙子とデバイス ID の両方を提供する場合、この関数は列挙子に関連付けられている指定されたデバイスのインスタンスに対してのみデバイスインスタンス ID を返します。

CM_GETIDLIST_FILTER_NONE

このフラグが設定されている場合、 pszFilter は無視され、システム上のすべてのデバイスの一覧が返されます。

CM_GETIDLIST_FILTER_POWERRELATIONS

このフラグが設定されている場合、 pszFilter はデバイスインスタンス識別子を指定する必要があります。関数は、指定されたデバイスインスタンスの電源関係のデバイスインスタンス ID を返します。

CM_GETIDLIST_FILTER_REMOVALRELATIONS

このフラグが設定されている場合、 pszFilter はデバイスインスタンス識別子を指定する必要があります。関数は、指定されたデバイスインスタンスの削除関係のデバイスインスタンス ID を返します。

CM_GETIDLIST_FILTER_SERVICE

このフラグが設定されている場合、 pszFilter は Microsoft Windows サービス (通常はドライバー) の名前を指定する必要があります。関数は、指定されたサービスによって制御されるデバイスインスタンスのデバイスインスタンス ID を返します。

デバイスツリーに指定されたサービスの devnode が含まれていない場合、この関数は既定で作成します。この動作を抑制するには、CM_GETIDLIST_DONOTGENERATEも設定します。

検索フィルターフラグが指定されていない場合、関数はすべてのデバイスインスタンスのすべてのデバイスインスタンス ID を返します。

戻り値

操作が成功した場合、関数は CR_SUCCESSを返します。それ以外の場合は、 Cfgmgr32.h で定義されているCR_プレフィックス付きのエラーコードのいずれかを返します。

注釈

Windows 7 以降、パケットベースのデータの複数のトランスポートパスをサポートするデバイスは複合デバイスと呼ばれ、複合開発ノードによって表されます。複合 devnode は、複合開発ノードが物理デバイスへの複数のパスを持つことができますが、ユーザーとアプリケーションに対する複合デバイスを 1 つのデバイスとして論理的に表します。

物理デバイスへの各アクティブなトランスポートパスは、トランスポート開発ノードで表され、複合デバイスの トランスポート関係 と呼ばれます。

複合開発ノード (ただし、関連するトランスポート devnode ではない) は、デバイスインターフェイスをアプリケーションとシステムに公開します。アプリケーションでこれらのパブリックデバイスインターフェイスを使用する場合、複合デバイスはパケットベースのデータをこれらのトランスポート devnode の 1 つ以上にルーティングし、そのデータを物理デバイスに転送します。

たとえば、物理携帯電話が USB と Bluetooth バス上のコンピューターに同時に接続されている場合、各バスは、デバイスの物理接続を表すために、そのバス上の子トランスポート devnode を列挙します。

この場合、 ulFlags でCM_GETIDLIST_FILTER_TRANSPORTRELATIONS フラグを設定し、 pszFilter で携帯電話の複合開発ノードのデバイスインスタンス ID を指定すると、この関数は Buffer パラメーターの 2 つのトランスポート開発ノードのデバイスインスタンス ID を返します。

デバイスインスタンス ID の詳細については、「デバイス識別文字列」を参照してください。

注意

cfgmgr32.h ヘッダーは、unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとしてCM_Get_Device_ID_Listを定義します。エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

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

こちらもご覧ください

CM_Get_Device_ID_List_Size