IUPnPRegistrar

IUPnPRegistrar インターフェイスは、デバイスホストのコンテキストで実行されるデバイスを登録します。

RegisterDevice メソッドは、デバイスをデバイスホストに登録します。デバイス情報はデバイスホストによって格納されます。その後、デバイスホストはデバイス識別子を返し、ネットワーク上でデバイスを公開してアナウンスします。

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

制御要求またはイベント要求を受信すると、デバイスがインスタンス化され、 IUPnPDeviceControl::Initialize が呼び出されます。

UnregisterDevice または IUPnPReregistrar::ReregisterDevice を呼び出す際には、pbstrDeviceIdentifier で返された識別子を使用してください。

この関数の呼び出し時に発生する一般的なエラーには、次のようなものがあります。

• 必要な COM オブジェクトが見つからなかった。
• LocalService から COM オブジェクトにアクセスできない。
• 下位の COM インターフェイスに関する問題。
• XML 記述の制限 ( デバイス記述の作成 を参照)。
• イベント対象の変数が成功コードを返さず、デバイスがシャットダウンされた。
• サービス記述が無効だった。validatesd.exe を使用して、サービス記述が有効であることを確認してください。
• サービスが IUPnPEventSource を実装しておらず、 IUPnPEventSource::Advise に成功コードを返さなかったため、デバイスがシャットダウンされた。

RegisterRunningDevice メソッドは、実行中のデバイスをデバイスホストに登録します。

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

このメソッドを呼び出すクライアントは、処理を完了するために LocalService を偽装 (impersonate) できる必要があります。

最初の制御要求またはイベント要求を受信すると、 IUPnPDeviceControl::Initialize メソッドが呼び出されます。

UnregisterDevice または IUPnPReregistrar::ReregisterRunningDevice を呼び出す際には、pbstrDeviceIdentifier で返された識別子を使用してください。

このデバイスの登録は、システムの再起動をまたいで保持されません。

この関数の呼び出し時に発生する一般的なエラーには、次のようなものがあります。

• 必要な COM オブジェクトが見つからなかった。
• LocalService から COM オブジェクトにアクセスできない。
• 下位の COM インターフェイスに関する問題。
• XML 記述の制限 ( デバイス記述の作成 を参照)。
• イベント対象の変数が成功コードを返さず、デバイスがシャットダウンされた。
• サービス記述が無効だった。validatesd.exe を使用して、サービス記述が有効であることを確認してください。
• サービスが IUPnPEventSource を実装しておらず、 IUPnPEventSource::Advise に成功コードを返さなかったため、デバイスがシャットダウンされた。

RegisterDeviceProvider メソッドは、デバイスプロバイダーをデバイスホストに登録します。デバイスプロバイダー自体はネットワーク上に公開されません。代わりに、デバイスプロバイダーは動的にデバイスを作成し、RegisterRunningDevice を使用してそれらを登録します。

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

この関数の呼び出し時に発生する一般的なエラーには、次のようなものがあります。

• 必要な COM オブジェクトが見つからなかった。
• LocalService から COM オブジェクトにアクセスできない。
• 下位の COM インターフェイスに関する問題。

GetUniqueDeviceName メソッドは、指定されたデバイスの UDN を取得します。

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

デバイス記述テンプレート内でデバイスに指定された各 UDN は、登録時に置き換えられます。デバイスホストは、各 UDN をグローバルに一意な値に置き換えます。

UnregisterDevice メソッドは、デバイスホストからデバイスの登録を解除します。デバイスの登録解除は、一時的または恒久的のいずれかで行われます。

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

このメソッドは、デバイスホストからデバイスを削除します。fPermanent が TRUE の場合、デバイスの登録は恒久的に解除されます。それ以外の場合、デバイス識別子 ( RegisterDevice または RegisterRunningDevice から返された値) とデバイスホストが生成した UDN とのマッピングは、デバイスホスト内に保持されます。デバイスの登録を一時的に解除した場合、そのデバイスを再登録するときには、以前にデバイスに関連付けられていた UDN を使用します。

UnregisterDeviceProvider メソッドは、デバイスホストからデバイスプロバイダーの登録を恒久的に解除し、アンロードします。IUPnPDeviceProvider::Stop メソッドが呼び出されます。

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