ホーム › Devices.Enumeration.Pnp › IUPnPDescriptionDocument

IUPnPDescriptionDocument

COMIDispatch (デュアル)

📘 Microsoft Learn (日本語) · English

✅ IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。

IID11d1c1b2-7daa-4c9e-9595-7f82ed206d1e継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

IUPnPDescriptionDocument インターフェイスは、アプリケーションがデバイス記述を読み込むことを可能にします。

メソッド 7

vtbl = vtable インデックス(0始まり)。IDispatch 実装のため HSP ではメソッド名でも呼べます(上記)。低レベルの index 呼び出し用に vtbl も掲載。0〜2 は IUnknown。

vtbl 7 HRESULT get_ReadyState(INT* plReadyState)

ReadyState プロパティは、ドキュメントの読み込み操作の状態を示します。

plReadyState

INT*

out

準備状態への参照を受け取ります。このパラメーターが受け取ることのできる値は次のとおりです (ユニバーサルプラグアンドプレイで使用される順に記載):

plReadyState の値	意味
READYSTATE_UNINITIALIZED	ドキュメントオブジェクトが作成されました。
READYSTATE _LOADING	読み込み操作が開始されました。
READYSTATE _COMPLETE	読み込み操作が完了しました。ドキュメントはダウンロードされ、XML が解析されました。
READYSTATE _INTERACTIVE	将来使用するために予約されています。
READYSTATE _LOADED	将来使用するために予約されています。

戻り値

C++ の場合: このプロパティの "get" メソッドが成功すると、戻り値は S_OK です。それ以外の場合は、WinError.h で定義されている COM エラーコードのいずれかを返します。

vtbl 8 HRESULT Load(LPWSTR bstrUrl)

Load メソッドは、ドキュメントを同期的に読み込みます。このメソッドは、読み込み操作が完了するまで呼び出し元に制御を返しません。

bstrUrl

LPWSTR

読み込むドキュメントの URL を指定します。

戻り値

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

リターンコード	説明
UPNP_E_DEVICE_ELEMENT_EXPECTED	XML ドキュメントに device 要素がありません。ルート要素または DeviceList 要素のいずれかから欠落しています。
UPnP_E_DEVICE_ELEMENT_EXPECTED	指定された記述ドキュメントに Device 要素がありません。
UPNP_E_DEVICE_NODE_INCOMPLETE	XML ドキュメントの Device 要素に必須要素の 1 つが欠落しています。
UPNP_E_ICON_ELEMENT_EXPECTED	XML ドキュメントに icon 要素がありません。IconList 要素から欠落しているか、DeviceList 要素が IconList 要素を含んでいません。
UPnP_E_ICON_ELEMENT_EXPECTED	指定された記述ドキュメントに Icon 要素がありません。
UPNP_E_ICON_NODE_INCOMPLETE	XML ドキュメントの Icon 要素に必須要素の 1 つが欠落しています。
UPnP_E_ICON_NODE_INCOMPLETE	指定された記述ドキュメントに Icon ノードがありません。
UPNP_E_ROOT_ELEMENT_EXPECTED	XML ドキュメントの最上位にルート要素がありません。
UPnP_E_ROOT_ELEMENT_EXPECTED	指定された記述ドキュメントに Root 要素がありません。
UPNP_E_SERVICE_ELEMENT_EXPECTED	XML ドキュメントに service 要素がありません。ServiceList 要素から欠落しているか、DeviceList 要素が ServiceList 要素を含んでいません。
UPNP_E_SERVICE_NODE_INCOMPLETE	XML ドキュメントの Service 要素に必須要素の 1 つが欠落しています。

解説(Remarks)

このメソッドは戻るまでに長い時間がかかる場合があるため、ユーザーインターフェイススレッドから呼び出さないでください。

Load メソッドが Web ページ内のスクリプトから呼び出される場合、bstrUrl には相対 URL を指定できます。現在の Web ページのアドレスがベース URL として使用されます。

このメソッドを Web ページから呼び出す場合、呼び出し元が指定する URL は、その Web ページの読み込み元と同じサーバーを参照している必要があります。

vtbl 9 HRESULT LoadAsync(LPWSTR bstrUrl, IUnknown* punkCallback)

