ホーム › Devices.Enumeration.Pnp › IUPnPServiceAsync

IUPnPServiceAsync

COM

IID098bdaf5-5ec1-49e7-a260-b3a11dd8680c継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

このインターフェイスを使用すると、サービスのインスタンスに対して状態変数の非同期クエリやアクションの呼び出しを行えます。

メソッド 9

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

vtbl 3 HRESULT BeginInvokeAction(LPWSTR bstrActionName, VARIANT vInActionArgs, IUPnPAsyncResult* pAsyncResult, ULONGLONG* pullRequestID)

BeginInvokeAction メソッドは、デバイス上のアクションを非同期モードで呼び出します。さらに、SCPD の遅延ダウンロードとイベントサブスクリプションがオプトインされており、まだ実行されていない場合、このメソッドは SCPD のダウンロードを開始します。

bstrActionName	LPWSTR	in	呼び出すメソッドを指定します。
vInActionArgs	VARIANT	in	メソッドへの入力引数の配列を指定します。アクションに入力引数がない場合、このパラメーターには空の配列を指定する必要があります。この配列の内容はサービス固有です。
pAsyncResult	IUPnPAsyncResult*	in	IUPnPAsyncResult オブジェクトへのポインター。BeginInvokeAction の呼び出しが完了すると、 UPnP は IUPnPAsyncResult::AsyncOperationComplete メソッドを使用してコントロールポイントに通知します。
pullRequestID	ULONGLONG*	out	非同期 I/O 操作を識別するために使用される 64 ビットの ULONG 値へのポインター。コントロールポイントは、EndInvokeAction でこの操作を終了またはキャンセルする際に、このハンドルをクッキーとして使用する必要があります。

戻り値

成功した場合は S_OK を返します。それ以外の場合、このメソッドは WinError.h で定義された COM エラーコード、または次の値のいずれかを返します。

戻り値	説明
E_PENDING	この IUPnPServiceAsync オブジェクトで別の非同期操作が実行中です。別の IUPnPServiceAsync インスタンスを作成するか、IUPnPServiceAsync::CancelAsyncOperation を使用して実行中の操作をキャンセルしてください。
E_FAIL	操作を開始できませんでした。
UPNP_E_INVALID_ACTION	このアクションはデバイスでサポートされていません。

注意値によっては、UPnP 認定デバイスからエラーを受け取ったことを示す場合があります。詳細については、Device Error Codes を参照してください。

vtbl 4 HRESULT EndInvokeAction(ULONGLONG ullRequestID, VARIANT* pvOutActionArgs, VARIANT* pvRetVal)

EndInvokeAction メソッドは、直前の BeginInvokeAction 操作の結果を取得し、その出力引数を受け取ります。

ullRequestID	ULONGLONG	in	入力時には空の配列への参照を格納します。出力時には、サービス固有の出力引数の配列への参照を受け取ります。アクションに出力引数がない場合、このパラメーターには空の配列が格納されます。注意このパラメーターは VariantClear で解放してください。
pvOutActionArgs	VARIANT*	inout	入力時には空の配列への参照を格納します。出力時には、呼び出したアクションの戻り値を格納する VARIANT への参照を受け取ります。注意このパラメーターは VariantClear で解放してください。
pvRetVal	VARIANT*	inout	この呼び出しの前に開始された BeginInvokeAction 操作に対応する 64 ビットの ULONG 値。

戻り値

戻り値	説明
UPNP_E_DEVICE_TIMEOUT	デバイスが 30 秒のタイムアウト期間内に応答しませんでした。
UPNP_E_DEVICE_ERROR	不明なエラーが発生しました。
UPNP_E_INVALID_ARGUMENTS	渡された引数のうち 1 つ以上が無効です。
UPNP_E_INVALID_ACTION	このアクションはデバイスでサポートされていません。
UPNP_E_ERROR_PROCESSING_RESPONSE	デバイスが処理できない応答を送信しました。たとえば、応答が破損していた場合などです。
UPNP_E_PROTOCOL_ERROR	UPnP 制御プロトコルのレベルでエラーが発生しました。
UPNP_E_TRANSPORT_ERROR	HTTP エラーが発生しました。実際の HTTP ステータスコードを取得するには、IUPnPService::LastTransportStatus プロパティを使用してください。注意このエラーコードは、SOAP 応答が 100 キロバイトを超えた場合にも返されます。

