ホーム › Devices.WebServicesOnDevices › IWSDDeviceHost

IWSDDeviceHost

COM

📘 Microsoft Learn (日本語) · English

IID917fe891-3d13-4138-9809-934c8abeb12c継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

DPWS 準拠のデバイスを表します。

解説(Remarks)

このインターフェイスを取得した後、アプリケーションは次の処理を行います。

RegisterPortType メソッドを呼び出して、必要なポート型をすべて登録します。
SetMetadata を呼び出してデバイスを記述し、必要に応じて RegisterService を 1 回以上呼び出して、サービスホストメタデータに記述されたサービスを登録します。
Start メソッドを呼び出してデバイスホストを開始し、WS-Discovery を使用してデバイスを公開します。デバイスホストの開始後、必要に応じて次の処理を行えます。
1. サービスホストメタデータに記述されていないサービス (たとえばアドホックな印刷ジョブ) については、AddDynamicService を呼び出します。
2. RetireService を呼び出して、RegisterService メソッドによって有効化されたサービスの動作を終了し、切断します。
3. SignalEvent メソッドを呼び出して、特定のイベントに関連するサブスクリプションに対して通知を送信すべきであることを示します。
Stop メソッドを呼び出して、ホストの実行とデバイスの公開を終了します。

IWSDDeviceHost オブジェクトは、ホストがあるサービス宛ての要求メッセージを受信したときに、(通知コールバックを使用して) そのサービスのオブジェクトをオンデマンドで提供できます。

メソッド 12

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

vtbl 3 HRESULT Init(LPWSTR pszLocalId, IWSDXMLContext* pContext, IWSDAddress** ppHostAddresses, DWORD dwHostAddressCount)

IWSDDeviceHost オブジェクトのインスタンスを初期化します。

pszLocalId	LPWSTR	in	デバイスの論理アドレスまたは物理アドレス。論理アドレスは `urn:uuid:{guid}` の形式です。pszLocalId が論理アドレスである場合、ホストはその論理アドレスをアナウンスし、Resolve または Probe メッセージを受信したときにそのアドレスを物理アドレスへ変換します。 pszLocalId が物理アドレス (http または https で始まる URL など) である場合、ホストはそのアドレスを物理アドレスとして使用し、既定のアドレスではなくそのアドレス上でホストします。セキュリティで保護された通信を行う場合、pszLocalId は https で始まる URL である必要があり、ホストは URL で指定されたポートで SSL/TLS プロトコルを使用します。推奨されるポートは 5358 です。このポートは WSDAPI のセキュリティで保護された接続用に予約されています。ポートが指定されていない場合、ホストはポート 443 を使用します。ホストのポートには SSL サーバー証明書を構成する必要があります。ホストのポートの構成の詳細については、HttpSetServiceConfiguration を参照してください。 URL (http または https) は必ず末尾をスラッシュで終える必要があります。また URL には有効な IP アドレスまたはホスト名を含める必要があります。次の一覧は pszLocalId の値の例です。有効な値の完全な一覧ではありません。 http://192.168.0.1:5357/ http://localhost/ http://myHostname:5357/ https://192.168.0.1:5358/ https://myHostname/ https://myHostname/myDevice/ https://myHostname:5358/
pContext	IWSDXMLContext*	inoptional	カスタムのメッセージ型または名前空間を定義する IWSDXMLContext インターフェイス。
ppHostAddresses	IWSDAddress**	inoptional	単一の IWSDAddress オブジェクトまたは IWSDTransportAddress オブジェクト。これらのオブジェクトは、ホストがリッスンすべき特定のアドレスに関する情報を提供します。 pszLocalId にローカルアドレスが含まれている場合、結果として論理アドレスと (既定の物理アドレスではなく) 指定された物理アドレスとの間のマッピングが行われます。
dwHostAddressCount	DWORD	inoptional	ppHostAddresses 配列の要素数。ppHostAddresses が IWSDAddress インターフェイスである場合、この数は 1 でなければなりません。

戻り値

戻り値には次のものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_INVALIDARG	pszLocalId が NULL であるか、pszLocalId の文字数が WSD_MAX_TEXT_LENGTH (8192) を超えているか、ppHostAddresses が参照するアドレスの数が dwHostAddressCount と一致しません。
E_FAIL	デバイスホストが予期しない状態です。
E_OUTOFMEMORY	操作を完了するためのメモリが不足しています。
E_ABORT	初期化を完了できませんでした。

解説(Remarks)

このメソッドは WSDCreateDeviceHost から呼び出されるため、通常はコードから直接呼び出す必要はありません。

vtbl 4 HRESULT Start(ULONGLONG ullInstanceId, WSD_URI_LIST* pScopeList, IWSDDeviceHostNotify* pNotificationSink)