LoadAsync メソッドは、ドキュメントを非同期的に読み込みます。このメソッドはただちに呼び出し元へ制御を返し、指定されたコールバックを使用して操作の完了を呼び出し元に通知します。

bstrUrl	LPWSTR	in	読み込むドキュメントの URL を指定します。指定された URL が相対 URL の場合、bstrUrl の値の先頭にサーバー名が付加されます。
punkCallback	IUnknown*	in	操作の完了時に UPnP フレームワークが呼び出し元へ通知するために使用するコールバックを指定する IUnknown への参照です。読み込み操作がただちに失敗しなかった場合、このコールバックは読み込み操作が成功したか失敗したかを示します。pUnkCallback が参照するオブジェクトは、 IUPnPDescriptionDocumentCallback インターフェイスまたは IDispatch インターフェイスのいずれかをサポートしている必要があります。

戻り値

リターンコード	説明
UPNP_E_DEVICE_ELEMENT_EXPECTED	XML ドキュメントに device 要素がありません。ルート要素または DeviceList 要素のいずれかから欠落しています。
UPNP_E_DEVICE_NODE_INCOMPLETE	XML ドキュメントの Device 要素に必須要素の 1 つが欠落しています。
UPNP_E_ICON_ELEMENT_EXPECTED	XML ドキュメントに icon 要素がありません。IconList 要素から欠落しているか、DeviceList 要素が IconList 要素を含んでいません。
UPNP_E_ICON_NODE_INCOMPLETE	XML ドキュメントの Icon 要素に必須要素の 1 つが欠落しています。
UPNP_E_ROOT_ELEMENT_EXPECTED	XML ドキュメントの最上位にルート要素がありません。
UPNP_E_SERVICE_ELEMENT_EXPECTED	XML ドキュメントに service 要素がありません。ServiceList 要素から欠落しているか、DeviceList 要素が ServiceList 要素を含んでいません。
UPNP_E_SERVICE_NODE_INCOMPLETE	XML ドキュメントの Service 要素に必須要素の 1 つが欠落しています。

解説(Remarks)

このメソッドは戻るまでに長い時間がかかる場合があるため、ユーザーインターフェイススレッドから呼び出さないでください。

同じオブジェクトに対して、前回の呼び出しの直後にこのメソッドを呼び出すと、最初の LoadAsync の呼び出しは中止されます。これを避けるには、 IUPnPDescriptionDocumentCallback::LoadComplete コールバックを待ってから、 LoadResult を使用して状態情報を確認してください。

LoadAsync メソッドが Web ページ内のスクリプトから呼び出される場合、bstrUrl には相対 URL を指定できます。現在の Web ページのアドレスがベース URL として使用されます。

pUnkCallback が参照するオブジェクトは、 IUPnPDescriptionDocumentCallback インターフェイスまたは IDispatch インターフェイスのいずれかをサポートしている必要があります。 LoadAsync メソッドは、まず pUnkCallback に対して IUPnPDescriptionDocumentCallback インターフェイスを照会します。このインターフェイスがサポートされていない場合、 LoadAsync メソッドは次に pUnkCallback に対して IDispatch インターフェイスを照会します。IDispatch インターフェイスもサポートされていない場合は、どちらの確認も失敗したことになり、 LoadAsync メソッドは E_FAIL を返します。

LoadAsync メソッドの IDispatch ベースのコールバックは、パラメーターを 1 つ取るスクリプト関数として動作します。このパラメーターは読み込み操作の結果です。パラメーターが 0 の場合、読み込みは成功しており、ドキュメントからデバイスオブジェクトを取得できます。パラメーターが 0 以外の場合、その値はエラーを示します。この値は IUPnPDescriptionDocument::Load メソッドが返すエラーコードと同じです。

Visual Basic Scripting Edition (VBScript) 開発ソフトウェアでは、2 番目の引数は GetRef(funcname) でなければなりません。funcname はコールバックサブルーチンの名前です。

この関数が S_OK を返した場合、 IUPnPDescriptionDocumentCallback::LoadComplete が UPnP フレームワークによって呼び出されます。

vtbl 10 HRESULT get_LoadResult(INT* phrError)

LoadResult プロパティは、完了した読み込み操作の成功または失敗のコードを示します。

phrError

INT*

out

成功または失敗のコードへの参照を受け取ります。このパラメーターが受け取ることのできる値は次のとおりです。