注意値によっては、UPnP 認定デバイスからエラーを受け取ったことを示す場合があります。詳細については、Device Error Codes を参照してください。

vtbl 5 HRESULT BeginQueryStateVariable(LPWSTR bstrVariableName, IUPnPAsyncResult* pAsyncResult, ULONGLONG* pullRequestID)

BeginQueryStateVariable メソッドは、特定のサービスから状態変数の値を取得する非同期要求を開始します。

bstrVariableName	LPWSTR	in	要求する状態変数の値を指定します。
pAsyncResult	IUPnPAsyncResult*	in	IUPnPAsyncResult オブジェクトへのポインター。BeginQueryStateVariable の呼び出しが完了すると、 UPnP は IUPnPAsyncResult::AsyncOperationComplete メソッドを使用してコントロールポイントに通知します。
pullRequestID	ULONGLONG*	out	非同期 I/O 操作を識別するために使用される 64 ビットの ULONG 値へのポインター。UPnP コントロールポイントは、EndQueryStateVariable でこの操作を終了またはキャンセルする際に、このハンドルを使用する必要があります。

戻り値

戻り値	説明
E_FAIL	非同期操作を開始できませんでした。
UPNP_E_INVALID_VARIABLE	bstrVariableName で指定された状態変数は存在しません。

注意値によっては、UPnP 認定デバイスからエラーを受け取ったことを示す場合があります。詳細については、Device Error Codes を参照してください。

解説(Remarks)

このメソッドでイベント付き状態変数を照会する前に、イベントサブスクリプションを完了しておく必要があります。完了していない場合は UPNP_E_VARIABLE_VALUE_UNKNOWN が返され、イベントサブスクリプションが内部的に実行されます。その結果、次回の BeginQueryStateVariable の呼び出しは成功します。

注意イベント付き変数を持たないサービスの場合、このメソッドは常に期待どおりに動作します。

vtbl 6 HRESULT EndQueryStateVariable(ULONGLONG ullRequestID, VARIANT* pValue)

EndQueryStateVariable メソッドは、直前の BeginQueryStateVariable 操作の結果を取得し、サービス固有の状態変数の値を受け取ります。

ullRequestID	ULONGLONG	in	この呼び出しの前に開始された BeginQueryStateVariable 操作に対応する 64 ビットの ULONG 値へのポインター。
pValue	VARIANT*	inout	入力時には空の配列を格納します。出力時には、BeginQueryStateVariable の bstrVariableName で指定した変数の値への参照を受け取ります。返されるデータの型は、クエリを実行した状態変数によって異なります。注意このパラメーターは VariantClear で解放してください。

戻り値

戻り値	説明
UPNP_E_DEVICE_ERROR	状態変数がイベント付きではなく、リモートクエリがエラーコードを返しました。これはトランスポートエラーではありません。デバイスは要求を受け取りましたが、エラーを返しました。
UPNP_E_INVALID_VARIABLE	要求された状態変数は存在しません。
UPNP_E_DEVICE_TIMEOUT	デバイスが 30 秒のタイムアウト期間内に応答しませんでした。
UPNP_E_INVALID_ARGUMENTS	vInActionArgs で渡された引数のうち 1 つ以上が無効です。
UPNP_E_PROTOCOL_ERROR	UPnP プロトコルレベルでの問題により、クエリが完了しませんでした。
UPNP_E_TRANSPORT_ERROR	状態変数がイベント付きではなく、HTTP の問題により値のリモートクエリが失敗しました。HTTP エラーコードを取得するには、IUPnPService::LastTransportStatus を使用してください。
UPNP_E_VARIABLE_VALUE_UNKNOWN	状態変数はイベント付きですが、UPnP ソフトウェアはイベント通知を待機中のため値を返せません。