デバイスホストを開始し、WS-Discovery の Hello メッセージを使用してデバイスホストを公開します。

ullInstanceId	ULONGLONG	in	インスタンス識別子。識別子が指定されない場合、現在のインスタンス値 + 1 が既定値として使用されます。注意 WS-Discovery 仕様との互換性のため、この値は UINT_MAX (4294967295) 以下でなければなりません。
pScopeList	WSD_URI_LIST*	in	デバイスホストのスコープ。NULL の場合、ホストにスコープは関連付けられません。
pNotificationSink	IWSDDeviceHostNotify*	inoptional	通知シンクを指定する IWSDDeviceHostNotify オブジェクトへの参照。

戻り値

戻り値には次のものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは正常に完了しました。
S_FALSE	デバイスホストは既に開始されています。
E_FAIL	メソッドが失敗しました。ホストが初期化されていないことが原因である可能性があります。Init を呼び出してデバイスホストを初期化してください。
E_ABORT	ホストに関連付けられたメタデータがありません。

vtbl 5 HRESULT Stop()

WS-Discovery の Bye メッセージを送信し、ホストを停止します。

戻り値

戻り値には次のものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは正常に完了しました。
S_FALSE	ホストは既に停止しています。
E_FAIL	ホストが初期化されていないか、ホストが開始されていません。

解説(Remarks)

このメソッドでデバイスホストを停止した場合、すべてのサービスはアタッチされたままですが、受信メッセージは処理も一切の対応もされません。

ホストが開始されていない場合、Stop を呼び出す必要はありません。

vtbl 6 HRESULT Terminate()

ホストを終了し、アタッチされているすべてのサービスを解放します。

戻り値

戻り値には次のものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_FAIL	ホストが初期化されていないか、ホストが既に終了しています。

解説(Remarks)

Terminate メソッドの完了後、サービスおよび通知シンクはメッセージを受信しません。

このデバイスホストが IWSDDeviceHost::Start の呼び出しによって開始されている場合、Terminate を呼び出す前に IWSDDeviceHost::Stop を呼び出して停止する必要があります。

Terminate は IWSDDeviceHost を解放する前に呼び出す必要があります。

vtbl 7 HRESULT RegisterPortType(WSD_PORT_TYPE* pPortType)

受信メッセージ用のポート型を登録します。

pPortType

WSD_PORT_TYPE*

ポート型を記述する WSD_PORT_TYPE 構造体への参照。

戻り値

戻り値には次のものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_OUTOFMEMORY	操作を完了するためのメモリが不足しています。
S_FALSE	pPortType で指定されたポート型は既に登録されています。

vtbl 8 HRESULT SetMetadata(WSD_THIS_MODEL_METADATA* pThisModelMetadata, WSD_THIS_DEVICE_METADATA* pThisDeviceMetadata, WSD_HOST_METADATA* pHostMetadata, WSD_METADATA_SECTION_LIST* pCustomMetadata)

ユーザー定義のサービスメタデータを除く、デバイスのメタデータを設定します。

pThisModelMetadata	WSD_THIS_MODEL_METADATA*	in	このデバイスのモデルのすべてのインスタンスに共通するメタデータを指定する WSD_THIS_MODEL_METADATA 構造体への参照。この構造体の Manufacturer、ModelNames、ModelNumber の各メンバーには、NULL でも空でもない値を設定する必要があります。
pThisDeviceMetadata	WSD_THIS_DEVICE_METADATA*	in	このデバイスに固有のメタデータを指定する WSD_THIS_DEVICE_METADATA 構造体への参照。この構造体の FriendlyName、FirmwareVersion、SerialNumber の各メンバーには、NULL でも空でもない値を設定する必要があります。
pHostMetadata	WSD_HOST_METADATA*	inoptional	サービスホストメタデータを指定する WSD_HOST_METADATA 構造体への参照。これはデバイス固有のデータや特性 (たとえばプリンターがカラー印刷やステープル機能をサポートしているかなど) を表します。
pCustomMetadata	WSD_METADATA_SECTION_LIST*	inoptional	このデバイスに関連付けられる追加のカスタムメタデータを指定する WSD_METADATA_SECTION_LIST 構造体への参照。

戻り値

戻り値には次のものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_INVALIDARG	pThisDeviceMetadata が NULL であるか、pThisModelMetadata が NULL であるか、いずれかの構造体に必須のメンバーが含まれていません。必須メンバーの一覧については、各パラメーターの説明を参照してください。
E_OUTOFMEMORY	操作を完了するためのメモリが不足しています。

解説(Remarks)

このメソッドは、RegisterService で登録されたデバイスホストを開始する前に、少なくとも 1 回呼び出す必要があります。デバイスの開始後にメタデータを更新するために呼び出すこともでき、その場合は新しいメタデータバージョンを示す WS-Discovery の Hello メッセージが送信されます。

