CM_Get_Device_ID_ListW関数 (cfgmgr32.h)
CM_Get_Device_ID_List関数は、ローカル コンピューターのデバイス インスタンスのデバイス インスタンス ID の一覧を取得します。
構文
CMAPI CONFIGRET CM_Get_Device_ID_ListW(
[in, optional] PCWSTR pszFilter,
[out] PZZWSTR 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 によって表されます。 複合 devnode は、複合開発ノードが物理デバイスへの複数のパスを持つことができますが、ユーザーとアプリケーションに対する複合デバイスを論理的に 1 つのデバイスとして表します。
物理デバイスへのアクティブな各トランスポート パスは、トランスポート devnode で表され、複合デバイスの トランスポート関係 と呼ばれます。
複合 devnode (ただし、関連するトランスポート devnodes ではない) は、アプリケーションとシステムにデバイス インターフェイスを公開します。 アプリケーションでこれらのパブリック デバイス インターフェイスを使用すると、複合デバイスはパケット ベースのデータをこれらのトランスポート devnode の 1 つ以上にルーティングし、そのデータを物理デバイスに転送します。
たとえば、物理携帯電話が USB 上のコンピューターと Bluetooth バスに同時に接続されている場合、各バスはそのバス上の子トランスポート devnode を列挙して、デバイスの物理的な接続を表します。
この場合、 ulFlags でCM_GETIDLIST_FILTER_TRANSPORTRELATIONS フラグを設定し、 pszFilter で携帯電話の複合 devnode のデバイス インスタンス ID を指定すると、この関数は Buffer パラメーターの 2 つのトランスポート devnode のデバイス インスタンス ID を返します。
デバイス インスタンス ID の詳細については、「 デバイス識別文字列」を参照してください。
注意
cfgmgr32.h ヘッダーは、CM_Get_Device_ID_Listを別名として定義します。これは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
要件 | 値 |
---|---|
サポートされている最小のクライアント | Microsoft Windows 2000 以降のバージョンの Windows で使用できます。 |
対象プラットフォーム | ユニバーサル |
Header | cfgmgr32.h (Cfgmgr32.h を含む) |
Library | Cfgmgr32.lib |
[DLL] | CfgMgr32.dll |