Eventing in the UPnP AV Framework (Windows CE 5.0)
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 sample code that demonstrates how to receive and send events using the UPnP AV Framework, see UPnP AV Control Point Sample (for receiving events) and UPnP AV Renderer Sample (for sending events).
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.
Raising Events in Devices
To raise events, a device creates a class that derives from IEventSource and implements Advise and Unadvise to accept subscribe and unsubscribe requests.
The Advise implementation stores the passed IEventSink pointer. The service then uses the saved pointer to raise events by calling OnStateChanged whenever an evented state variable changes.
The UPnP AV Framework handles any necessary event moderation transparently on the device. If a device calls OnStateChanged multiple times before the moderation time interval has passed, the UPnP AV Framework only events a single value. The particular value that is sent is not specified, and the point at which the value is sent is also not specified. The events are sent in accordance with the UPnP specifications.
The connection between the device and the control point is provided by a device proxy class included with the UPnP AV Framework. This proxy class packages calls to OnStateChanged into events transmitted using UPnP eventing.
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.
See Also
Send Feedback on this topic to the authors