注意値によっては、UPnP 認定デバイスからエラーを受け取ったことを示す場合があります。詳細については、Device Error Codes を参照してください。

vtbl 7 HRESULT BeginSubscribeToEvents(IUnknown* pUnkCallback, IUPnPAsyncResult* pAsyncResult, ULONGLONG* pullRequestID)

BeginSubscribeToEvents は、イベントサブスクリプションを非同期モードで開始し、アプリケーションのコールバックを UPnP フレームワークに登録します。

pUnkCallback	IUnknown*	in	登録するコールバックを含むインターフェイスオブジェクトへの参照を指定します。このオブジェクトは IUPnPServiceCallback インターフェイスまたは IDispatch インターフェイスをサポートしている必要があります。
pAsyncResult	IUPnPAsyncResult*	in	IUPnPAsyncResult オブジェクトへの参照を指定します。BeginSubscribeToEvents の呼び出しが完了すると、 UPnP は IUPnPAsyncResult::AsyncOperationComplete メソッドを使用してコントロールポイントに通知します。
pullRequestID	ULONGLONG*	out	非同期 I/O 操作を識別するために使用される 64 ビットの ULONG 値へのポインター。コントロールポイントは、EndSubscribeToEvents または CancelAsyncOperation で操作を終了またはキャンセルする際に、このハンドルを使用する必要があります。

戻り値

戻り値	説明
E_FAIL	非同期操作を開始できませんでした。

注意値によっては、UPnP 認定デバイスからエラーを受け取ったことを示す場合があります。詳細については、Device Error Codes を参照してください。

解説(Remarks)

BeginQueryStateVariable でイベント付き状態変数を照会する前に、イベントサブスクリプションを完了しておく必要があります。完了していない場合は UPNP_E_VARIABLE_VALUE_UNKNOWN が返され、イベントサブスクリプションが内部的に実行されます。その結果、次回の BeginQueryStateVariable の呼び出しは成功します。

注意イベント付き変数を持たないサービスの場合、BeginQueryStateVariable は常に期待どおりに動作します。

このメソッドを複数回呼び出すと、複数のコールバックが追加されます。

vtbl 8 HRESULT EndSubscribeToEvents(ULONGLONG ullRequestID)

EndSubscribeToEvents メソッドは、直前の BeginSubscribeToEvents 操作の結果を取得します。

ullRequestID

ULONGLONG

この呼び出しの前に要求された BeginSubscribeToEvents 操作に対応する 64 ビットの ULONG 値。

戻り値

戻り値	説明
UPNP_E_DEVICE_ERROR	デバイスは要求を受け取りましたが、エラーを返しました。
UPNP_E_DEVICE_TIMEOUT	デバイスが 30 秒のタイムアウト期間内に応答しませんでした。
UPNP_E_PROTOCOL_ERROR	UPnP プロトコルレベルでの問題により、クエリが完了しませんでした。
UPNP_E_TRANSPORT_ERROR	HTTP の問題によりリモート操作が失敗しました。HTTP エラーコードを取得するには、IUPnPService::LastTransportStatus を使用してください。

注意値によっては、UPnP 認定デバイスからエラーを受け取ったことを示す場合があります。詳細については、Device Error Codes を参照してください。

vtbl 9 HRESULT BeginSCPDDownload(IUPnPAsyncResult* pAsyncResult, ULONGLONG* pullRequestID)

BeginSCPDDownload メソッドは、Service Control Protocol Description (SCPD) ドキュメントの非同期ダウンロードを開始します。

pAsyncResult	IUPnPAsyncResult*	in	IUPnPAsyncResult オブジェクトへのポインターを指定します。BeginSCPDDownload の呼び出しが完了すると、 UPnP は IUPnPAsyncResult::AsyncOperationComplete メソッドを使用してコントロールポイントに通知します。
pullRequestID	ULONGLONG*	out	この呼び出しの前に要求された BeginSCPDDownload 操作を識別するために使用される 64 ビットの ULONG 値へのポインター。

