Creating an IUPnPDeviceControl Implementation
A version of this page is also available for
4/8/2010
The Device Host API is a framework that handles the communication between control points and devices and services. Although this communication is general to all UPnP devices, the specific implementation of functionality for each device and each service in a device differs.
To provide this functionality, the Device Host API relies on a set of custom COM objects written by the UPnP device developer. For for each device, the Device Host API relies on a device control object; for each service that the device provides, this API relies on a service object.
A device control object, which implements the IUPnPDeviceControl interface, serves as the central control point for all service objects associated with a device. During setup, a device application registers with the UPnP Device Host API by providing the device control object. Then, when a control request arrives for one of the device's services, the API calls the device control object and requests the relevant service object. The device control object can then create and return a new service object instance, or it can use an existing instance (such as one that was used for a previous request).
The Device Host API initializes the device control object by calling IUPnPDeviceControl::Initialize and passing in the full text of the UPnP device description and an initialization string that was specified at registration time.
Later, when a control request arrives for one of the device's services, the Device Host API calls IUPnPDeviceControl::GetServiceObject on the device control object to obtain a pointer to a service object that implements the requested service. The Device Host API passes in the unique device name and the service identifier of the requested service. It also passes in the address of a pointer to an IDispatch interface, at which the method is expected to return the service object.
A service object is a COM object that provides methods for the actions in a UPnP service. In the UPnP service description, the service interfaces are specified in UPnP Template Language (UTL). COM object interfaces are typically specified in Interface Definition Language (IDL), a type library, or a header file.
For assistance in generating the appropriate IDL file for a particular UPnP service description, developers can use the utl2idl tool. This tool translates a UTL service description into a COM IDL interface. This tool is not included with Platform Builder for Windows CE 5.0; however, you can download it as part of the Microsoft Platform SDK. For more information, see this Microsoft Web site.