ホーム › Devices.PortableDevices › IPortableDeviceCapabilities

IPortableDeviceCapabilities

COM

IID2c8c6dbf-e3dc-4061-becc-8542e810d126継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IPortableDeviceCapabilities インターフェイスは、サポートされるフォーマット、コマンド、機能オブジェクトなど、さまざまなデバイスの機能 (ケイパビリティ) を表します。このインターフェイスは、IPortableDevice::Capabilities を呼び出すことでデバイスから取得できます。

メソッド 11

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

vtbl 3 HRESULT GetSupportedCommands(IPortableDeviceKeyCollection** ppCommands)

GetSupportedCommands メソッドは、このデバイスがサポートするすべてのコマンドの一覧を取得します。

ppCommands

IPortableDeviceKeyCollection**

out

有効なすべてのコマンドを保持する IPortableDeviceKeyCollection インターフェイスへのポインターを受け取る変数のアドレスです。Windows Portable Devices で定義されているコマンドの一覧については、Commands を参照してください。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。

戻り値

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

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

解説(Remarks)

なし。

vtbl 4 HRESULT GetCommandOptions(PROPERTYKEY* Command, IPortableDeviceValues** ppOptions)

GetCommandOptions メソッドは、デバイス上の指定されたコマンドについて、サポートされるすべてのオプションを取得します。

Command	PROPERTYKEY*	in	サポートされるオプションを照会する対象のコマンドを指定する REFPROPERTYKEY です。Windows Portable Devices で定義されているコマンドの一覧については、Commands を参照してください。
ppOptions	IPortableDeviceValues**	out	サポートされるオプションを格納した IPortableDeviceValues インターフェイスへのポインターを受け取る変数のアドレスです。オプションがサポートされていない場合、値は 1 つも格納されません。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。詳細については「解説」を参照してください。

戻り値

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

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

解説(Remarks)

このメソッドは、IPortableDevice::SendCommand を呼び出してドライバーに対して直接コマンドを発行しようとするアプリケーションから呼び出されます。コマンドによっては、呼び出し元が追加のオプションを指定できます。たとえば、一部のドライバーは、WPD_COMMAND_OBJECT_MANAGEMENT_DELETE_OBJECTS コマンドでオブジェクトを削除する際に、子オブジェクトの再帰的な削除をサポートします。

オプションが単純なブール値である場合、取得した IPortableDeviceValues インターフェイスのキーはそのオプションの名前になり、PROPVARIANT の値は True または False の VT_BOOL 値になります。オプションが複数の値を持つ場合、取得される PROPVARIANT の値は、サポートされる値を保持するコレクション型になります。

WPD_COMMAND_STORAGE_FORMAT コマンドに対してこのメソッドを呼び出し、ppOptions パラメーターに WPD_OPTION_VALID_OBJECT_IDS が設定されている場合、ドライバーはフォーマット可能なデバイス上の各オブジェクトの識別子を示す、VT_LPWSTR 型の IPortableDevicePropVariant コレクションを返します。(このオプションが存在しない場合、フォーマットコマンドはすべてのオブジェクトで利用可能です。)

vtbl 5 HRESULT GetFunctionalCategories(IPortableDevicePropVariantCollection** ppCategories)

GetFunctionalCategories メソッドは、デバイスがサポートするすべての機能カテゴリを取得します。

ppCategories

IPortableDevicePropVariantCollection**

out

このデバイスのすべての機能カテゴリを保持する IPortableDevicePropVariantCollection インターフェイスへのポインターを受け取る変数のアドレスです。値は、取得される PROPVARIANT 値において VT_CLSID 型の GUID になります。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。

戻り値

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

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

解説(Remarks)

機能カテゴリは、画像のキャプチャ、音声のキャプチャ、ストレージなど、デバイスが実行できる機能の種類を表します。通常、ドライバーは起動時にのみデバイスへ照会し、その結果をキャッシュするため、このメソッドは非常に高速です。

例

このメソッドの使用例については、Retrieving the Functional Categories Supported by a Device を参照してください。

vtbl 6 HRESULT GetFunctionalObjects(GUID* Category, IPortableDevicePropVariantCollection** ppObjectIDs)

GetFunctionalObjects メソッドは、デバイス上で指定されたカテゴリに一致するすべての機能オブジェクトを取得します。

Category	GUID*	in	検索対象のカテゴリを指定する REFGUID です。すべての機能オブジェクトを返すには、WPD_FUNCTIONAL_CATEGORY_ALL を指定できます。
ppObjectIDs	IPortableDevicePropVariantCollection**	out	機能オブジェクトのオブジェクト ID を文字列として (取得される PROPVARIANT 項目では VT_LPWSTR 型) 格納する IPortableDevicePropVariantCollection インターフェイスへのポインターを受け取る変数のアドレスです。要求された種類のオブジェクトが見つからない場合、これは (NULL ではなく) 空のコレクションになります。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。

