Edit

Share via

IUPnPService::InvokeAction method (upnp.h)

  • Article

The InvokeAction method invokes a method on the device.

Syntax

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

Parameters

[in] bstrActionName

Specifies the method to invoke.

[in] vInActionArgs

Specifies an array of input arguments to the method. If the action has no input arguments, this parameter must contain an empty array.

The contents of this array are service-specific.

[in, out] pvOutActionArgs

On input, contains a reference to an empty array. On output, receives a reference to the array of output arguments. If the action has no output arguments, this parameter contains an empty array.

The contents of this parameter are service-specific.

Free this parameter with VariantClear.

[in, out] pvRetVal

On input, contains a reference to an empty array. On output, receives a reference to a VARIANT that contains the return value of this action.

If the device returns an error after the action is invoked on it and this parameter is not set to NULL, this parameter will contain specific text describing the error upon return. For more information on the errors returned by devices, please refer to the Device Error Codes documentation.

Free this parameter with VariantClear.

Return value

If the method succeeds, the return value is S_OK. Otherwise, the method returns one of the COM error codes defined in WinError.h or one of the UPnP-specific return values shown in the following table. Some of these values indicate that an error was received from a UPnP-certified device. For more information, see Device Error Codes.

Return code Description
UPNP_E_ACTION_REQUEST_FAILED
 The device had an internal error; the request could not be executed.
UPNP_E_DEVICE_ERROR
 An unknown error occurred.
UPNP_E_DEVICE_TIMEOUT
 The device has not responded within the 30 second time-out period.
UPNP_E_ERROR_PROCESSING_RESPONSE
 The device has sent a response that cannot be processed; for example, the response was corrupted.
UPNP_E_INVALID_ACTION
 The action is not supported by the device.
UPNP_E_INVALID_ARGUMENTS
 One or more of the arguments passed in vInActionArgs is invalid.
UPNP_E_PROTOCOL_ERROR
 An error occurred at the UPnP control-protocol level.
UPNP_E_TRANSPORT_ERROR
 An HTTP error occurred. Use the IUPnPService::LastTransportStatus property to obtain the actual HTTP status code.
Note  This error code is also returned when the SOAP response exceeds 100 kilobytes.
 

Remarks

When an application invokes the method InvokeAction, it includes a list of arguments that should match the arguments expected by the service. The Control Point maps these VARIANT arguments to the required type. The following table shows the mappings that are used.

Data type Type returned by 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 (a wchar)
SDT_URI VT_BSTR
 
Note  Parameters that receive values must not be passed a NULL value when the method is called.
 
Note  A floating-point value sent by a device as an [out] argument or a return value will be changed when received by the control point. For example, consider a device with an action Action1Out_float that returns a single [out] floating-point argument. When a control point invokes this action, the device returns the value -234.567; however, the control point actually receives the value -234.567001342773 instead of the expected value -234.567.

To work around this issue, use r4 instead of float as the UPnP data type for non-integer numeric values.

 

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server None supported
Target Platform Windows
Header upnp.h
DLL Upnp.dll

See also

IUPnPService