Implementing and Calling Custom Actions (Windows Embedded CE 6.0)
1/6/2010
The UPnP AV Framework supports the addition of custom actions to the services defined by the UPnP AV DCP.
.gif "Ee501218.collapse(en-US,WinEmbedded.60).gif")
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.
Note
The UPnP AV renderer sample includes code that demonstrates ignoring the first parameter. For more information, examine the CAVTransport::InvokeVendorAction method implementation in AVTransport.cpp in the UPnP AV renderer sample. For more information about this sample, see UPnP AV Renderer Sample.
Implementing Custom Actions for Windows Embedded CE
To implement a custom action in a device, perform the tasks in the following list.
- Modify the XML service description document to include the action and any required state variables. By convention, all custom actions should start with the string X_. For example, the demonstration custom actions in the AV Renderer sample are called X_VendorExtensionExample.
- Implement the functionality in the action by overriding the InvokeVendorAction method defined in the service interface. For example, to provide custom action processing in AVTransport, override IAVTransport::InvokeVendorAction (each of the four UPnP AV services has an InvokeVendorAction method).
For sample code that demonstrates how to implement and call custom actions using the UPnP AV Framework, see UPnP AV Control Point Sample and UPnP AV Renderer Sample.**