Implementing and Calling Custom Actions
A version of this page is also available for
4/8/2010
The UPnP AV Framework supports the addition of custom actions to the services defined by the UPnP AV DCP.
Calling Custom Actions
To call a custom action from a control point, call InvokeVendorAction. As it does with predefined actions, the UPnP AV Framework packages the InvokeVendorAction parameters, sends them to the service using UPnP, and calls the InvokeVendorAction method on the appropriate device service class.
For more information, see UPnP AV DCP Documentation.
Custom Action Parameters
To support the passing of varying numbers of parameters in custom actions, the InvokeVendorAction method signature uses an instance of the COM DISPPARAMS structure. DISPPARAMS can contain an arbitrary number of parameters.
For more information about using DISPPARAMS instances, see Passing Parameters.
Virtual Services and the First Custom Action Parameters
The AVTransport and RenderingControl services can support multiple virtual services. At the UPnP network level, each service is identified by an instance ID that is passed to all actions. The UPnP AV Framework hides this detail and enables device implementers to handle virtual instances by creating instances of classes that derive from the top-level interface classes, like IAVTransport, and so do not require the use of instance IDs.
A control point that calls a custom action does not need to do anything with instance IDs. The UPnP AV Framework automatically adds the instance ID as the first parameter of the DISPPARAMS structure before it sends the action invocation request to the device.
The UPnP AV Framework ensures that action invocations are routed to the appropriate device instance and does not require processing the instance ID. However, it does not remove the instance ID from the DISPPARAMS structure. Therefore, device implementation code in virtual services should ignore the first parameter in the DISPPARAMS structure.