Device Control
A version of this page is also available for
4/8/2010
A control point controls a UPnP device by interacting with the services that the device exposes.
Retrieving Service Instances
A UPnP service is the smallest controllable entity in the UPnP architecture. A device typically exposes one service for each primary function it performs. A complex device is typically composed of several simple services, and embedded devices that contain their own services.
In the Control Point API, services are represented by objects that implement the IUPnPService interface. You can retrieve a collection of IUPnPService instances for a particular device using the IUPnPDevice::Services method.
Invoking Actions and Retrieving State Information
A service consists of a set of state variables and a set of actions an application can invoke that operate on those state variables.
- To invoke actions, call the IUPnPService::InvokeAction method.
- To retrieve service state variable information, call the IUPnPService::QueryStateVariable method.
To control devices, the Control Point API uses the control model exposed by the UPnP architecture. The control model is introduced in UPnP Control.
Service Types and Service Identifiers
A service type defines the state variables and actions supported by a particular service. For example, the service type for a clock service defines a Time state variable, and GetTime and SetTime actions. To retrieve the service type, use the IUPnPService::ServiceTypeIdentifier method.
A service identifier differentiates multiple common service types within a single device. For example, there can be two clock services in an alarm clock, one for the regular clock, and one for the alarm. The two services have identical service types but different service identifiers. To retrieve the service identifier, use the IUPnPService::Id method.
Registering for Variable Change and Other Notifications
In addition to using the QueryStateVariable method to poll for changes in state variables, control point applications can register to be notified when a state variable changes, using the IUPnPService::AddCallback method.
To use this method, a control point application passes an object that contains a method. The Control Point API will call this method when a state variable changes or when the service has sent a notification that it is no longer available for requests. This method can be used to register more than one callback so that multiple pieces of code can execute on any particular state variable change or notification.
To provide these notifications, the Control Point API uses the event model exposed by the UPnP architecture. The event model is introduced in UPnP Eventing.