ホーム › Devices.PortableDevices › IPortableDeviceManager

IPortableDeviceManager

COM

📘 Microsoft Learn (日本語) · English

IIDa1567595-4c2f-4574-a6fa-ecef917b9a40継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

コンピューターに接続されているデバイスを列挙し、製造元、フレンドリ名、説明などのインストール情報を簡単に要求する手段を提供します。

メソッド 7

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT GetDevices(LPWSTR* pPnPDeviceIDs, DWORD* pcPnPDeviceIDs)

コンピューターに接続されているポータブルデバイスの一覧を取得します。

pPnPDeviceIDs	LPWSTR*	inout	接続されているすべてのデバイスのプラグアンドプレイ名を格納する、呼び出し元が割り当てた文字列ポインターの配列です。このパラメーターに必要なサイズを知るには、まずこのパラメーターを NULL、pcPnPDeviceIDs を 0 に設定してこのメソッドを呼び出し、pcPnPDeviceIDs で取得された値に従ってバッファーを割り当てます。これらの名前は、デバイスへの接続を作成するために IPortableDevice::Open で使用できます。
pcPnPDeviceIDs	DWORD*	inout	入力時は、pPnPDeviceIDs が保持できる値の数です。出力時は、実際に pPnPDeviceIDs に書き込まれたデバイス数へのポインターです。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表の値が含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	必須の引数のうち少なくとも 1 つが NULL ポインターでした。
S_FALSE	pPnPDeviceIDs バッファーが要求されたすべての値を保持するには小さすぎますが、pcPnPDeviceIDs 個の値が pPnPDeviceIDs に書き込まれました。

解説(Remarks)

デバイスの一覧はデバイスマネージャーがインスタンス化された時点で生成され、デバイスの接続や切断に応じて更新されることはありません。接続されているデバイスの一覧を更新するには、RefreshDeviceList を呼び出してください。

pPnPDeviceIDs 配列が指す各文字列のメモリは API が割り当てます。アプリケーションでこれらの文字列が不要になったら、この配列を反復処理し、CoTaskMemFree 関数を呼び出して関連するメモリを解放する必要があります。

例

このメソッドを使用してデバイスを列挙する方法の例については、Enumerating Devices を参照してください。このメソッドを使用してサービスを列挙する方法の例については、Enumerating Services を参照してください。

vtbl 4 HRESULT RefreshDeviceList()

RefreshDeviceList メソッドは、コンピューターに接続されているデバイスの一覧を更新します。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表の値が含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。

解説(Remarks)

IPortableDeviceManager インターフェイスが最初にインスタンス化されるとき、接続されているデバイスの一覧が生成されます。しかし、デバイスはコンピューターに接続されたり切断されたりするため、元の一覧は古くなる可能性があります。このメソッドを使用すると、アプリケーションは接続されているデバイスの一覧を更新できます。

このメソッドは、新しいデバイス一覧を生成するために新たにデバイスマネージャーをインスタンス化するよりもリソース消費が少なくて済みます。ただし、ある程度のリソースは必要とするため、むやみに呼び出さないことを推奨します。最適な方法は、アプリケーションでデバイスの到着および削除の通知を受け取るように登録し、通知を受け取ったときにこの関数を呼び出すことです。

vtbl 5 HRESULT GetDeviceFriendlyName(LPWSTR pszPnPDeviceID, LPWSTR pDeviceFriendlyName, DWORD* pcchDeviceFriendlyName)

デバイスのユーザーフレンドリ名を取得します。

pszPnPDeviceID	LPWSTR	in	デバイスのプラグアンドプレイ ID を含む null 終端文字列へのポインターです。コンピューターに接続されているすべてのデバイスのプラグアンドプレイ名の一覧は、GetDevices を呼び出すことで取得できます。
pDeviceFriendlyName	LPWSTR	inout	デバイスのユーザーフレンドリ名を保持するために使用される、呼び出し元が割り当てたバッファーです。このパラメーターに必要なサイズを知るには、まずこのパラメーターを NULL、pcchDeviceFriendlyName を 0 に設定してこのメソッドを呼び出します。メソッドは成功し、終端文字を含めてデバイスのフレンドリ名を保持するために必要なバッファーサイズが pcchDeviceFriendlyName に設定されます。
pcchDeviceFriendlyName	DWORD*	inout	入力時は、終端文字を含めて pDeviceFriendlyName が保持できる最大文字数です。出力時は、同じく終端文字を含めて pDeviceFriendlyName によって返される文字数です。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表の値が含まれますが、これらに限定されません。

戻り値	説明
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	指定されたバッファーはデバイスの説明を保持するのに十分な大きさではありません。(必要なサイズについては pcchDeviceDescription に返された値を参照してください。)
HRESULT_FROM_WIN32(ERROR_INVALID_DATA)	デバイスの説明が見つかりませんでした。
S_OK	メソッドは成功しました。
E_POINTER	必須の引数のうち少なくとも 1 つが NULL ポインターでした。

