CM_Get_Device_ID_ListA関数 (cfgmgr32.h)
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 |