USER AUTH Device Host

About the Device Host API

This topic has not yet been rated - Rate this topicThe Device Host API with UPnP technology is a framework for implementing UPnP-based device functionality on the Windows platform. Developers who are creating devices by using the Device Host API with UPnP technology (referred to as hosted devices) need only implement the device's core functionality. Developers can rely on the device host to handle the UPnP-specific details of discovery, description, control, eventing, and presentation. The device host validates incoming data from UPnP-based clients and formats all outgoing data from hosted devices according to the UPnP device architecture.The following sections explain, in general, how the UPnP device host works:Implementing a Hosted DeviceRegistering a Hosted Device with the Device HostDevice ProvidersEventingPresentation 

Device Providers

This topic has not yet been rated - Rate this topicDevice providers are registered objects that the computer starts on every system startup. Device providers register and unregister running devices with the device host in response to some event. These devices are devices that have been automatically started at system startup time. For security reasons, a device provider should generally run as LocalService, rather than LocalSystem.Device providers can be used for transient devices. Device providers can also be used to bridge devices to polled media. For example, a peripheral device such as a digital music player is connected to a computer via a serial port. To expose the music player as a UPnP-based device, a device control object and a set of service objects are required. These objects implement the UPnP-based music player actions as serial commands. However, the music player must be plugged into the serial port and available for control before these objects are registered.Because the serial port does not offer an explicit notification mechanism when devices are connected, polling code is required. This code can be implemented in a device provider object, a service, or in a standalone application. When the computer is started, the device host instantiates the device provider object, and then invokes itsStart method. When the device provider detects the presence of a music player device, it instantiates the appropriate device control object and registers it by callingIUPnPRegistrar::RegisterRunningDevice. This method publishes the device and announces it to the UPnP-based network.The same functionality can also be achieved by implementing a service that polls the serial port. However, device providers simplify things by requiring only the core functionality—the polling—to be implemented because device providers rely on the device host to start and stop them. Using device providers is simpler than implementing a service.At registration time, and on every subsequent system startup, the computer instantiates the device provider object, and then invokes its IUPnPDeviceProvider::Startmethod, passing it the initialization string specified during registration.Once the Start method is called, the device provider performs any necessary processing, and when necessary, the device provider registers devices by callingIUPnPRegistrar::RegisterRunningDevice, as described in the section Registering a Hosted Device with the Device Host.When the computer is shut down, the device host invokes the IUPnPDeviceProvider::Stop method to indicate that the device provider terminate its operations. 

Eventing

0 out of 1 rated this helpful - Rate this topicA hosted service must implement the IUPnPEventSourceinterface if it has evented state variables. This interface has two methods: Advise and Unadvise. This interface provides a mechanism for the device host to subscribe to event notifications generated by the hosted service. There will be no more than one event sink registered at a time.A hosted service must implement the Advise method by holding a reference to the IUPnPEventSink interface, which was passed as a parameter. If the interface is found, theAdvise method holds a reference to that interface untilUnadvise is invoked, or until the hosted service object is removed. Advise is called only once.To remove the subscription, the device host invokesUnadvise and passes in the object pointer used when it called Advise. The hosted service removes the subscription if the pointer is the same as the one passed to Advise.When a state variable's value changes, the hosted service must signal that an event has occurred. The services does this by invoking the IUPnPEventSink::OnStateChangedmethod.When the device host no longer needs to receive notifications from the hosted service, it invokesIUPnPEventSource::Unadvise, passing in the same object pointer that it received from Advise. The device host invokes this method when the device is no longer going to be on the network. 

Presentation

3 out of 4 rated this helpful - Rate this topicPresentation is the final step in the UPnP process. If a device has a URL for presentation, a control point can retrieve a page from this URL and load the page into a browser. Depending on the capabilities of the presentation page and the device, the control point can control the device and view the status of the device.The resource path, which is passed to IUPnPRegistrarduring registration, is where all the files relevant to the presentation of the device are located. Device developers can provide separate pages for each embedded device. The presentation URL in the device description template can either be an absolute URL or a relative URL. For relative URLs, which are relative to the resource path, the device description template should contain a file name.IUPnPRegistrar converts this to a URL with the actual location. For absolute URLs, the location is not modified.To support client side scripts within a presentation page, extra information is normally appended to the URL in the form of a "query string". The extra information that is appended is the URL to the device description document, and the UDN of the device or embedded device. The device description URL can be used to load a description document in the script, and then control the device through its services. The UDN is used to select an embedded device from the root device.The format of the modified presentation URL is: the actual presentation URL, a question mark ("?"), the device description URL, a plus sign ("+"), the device UDN. The question mark denotes the start of the query string.If the presentation URL in the device description template was an absolute URL and it already contained a question mark ("?"), then the extra information is not added to the presentation URL.

DescriptionURLIn the device description templatepresentationURLMyDevice.html/presentationURLGenerated by the device hostpresentationURLhttp://machinename/deviceID/MyDevice.html/?http://machine/upnphost/udhisapi.dll?content=uuid:487394… + UDN/presentationURL 

A client-side script may have to extract the device description URL from the presentation URL to load theIUPnPDescriptionDocument object. This is done by taking the query string, and terminating it at the plus sign ("+").


VBDim QueryString QueryString = window.location.search Dim DescURLString DescURLString = Trim(Mid(QueryString,2,Instr(QueryString,"+")-2))& vbCrLf Dim LightDesc Set LightDesc = CreateObject("UPnP.DescriptionDocument.1") LightDesc.Load(DescURLString)


In the case of a presentation page for an embedded device, some additional work is required. After loading the UPnPDescriptionDocument, the script must obtain the collection of embedded devices, then select the device that matches the UDN in the query string. The following script shows how to select the embedded device for the current presentation page. It assumes LightDesc is already loaded.


VBDim LightDevice Set LightDevice = LightDesc.RootDevice Dim EmbeddedDevices set EmbeddedDevices = LightDevice.Children Dim DeviceUdnString DeviceUdnString = Trim(Mid(QueryString,Instr(QueryString,"+")+1,Len(QueryString))) Dim Item set Item = EmbeddedDevices.Item(DeviceUdnString)

http://msdn.microsoft.com/en-us/library/aa382263(v=vs.85).aspx

http://msdn.microsoft.com/en-us/library/aa382303(v=vs.85).aspx