IUPnPRegistrar::RegisterDevice-Methode (upnphost.h)
Die RegisterDevice-Methode registriert ein Gerät beim Gerätehost. Die Geräteinformationen werden vom Gerätehost gespeichert. Anschließend gibt der Gerätehost eine Geräte-ID zurück und veröffentlicht und kündigt das Gerät im Netzwerk an.
Syntax
HRESULT RegisterDevice(
[in] BSTR bstrXMLDesc,
[in] BSTR bstrProgIDDeviceControlClass,
[in] BSTR bstrInitString,
[in] BSTR bstrContainerId,
[in] BSTR bstrResourcePath,
[in] long nLifeTime,
[out] BSTR *pbstrDeviceIdentifier
);
Parameter
[in] bstrXMLDesc
Gibt die XML-Gerätebeschreibungsvorlage des zu registrierenden Geräts an.
[in] bstrProgIDDeviceControlClass
Gibt die ProgID eines Gerätesteuerungsobjekts an, das die IUPnPDeviceControl-Schnittstelle implementiert. Diese Schnittstelle muss ein prozessinterner COM-Server (CLSCTX_INPROC_SERVER) sein und für LocalService zugänglich sein.
[in] bstrInitString
Identifiziert die für das Gerät spezifische Initialisierungszeichenfolge. Diese Zeichenfolge wird später an IUPnPDeviceControl::Initialize übergeben.
[in] bstrContainerId
Gibt eine Zeichenfolge an, die die Prozessgruppe identifiziert, zu der das Gerät gehört. Alle Geräte mit derselben Container-ID sind im gleichen Prozess enthalten.
[in] bstrResourcePath
Gibt den Speicherort des Ressourcenverzeichnisses des Geräts an. Dieses Ressourcenverzeichnis enthält die Symboldateien und Dienstbeschreibungen, die in der Gerätebeschreibungsvorlage bstrXMLDesc angegeben sind. Das Ressourcenverzeichnis kann auch die Präsentationsdateien enthalten. Dies ist jedoch optional.
[in] nLifeTime
Gibt die Lebensdauer der Geräteankündigung in Sekunden an. Nach Ablauf des Timeouts werden die Ankündigungen aktualisiert. Wenn Sie null angeben, wird der Standardwert 1800 (30 Minuten) verwendet. Der zulässige Mindestwert beträgt 900 (15 Minuten); Wenn Sie etwas kleiner als 900 angeben, wird ein Fehler zurückgegeben.
[out] pbstrDeviceIdentifier
Empfängt den Gerätebezeichner. Verwenden Sie diesen Bezeichner, wenn Sie die Registrierung des Geräts aufheben oder erneut registrieren. Speichern Sie diese Geräte-ID. sie müssen beim Aufrufen von UnregisterDevice verwendet werden.
Rückgabewert
Wenn die Methode erfolgreich ist, wird der Rückgabewert S_OK. Andernfalls gibt die Methode einen der in WinError.h definierten COM-Fehlercodes oder einen der folgenden UPnP-spezifischen Fehlercodes zurück.
| Rückgabecode | Beschreibung |
|---|---|
|
Eine doppelte Dienst-ID für einen Dienst innerhalb desselben übergeordneten Geräts ist vorhanden. |
|
Die Gerätebeschreibung ist ungültig. |
|
Im Symbolelement der Gerätebeschreibung ist ein Fehler vorhanden. |
|
In einem Dienstelement in der Gerätebeschreibung ist ein Fehler vorhanden. |
|
Ein erforderliches Element fehlt. |
Hinweise
Ein Gerät wird instanziiert, und IUPnPDeviceControl::Initialize wird aufgerufen, wenn eine Steuerelement- oder Ereignisanforderung empfangen wird.
Verwenden Sie den in pbstrDeviceIdentifier zurückgegebenen Bezeichner, wenn Sie UnregisterDevice oder IUPnPReregistrar::ReregisterDevice aufrufen.
Häufige Fehler, die beim Aufrufen dieser Funktion auftreten können, sind:
- Das erforderliche COM-Objekt wurde nicht gefunden.
- Es gibt keinen Zugriff auf das COM-Objekt für LocalService.
- Untergeordnete COM-Schnittstellen.
- Die XML-Beschreibungsgrenzwerte (siehe Erstellen einer Gerätebeschreibung).
- Ereignisvariablen haben keine Erfolgscodes zurückgegeben, und das Gerät wurde heruntergefahren.
- Die Dienstbeschreibung war ungültig. Verwenden Sie validatesd.exe, um sicherzustellen, dass Dienstbeschreibungen gültig sind.
- Der Dienst hat IUPnPEventSource nicht implementiert und keinen Erfolgscode an IUPnPEventSource::Advise zurückgegeben, und das Gerät wurde heruntergefahren.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Nicht unterstützt |
| Zielplattform | Windows |
| Kopfzeile | upnphost.h |
| DLL | Upnphost.dll |