IUPnPService ::InvokeAction, méthode (upnp.h)

Article
03/06/2024

La méthode InvokeAction appelle une méthode sur l’appareil.

Syntaxe

HRESULT InvokeAction(
  [in]      BSTR    bstrActionName,
  [in]      VARIANT vInActionArgs,
  [in, out] VARIANT *pvOutActionArgs,
  [in, out] VARIANT *pvRetVal
);

Paramètres

[in] bstrActionName

Spécifie la méthode à appeler.

[in] vInActionArgs

Spécifie un tableau d’arguments d’entrée pour la méthode . Si l’action n’a pas d’arguments d’entrée, ce paramètre doit contenir un tableau vide.

Le contenu de ce tableau est spécifique au service.

[in, out] pvOutActionArgs

En entrée, contient une référence à un tableau vide. Lors de la sortie, reçoit une référence au tableau d’arguments de sortie. Si l’action n’a pas d’arguments de sortie, ce paramètre contient un tableau vide.

Le contenu de ce paramètre est spécifique au service.

Libérez ce paramètre avec VariantClear.

[in, out] pvRetVal

En entrée, contient une référence à un tableau vide. Lors de la sortie, reçoit une référence à un VARIANT qui contient la valeur de retour de cette action.

Si l’appareil retourne une erreur après l’appel de l’action sur celui-ci et que ce paramètre n’est pas défini sur NULL, ce paramètre contient du texte spécifique décrivant l’erreur lors du retour. Pour plus d’informations sur les erreurs retournées par les appareils, consultez la documentation Relative aux codes d’erreur des appareils.

Libérez ce paramètre avec VariantClear.

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’une des valeurs de retour spécifiques à UPnP indiquées dans le tableau suivant. Certaines de ces valeurs indiquent qu’une erreur a été reçue d’un appareil certifié UPnP. Pour plus d’informations, consultez Codes d’erreur d’appareil.

Code de retour	Description
UPNP_E_ACTION_REQUEST_FAILED	L’appareil a rencontré une erreur interne ; la demande n’a pas pu être exécutée.
UPNP_E_DEVICE_ERROR	Une erreur inconnue s'est produite.
UPNP_E_DEVICE_TIMEOUT	L’appareil n’a pas répondu dans le délai d’attente de 30 secondes.
UPNP_E_ERROR_PROCESSING_RESPONSE	L’appareil a envoyé une réponse qui ne peut pas être traitée ; par exemple, la réponse a été endommagée.
UPNP_E_INVALID_ACTION	L’action n’est pas prise en charge par l’appareil.
UPNP_E_INVALID_ARGUMENTS	Un ou plusieurs des arguments passés dans vInActionArgs ne sont pas valides.
UPNP_E_PROTOCOL_ERROR	Une erreur s’est produite au niveau du protocole de contrôle UPnP.
UPNP_E_TRANSPORT_ERROR	Une erreur HTTP s’est produite. Utilisez la propriété IUPnPService ::LastTransportStatus pour obtenir le code http status réel. Note Ce code d’erreur est également retourné lorsque la réponse SOAP dépasse 100 kilo-octets.

Remarques

Lorsqu’une application appelle la méthode InvokeAction, elle inclut une liste d’arguments qui doivent correspondre aux arguments attendus par le service. Le point de contrôle mappe ces arguments VARIANT au type requis. Le tableau suivant présente les mappages utilisés.

Type de données	Type retourné par MSXML
SDT_STRING = 0	VT_BSTR
SDT_NUMBER	VT_BSTR
SDT_INT	VT_I4
SDT_FIXED_14_4	VT_CY
SDT_BOOLEAN	VT_BOOL
SDT_DATETIME_ISO8601	VT_DATE
SDT_DATETIME_ISO8601TZ	VT_DATE
SDT_DATE_ISO8601	VT_DATE
SDT_TIME_ISO8601	VT_DATE
SDT_TIME_ISO8601TZ	VT_DATE
SDT_I1	VT_I1
SDT_I2	VT_I2
SDT_I4	VT_I4
SDT_UI1	VT_UI1
SDT_UI2	VT_UI2
SDT_UI4	VT_UI4
SDT_R4	VT_FLOAT
SDT_R8	VT_DOUBLE
SDT_FLOAT	VT_DOUBLE
SDT_UUID	VT_BSTR
SDT_BIN_BASE64	VT_ARRAY
SDT_BIN_HEX	VT_ARRAY
SDT_CHAR	VT_UI2 (un wchar)
SDT_URI	VT_BSTR

Note Les paramètres qui reçoivent des valeurs ne doivent pas recevoir de valeur NULL lorsque la méthode est appelée.

Note Une valeur à virgule flottante envoyée par un appareil en tant qu’argument [out] ou une valeur de retour est modifiée lorsqu’elle est reçue par le point de contrôle. Par exemple, considérez un appareil avec une action Action1Out_float qui retourne un seul argument à virgule flottante [out]. Lorsqu’un point de contrôle appelle cette action, l’appareil retourne la valeur -234.567 ; toutefois, le point de contrôle reçoit en fait la valeur -234.567001342773 au lieu de la valeur attendue -234.567.

Pour contourner ce problème, utilisez r4 au lieu de float comme type de données UPnP pour les valeurs numériques non entières.

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	upnp.h
DLL	Upnp.dll

Voir aussi

IUPnPService

Partager via