戻り値

戻り値	説明
E_FAIL	SCPD のダウンロードを開始できませんでした。
E_INVALIDARG	pAsyncResult が無効です。

vtbl 10 HRESULT EndSCPDDownload(ULONGLONG ullRequestID, LPWSTR* pbstrSCPDDoc)

EndSCPDDownload メソッドは、直前に実行した Service Control Protocol Description (SCPD) ドキュメントの非同期ダウンロードの結果を取得します。

ullRequestID	ULONGLONG	in	この呼び出しの前に要求された BeginSCPDDownload 操作に対応する 64 ビットの ULONG 値へのポインター。
pbstrSCPDDoc	LPWSTR*	out	SCPD ドキュメントを格納するバッファー。

戻り値

戻り値	説明
E_FAIL	SCPD のダウンロードを完了し、ドキュメント文字列を取得することができませんでした。
E_INVALIDARG	ullRequestID が保留中の非同期呼び出しと一致しません。

vtbl 11 HRESULT CancelAsyncOperation(ULONGLONG ullRequestID)

CancelAsyncOperation メソッドは、BeginInvokeAction、BeginQueryStateVariable、BeginSubscribeToEvents、または BeginSCPDDownload の各メソッドによって開始された保留中の非同期操作をキャンセルします。

ullRequestID

ULONGLONG

保留中の非同期 UPnP 操作に対応する 64 ビットの ULONG 値。

戻り値

戻り値	説明
E_FAIL	非同期操作をキャンセルできませんでした。
E_INVALIDARG	ullRequestID が保留中の非同期呼び出しと一致しません。

解説(Remarks)

保留中の BeginSCPDDownload 操作に対してこのメソッドを呼び出した場合、SCPD のダウンロードはバックグラウンドで引き続き実行されますが、その操作に関連するイベントがコールバックに通知されることはありません。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IUPnPServiceAsync "{098BDAF5-5EC1-49E7-A260-B3A11DD8680C}"
#usecom global IUPnPServiceAsync IID_IUPnPServiceAsync "{}"
#comfunc global IUPnPServiceAsync_BeginInvokeAction        3 wstr,int,sptr,var
#comfunc global IUPnPServiceAsync_EndInvokeAction          4 int64,var,var
#comfunc global IUPnPServiceAsync_BeginQueryStateVariable  5 wstr,sptr,var
#comfunc global IUPnPServiceAsync_EndQueryStateVariable    6 int64,var
#comfunc global IUPnPServiceAsync_BeginSubscribeToEvents   7 sptr,sptr,var
#comfunc global IUPnPServiceAsync_EndSubscribeToEvents     8 int64
#comfunc global IUPnPServiceAsync_BeginSCPDDownload        9 sptr,var
#comfunc global IUPnPServiceAsync_EndSCPDDownload          10 int64,var
#comfunc global IUPnPServiceAsync_CancelAsyncOperation     11 int64
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IUPnPServiceAsync "{098BDAF5-5EC1-49E7-A260-B3A11DD8680C}"
#usecom global IUPnPServiceAsync IID_IUPnPServiceAsync "{}"
#comfunc global IUPnPServiceAsync_BeginInvokeAction        3 wstr,int,sptr,sptr
#comfunc global IUPnPServiceAsync_EndInvokeAction          4 int64,sptr,sptr
#comfunc global IUPnPServiceAsync_BeginQueryStateVariable  5 wstr,sptr,sptr
#comfunc global IUPnPServiceAsync_EndQueryStateVariable    6 int64,sptr
#comfunc global IUPnPServiceAsync_BeginSubscribeToEvents   7 sptr,sptr,sptr
#comfunc global IUPnPServiceAsync_EndSubscribeToEvents     8 int64
#comfunc global IUPnPServiceAsync_BeginSCPDDownload        9 sptr,sptr
#comfunc global IUPnPServiceAsync_EndSCPDDownload          10 int64,sptr
#comfunc global IUPnPServiceAsync_CancelAsyncOperation     11 int64
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。