ホーム › Devices.PortableDevices › IPortableDeviceContent

IPortableDeviceContent

COM

IID6a96ed84-7c73-4480-9938-bf5af477d426継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IPortableDeviceContent インターフェイスは、デバイス上のコンテンツを作成、列挙、調査、削除するためのメソッドを提供します。このインターフェイスを取得するには、IPortableDevice::Content を呼び出します。

メソッド 10

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

vtbl 3 HRESULT EnumObjects(DWORD dwFlags, LPWSTR pszParentObjectID, IPortableDeviceValues* pFilter, IEnumPortableDeviceObjectIDs** ppEnum)

EnumObjects メソッドは、あるオブジェクトの直下の子オブジェクトを列挙するために使用するインターフェイスを取得します。特定のプロパティを持つオブジェクトを列挙できる、省略可能なフィルターを備えています。

dwFlags	DWORD	in	現在は無視されます。ゼロを指定してください。
pszParentObjectID	LPWSTR	in	親の ID を指定する、null で終わる文字列へのポインター。空文字列 (ただし NULL ポインターは不可) を指定できるほか、デバイスのルートを示すために定義済み定数 WPD_DEVICE_OBJECT_ID を指定できます。
pFilter	IPortableDeviceValues*	in	このパラメーターは無視されます。NULL を設定してください。
ppEnum	IEnumPortableDeviceObjectIDs**	out	見つかったオブジェクトを列挙するために使用する IEnumPortableDeviceObjectIDs インターフェイスへのポインターを受け取る変数のアドレス。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。

戻り値

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

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

vtbl 4 HRESULT Properties(IPortableDeviceProperties** ppProperties)

Properties メソッドは、デバイス上のオブジェクトのプロパティを取得または設定するために必要なインターフェイスを取得します。

ppProperties

IPortableDeviceProperties**

out

オブジェクトのプロパティを取得または設定するために使用する IPortableDeviceProperties インターフェイスへのポインターを受け取る変数のアドレス。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。

戻り値

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

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

解説(Remarks)

取得されるインターフェイスは、デバイス上の特定のオブジェクトに固有のものではなく、デバイスに固有のものです。プロパティを取得または設定する際には、対象とするオブジェクトの ID を指定する必要があります。

例

このメソッドの使用例については、Setting Properties for a Single Object を参照してください。

vtbl 5 HRESULT Transfer(IPortableDeviceResources** ppResources)

Transfer メソッドは、既存のオブジェクトリソースのコンテンツデータを読み書きするために使用するインターフェイスを取得します。

ppResources

IPortableDeviceResources**

out

オブジェクトのリソースを変更するために使用する IPortableDeviceResources インターフェイスへのポインターを受け取る変数のアドレス。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。

戻り値

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

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

解説(Remarks)

このメソッドは通常、既存のオブジェクトから読み取るために使用します。

例

このメソッドの使用例については、Adding a Resource to an Object を参照してください。

vtbl 6 HRESULT CreateObjectWithPropertiesOnly(IPortableDeviceValues* pValues, LPWSTR* ppszObjectID)

CreateObjectWithPropertiesOnly メソッドは、プロパティのみを持つオブジェクトをデバイス上に作成します。

pValues	IPortableDeviceValues*	in	オブジェクトに割り当てるプロパティの IPortableDeviceValues コレクション。オブジェクトに必要なプロパティおよび省略可能なプロパティの一覧については、Requirements for Objects を参照してください。
ppszObjectID	LPWSTR*	inout	新しいオブジェクトの名前を受け取る、省略可能な文字列ポインター。不要であれば NULL を指定できます。Windows Portable Devices では、デバイスを表す定数 WPD_DEVICE_OBJECT_ID が定義されています。このメモリは SDK が割り当てるため、呼び出し元は CoTaskMemFree を使用して解放する必要があります。

戻り値

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

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

解説(Remarks)

オブジェクトには、プロパティの集合にすぎないもの (他のオブジェクトへのポインターの集合にすぎないフォルダーなど) と、プロパティとデータの両方から成るもの (すべてのプロパティと実際の音楽データを含むオーディオファイルなど) があります。このメソッドは、プロパティのみを含むオブジェクトを作成するために使用します。プロパティとデータの両方を持つオブジェクトを作成するには、CreateObjectWithPropertiesAndData を使用してください。

このメソッドは同期的です。戻った時点で、新しいオブジェクトはデバイス上に存在しているはずです。

ドライバーが実際に作成するオブジェクトは、ドライバーにとって最も都合のよいオブジェクトの種類に応じて、プロパティとデータの両方を持つオブジェクトになる場合があります。ドライバーがどの種類のオブジェクトを作成したかを確認するには、新しいオブジェクトの WPD_OBJECT_FORMAT プロパティを要求してください。