解説(Remarks)

デバイスがこのメソッドをサポートする必要はありません。このメソッドで名前を取得できない場合は、デバイスオブジェクト (ID が WPD_DEVICE_OBJECT_ID のオブジェクト) の WPD_OBJECT_NAME プロパティを要求してみてください。

vtbl 6 HRESULT GetDeviceDescription(LPWSTR pszPnPDeviceID, LPWSTR pDeviceDescription, DWORD* pcchDeviceDescription)

デバイスの説明を取得します。

pszPnPDeviceID	LPWSTR	in	デバイスのプラグアンドプレイ ID を含む null 終端文字列へのポインターです。現在接続されているデバイスのプラグアンドプレイ名の一覧は、GetDevices を呼び出すことで取得できます。
pDeviceDescription	LPWSTR	inout	デバイスのユーザー向けの説明名を保持する、呼び出し元が割り当てたバッファーです。呼び出し元はこのパラメーターのメモリを割り当てる必要があります。このパラメーターに必要なサイズを知るには、まずこのパラメーターを NULL、pcchDeviceDescription を 0 に設定してこのメソッドを呼び出します。メソッドは成功し、終端文字を含めてデバイスのフレンドリ名を保持するために必要なバッファーサイズが pcchDeviceDescription に設定されます。
pcchDeviceDescription	DWORD*	inout	pDeviceDescription 内の文字数 (終端文字は含みません)。入力時は pDeviceDescription の最大長、出力時は pDeviceDescription に返された文字列の長さです。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表の値が含まれますが、これらに限定されません。

戻り値	説明
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	指定されたバッファーはデバイスの説明を保持するのに十分な大きさではありません。(必要なサイズについては pcchDeviceDescription に返された値を参照してください。)
HRESULT_FROM_WIN32(ERROR_INVALID_DATA)	デバイスの説明が見つかりませんでした。
S_OK	メソッドは成功しました。
E_POINTER	必須の引数のうち少なくとも 1 つが NULL ポインターでした。

vtbl 7 HRESULT GetDeviceManufacturer(LPWSTR pszPnPDeviceID, LPWSTR pDeviceManufacturer, DWORD* pcchDeviceManufacturer)

デバイスの製造元名を取得します。

pszPnPDeviceID	LPWSTR	in	デバイスのプラグアンドプレイ ID を含む null 終端文字列へのポインターです。コンピューターに接続されているすべてのデバイスのプラグアンドプレイ名の一覧は、GetDevices を呼び出すことで取得できます。
pDeviceManufacturer	LPWSTR	inout	デバイスの製造元名を保持する、呼び出し元が割り当てたバッファーです。このパラメーターに必要なサイズを知るには、まずこのパラメーターを NULL、pcchDeviceManufacturer を 0 に設定してこのメソッドを呼び出します。メソッドは成功し、終端文字を含めてデバイスのフレンドリ名を保持するために必要なバッファーサイズが pcchDeviceManufacturer に設定されます。
pcchDeviceManufacturer	DWORD*	inout	入力時は、終端文字を含めずに pDeviceManufacturer が保持できる最大文字数です。出力時は、同じく終端文字を含めずに pDeviceManufacturer によって返される文字数です。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表の値が含まれますが、これらに限定されません。

戻り値	説明
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	指定されたバッファーはデバイスの説明を保持するのに十分な大きさではありません。(必要なサイズについては pcchDeviceDescription に返された値を参照してください。)
HRESULT_FROM_WIN32(ERROR_INVALID_DATA)	デバイスの説明が見つかりませんでした。
S_OK	メソッドは成功しました。
E_POINTER	必須の引数のうち少なくとも 1 つが NULL ポインターでした。

vtbl 8 HRESULT GetDeviceProperty(LPWSTR pszPnPDeviceID, LPWSTR pszDevicePropertyName, BYTE* pData, DWORD* pcbData, DWORD* pdwType)

デバイスがコンピューター上に保存したプロパティ値を取得します。(これらは Windows Portable Devices によって定義される標準のプロパティではありません。)

pszPnPDeviceID	LPWSTR	in	デバイスのプラグアンドプレイ ID を含む null 終端文字列へのポインターです。コンピューターに接続されているすべてのデバイスのプラグアンドプレイ名の一覧は、GetDevices を呼び出すことで取得できます。
pszDevicePropertyName	LPWSTR	in	要求するプロパティの名前を含む null 終端文字列へのポインターです。これらはデバイス製造元によって定義されたカスタムプロパティ名です。
pData	BYTE*	inout	取得したデータを保持する、呼び出し元が割り当てたバッファーです。必要なサイズを取得するには、このパラメーターを NULL、pcbData を 0 に設定してこのメソッドを呼び出すと、必要なサイズが pcbData に取得されます。この呼び出しではエラーも返されますが、無視して構いません。「戻り値」を参照してください。
pcbData	DWORD*	inout	pData によって割り当てられた、または返されたバッファーのサイズ (バイト単位)。
pdwType	DWORD*	inout	pData に返されるデータの型を示す定数です。このパラメーターの値は、Platform SDK 関数 RegQueryValueEx の lpType パラメーターを表すために使用される型と同じです。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表の値が含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	指定されたバッファーは要求されたデータを保持するのに十分な大きさではありません。(pData が NULL の場合、この結果が常に返されます。必要なバッファーサイズを取得するためにこのメソッドを呼び出している場合は、この結果を無視できます。pData パラメーターの説明を参照してください。)
E_POINTER	必須の引数のうち少なくとも 1 つが NULL ポインターでした。

