ホーム › Devices.PortableDevices › IPortableDeviceResources

IPortableDeviceResources

COM

IIDfd8878ac-d841-4d17-891c-e6829cdb6934継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IPortableDeviceResources インターフェイスは、オブジェクトの生データへのアクセスを提供します。オブジェクト内のリソースの読み取りや書き込みには、このインターフェイスを使用します。このインターフェイスを取得するには、IPortableDeviceContent::Transfer を呼び出します。

メソッド 6

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

vtbl 3 HRESULT GetSupportedResources(LPWSTR pszObjectID, IPortableDeviceKeyCollection** ppKeys)

GetSupportedResources メソッドは、特定のオブジェクトがサポートするリソースの一覧を取得します。

pszObjectID	LPWSTR	in	オブジェクトの ID を格納した、null で終わる文字列へのポインター。
ppKeys	IPortableDeviceKeyCollection**	out	このオブジェクト型がサポートするリソースの種類を示す PROPERTYKEY 値のコレクションを保持する IPortableDeviceKeyCollection インターフェイスへのポインターを受け取る変数のアドレス。オブジェクトがリソースを保持できない場合は、空のコレクションになります。呼び出し元は、使用を終えたらこのインターフェイスを解放する必要があります。

戻り値

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

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

解説(Remarks)

このメソッドが返すリソースの一覧には、そのオブジェクトがサポートし得るすべてのリソースが含まれます。これは、一覧に含まれるすべてのリソースが実際にデータを持っていることを意味するのではなく、オブジェクトが一覧の各リソースをサポートする能力を持つことを意味します。

vtbl 4 HRESULT GetResourceAttributes(LPWSTR pszObjectID, PROPERTYKEY* Key, IPortableDeviceValues** ppResourceAttributes)

GetResourceAttributes メソッドは、オブジェクト内の指定されたリソースからすべての属性を取得します。

pszObjectID	LPWSTR	in	リソースを保持しているオブジェクトのオブジェクト ID を格納した、null で終わる文字列へのポインター。
Key	PROPERTYKEY*	in	照会するリソースを指定する REFPROPERTYKEY。
ppResourceAttributes	IPortableDeviceValues**	out	各属性とその値をそれぞれ記述する PROPERTYKEY/PROPVARIANT のペアを保持する IPortableDeviceValues インターフェイスポインターへのポインター。属性値の値型はさまざまです。プロパティを返せなかった場合、返されるプロパティの値は VT_ERROR となり、PROPVARIANT の scode メンバーにその失敗を示す HRESULT が格納されます。

戻り値

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

戻り値	説明
S_OK	すべての属性値を取得しました。
S_FALSE	1 つ以上の属性値を取得できませんでした。それらは、取得された ppResourceAttributes パラメーター内で VT_ERROR 型の HRESULT 値を持ちます。
E_POINTER	必須のポインター引数のうち、少なくとも 1 つが NULL でした。

解説(Remarks)

リソース属性は、リソースに関連するアクセス権、サイズ、形式などの情報を表します。たとえば、画像オブジェクト上の音声注釈リソースの属性には、ビットレート、チャネル数、音声のデータ形式などが指定されることがあります。

vtbl 5 HRESULT GetStream(LPWSTR pszObjectID, PROPERTYKEY* Key, DWORD dwMode, DWORD* pdwOptimalBufferSize, IStream** ppStream)

GetStream メソッドは、デバイス上のオブジェクト内のコンテンツデータを読み書きするための IStream インターフェイスを取得します。取得したインターフェイスにより、オブジェクトのデータの読み取りや書き込みが可能になります。

pszObjectID	LPWSTR	in	オブジェクトのオブジェクト ID を格納した、null で終わる文字列へのポインター。
Key	PROPERTYKEY*	in	読み取るリソースを指定する REFPROPERTYKEY。オブジェクトのすべてのリソースのキーは、GetSupportedResources を呼び出して取得できます。
dwMode	DWORD	in	次のいずれかのアクセスモード: STGM_READ (読み取り専用アクセス) STGM_WRITE (書き込み専用アクセス) STGM_READWRITE (読み書きアクセス)
pdwOptimalBufferSize	DWORD*	inout	ppStream を使用してデータを読み書きする際に最適と推定されるバッファーサイズを格納する DWORD への省略可能なポインター。ドライバーはこの値をサポートする必要があります。
ppStream	IStream**	out	IStream インターフェイスポインターへのポインター。このインターフェイスは、オブジェクトへのデータの読み書きに使用されます。呼び出し元は、使用を終えたらこのインターフェイスを解放する必要があります。

戻り値

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

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

解説(Remarks)

取得したストリームでは、フォルダーの内容を再帰的に読み取ることはできません。オブジェクト内のすべてのリソースをコピーするには、Key に WPD_RESOURCE_DEFAULT を指定します。