このメソッドが戻る時点で、オブジェクトはデバイス上に作成されています。

例

このメソッドの使用例については、Transferring a Properties-Only Object to the Device を参照してください。

vtbl 7 HRESULT CreateObjectWithPropertiesAndData(IPortableDeviceValues* pValues, IStream** ppData, DWORD* pdwOptimalWriteBufferSize, LPWSTR* ppszCookie)

CreateObjectWithPropertiesAndData メソッドは、プロパティとデータの両方を持つオブジェクトをデバイス上に作成します。

pValues	IPortableDeviceValues*	in	オブジェクトに割り当てるプロパティの IPortableDeviceValues コレクション。オブジェクトに必要なプロパティおよび省略可能なプロパティの一覧については、Requirements for Objects を参照してください。
ppData	IStream**	out	アプリケーションがオブジェクトのデータをデバイスへ送信するために使用する IStream インターフェイスへのポインターを受け取る変数のアドレス。アプリケーションが ppData->Commit を呼び出してデータを送信するまで、オブジェクトはデバイス上に作成されません。進行中のデータ転送を中止するには、ppData -> Revert を呼び出します。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。基になるオブジェクトは IStream と IPortableDeviceDataStream の両方を拡張しています。
pdwOptimalWriteBufferSize	DWORD*	inout	アプリケーションが ppData にデータを書き込む際に使用する最適なバッファーサイズを示す、省略可能な DWORD ポインター。アプリケーションはこれを無視するために TRUE を指定できます。
ppszCookie	LPWSTR*	inout	アプリケーションの IPortableDeviceEventCallback の実装 (実装している場合) において、この作成要求を識別するために使用される、省略可能な一意の null 終端文字列 ID。デバイスはオブジェクトの作成を完了すると、この識別子をコールバック関数に送信します。この識別子により、アプリケーションは CreateObjectWithPropertiesOnly を呼び出したスレッドとは別のスレッドでオブジェクトの作成を監視できます。このメモリは SDK が割り当てるため、呼び出し元は CoTaskMemFree を使用して解放する必要があります。

戻り値

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

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

解説(Remarks)

オブジェクトには、プロパティの集合にすぎないもの (他のオブジェクトへのポインターの集合にすぎないフォルダーなど) と、プロパティとデータの両方から成るもの (すべてのプロパティと実際の音楽データを含むオーディオファイルなど) があります。このメソッドは、プロパティとデータの両方を必要とするオブジェクトを作成するために使用します。プロパティのみのオブジェクトを作成するには、CreateObjectWithPropertiesOnly を呼び出してください。

オブジェクトは、アプリケーションが取得した IStream ppData に対して Commit を呼び出すまで作成されないため、Commit が呼び出されるまでオブジェクトには ID がありません。Commit は同期的であり、このメソッドが正常に戻った時点でオブジェクトはデバイス上に存在します。

Commit を呼び出してオブジェクトを作成した後、ppData に対して QueryInterface を呼び出して IPortableDeviceDataStream を取得し、続いて IPortableDeviceDataStream::GetObjectID を呼び出すことで、新しく作成されたオブジェクトの ID を取得できます。

例

このメソッドの使用例については、Transferring an Image or Music File to the Device を参照してください。

vtbl 8 HRESULT Delete(DWORD dwOptions, IPortableDevicePropVariantCollection* pObjectIDs, IPortableDevicePropVariantCollection** ppResults)

Delete メソッドは、1 つ以上のオブジェクトをデバイスから削除します。

dwOptions	DWORD	in	DELETE_OBJECT_OPTIONS の列挙子のいずれか。
pObjectIDs	IPortableDevicePropVariantCollection*	in	削除するオブジェクトのオブジェクト ID を指定する、1 つ以上の null 終端文字列 (型 VT_LPWSTR) を保持する IPortableDevicePropVariantCollection インターフェイスへのポインター。
ppResults	IPortableDevicePropVariantCollection**	inout	省略可能。戻り時に、このパラメーターには操作の成否を示す VT_ERROR 値のコレクションが格納されます。ppResults で返される最初の要素は pObjectIDs コレクションの最初のオブジェクトに対応し、2 番目の要素は 2 番目のオブジェクトに対応します (以下同様)。アプリケーションが結果を必要としない場合、このパラメーターは NULL にできます。

戻り値

このメソッドは HRESULT を返します。戻り値には次の表の値が含まれますが、これらに限定されません。エラー値が返された場合、デバイス上のオブジェクトは 1 つも削除されていません。

