Méthode IUPnPRegistrar ::RegisterDevice (upnphost.h)

La méthode RegisterDevice inscrit un appareil auprès de l’hôte de l’appareil. Les informations de l’appareil sont stockées par l’hôte de l’appareil. Ensuite, l’hôte de l’appareil retourne un identificateur d’appareil et publie et annonce l’appareil sur le réseau.

Syntaxe

HRESULT RegisterDevice(
  [in]  BSTR bstrXMLDesc,
  [in]  BSTR bstrProgIDDeviceControlClass,
  [in]  BSTR bstrInitString,
  [in]  BSTR bstrContainerId,
  [in]  BSTR bstrResourcePath,
  [in]  long nLifeTime,
  [out] BSTR *pbstrDeviceIdentifier
);

Paramètres

[in] bstrXMLDesc

Spécifie le modèle de description d’appareil XML de l’appareil à inscrire.

[in] bstrProgIDDeviceControlClass

Spécifie le ProgID d’un objet de contrôle d’appareil qui implémente l’interface IUPnPDeviceControl . Cette interface doit être un serveur COM in-process (CLSCTX_INPROC_SERVER) et doit être accessible à LocalService.

[in] bstrInitString

Identifie la chaîne d’initialisation spécifique à l’appareil. Cette chaîne est passée ultérieurement à IUPnPDeviceControl ::Initialize.

[in] bstrContainerId

Spécifie une chaîne qui identifie le groupe de processus auquel appartient l’appareil. Tous les appareils avec le même ID de conteneur sont contenus dans le même processus.

[in] bstrResourcePath

Spécifie l’emplacement du répertoire de ressources de l’appareil. Ce répertoire de ressources contient les fichiers d’icônes et les descriptions de service spécifiés dans le modèle de description d’appareil bstrXMLDesc. Le répertoire de ressources peut également contenir les fichiers de présentation. Toutefois, cette option est facultative.

[in] nLifeTime

Spécifie la durée de vie de l’annonce de l’appareil, en secondes. Une fois le délai d’expiration expiré, les annonces sont actualisées. Si vous spécifiez zéro, la valeur par défaut de 1800 (30 minutes) est utilisée. La valeur minimale autorisée est 900 (15 minutes) ; si vous spécifiez une valeur inférieure à 900, une erreur est retournée.

[out] pbstrDeviceIdentifier

Reçoit l’identificateur de l’appareil. Utilisez cet identificateur lors de l’annulation de l’inscription ou de la réinscription de l’appareil. Enregistrez cet ID d’appareil ; vous devez l’utiliser lors de l’appel de UnregisterDevice.

Valeur retournée

Si la méthode réussit, la valeur de retour est S_OK. Sinon, la méthode retourne l’un des codes d’erreur COM définis dans WinError.h ou l’un des codes d’erreur UPnP suivants.

Remarques

Un appareil est instancié et IUPnPDeviceControl ::Initialize est appelé lorsqu’une demande de contrôle ou d’événement est reçue.

Utilisez l’identificateur retourné dans pbstrDeviceIdentifier lors de l’appel de UnregisterDevice ou IUPnPReregistrar ::ReregisterDevice.

Les erreurs courantes qui peuvent se produire lors de l’appel de cette fonction sont les suivantes :

• L’objet COM nécessaire est introuvable.
• Il n’existe aucun accès à l’objet COM pour LocalService.
• Interfaces COM subordonnées.
• Limites de la description XML (voir Création d’une description d’appareil).
• Les variables événementielles n’ont pas retourné de codes de réussite et l’appareil a été arrêté.
• La description du service n’était pas valide. Utilisez validatesd.exe pour vous assurer que les descriptions de service sont valides.
• Le service n’a pas implémenté IUPnPEventSource et n’a pas retourné de code de réussite à IUPnPEventSource ::Advise et l’appareil a été arrêté.

Configuration requise

Voir aussi

IUPnPRegistrar

IUPnPRegistrar ::UnregisterDevice

IUPnPReregistrar