解説(Remarks)

これらのプロパティ値は、デバイスのインストール時に保存されるか、接続セッションをまたいで保持できるようにデバイスが動作中に保存したものです。アプリケーションはデバイス自身が指定するプロパティの正確な名前を知っている必要があります。したがって、このメソッドは独自のアプリケーションを作成するデバイス開発者による使用を想定しています。

デバイスオブジェクトから Windows Portable Devices のプロパティを取得するには、IPortableDeviceProperties::GetValues を呼び出し、デバイスオブジェクトを WPD_DEVICE_OBJECT_ID で指定します。

vtbl 9 HRESULT GetPrivateDevices(LPWSTR* pPnPDeviceIDs, DWORD* pcPnPDeviceIDs)

GetPrivateDevices メソッドは、コンピューターに接続されているプライベートポータブルデバイスの一覧を取得します。これらのプライベートデバイスには、当該デバイス専用に設計されたアプリケーションからのみアクセスできます。

pPnPDeviceIDs	LPWSTR*	inout	接続されているすべてのデバイスのプラグアンドプレイ名を格納する、呼び出し元が割り当てた文字列ポインターの配列です。このパラメーターに必要なサイズを知るには、まずこのパラメーターを NULL、pcPnPDeviceIDs を 0 に設定してこのメソッドを呼び出し、pcPnPDeviceIDs で取得された値に従ってバッファーを割り当てます。これらの名前は、デバイスへの接続を作成するために IPortableDevice::Open で使用できます。
pcPnPDeviceIDs	DWORD*	inout	入力時は、pPnPDeviceIDs が保持できる値の数です。出力時は、実際に pPnPDeviceIDs に書き込まれたデバイス数へのポインターです。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表の値が含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	必須の引数のうち少なくとも 1 つが NULL ポインターでした。
S_FALSE	pPnPDeviceIDs バッファーが要求されたすべての値を保持するには小さすぎますが、pcPnPDeviceIDs 個の値が pPnPDeviceIDs に書き込まれました。

解説(Remarks)

プライベートデバイスと通信するアプリケーションを作成するには、特定のデバイスドライバーが公開するカスタム機能に関する知識が必要です。この機能の説明はデバイス製造元から入手する必要があります。

プライベートデバイスは、オブジェクトの列挙、リソースの転送、デバイスの機能 (ケイパビリティ) の取得などを行う標準の Windows Portable Devices 関数呼び出しに正しく応答しない場合があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IPortableDeviceManager "{A1567595-4C2F-4574-A6FA-ECEF917B9A40}"
#usecom global IPortableDeviceManager IID_IPortableDeviceManager "{0AF10CEC-2ECD-4B92-9581-34F6AE0637F3}"
#comfunc global IPortableDeviceManager_GetDevices             3 var,var
#comfunc global IPortableDeviceManager_RefreshDeviceList      4
#comfunc global IPortableDeviceManager_GetDeviceFriendlyName  5 wstr,var,var
#comfunc global IPortableDeviceManager_GetDeviceDescription   6 wstr,var,var
#comfunc global IPortableDeviceManager_GetDeviceManufacturer  7 wstr,var,var
#comfunc global IPortableDeviceManager_GetDeviceProperty      8 wstr,wstr,var,var,var
#comfunc global IPortableDeviceManager_GetPrivateDevices      9 var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IPortableDeviceManager "{A1567595-4C2F-4574-A6FA-ECEF917B9A40}"
#usecom global IPortableDeviceManager IID_IPortableDeviceManager "{0AF10CEC-2ECD-4B92-9581-34F6AE0637F3}"
#comfunc global IPortableDeviceManager_GetDevices             3 sptr,sptr
#comfunc global IPortableDeviceManager_RefreshDeviceList      4
#comfunc global IPortableDeviceManager_GetDeviceFriendlyName  5 wstr,sptr,sptr
#comfunc global IPortableDeviceManager_GetDeviceDescription   6 wstr,sptr,sptr
#comfunc global IPortableDeviceManager_GetDeviceManufacturer  7 wstr,sptr,sptr
#comfunc global IPortableDeviceManager_GetDeviceProperty      8 wstr,wstr,sptr,sptr,sptr
#comfunc global IPortableDeviceManager_GetPrivateDevices      9 sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。