オブジェクトがリソースをサポートしていない場合、このメソッドはエラーを返し、ppStream は NULL になります。

アプリケーションは、読み取りまたは書き込み操作用のバッファーを割り当てる際に、pdwOptimalBufferSize で返されたバッファーサイズを使用してください。

vtbl 6 HRESULT Delete(LPWSTR pszObjectID, IPortableDeviceKeyCollection* pKeys)

Delete メソッドは、pszObjectID パラメーターで指定されたオブジェクトから 1 つ以上のリソースを削除します。

pszObjectID	LPWSTR	in	オブジェクトのオブジェクト ID を格納した、null で終わる文字列へのポインター。
pKeys	IPortableDeviceKeyCollection*	in	削除するリソースを列挙する IPortableDeviceKeyCollection インターフェイスへのポインター。オブジェクトがどのリソースを持つかは、GetSupportedResources を呼び出して確認できます。

戻り値

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

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

解説(Remarks)

1 つのオブジェクトは複数のリソースを持つことができます。たとえば、あるオブジェクトが画像データ、サムネイル画像データ、音声データを含むことがあります。

アプリケーションは、GetSupportedResources メソッドを呼び出すことで、サポートされるリソースの一覧を取得できます。

vtbl 7 HRESULT Cancel()

Cancel メソッドは、保留中の操作をキャンセルします。(IPortableDeviceResources.Cancel)

戻り値

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

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

解説(Remarks)

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

vtbl 8 HRESULT CreateResource(IPortableDeviceValues* pResourceAttributes, IStream** ppData, DWORD* pdwOptimalWriteBufferSize, LPWSTR* ppszCookie)

CreateResource メソッドは、リソースを作成します。

pResourceAttributes

IPortableDeviceValues*

次のオブジェクトパラメーター属性へのポインター。

属性	説明
WPD_OBJECT_NAME	オブジェクト名。
WPD_RESOURCE_ATTRIBUTE_TOTAL_SIZE	リソースデータストリームの合計サイズ。
WPD_RESOURCE_ATTRIBUTE_FORMAT	リソースデータストリームの形式。
WPD_RESOURCE_ATTRIBUTE_RESOURCE_KEY	リソースキー。

ppData

IStream**

out

呼び出し元がリソースデータを書き込むためのストリームへのポインター。

pdwOptimalWriteBufferSize

DWORD*

inout

ストリームへの書き込み時に最適なバッファーサイズを示す値へのポインター。このパラメーターは省略可能です。

ppszCookie

LPWSTR*

inout

リソース作成要求を識別するクッキーへのポインター。このパラメーターは省略可能です。

戻り値

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

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

解説(Remarks)

アプリケーションがこのメソッドを呼び出す際は、リソース属性を指定し、このメソッドが返すストリームに必要なデータを書き込む必要があります。

リソースはメソッドが返った時点では作成されません。ppData が指すストリームに対してアプリケーションが Commit メソッドを呼び出してデータをコミットした時点で作成されます。

リソースへのデータ転送をキャンセルするには、アプリケーションは ppData が指すストリームに対して Revert メソッドを呼び出す必要があります。転送がキャンセルされたら、アプリケーションは IUnknown::Release を呼び出してストリームを閉じる必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IPortableDeviceResources "{FD8878AC-D841-4D17-891C-E6829CDB6934}"
#usecom global IPortableDeviceResources IID_IPortableDeviceResources "{}"
#comfunc global IPortableDeviceResources_GetSupportedResources  3 wstr,sptr
#comfunc global IPortableDeviceResources_GetResourceAttributes  4 wstr,var,sptr
#comfunc global IPortableDeviceResources_GetStream              5 wstr,var,int,var,sptr
#comfunc global IPortableDeviceResources_Delete                 6 wstr,sptr
#comfunc global IPortableDeviceResources_Cancel                 7
#comfunc global IPortableDeviceResources_CreateResource         8 sptr,sptr,var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IPortableDeviceResources "{FD8878AC-D841-4D17-891C-E6829CDB6934}"
#usecom global IPortableDeviceResources IID_IPortableDeviceResources "{}"
#comfunc global IPortableDeviceResources_GetSupportedResources  3 wstr,sptr
#comfunc global IPortableDeviceResources_GetResourceAttributes  4 wstr,sptr,sptr
#comfunc global IPortableDeviceResources_GetStream              5 wstr,sptr,int,sptr,sptr
#comfunc global IPortableDeviceResources_Delete                 6 wstr,sptr
#comfunc global IPortableDeviceResources_Cancel                 7
#comfunc global IPortableDeviceResources_CreateResource         8 sptr,sptr,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。