Registering a Hosted Device
A version of this page is also available for
4/8/2010
To register a hosted device, you must provide a device description and the corresponding device control object. The UPnP Device Host API uses this information to create complete UPnP device descriptions and publish them on the network so that control points can access them.
You can register a hosted device in the following ways:
- Create an instance of the device control object and pass a pointer to the object to the Device Host API.
- Pass the ProgID of a device control object to the Device Host API, which will instantiate the object when needed.
- Specify the ProgID of the device control object in the registry, and let the Device Host API instantiate the object when needed.
Although in all cases the Device Host API publishes and announces the device on the network after registering the device, the time when the device code is loaded differs:
- In the first case listed above, the device code is loaded directly at the time of registration.
- In the second case and third cases, the device code is loaded only when the device receives a control or event subscription request. Although this method can, in some situations, lead to more efficient use of memory, it is unsuitable for devices that must be running before any control or event subscription requests arrive for them.
A device is registered through the UpnPRegistrar object, which exposes the IUPnPRegistrarinterface.
Using an Existing Device Control Object
To register a device by using an existing device control object, call IUPnPRegistrar::RegisterRunningDevice and pass, among other things, an IUnknown reference to the device control object. RegisterRunningDevice is only supported when it is called from a service that is loaded in the services.exe process.
Using Object Created by the UPnP Device Host API
To register a device and have the UPnP Device Host API create the object when it is needed, call IUPnPRegistrar::RegisterDevice and pass, among other things, the ProgID of the object to create. RegisterDevice can be called from any process.
Using the Registry
To register a device by using the registry, without writing code, create a key named after your device in the HKEY_LOCAL_MACHINE\Comm\UPnPDevices key and then create registry entries beneath this new key to specify the ProgID of the object and other required initialization information. For more information, see UPnP Registry Device Creation.
To Unregister
To unregister a hosted device, call IUPnPRegistrar::UnregisterDevice method. If the fPermanent flag is set, this method permanently removes the device from the host. If the flag is not set, the device is removed, but the application can register it again by using the IUPnPReregistrar interface.