戻り値	説明
S_OK	メソッドは成功しました。
S_FALSE	少なくとも 1 つのオブジェクトを削除できませんでした。ppResults パラメーターを指定した場合、そこにオブジェクトごとのエラーコードが格納されます。
E_XXXXXXXX	ドライバーはオブジェクトを 1 つも削除しませんでした。
E_INVALIDARG	dwOptions に無効な値が指定されました。
E_ACCESSDENIED	アプリケーションにはオブジェクトを削除する権限がありません。
HRESULT_FROM_WIN32(ERROR_DIR_NOT_EMPTY)	指定されたフォルダーまたはディレクトリは空ではなかったため、削除できませんでした。
HRESULT_FROM_WIN32(ERROR_INVALID_OPERATION)	アプリケーションが PORTABLE_DEVICE_DELETE_NO_RECURSION を指定しましたが、オブジェクトに子が存在します。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	オブジェクトはデバイス上に存在しないため、削除できませんでした。

解説(Remarks)

再帰的な削除がサポートされているかどうかを確認するには、IPortableDeviceCapabilities::GetCommandOptions を呼び出します。取得した IPortableDeviceValues インターフェイスに WPD_OPTION_OBJECT_MANAGEMENT_RECURSIVE_DELETE_SUPPORTED というプロパティ値が含まれ、その boolVal の値が True であれば、そのデバイスは再帰的な削除をサポートしています。

次の表は、ppResults が指すコレクションに現れる可能性のある戻りコードの一覧です。

例

このメソッドの使用例については、Deleting Content from the Device を参照してください。

vtbl 9 HRESULT GetObjectIDsFromPersistentUniqueIDs(IPortableDevicePropVariantCollection* pPersistentUniqueIDs, IPortableDevicePropVariantCollection** ppObjectIDs)

GetObjectIDsFromPersistentUniqueIDs メソッドは、永続的一意 ID (PUID) を指定して、1 つ以上のオブジェクトの現在のオブジェクト ID を取得します。

pPersistentUniqueIDs	IPortableDevicePropVariantCollection*	in	1 つ以上の永続的一意 ID (PUID) の文字列値 (型 VT_LPWSTR) を含む IPortableDevicePropVariantCollection インターフェイスへのポインター。
ppObjectIDs	IPortableDevicePropVariantCollection**	out	取得したオブジェクト ID を VT_LPWSTR 型で含む IPortableDevicePropVariantCollection インターフェイスポインターへのポインター。取得される ID は、指定した PUID と同じ順序で並びます。値が見つからなかった場合は空文字列で示されます。呼び出し元は、使用が終わったらこのインターフェイスを解放する必要があります。

戻り値

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

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

解説(Remarks)

Windows Portable Devices のオブジェクト ID はデバイス内で一意ですが、セッションが変わると異なる場合があります。アプリケーションがデバイスに再接続すると、オブジェクト ID が変化することがあります。

同期エンジンなど一部のアプリケーションでは、接続セッションをまたいでオブジェクトを識別する手段が必要になります。すべてのオブジェクトは WPD_OBJECT_PERSISTENT_UNIQUE_ID プロパティを持ち、これはセッションをまたいで永続する識別子を示します。アプリケーションは、Properties メソッドを呼び出すことで、最初のセッションでこのプロパティを読み取って保存できます。

例

このメソッドの使用例については、Retrieving an Object Identifier from a Persistent Unique Identifier を参照してください。

vtbl 10 HRESULT Cancel()

Cancel メソッドは、このインターフェイスに対して呼び出された保留中の操作をキャンセルします。

戻り値

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

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

解説(Remarks)

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

vtbl 11 HRESULT Move(IPortableDevicePropVariantCollection* pObjectIDs, LPWSTR pszDestinationFolderObjectID, IPortableDevicePropVariantCollection** ppResults)

Move メソッドは、1 つ以上のオブジェクトをデバイス上のある場所から別の場所へ移動します。

pObjectIDs	IPortableDevicePropVariantCollection*	in	移動するオブジェクトのオブジェクト ID を指定する、1 つ以上の null 終端文字列 (型 VT_LPWSTR) を保持する IPortableDevicePropVariantCollection インターフェイスへのポインター。
pszDestinationFolderObjectID	LPWSTR	in	移動先の ID を指定する、null で終わる文字列へのポインター。
ppResults	IPortableDevicePropVariantCollection**	inout	省略可能。戻り時に、このパラメーターには操作の成否を示す VT_ERROR 値のコレクションが格納されます。ppResults で返される最初の要素は pObjectIDs コレクションの最初のオブジェクトに対応し、2 番目の要素は 2 番目のオブジェクトに対応します (以下同様)。アプリケーションが結果を必要としない場合、このパラメーターは NULL にできます。