phrError の値	意味
E_FAIL	読み込み操作が失敗しました。
E_PENDING	読み込み操作はまだ完了していません。
E_UNEXPECTED	読み込み操作中に予期しないエラーが発生しました。
S_OK	読み込み操作が成功しました。

戻り値

解説(Remarks)

このプロパティは、IUPnPDescriptionDocument::Load メソッドまたは IUPnPDescriptionDocument::LoadAsync メソッドが生成したエラーを示します。このプロパティは、読み込み操作とエラーチェックを分離する必要がある場合に役立ちます。

vtbl 11 HRESULT Abort()

Abort メソッドは、IUPnPDescriptionDocument::LoadAsync によって開始された非同期の読み込み操作を停止します。

戻り値

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

vtbl 12 HRESULT RootDevice(IUPnPDevice** ppudRootDevice)

RootDevice メソッドは、現在読み込まれているドキュメントのデバイスツリーのルートデバイスを返します。

ppudRootDevice

IUPnPDevice**

out

デバイスを記述する IUPnPDevice オブジェクトへの参照を受け取ります。この参照は不要になった時点で解放する必要があります。

戻り値

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

解説(Remarks)

IUPnPDescriptionDocument::Load または IUPnPDescriptionDocument::LoadAsync のいずれかでデバイス記述を先に読み込まずに RootDevice を使用しないでください。検索操作は、現在読み込まれているデバイス記述の中だけを検索します。

vtbl 13 HRESULT DeviceByUDN(LPWSTR bstrUDN, IUPnPDevice** ppudDevice)

DeviceByUDN メソッドは、読み込まれた記述ドキュメント内に含まれる、指定された一意のデバイス名 (UDN) を持つデバイスを返します。

bstrUDN	LPWSTR	in	デバイスの UDN を指定します。
ppudDevice	IUPnPDevice**	out	デバイスを記述する IUPnPDevice オブジェクトへの参照を受け取ります。この参照は使用しなくなった時点で解放する必要があります。

戻り値

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

解説(Remarks)

DeviceByUDN は、 IUPnPDescriptionDocument::Load または IUPnPDescriptionDocument::LoadAsync でデバイス記述を読み込んだ後に使用します。このとき IUPnPDescriptionDocument::ReadyState プロパティは READYSTATE_COMPLETED を返します。

IUPnPDescriptionDocument::Load または IUPnPDescriptionDocument::LoadAsync のいずれかでデバイス記述を先に読み込まずに DeviceByUDN を使用しないでください。検索操作は、現在読み込まれているデバイス記述の中だけを検索します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IUPnPDescriptionDocument "{11D1C1B2-7DAA-4C9E-9595-7F82ED206D1E}"
#usecom global IUPnPDescriptionDocument IID_IUPnPDescriptionDocument "{1D8A9B47-3A28-4CE2-8A4B-BD34E45BCEEB}"
#comfunc global IUPnPDescriptionDocument_get_ReadyState  7 var
#comfunc global IUPnPDescriptionDocument_Load            8 wstr
#comfunc global IUPnPDescriptionDocument_LoadAsync       9 wstr,sptr
#comfunc global IUPnPDescriptionDocument_get_LoadResult  10 var
#comfunc global IUPnPDescriptionDocument_Abort           11
#comfunc global IUPnPDescriptionDocument_RootDevice      12 sptr
#comfunc global IUPnPDescriptionDocument_DeviceByUDN     13 wstr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。#define global IID_IUPnPDescriptionDocument "{11D1C1B2-7DAA-4C9E-9595-7F82ED206D1E}"
#usecom global IUPnPDescriptionDocument IID_IUPnPDescriptionDocument "{1D8A9B47-3A28-4CE2-8A4B-BD34E45BCEEB}"
#comfunc global IUPnPDescriptionDocument_get_ReadyState  7 sptr
#comfunc global IUPnPDescriptionDocument_Load            8 wstr
#comfunc global IUPnPDescriptionDocument_LoadAsync       9 wstr,sptr
#comfunc global IUPnPDescriptionDocument_get_LoadResult  10 sptr
#comfunc global IUPnPDescriptionDocument_Abort           11
#comfunc global IUPnPDescriptionDocument_RootDevice      12 sptr
#comfunc global IUPnPDescriptionDocument_DeviceByUDN     13 wstr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。