注意この更新機能はまだ実装されていません。

vtbl 9 HRESULT RegisterService(LPWSTR pszServiceId, IUnknown* pService)

受信要求を処理するサービスオブジェクトを登録し、そのサービスをデバイスホストのメタデータに追加します。

pszServiceId	LPWSTR	in	登録するサービスの ID。この ID はデバイスのサービスホストメタデータに含まれている必要があります。
pService	IUnknown*	in	指定されたサービス宛ての要求を処理するサービスオブジェクト。

戻り値

戻り値には次のものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_INVALIDARG	pszServiceId が NULL であるか、pszServiceId の文字数が WSD_MAX_TEXT_LENGTH (8192) を超えているか、pszServiceId に一致するサービスが既に登録されています。

vtbl 10 HRESULT RetireService(LPWSTR pszServiceId)

RegisterService を使用して登録されたサービスオブジェクトの登録を解除し、デバイスホストのメタデータからそのサービスを削除します。

pszServiceId

LPWSTR

削除するサービスの ID。

戻り値

戻り値には次のものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_POINTER	pszServiceId が NULL です。
E_INVALIDARG	pszServiceId の文字数が WSD_MAX_TEXT_LENGTH (8192) を超えているか、pszServiceId が登録済みサービスの一覧に見つかりませんでした。
E_FAIL	メソッドが失敗しました。ホストが初期化されていないことが原因である可能性があります。Init を呼び出してデバイスホストを初期化してください。

解説(Remarks)

サービスの登録解除後、デバイスホストはサービスオブジェクトへの参照を解放します。RetireService の完了後、サービスオブジェクトはコールバックを受け取りません。

vtbl 11 HRESULT AddDynamicService(LPWSTR pszServiceId, LPWSTR pszEndpointAddress, WSD_PORT_TYPE* pPortType, WSDXML_NAME* pPortName, WSDXML_ELEMENT* pAny, IUnknown* pService)

受信要求を処理するサービスオブジェクトを登録しますが、そのサービスをデバイスホストのメタデータには追加しません。これは一時的な (動的な) サービスに使用します。

pszServiceId	LPWSTR	in	動的サービスの ID。このサービス ID は、サービスホストメタデータ内のすべてのサービス ID、および他の登録済み動的サービスの ID と異なる必要があります。pszServiceId は URI でなければなりません。
pszEndpointAddress	LPWSTR	inoptional	このサービスのエンドポイントアドレスとして使用する省略可能な URI。指定しない場合、デバイスホストはそのサービスがすべてのローカルトランスポートアドレスで利用可能であるとみなします。
pPortType	WSD_PORT_TYPE*	inoptional	ポート型を指定する WSD_PORT_TYPE 構造体への参照。 NULL を指定できます。pPortType と pPortName のいずれか一方のみを指定してください。
pPortName	WSDXML_NAME*	inoptional	サービスの型を指定し、サービスを指定のポートに関連付ける WSDXML_NAME 構造体への参照。pPortType と pPortName のいずれか一方のみを指定してください。
pAny	WSDXML_ELEMENT*	inoptional	動的サービスのメタデータに含める拡張セクションへの省略可能な参照。
pService	IUnknown*	inoptional	登録するホストサービスオブジェクトへの省略可能な参照。

戻り値

戻り値には次のものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_POINTER	pszServiceId が NULL です。
E_INVALIDARG	pszServiceId または pszEndpointAddress の文字数が WSD_MAX_TEXT_LENGTH (8192) を超えているか、pPortType と pPortName の両方が指定されています。
E_FAIL	メソッドが失敗しました。ホストが初期化されていないか、pszServiceId で指定されたサービスが見つからなかったことが原因である可能性があります。Init を呼び出してデバイスホストを初期化してください。
E_OUTOFMEMORY	操作を完了するためのメモリが不足しています。

解説(Remarks)

このメソッドが呼び出されると、デバイスはサービスオブジェクトへの参照を追加し、そのサービス宛ての要求メッセージに応じてそのメソッドを呼び出します。デバイスホストの RemoveDynamicService メソッドを呼び出すと、サービスへの参照が解放され、サービスのメソッド呼び出しが停止します。

vtbl 12 HRESULT RemoveDynamicService(LPWSTR pszServiceId)

AddDynamicService を使用して登録されたサービスオブジェクトの登録を解除します。

pszServiceId

LPWSTR

削除する動的サービスの ID。

戻り値

戻り値には次のものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_INVALIDARG	pszServiceId が NULL であるか、pszServiceId の文字数が WSD_MAX_TEXT_LENGTH (8192) を超えているか、pszServiceId が動的サービスの一覧に見つかりませんでした。
E_FAIL	メソッドが失敗しました。ホストが初期化されていないことが原因である可能性があります。Init を呼び出してデバイスホストを初期化してください。

