Eventing in the UPnP AV Framework
A version of this page is also available for
4/8/2010
In general, UPnP AV devices and control points use UPnP eventing like all UPnP devices: control points subscribe to receive events for state variable changes, and devices send events to subscribers.
The UPnP AV Framework provides a mechanism that abstracts the details of event notifications from control points and devices. This functionality makes subscribing to, sending, and receiving events appear like calling and implementing methods on a C++ object.
For more information about eventing details in the UPnP AV DCP, see UPnP AV DCP Documentation.
Receiving Events in Control Points
To receive events, a control point creates a class that derives from IEventSink and implements IEventSink::OnStateChanged so that it contains code to be executed when an event is received.
After this instance is registered with the service(s) raising events, any event that a service raises ultimately results in the execution of the code in the provided OnStateChanged method.
The connection between the control point and devices is provided by a control point proxy class included with the UPnP AV Framework. The control point proxy class receives events transmitted using UPnP eventing and transforms them into calls to OnStateChanged.
To register the IEventSink implementation with a device, the control point calls the IEventSource::Advise method on the service that raises the events in which it is interested. For example, to subscribe to events from the AVTransport service, a control passes an IEventSink implementation to IAVTransport::Advise.
To unsubscribe from events, the control point calls IEventSource::Unadvise and passes the original IEventSink pointer.
Events from Virtual Services
A single AVTransport and RenderingControl service can support multiple virtual instances, one for each transport or rendering device.
At the level of the UPnP messages sent over the network, the particular virtual service is identified by an instance ID value that each AVTransport and RenderingControl action accepts. Eventing for AVTransport and RenderingControl services is accomplished through a LastChange state variable that contains instance IDs and the changes associated with each instance ID.
The UPnP AV Framework hides these details using the IEventSink, IEventSource, IAVTransport and IRenderingControl classes. From the perspective of control point or device implementation code, each IAVTransport or IRenderingControl instance is a separate instance.
Because of this, code using the UPnP AV Framework does not need to manage instance IDs or use the LastChange state variable. Instead, it calls or implements OnStateChanged and lets the UPnP AV Framework generate or receive the correct UPnP messages at the correct times.