戻り値

戻り値	説明
S_OK	メソッドは成功しました。
S_FALSE	1 つ以上のオブジェクトは削除されましたが、少なくとも 1 つのオブジェクトを削除できませんでした。削除されなかったオブジェクトを確認するには、ppFailedObjectIDs を参照してください。
E_ACCESSDENIED	アプリケーションにはオブジェクトを移動する権限がありません。
E_POINTER	必須の引数のうち少なくとも 1 つが NULL ポインターでした。

解説(Remarks)

指定したデバイスが機能ストレージ (functional storage) 上での移動操作をサポートしている場合、pszDestinationFolderObjectID パラメーターに機能ストレージの識別子を指定できます。

例

このメソッドの使用例については、Moving Content on the Device を参照してください。

vtbl 12 HRESULT Copy(IPortableDevicePropVariantCollection* pObjectIDs, LPWSTR pszDestinationFolderObjectID, IPortableDevicePropVariantCollection** ppResults)

Copy メソッドは、デバイス上のある場所から別の場所へオブジェクトをコピーします。

pObjectIDs	IPortableDevicePropVariantCollection*	in	このメソッドがコピーするオブジェクトのオブジェクト識別子のコレクション。
pszDestinationFolderObjectID	LPWSTR	in	このメソッドが指定されたオブジェクトのコピー先とする、コピー先フォルダー (または機能ストレージ) のオブジェクト識別子。
ppResults	IPortableDevicePropVariantCollection**	inout	個々の要素のコピーの成否を示す VT_ERROR 値のコレクション。最初のエラー値はオブジェクト識別子コレクションの最初のオブジェクトに対応し、2 番目のエラー値は 2 番目の要素に対応します (以下同様)。この引数は NULL にできます。

戻り値

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

戻り値	説明
S_OK	メソッドは成功しました。
S_FALSE	少なくとも 1 つのオブジェクトでコピー操作が失敗しました。
E_ACCESSDENIED	アプリケーションには、指定されたオブジェクトのいずれかをコピーする権限がありません。

解説(Remarks)

指定したデバイスが機能ストレージ (functional storage) へのコピー操作をサポートしている場合、pszDestinationFolderObjectID パラメーターに機能ストレージの識別子を指定できます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IPortableDeviceContent "{6A96ED84-7C73-4480-9938-BF5AF477D426}"
#usecom global IPortableDeviceContent IID_IPortableDeviceContent "{}"
#comfunc global IPortableDeviceContent_EnumObjects                          3 int,wstr,sptr,sptr
#comfunc global IPortableDeviceContent_Properties                           4 sptr
#comfunc global IPortableDeviceContent_Transfer                             5 sptr
#comfunc global IPortableDeviceContent_CreateObjectWithPropertiesOnly       6 sptr,var
#comfunc global IPortableDeviceContent_CreateObjectWithPropertiesAndData    7 sptr,sptr,var,var
#comfunc global IPortableDeviceContent_Delete                               8 int,sptr,sptr
#comfunc global IPortableDeviceContent_GetObjectIDsFromPersistentUniqueIDs  9 sptr,sptr
#comfunc global IPortableDeviceContent_Cancel                               10
#comfunc global IPortableDeviceContent_Move                                 11 sptr,wstr,sptr
#comfunc global IPortableDeviceContent_Copy                                 12 sptr,wstr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IPortableDeviceContent "{6A96ED84-7C73-4480-9938-BF5AF477D426}"
#usecom global IPortableDeviceContent IID_IPortableDeviceContent "{}"
#comfunc global IPortableDeviceContent_EnumObjects                          3 int,wstr,sptr,sptr
#comfunc global IPortableDeviceContent_Properties                           4 sptr
#comfunc global IPortableDeviceContent_Transfer                             5 sptr
#comfunc global IPortableDeviceContent_CreateObjectWithPropertiesOnly       6 sptr,sptr
#comfunc global IPortableDeviceContent_CreateObjectWithPropertiesAndData    7 sptr,sptr,sptr,sptr
#comfunc global IPortableDeviceContent_Delete                               8 int,sptr,sptr
#comfunc global IPortableDeviceContent_GetObjectIDsFromPersistentUniqueIDs  9 sptr,sptr
#comfunc global IPortableDeviceContent_Cancel                               10
#comfunc global IPortableDeviceContent_Move                                 11 sptr,wstr,sptr
#comfunc global IPortableDeviceContent_Copy                                 12 sptr,wstr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。