解説(Remarks)

サービスの登録解除後、デバイスホストはサービスオブジェクトへの参照を解放します。RemoveDynamicService の完了後、サービスオブジェクトはコールバックを受け取りません。

vtbl 13 HRESULT SetServiceDiscoverable(LPWSTR pszServiceId, BOOL fDiscoverable)

WS-Discovery を使用してサービスをアドバタイズするかどうかを制御します。

pszServiceId	LPWSTR	in	サービスの ID。
fDiscoverable	BOOL	in	サービスを WS-Discovery で探索 (ディスカバリー) できる場合は TRUE、サービスを WS-Discovery から見えないようにする場合は FALSE。

戻り値

このメソッドは次のいずれかの値を返すことがあります。

戻り値には次のものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_INVALIDARG	pszServiceId が NULL であるか、pszServiceId の文字数が WSD_MAX_TEXT_LENGTH (8192) を超えているか、pszServiceId が登録済みのサービスに対応していません。

vtbl 14 HRESULT SignalEvent(LPWSTR pszServiceId, void* pBody, WSD_OPERATION* pOperation)

イベントが発生したことを、サブスクライブしているすべてのクライアントに通知します。

pszServiceId	LPWSTR	in	イベントを生成するサービスの ID。
pBody	void*	inoptional	イベントの本文。
pOperation	WSD_OPERATION*	in	操作を指定する WSD_OPERATION 構造体への参照。

戻り値

戻り値には次のものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは正常に完了しました。
E_FAIL	ホストが開始されていません。Start を呼び出してデバイスホストを開始してください。
E_INVALIDARG	pszServiceId が NULL であるか、pOperation が NULL であるか、pszServiceId の文字数が WSD_MAX_TEXT_LENGTH (8192) を超えているか、pOperation に関連付けられた ResponseType 構造体が存在しないか、pszServiceId で指定されたサービスが pOperation の ResponseType メンバーで指定されたイベントをサブスクライブしていません。

解説(Remarks)

SignalEvent は、イベントがすべてのクライアントへ送信されるまでブロックします。クライアントには順次接続されるため、応答が遅いクライアントや到達できないクライアントがある場合、SignalEvent が長時間ブロックされる可能性があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IWSDDeviceHost "{917FE891-3D13-4138-9809-934C8ABEB12C}"
#usecom global IWSDDeviceHost IID_IWSDDeviceHost "{}"
#comfunc global IWSDDeviceHost_Init                    3 wstr,sptr,sptr,int
#comfunc global IWSDDeviceHost_Start                   4 int64,var,sptr
#comfunc global IWSDDeviceHost_Stop                    5
#comfunc global IWSDDeviceHost_Terminate               6
#comfunc global IWSDDeviceHost_RegisterPortType        7 var
#comfunc global IWSDDeviceHost_SetMetadata             8 var,var,var,var
#comfunc global IWSDDeviceHost_RegisterService         9 wstr,sptr
#comfunc global IWSDDeviceHost_RetireService           10 wstr
#comfunc global IWSDDeviceHost_AddDynamicService       11 wstr,wstr,var,var,var,sptr
#comfunc global IWSDDeviceHost_RemoveDynamicService    12 wstr
#comfunc global IWSDDeviceHost_SetServiceDiscoverable  13 wstr,int
#comfunc global IWSDDeviceHost_SignalEvent             14 wstr,sptr,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IWSDDeviceHost "{917FE891-3D13-4138-9809-934C8ABEB12C}"
#usecom global IWSDDeviceHost IID_IWSDDeviceHost "{}"
#comfunc global IWSDDeviceHost_Init                    3 wstr,sptr,sptr,int
#comfunc global IWSDDeviceHost_Start                   4 int64,sptr,sptr
#comfunc global IWSDDeviceHost_Stop                    5
#comfunc global IWSDDeviceHost_Terminate               6
#comfunc global IWSDDeviceHost_RegisterPortType        7 sptr
#comfunc global IWSDDeviceHost_SetMetadata             8 sptr,sptr,sptr,sptr
#comfunc global IWSDDeviceHost_RegisterService         9 wstr,sptr
#comfunc global IWSDDeviceHost_RetireService           10 wstr
#comfunc global IWSDDeviceHost_AddDynamicService       11 wstr,wstr,sptr,sptr,sptr,sptr
#comfunc global IWSDDeviceHost_RemoveDynamicService    12 wstr
#comfunc global IWSDDeviceHost_SetServiceDiscoverable  13 wstr,int
#comfunc global IWSDDeviceHost_SignalEvent             14 wstr,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。