ホーム › Devices.PortableDevices › IPortableDeviceService

IPortableDeviceService

COM

📘 Microsoft Learn (日本語) · English

IIDd3bd3a44-d7b5-40a9-98b7-2fa4d01dec08継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

サービスへのアクセスを提供します。

メソッド 11

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

vtbl 3 HRESULT Open(LPWSTR pszPnPServiceID, IPortableDeviceValues* pClientInfo)

サービスへの接続を開きます。

pszPnPServiceID	LPWSTR	in	サービスのプラグアンドプレイ (PnP) 識別子。GetPnPServiceId メソッドで取得される識別子と同じものです。
pClientInfo	IPortableDeviceValues*	in	クライアント情報を指定する IPortableDeviceValues インターフェイス。

戻り値

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

戻り値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	pszPnPServiceID パラメーターで指定された PnP 識別子が無効です。
E_POINTER	NULL のパラメーターが指定されました。
E_WPD_SERVICE_ALREADY_OPENED	このメソッドは、そのサービスに対して既に呼び出されています。

vtbl 4 HRESULT Capabilities(IPortableDeviceServiceCapabilities** ppCapabilities)

サービスの機能 (ケイパビリティ) を取得します。

ppCapabilities

IPortableDeviceServiceCapabilities**

out

サービスの機能 (ケイパビリティ) を示す IPortableDeviceServiceCapabilities インターフェイス。

戻り値

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

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	NULL のパラメーターが指定されました。

vtbl 5 HRESULT Content(IPortableDeviceContent2** ppContent)

サービスのコンテンツへのアクセスを取得します。

ppContent

IPortableDeviceContent2**

out

サービスのコンテンツにアクセスする IPortableDeviceContent2 インターフェイス。

戻り値

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

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	NULL のパラメーターが指定されました。

vtbl 6 HRESULT Methods(IPortableDeviceServiceMethods** ppMethods)

サービス上のカスタム機能を呼び出すために使用する IPortableDeviceServiceMethods インターフェイスを取得します。

ppMethods

IPortableDeviceServiceMethods**

out

指定したサービス上でメソッドを呼び出すために使用する IPortableDeviceServiceMethods インターフェイス。

戻り値

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

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	NULL のパラメーターが指定されました。

vtbl 7 HRESULT Cancel()

このインターフェイスで保留中の操作をキャンセルします。

戻り値

メソッドが成功すると S_OK を返します。それ以外の HRESULT 値は、呼び出しが失敗したことを示します。

解説(Remarks)

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

アプリケーションが複数のスレッドから WPD API を呼び出す場合は、各スレッドで IPortableDeviceService インターフェイスの新しいインスタンスを作成してください。こうすることで、キャンセル操作の影響が該当スレッドの I/O のみに限定されます。

vtbl 8 HRESULT Close()

サービスへの接続を解放します。

戻り値

メソッドが成功すると S_OK を返します。それ以外の HRESULT 値は、呼び出しが失敗したことを示します。

解説(Remarks)

サービスへの最後の参照が解放された時点で Windows Portable Devices (WPD) API が自動的にこのメソッドを呼び出すため、通常、アプリケーションがこのメソッドを呼び出すことはありません。

アプリケーションがこのメソッドを呼び出した場合、WPD API はサービス接続を解放するため、そのサービスに接続されている WPD オブジェクトは E_WPD_SERVICE_NOT_OPEN エラーを返すようになります。

vtbl 9 HRESULT GetServiceObjectID(LPWSTR* ppszServiceObjectID)

サービスのオブジェクト識別子を取得します。このオブジェクト識別子は、たとえばサービスのプロパティにアクセスするために使用できます。

ppszServiceObjectID

LPWSTR*

out

取得されたサービスのオブジェクト識別子。

戻り値

メソッドが成功すると S_OK を返します。それ以外の HRESULT 値は、呼び出しが失敗したことを示します。

vtbl 10 HRESULT GetPnPServiceID(LPWSTR* ppszPnPServiceID)

サービスのプラグアンドプレイ (PnP) 識別子を取得します。

ppszPnPServiceID

LPWSTR*

out

取得された PnP 識別子。Open メソッドに渡された識別子と同じものです。

戻り値

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

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	NULL のパラメーターが指定されました。
E_WPD_SERVICE_NOT_OPEN	そのサービスに対して Open メソッドがまだ呼び出されていません。

解説(Remarks)

PnP 識別子を取得するには、事前にサービスに対して Open メソッドを呼び出しておく必要があります。

PnP 識別子が不要になったら、アプリケーションは CoTaskMemFree 関数を呼び出して識別子のメモリを解放してください。

vtbl 11 HRESULT Advise(DWORD dwFlags, IPortableDeviceEventCallback* pCallback, IPortableDeviceValues* pParameters, LPWSTR* ppszCookie)

サービスイベントを受け取る、アプリケーション定義のコールバックオブジェクトを登録します。

