IUPnPRegistrar ::RegisterRunningDevice, méthode (upnphost.h)
La méthode RegisterRunningDevice inscrit un appareil en cours d’exécution 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. La publication de cet appareil ne persiste pas entre les démarrages système.
Syntaxe
HRESULT RegisterRunningDevice(
[in] BSTR bstrXMLDesc,
[in] IUnknown *punkDeviceControl,
[in] BSTR bstrInitString,
[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] punkDeviceControl
Spécifie le pointeur IUnknown vers l’objet de contrôle d’appareil de l’appareil.
[in] bstrInitString
Identifie la chaîne d’initialisation spécifique à l’appareil. Cette chaîne est passée ultérieurement à IUPnPDeviceControl ::Initialize.
[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.
[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.
| Code de retour | Description |
|---|---|
|
Un élément en double existe. |
|
Il existe un ID de service en double pour un service au sein du même appareil parent. |
|
La description de l’appareil n’est pas valide. |
|
Une erreur est présente dans l’élément icon de la description de l’appareil. |
|
Une erreur est présente dans un élément de service dans la description de l’appareil. |
|
Un élément obligatoire est manquant. |
Remarques
Le client qui appelle cette méthode doit être en mesure d’emprunter l’identité de LocalService pour terminer le traitement de cette méthode.
La méthode IUPnPDeviceControl ::Initialize est appelée lors de la première demande de contrôle ou d’événement reçue.
Utilisez l’identificateur retourné dans pbstrDeviceIdentifier lors de l’appel de UnregisterDevice ou IUPnPReregistrar ::ReregisterRunningDevice.
L’inscription de cet appareil ne persiste pas entre les démarrages système.
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
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Aucun pris en charge |
| Plateforme cible | Windows |
| En-tête | upnphost.h |
| DLL | Upnphost.dll |