戻り値

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

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

解説(Remarks)

ドライバーはコンテンツの完全な列挙を行う必要がなく、また取得される機能オブジェクトの数も通常は 10 個未満であるため、この操作は通常高速です。要求された種類のオブジェクトが見つからない場合でも、このメソッドはエラーを返さず、ppObjectIDs に空のコレクションを返します。

例

このメソッドの使用例については、Retrieving the Functional Object Identifiers for a Device を参照してください。

vtbl 7 HRESULT GetSupportedContentTypes(GUID* Category, IPortableDevicePropVariantCollection** ppContentTypes)

GetSupportedContentTypes メソッドは、デバイス上の指定された機能オブジェクトの種類について、サポートされるすべてのコンテンツの種類を取得します。

Category	GUID*	in	機能オブジェクトのカテゴリを指定する REFGUID です。デバイス上の機能カテゴリの一覧を取得するには、IPortableDeviceCapabilities::GetFunctionalCategories を呼び出します。
ppContentTypes	IPortableDevicePropVariantCollection**	out	指定された機能オブジェクトのカテゴリに対してサポートされるすべてのオブジェクトの種類を列挙する IPortableDevicePropVariantCollection インターフェイスへのポインターを受け取る変数のアドレスです。これらのオブジェクトの種類は、取得される PROPVARIANT 項目において VT_CLSID 型の GUID 値になります。Windows Portable Devices で定義されているオブジェクトの種類の一覧については、Requirements for Objects を参照してください。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。

戻り値

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

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

vtbl 8 HRESULT GetSupportedFormats(GUID* ContentType, IPortableDevicePropVariantCollection** ppFormats)

GetSupportedFormats メソッドは、デバイス上の指定されたオブジェクトの種類についてサポートされるフォーマットを取得します。たとえば、音声オブジェクトを指定すると、WPD_OBJECT_FORMAT_WMA、WPD_OBJECT_FORMAT_WAV、WPD_OBJECT_FORMAT_MP3 が返されることがあります。

ContentType	GUID*	in	画像、音声、ビデオなど、コンテンツの種類を指定する REFGUID です。Windows Portable Devices で定義されているコンテンツの種類の一覧については、Requirements for Objects を参照してください。
ppFormats	IPortableDevicePropVariantCollection**	out	指定されたコンテンツの種類に対してサポートされるフォーマットを列挙する IPortableDevicePropVariantCollection インターフェイスへのポインターを受け取る変数のアドレスです。これらは、取得されるコレクション項目における GUID 値 (VT_CLSID 型) です。Windows Portable Devices でサポートされるフォーマットの一覧については、Object Formats を参照してください。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。

戻り値

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

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	引数の少なくとも 1 つが NULL ポインターでした。

vtbl 9 HRESULT GetSupportedFormatProperties(GUID* Format, IPortableDeviceKeyCollection** ppKeys)

GetSupportedFormatProperties メソッドは、デバイス上で指定されたフォーマットのオブジェクトがサポートするプロパティを取得します。

Format	GUID*	in	オブジェクトのフォーマットを指定する REFGUID です。Windows Portable Devices で定義されているフォーマットの一覧については、Object Formats を参照してください。
ppKeys	IPortableDeviceKeyCollection**	out	指定されたフォーマットでサポートされるプロパティを格納した IPortableDeviceKeyCollection インターフェイスへのポインターを受け取る変数のアドレスです。Windows Portable Devices で定義されているプロパティの一覧については、Properties and Attributes を参照してください。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。

戻り値

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

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

解説(Remarks)

プロパティ属性の完全な一式を取得するには、Format パラメーターに WPD_OBJECT_FORMAT_ALL を指定できます。

オブジェクトが特定のプロパティに値を持たない場合や、そのプロパティが削除されている場合、デバイスによってはプロパティの列挙時にそのプロパティをまったく報告しないことがあります。一方、別のデバイスでは、そのプロパティを空の文字列やゼロの値とともに報告することがあります。こうした不整合を避けるために、このメソッドを呼び出して、特定のオブジェクトに設定できるすべてのプロパティを把握できます。

vtbl 10 HRESULT GetFixedPropertyAttributes(GUID* Format, PROPERTYKEY* Key, IPortableDeviceValues** ppAttributes)

GetFixedPropertyAttributes メソッドは、指定されたプロパティとフォーマットに対する標準のプロパティ属性を取得します。

Format	GUID*	in	対象となるオブジェクトのフォーマットを指定する REFGUID です。フォーマットの GUID 値については、Object Formats を参照してください。
Key	PROPERTYKEY*	in	属性を知りたいプロパティを指定する REFPROPERTYKEY です。Windows Portable Devices で定義されているプロパティは、Properties and Attributes に一覧があります。
ppAttributes	IPortableDeviceValues**	out	属性とその値を保持する IPortableDeviceValues インターフェイスへのポインターを受け取る変数のアドレスです。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。