dwFlags	DWORD	in	使用されません。
pCallback	IPortableDeviceEventCallback*	in	登録するコールバックオブジェクトを指定する IPortableDeviceEventCallback インターフェイス。
pParameters	IPortableDeviceValues*	in	イベント登録パラメーターを指定する IPortableDeviceValues インターフェイス。コールバックオブジェクトがすべてのサービスイベントを受け取る場合は NULL を指定します。
ppszCookie	LPWSTR*	out	コールバックオブジェクトの一意なコンテキスト ID。この値は、コールバックオブジェクトの登録を解除する Unadvise メソッドで使用する値と一致します。

戻り値

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

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	pCallback パラメーターまたは ppszCookie パラメーターに NULL 値が指定されました。

解説(Remarks)

クリーンアップ時には、アプリケーションは Unadvise メソッドを呼び出してコールバックオブジェクトの登録を解除し、その後 CoTaskMemFree 関数を呼び出して ppszCookie パラメーターが参照するメモリを解放してください。

vtbl 12 HRESULT Unadvise(LPWSTR pszCookie)

サービスイベントのコールバックオブジェクトの登録を解除します。

pszCookie

LPWSTR

アプリケーションが提供したコールバックオブジェクトの一意なコンテキスト ID。この値は、Advise メソッドの ppszCookie パラメーターで得られた値と一致します。

戻り値

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

戻り値	説明
S_OK	メソッドは成功しました。
E_POINTER	NULL のパラメーターが指定されました。

vtbl 13 HRESULT SendCommand(DWORD dwFlags, IPortableDeviceValues* pParameters, IPortableDeviceValues** ppResults)

標準の WPD コマンドとそのパラメーターをサービスに送信します。

dwFlags	DWORD	in	使用されません。
pParameters	IPortableDeviceValues*	in	コマンドパラメーターを指定する IPortableDeviceValues インターフェイス。
ppResults	IPortableDeviceValues**	out	コマンドの結果を示す IPortableDeviceValues インターフェイス。

戻り値

メソッドが成功すると S_OK を返します。それ以外の HRESULT 値は、呼び出しが失敗したことを示します。

解説(Remarks)

このメソッドは、標準の WPD コマンドをサービスに送信する場合にのみ使用してください。サービスのメソッドを呼び出すには、IPortableDeviceServiceMethods インターフェイスを使用します。

このメソッドは、HRESULT 値として S_OK を返した場合でも失敗していることがあります。コマンドが成功したかどうかを判断するために、アプリケーションは必ず ppResults パラメーターが参照するプロパティを確認してください。

WPD_PROPERTY_COMMON_HRESULT プロパティは、コマンドが成功したかどうかを示します。
コマンドが失敗した場合、WPD_PROPERTY_COMMON_DRIVER_ERROR_CODE プロパティにドライバー固有のエラーコードが格納されます。

pParameters パラメーターが参照するオブジェクトには、少なくとも次のプロパティを指定する必要があります。

WPD_PROPERTY_COMMON_COMMAND_CATEGORY: コマンドカテゴリ (WPD_COMMAND_COMMON_RESET_DEVICE プロパティの fmtid メンバーなど) を格納します。
WPD_PROPERTY_COMMON_COMMAND_ID: コマンド識別子 (WPD_COMMAND_COMMON_RESET_DEVICE プロパティの pid メンバーなど) を格納します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IPortableDeviceService "{D3BD3A44-D7B5-40A9-98B7-2FA4D01DEC08}"
#usecom global IPortableDeviceService IID_IPortableDeviceService "{EF5DB4C2-9312-422C-9152-411CD9C4DD84}"
#comfunc global IPortableDeviceService_Open                3 wstr,sptr
#comfunc global IPortableDeviceService_Capabilities        4 sptr
#comfunc global IPortableDeviceService_Content             5 sptr
#comfunc global IPortableDeviceService_Methods             6 sptr
#comfunc global IPortableDeviceService_Cancel              7
#comfunc global IPortableDeviceService_Close               8
#comfunc global IPortableDeviceService_GetServiceObjectID  9 var
#comfunc global IPortableDeviceService_GetPnPServiceID     10 var
#comfunc global IPortableDeviceService_Advise              11 int,sptr,sptr,var
#comfunc global IPortableDeviceService_Unadvise            12 wstr
#comfunc global IPortableDeviceService_SendCommand         13 int,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IPortableDeviceService "{D3BD3A44-D7B5-40A9-98B7-2FA4D01DEC08}"
#usecom global IPortableDeviceService IID_IPortableDeviceService "{EF5DB4C2-9312-422C-9152-411CD9C4DD84}"
#comfunc global IPortableDeviceService_Open                3 wstr,sptr
#comfunc global IPortableDeviceService_Capabilities        4 sptr
#comfunc global IPortableDeviceService_Content             5 sptr
#comfunc global IPortableDeviceService_Methods             6 sptr
#comfunc global IPortableDeviceService_Cancel              7
#comfunc global IPortableDeviceService_Close               8
#comfunc global IPortableDeviceService_GetServiceObjectID  9 sptr
#comfunc global IPortableDeviceService_GetPnPServiceID     10 sptr
#comfunc global IPortableDeviceService_Advise              11 int,sptr,sptr,sptr
#comfunc global IPortableDeviceService_Unadvise            12 wstr
#comfunc global IPortableDeviceService_SendCommand         13 int,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。