戻り値

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

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

解説(Remarks)

プロパティ属性の完全な一式を取得するには、Format パラメーターに WPD_OBJECT_FORMAT_ALL を指定できます。

属性はプロパティを記述します。属性の例としては、WPD_PROPERTY_ATTRIBUTE_CAN_READ や WPD_PROPERTY_ATTRIBUTE_CAN_WRITE があります。このメソッドはリソース属性を取得しません。

vtbl 11 HRESULT Cancel()

Cancel メソッドは、このインターフェイスで保留中の要求をキャンセルします。

戻り値

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

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

解説(Remarks)

このメソッドは、現在のデバイスハンドル (IPortableDevice インターフェイスに関連付けられたセッションに対応します) 上で保留中のすべての操作をキャンセルします。Windows Portable Devices (WPD) API は、特定の操作だけを対象としたキャンセルをサポートしていません。

vtbl 12 HRESULT GetSupportedEvents(IPortableDevicePropVariantCollection** ppEvents)

GetSupportedEvents メソッドは、このデバイスがサポートするイベントを取得します。

ppEvents

IPortableDevicePropVariantCollection**

out

サポートされるイベントを列挙する IPortableDevicePropVariantCollection インターフェイスへのポインターを受け取る変数のアドレスです。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。

戻り値

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

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	引数の少なくとも 1 つが NULL ポインターでした。

vtbl 13 HRESULT GetEventOptions(GUID* Event, IPortableDeviceValues** ppOptions)

GetEventOptions メソッドは、デバイス上の指定されたイベントについて、サポートされるすべてのオプションを取得します。

Event	GUID*	in	サポートされるオプションを照会する対象のイベントを指定する REFGUID です。Windows Portable Devices で定義されているイベントの一覧については、Events を参照してください。
ppOptions	IPortableDeviceValues**	out	サポートされるオプションを格納した IPortableDeviceValues インターフェイスへのポインターを受け取る変数のアドレスです。オプションがサポートされていない場合、値は 1 つも格納されません。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。

戻り値

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

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	引数の少なくとも 1 つが NULL ポインターでした。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IPortableDeviceCapabilities "{2C8C6DBF-E3DC-4061-BECC-8542E810D126}"
#usecom global IPortableDeviceCapabilities IID_IPortableDeviceCapabilities "{}"
#comfunc global IPortableDeviceCapabilities_GetSupportedCommands          3 sptr
#comfunc global IPortableDeviceCapabilities_GetCommandOptions             4 var,sptr
#comfunc global IPortableDeviceCapabilities_GetFunctionalCategories       5 sptr
#comfunc global IPortableDeviceCapabilities_GetFunctionalObjects          6 var,sptr
#comfunc global IPortableDeviceCapabilities_GetSupportedContentTypes      7 var,sptr
#comfunc global IPortableDeviceCapabilities_GetSupportedFormats           8 var,sptr
#comfunc global IPortableDeviceCapabilities_GetSupportedFormatProperties  9 var,sptr
#comfunc global IPortableDeviceCapabilities_GetFixedPropertyAttributes    10 var,var,sptr
#comfunc global IPortableDeviceCapabilities_Cancel                        11
#comfunc global IPortableDeviceCapabilities_GetSupportedEvents            12 sptr
#comfunc global IPortableDeviceCapabilities_GetEventOptions               13 var,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IPortableDeviceCapabilities "{2C8C6DBF-E3DC-4061-BECC-8542E810D126}"
#usecom global IPortableDeviceCapabilities IID_IPortableDeviceCapabilities "{}"
#comfunc global IPortableDeviceCapabilities_GetSupportedCommands          3 sptr
#comfunc global IPortableDeviceCapabilities_GetCommandOptions             4 sptr,sptr
#comfunc global IPortableDeviceCapabilities_GetFunctionalCategories       5 sptr
#comfunc global IPortableDeviceCapabilities_GetFunctionalObjects          6 sptr,sptr
#comfunc global IPortableDeviceCapabilities_GetSupportedContentTypes      7 sptr,sptr
#comfunc global IPortableDeviceCapabilities_GetSupportedFormats           8 sptr,sptr
#comfunc global IPortableDeviceCapabilities_GetSupportedFormatProperties  9 sptr,sptr
#comfunc global IPortableDeviceCapabilities_GetFixedPropertyAttributes    10 sptr,sptr,sptr
#comfunc global IPortableDeviceCapabilities_Cancel                        11
#comfunc global IPortableDeviceCapabilities_GetSupportedEvents            12 sptr
#comfunc global IPortableDeviceCapabilities_GetEventOptions               13 sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。