Auto-configuring of peripheral on host/peripheral computing platform with peer networking-to-host/peripheral adapter for peer networking connectivity6779004Abstract A self-installing and configuring peer networking-to-host/peripheral connectivity adapter, such as a set of software modules running on a host, operates to convert between a device control protocol with peer networking connectivity and a host/peripheral connectivity protocol for a set of host-connected peripheral devices. The adapter is automatically installed on the host upon connecting a new peripheral device, such as by a plug-and-play operating system of the host. The adapter operates as a peer-networking addressable controlled device module, which responds to communication in the device control protocol from other peer devices that are networked with the host. The adapter converts the device control protocol communications from the peer devices into a host/peripheral protocol for controlling the peripheral devices. The peripheral devices thereby are controllable as peer networking devices via the peer networking connectivity device control protocol. Claims I claim: Description TECHNICAL FIELD
User Control Point Controlled Device
Function Module Function Module
Initiate discovery Discovery Client Respond to Discovery
of Controlled discovery Server
Devices. requests.
Retrieve Description Client Provide Description
Description Description Server
Documents. Documents.
Display a folder Visual Navigation
of icons per
discovered
Device and allow
transfer of
control to a
selected device.
View user Web Browser Provide user Presentation
interface exposed inteface for (Web) Server
by a Controlled remote User
Device. Control Points.
Execute Application
applications. Execution
Environment
Invoke Rehydrator Accept incoming Control Server
Commands on a Commands in plus native
Controlled Device SCPs and control logic
by sending execute them.
Service Control
Protocols in
response to local
API calls.
Inform a Event Accept requests Event
Controlled Device Subscription for Events and Subscription
of a desire to Client remember them. Server
receive Events.
Receive an Event. Event Sink Send an Event. Event Source
Device Model The UPnP Device Model 200 shown in FIG. 3 is the model of a UPnP Controlled Device or Bridge that is emulating native Controlled Devices. The Device Model includes the addressing scheme, eventing scheme, Description Document schema, Devices and Services schema and hierarchy, and the functional description of modules. The UPnP Device Model extends beyond simple API or a command and control protocol definitions to enable multiple User Control Points to have a consistent view of Controlled Devices. This requires that the state of running services be formally modeled and that all state changes be visible to User Control Points. Central to the distributed UPnP architecture is the rule that Controlled Devices are the ultimate authority for the state of Services running on them. Service The fundamental controllable entity in UPnP is a Service 210-217. Every running instance of a Service includes: A Service State Table (SST) 230, which represents the current state of the Service. The SST 230 can be used to represent the operational mode of device or to act as an information source or sink for structured data or simple files. The SST of a VCR 254 (FIG. 4) could represent the current transport mode, tuner channel selection, input and output switch selections, audio and video decoding format and current timer program. The SST of clock 251 (FIG. 4) would likely represent the current time. The SST of an image rendering device could implement a video frame-buffer that can accept raw pixel information or formatted JPG files. The SST of an audio or video playback device could implement a transfer buffer or queue of material to be played. The SST of PDA could implement a collection of formatted data that has changed and needed to be synchronized with another device, in addition to a transfer buffer for accepting incoming formatted data. The logical structure of a SST published in the Service Definition, but the actual storage format of an instance of a SST is entirely up the device. The only interaction with a SST is through a formal application level network protocol. A Control Server 232, which accepts incoming Commands expressed in the Service's Service Control Protocol (SCP). The Control Server passes the command to the Service's native command processing logic and waits for command completion. When the command is completed successfully, the SST is updated, an event is generated, and a successful response is returned to the User Control Point. In the event of an illegal command or unsuccessful command, no changes are made to the SST and a failure response is returned. The Command and response sequence is payload to a TCP/HTTP request/response. An Event Subscription Server and Event Source 234. The Event Subscription Server accepts incoming GENA SUBSCRIBE messages from User Control Points and adds them to a list of User Control Points interested in SST change events from the Service. The Event Source initiates a TCP/HTTP connection to each interested User Control Point and sends a GENA NOTIFY each time the Service's DST changes. The NOTIFY payload includes the changed contents of the DST. A Control URL that identifies the Control Server. An Event URL that identifies the Event Subscription Server. The formal definition of a Service (Service Definition) includes: The definition of the SST. SST layouts are logically specified in terms of rows of [Variable, Type, Legal Values, Default Value]. The actual instance of a SST would also include a Current Value field in every row. The definition of the Service Command Set that can be invoked against the Service's SST. Commands are logically specified in terms of Command (Variable=New Value, Variable=New Value, . . . ). If a Command results in more than a single Variable change, the updates are atomic and the Command will fail if it is illegal to make the specified change to any one Variable. The definition of a structured unit of data called a Service Control Protocol Declaration (SCPD). SCPD is used to advertise the layout (schema) of the SST and Command Set of the Service to a User Control Point or Bridge. The SCPD enables the User Control Point to invoke Commands (through the Rehydrator) on the Controlled Device without any prior or persistent knowledge of the capabilities of the device. The SCPD is uploaded from the Controlling Device as part of the Description Document. Generation of the SCPD for a Service based on its SST definition and Command Set definition can be fully automated. The definition of a network protocol used to invoke Commands against the SST associated with a Service and to return results. The SCP can be generated from the SCPD. The Rehydrator's job is to convert SCPDs into SCPs. The reason for a formal SCP specification is to enable the implementation of the Control Server itself and to enable simple peer-to-peer device interoperation using only published protocols. An identifier, called the Service Type Identifier, that identifies a unique Service Definition. Service Definitions are versioned in controlled manner. Every later version of a Service must be proper superset of the previous version. Device According to the device model 200 shown in FIG. 3, a UPnP Device 202-205 (e.g., multiple function devices 102-103 of FIG. 1 and bridged devices 122-123 of FIG. 2) is a logical container of one or more Services 210-217. Generally a Device represents a physical entity such as a VCR. Typical Services in the VCR Device example might be "TRANSPORT", "TUNER", "TIMER" and "CLOCK". While Devices are often physical entities, a PC emulating the traditional functions of a VCR could also be modeled in the same way as the stand-alone VCR. Devices can contain other Devices. An example would be a TV/VCR 250 (FIG. 4) packaged into a single physical unit. A Device (e.g., devices 202-203) may also be a logical container of other Devices. The top-most Device in a hierarchy of nested Devices 203-205 is called the Root Device 202. A Device with no nested Devices is always a Root Device. The UPnP Device Model was designed to be general and flexible. It should be possible to model an entire Nuclear Power Plant as a single Service or as a deeply nested hierarchy of Devices and Services. In general, a Service 210-217 is cohesive set of functions that enables flexible packaging into a variety of Devices. Services can be versioned independently of Devices. All Devices, including Root Devices belong to one or more Device Types. Device Types are intended to enable instances of Devices to be simply and automatically grouped for presentation. An example of a Device Type is "VCR" 254 (FIG. 4). Device Types are formally defined in terms of a minimal set of versioned Services that a Device of Device Type must support. Device Types are not formally versioned. Device Type is a relatively high level grouping. A Device of Device Type only ensures that minimal set of Services of a minimal version is present. There can be other Services, higher versioned Services and Services with vendor extensions present on such a Device. UPnP enables SSDP level searches for a unique instance of a Device (by UDN), all Devices of type Device Type and all Devices that contain at least one Service Type of minimum version. The result of an SSDP search is always a URL that points to the Description Document contained in the Root Device. In the event that matching Device is not the Root Device, the Description Document has a tree of nested Devices that can be traversed to find the matching Device. Every Device includes: One or more Device Types. One or more Services. Optionally, one or more Devices. Optionally, a Presentation (Web) Server 220-223 that can be used to expose Device user interface. Every Presentation Server has an associated Presentation URL. A globally unique identifier called the Unique Device Name (UDN). The UDN is the fundamental identifier of an instance of a Device. Every Device, including Root Devices, has exactly one UDN. Every Root Device 202 also includes the Description Document 226 and Description Server 228 for all Devices under and including itself. The formal definition of a Device (Device Definition 226) includes: The fixed elements of the Description Document that describe the Device. The required hierarchy of Devices and Service Definitions. There can be many Device Definitions that belong to a single Device Type. Device Types The formal definition of a Device Type includes: A Device Type Identifier. The required hierarchy of Devices and Service Definitions of minimum versions. Service State Table A Service State Table (SST) logically consists of rows of: Variable, Type, Legal Values, Default Value, Current Value Although entries of the Service State Table in UPnP consist of these five items, the state table alternatively can contain fewer or additional items. Generally, each entry will minimally consist of a Variable name or identifier, and its current value. The following table lists various Types available in UPnP.
Type Description Example
String A sequence of UNICODE characters.
Number A number, with no limit on digits; may 15, 3.14, --
potentially have a leading sign, 123.456E+10
fractional digits, and optionally an
exponent. Punctuation as in US
English.
Boolean TRUE or FALSE.
DateTime A date in ISO8601 format, with 19941105T08:1
optional time and optional zone. 5:5+03
Fractional seconds may be as precise
as nanoseconds. See, "Data elements
and interchange formats - Information
interchange - Representation of dates
and times", which can be found at
http://www.iso.ch/markete/8601.pdf.
ByteBlock An unstructured sequence of bytes.
The ByteBlock is essentially a data buffer. In one use, a variable of this type can be used to effect transfer of a file from the Controlled Device to the User Control Point. The file to be transferred is kept in the Service State Table as the current value of this variable. On a change in the file, the file is transferred to any subscribing User Control Point in an event notification. The reason for representing Services this way is to ensure that the state of a Service is easily available in a common way to multiple User Control Points. An SST can be used to represent to current operational mode of device, act as an information source or sink and/or simply be a repository for commands. The SST of a VCR Service could represent the current transport mode, tuner channel selection, input and output'switch selections, audio and video decoding format and current timer program. Alternatively, the VCR 254 could be represented as a Transport Service 260, Tuner Service, I/O Switch Service, A/V Decoding Configuration Service and Programmable Timer Service 261. The SST of a clock 251 would likely represent the current time. Additionally an alarm clock could include Service Variables to configure the clock. The SST of an image rendering device could implement a video frame-buffer that can accept raw pixel information or formatted JPG files. The SST of an audio or video playback device could implement a transfer buffer or queue of material to be played. The SST of PDA could implement a collection of formatted data that has changed and needed to be synchronized with another device, in addition to a transfer buffer for accepting incoming formatted data. User Control Point Synchronization In accordance with an device state and eventing model illustrated in FIG. 5, UPnP rules require that every change to an SST generate a corresponding event to announce the change to the all interested User Control Points. Device Addressing With reference now to FIG. 6, UPnP is built on top of HTTP and leverages the native address format of the Web, Uniform Resource Locators (URLs). URLs minimally contain an identification of the application protocol family ("http") that the URL is valid for, a Hostname and a path. In the context of UPnP, the path part of a URL can represent either a filesystem path or simply an identifier of the local system module and context that can process incoming messages. While UPnP modules are described as HTTP servers, there is no requirement that implementations be based on actual Web servers. In most cases, the job of the HTTP server is simply to accept the incoming connection, look at the local destination part of the address (the path) and forward the payload to another module. UPnP enables, but does not require, that all HTTP Servers be based on a common software implementation or runtime instance. Controlled Devices and Bridges can include a TCP port specification as part of a URL to override the default value of 80. The successful result of a SSDP level search in UPnP is always one or more Description URLs. These URLs can be used to navigate to the Description Document of a Controlled Device or Bridge. A User Control Point uploads the Description Document and extracts the URLs of the Servers running on the Controlled Device or Bridge. All URLs returned in the Description Document have a lifetime equal to the lifetime of the Hostname embedded in them. User Control Points can store these URLs as addresses without going through a search sequence first. Once they have been advertised in a Description Document, Controlled Device and Bridges cannot arbitrarily change Server URLs. Whenever a Hostname changes, all URLs associated with all Devices addressed by that Hostname are invalidated. The UDN is the only UPnP identifier guaranteed never to change. Any persistent associations maintained by applications should at least store the UDN to able to unambiguously identify the target Device. The lifetime of a Description URL is determined by Controlled Device or Bridge that advertises it. If a Controlled Device or Bridge allows an SSDP advertisement of a Description URL to expire, the URL is invalidated. User Control Points use the Event Subscription URL returned by the Controlled Device or Bridge to connect to the Event Subscription Server. This server does the housekeeping of remembering all User Control Points that are interested in receiving Events on a Service. The Event Subscription Server needs an address to send the events back to. This address is called the Event Sink URL, and is supplied to the Controlled Device or Bridge in the GENA SUBSCRIBE message. The lifetime of an event subscription, and the Event Sink URL, is determined by the timeout on the SUBSCRIBE message. Further details of UPnP addressing are listed in the following table.
UPnP Addresses
URL Function
Description Points to the Description Server and Document path on a
URL Root Device. This URL is returned by the Description
Server as part of the discovery process.
Presentation Points to a Presentation (Web) Server on a Controlled
URL Device. There is one Presentation URL per Device,
including Root Devices. This URL can be entered into the
address bar of a Web browser to navigate to the root
Web page of a Device. This URL is returned in the
Description Document.
Control URL Points to the Control Server implementing a Service on a
Controlled Device. There is one Control URL per instance
of a Service. This URL is returned in the Description
Document.
Event Points to an Event Subscription Server on a Controlled
Subscription Device. This URL is returned in the Description Document.
URL
Event Sink Points to an Event Sink (an HTTP Server) on a User
URL Control Point. This URL is specified by the User Control
Point in the GENA SUBSCIBE message.
Device Discovery and Identification UPnP enables SSDP searches for a unique. Root or non-Root Device by UDN, devices of a specified Device Type and devices containing a Service of a specified Service Type.
UPnP SSDP Level Searches and Results
Search for Returns
A unique Root A single Description URL pointing to the Description
Device (by Server and Document path on the Root Device.
UDN)
A unique non- A single Description URL pointing to the Description
Root Device (by Server and Document path on the Root Device that
UDN) contains the non-Root Device.
Type of Device A set of Description URLs pointing to the Description
Servers/Document paths of all Root Devices that
match the Device Type, or contain a non-Root
Device that matches the Device Type.
Type of Service A set of Description URLs pointing to the Description
Servers/Document paths of all Root Devices that
contain a matching Service, or contain a non-Root
Device that contains a matching Service.
SSDP specifies Service Type (ST), Notification type (NT), and Unique Service Name (USN) header fields for queries and for announcements. UPnP uses the ST or NT header to carry one of the UPnP defined identifiers. A unique USN is required for each unique SSDP announcement. Multiple instances of the same Service Type within a Controlled Device 106-107 or Bridge 120 are not independently announced. UPnP search identifiers are used during the discovery process. The result of a successful discovery is one or more Description URLs. The format for search identifiers is: upnp:searchtype: [allformat.vertline.UDNformat.vertline.srvformat.vertline.devformat] searchtype=[UDN.vertline.SrvType.vertline.DevType.vertline.all] allformat=all UDNformat=UDN:namespace:uniqueid namespace=[GUID.vertline.IEEEMAC.vertline.1394] srvformat=SrvType:servicetype:version devformat=DevType:devicetype
UPnP Search Identifiers
Format Example
all upnp:all upnp:all
Unique Device upnp:UDN:namespace: upnp:UDN:IEEEMAC:0C009
Name (UDN) uniqueid 9123456
Device Type upnp:DevType: upnp:DevType:vcr
devicetype
Service Type upnp:SrvType: upnp:SrvType:clock:1
servicetype:ver
SSDP specifies that SSDP announcements must be made for all SSDP searchable values. The SSDP announcements with "all" as the notification header value must carry the Root Device UDN as the USN header value. SSDP announcements for Device Types must carry the UDN of the Root Device concatenated with the Device Type URI as the USN header value. SSDP announcements for a Service Type will carry the UDN of the Root Device concatenated with the Service Type URI value as the USN header value. SSDP announcements of UDNs will repeat the UDN value as the USN header.
UPnP SSDP Announcements
UPnP
Notification
Announcement Type SSDP USN
"all" Root Device UDN
Unique Root Root Device Root Device UDN
Device UDN
Unique non-Root Non-Root Device Non-Root Device UDN
Device UDN
Device Type Device Type Root Device UDN + Device Type
Identifier Identifier
Service Type Service Type Root Device UDN + Service Type
Identifier Identifier
UPnP Bridges 120 (FIG. 2) announce Bridged Devices 122-123 and associated Services using SSDP. The identifiers associated with the Bridged Devices are unique for the device, and they do not duplicate identifiers for Controlled Devices and Services directly available on the Bridge itself. This means that a Bridge that is also a Controlled Device must announce Bridged Devices and local Controlled Devices independently, with appropriate unique identifiers, Description Documents and associated URLs. Description The UPnP Description Document 226 (FIG. 3) provides the information necessary to identify, describe, connect and control a UPnP Controlled Device 106-107 or Bridge 120 from a User Control Point 104-105. The Description Document is an XML document. UPnP defines the use of HTTP and XML for the Description Document and wire protocols. UPnP adheres to the schema declaration rules of XML-Data and Y. Goland, "Flexible XML Processing Profile." The top level XML elements are separated into three categories: per Device, per Service and shared. Rehydrator With reference now to FIG. 7, all (UPnP) Controlled Devices 106-107 (FIG. 1) or Bridges 120 (FIG. 2) expose one or more Services 210-217 (FIG. 3) that can be controlled remotely. Controlling such Services involves a message exchange between a User Control Point 104 and the device 106. This message exchange happens according to a specific Service Control Protocol (SCP) 402, which specifies the content and sequence of the messages exchanged. User Control Points 104 are not required to have any prior knowledge of the SCPs 402 required to control the Services on the various devices. Therefore, a Controlled Device or Bridge must be able to describe to a User Control Point the protocols required to control its Services, such that the User Control Point will be able to implement these protocols dynamically. This requires a standard way of declaring Service Control Protocols in a concise and unambiguous fashion. UPnP introduces a technique for declaring Service Control Protocols using a series of XML documents. A Rehydrator 410 is a module that exposes a suitable API to applications and either invokes Commands on a Service or queries the state of that Service, or receives and responds to events. The primary job of the Rehydrator is to map between API calls and the Service Control Protocol sequence that invokes the Command. As part of the Service Definition 406, a Service State Table 230 and Command Set 408 are defined. These things can be combined in a deterministic way defined by UPnP to produce a Service Control Protocol Definition (SCPD) 406, which includes a Service Control Declaration 404 and a Service Control Protocol 402. The SCPD 406 is a representation of the schema of a Service. It is possible to reconstruct the SST, Command Set and SCP from the SCPD. The SCPD is directly embedded into the Description Document 226 of a Controlled Device. When the Description Document is uploaded into the User Control Point 104, the Rehydrator 410 can extract the SCPD from it. At this point, the Rehydrator has enough information to issue Service specific SCPs 402. General Operation of the Rehydrator More generally with reference to FIG. 8, the Rehydrator 410 operates as a universal adapter to provide a programmatic interface to any service-specific protocol of a remote computing device. The Rehydrator 410 simply obtains a data description or declaration of the methods, properties and events of the remote service, as well as a definition of the protocol of network data messages through which the Rehydrator invokes the methods, queries or sets the properties, and receives event notifications. In UPnP, this data description takes the form of the Description Document 226, which contains a Contract 412. The Contract defines network data packets 413 (e.g., XML data), request/response patterns, and protocol (e.g., GENA, HTTP, SSDP) via which the packets are exchanged. This information is sufficient for the Rehydrator to exchange the appropriate network data packets to interact with the Controlled. Device Service, including to invoke commands, query and set properties, and receive and respond to events, without download of any executable code to the User Control Point 104 device and with a zero installation or configuration experience. The Description Document 226 also includes a declaration of the methods, properties and events for the Service. Based on this declaration, the Rehydrator produces a corresponding programmatic interface for use by applications at the User Control Point. The programmatic interface is an application programming interface that can be in the form of an object integration interface of an object-oriented programming model, such as Microsoft COM, CORBA, Java classes, and scripting engine name extensions. In the example illustrated in FIG. 8, the Rehydrator 410 exposes a COM object integration interface ("IClock" interface 414), with methods getTime( ) and setTime( ), for a Controlled Device having a "Clock" Service with GetTime and SetTime commands. The Rehydrator 410 converts calls of an application program 416 to the IClock interface 414 into the network data messages specified in the Contract to invoke the corresponding commands of the Clock Service. The Rehydrator 410 likewise creates suitable further programmatic interfaces for other Services (e.g., Services 210-217 of FIG. 3) based on the Description Document of their respective Controlled Devices. Accordingly, the Rehydrator operates as a universal proxy object with data-driven conversion of programmatic interfaces to network data messages. Further, the Rehydrator produces the programmatic interface at the User Control Point based solely on an XML data description. This operation allows the Rehydrator to produce just-in-time transient interfaces to remote device Services without the complexity of code downloads and installation or configuration. Upon a later release of the interface by the application, the Rehydrator destroys the interface without need to de-install or clean up persistent configuration data in a registry or configuration file of the operating system or object execution run-time. Rehydrator Implementation Summary. With reference to FIG. 9, a preferred implementation 440 of the Rehydrator 410 is as an internal Microsoft Windows component that routes service control requests from the UPnP API to devices. Applications wishing to control a service on a UPnP device obtain a Service object through the UPnP API and use the methods of this object to query the state variables of the service and invoke its actions. Those methods use the Rehydrator API to turn the service control requests into network messages that travel to the UPnP device. In this sense, the Rehydrator performs a mapping between API calls and network protocols. Basic Functionality. The preferred implementation of the Rehydrator is able to translate a service control call to the UPnP API into the appropriate network messages defined by the Service Control Protocol. Asynchronous Event Notification. The preferred implementation of the Rehydrator is able to notify UPnP API clients of any asynchronous events generated by the devices they are controlling. Event notification is done by means of the event interfaces defined below. Error Reporting. For a variety of reasons, state variable queries and action invocations may fail. The preferred implementation of the Rehydrator is able to provide a way to communicate the success or failure status of such operations to the parties initiating them. Rehydrator Implementation Design. As illustrated in FIG. 9, the preferred implementation of the Rehydrator is used in two ways. First, the Device Finder 450 uses it to create Service objects 460. Then, these Service objects use it to carry out service control operations (querying state variables and invoking actions). Creating Service Objects. When the Device Finder 450 creates a Device object, it invokes the Rehydrator 410 to create Service objects 460 for each of the service instances on that device. Each service instance supports a particular Service Control Protocol and the Rehydrator needs a description of this protocol in order to create a properly hydrated Service object. The Service Control Protocol is declared in two separate XML documents: the DCPD and the Contract. The Rehydrator needs the information in both documents. These two documents are passed to the Rehydrator as IXMLDOMDocument interface pointers in the RehydratorCreateServiceObject( ) API call. HRESULT RehydratorCreateServiceObject( IN IXMLDOMDocument *PDCPD, IN IXMLDOMDocument *pContractDocument, OUT IUPnPService **pNewServiceObject); This API returns a pointer to an IUPnPService interface on a newly created Service object. In addition to the creating the Service object, the Rehydrator sets up its internal data structures so that it can properly handle requests to control the service. Specifically, it creates a list of the properties and actions exported by the service. Since all service instances of the same service type export the same properties and the same actions, this information is kept only once for each service type and is indexed by Service Type Identifier. The Rehydrator stores the information that is specific to a particular service instance as private data within the Service object itself. This includes the control URL and information about the control server 232 (such as the HTTP verbs it supports). The Service Type Identifier is the link between the Service object that represents one instance of a service type and the Rehydrator internal data structures that contain information common to all instances of that service type. The Service Type Identifier is stored as a private data member in the Service object. Querying Service Properties. Applications can query the values of service properties by invoking the IUPnPService::GetProperty( ) method on a Service object. Internally, this method makes a call to the RehydratorQueryStateVariable( ) function.
HRESULT
RehydratorQueryStateVariable(
IN LPCTSTR lpcszVerb,
IN LPCTSTR lpcszControlURL,
IN LPCTSTR lpcszSTI,
IN LPCTSTR lpcszVarName,
OUT VARIANT *pValue);
The first two in parameters to this function supply the service instance specific information: the HTTP verb to use and the control URL to which the network messages will be targeted. The third parameter is the Service Type Identifier that will be used to locate the Service Control Protocol information in the Rehydrator's internal data structures. The fourth parameter is the name of the variable that is being queried (the Rehydrator will validate this against is internal list of state variables exported by the service) and the final parameter is the address of a VARIANT structure in which the Rehydrator will place the variable's value. This function will generate an HTTP request to the control server on the device. The body of this request will be an XML fragment containing a XOAP-encoded request for the variable's value. The following is an example of such a request (the exact header and payload format of this message is defined in the service contract): M-POST/clockService HTTP/1.1 Host: spather-xeon:8586 Content-Type: text/xml Man: "http://www.microsoft.com/protocols/ext/XOAP"; ns=01 01-MethodName: queryStateVariable 01-MessageType: Call Accept-Language: en-gb, en;q=0.8 Referer: http://myhouse/VCR1Presentation Content-Length: 84 User-Agent: Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0) Connection: Keep-Alive <queryStateVariable> <variableName>currentTime</variableName> </queryStateVariable> The control server will respond to this message with another XML fragment: the XOAP-encoded method response. The following is an example of such a response: HTTP/1.1 200 OK Connection: Close Cache-Control: private Date: Mon October 11 12:13:38 PDT 1999 Expires: Mon October 11 12:13:38 PDT 1999 Content-Type: text/xml Content-Length: 62 Man: "http://www.microsoft.com/protocols/ext/XOAP"; ns=01 01-MessageType: CallResponse <queryStateVariableResponse> <_return>12:13:28</_return> </queryStateVariableResponse> The rehydrator will extract the return value from this XML fragment, place it in the VARIANT structure whose address was passed as the last parameter to RehydratorGetServiceProperty( ) and then return. Invoking Service Actions. The process of invoking a service action is very similar to querying a state variable. An application calls IUPnPService::InvokeAction( ) on a Service object, passing it the name of an action to invoke, and an array of arguments to the action. Internally, IUPnPService::InvokeAction( ) calls RehydratorInovkeServiceAction( ), declared as shown below.
HRESULT
RehydratorInvokeServiceAction(
IN LPCTSTR lpcszVerb,
IN LPCTSTR lpcszControlURL,
IN LPCTSTR lpcszSTI,
IN LPCTSTR lpcszActionName,
IN SAFEARRAY saActionArgs,
OUT LONG *pStatus);
As was the case for querying state variables, the service instance specific information is passed in the first two parameters, followed by the Service Type Identifier in the third. The action name and an array of arguments are passed as the next two parameters, and the final parameter is the address of a variable in which to store the status of the operation. RehydratorInovkeServiceAction( ) will send an HTTP request to the control server identified by the second parameter. As before, the body of this message will be an XML fragment containing a XOAP-encoded method call. An example HTTP request to invoke an action is shown below. M-POST/clockService HTTP/1.1 Host: spather-xeon:8586 Content-Type: text/xml Man: "http://www.microsoft.com/protocols/ext/XOAP"; ns=01 01-MethodName: invokeAction 01-MessageType: Call Accept-Language: en-gb, en;q=0.8 Referer: http://myhouse/VCR1Presentation Content-Length: 119 User-Agent: Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0) Connection: Keep-Alive <SerializedStream main="invokeAction"> <invokeAction id="invokeAction"> <actionName>setCurrentTime</actionName> <actionArg>15:41:29</actionArg> </invokeAction> </SerializedStream> The encoding of the body of this message is again specified in the service contract. The Rehydrator will wait for the HTTP response to this request, which would look something like the example below. HTTP/1.1200 OK Connection: Close Cache-Control: private Date: Mon October 11 15:22:38 PDT 1999 Expires: Mon Oct 11 15:22:38 PDT 1999 Content-Type: text/xml Content-Length: 50 Man: "http://www.microsoft.com/protocols/ext/XOAP"; ns=01 01-MessageType: CallResponse <invokeActionResponse> <_return>0</_return> </invokeActionResponse> After receiving a response such as this, the Rehydrator will extract the return value, place it in the out parameter it was passed, and then return. FIGS. 28 through 40 are program listings defining various interfaces used in the preferred implementation of the Rehydrator, including an IUPNPDevice Interface, an IUPNPPropertyBag Interface, an IUPNPService Interface, an IUPNPDevices Interface, and an IUPNPServices Interface. Description Document With reference to FIG. 13, User Control Points 104 can retrieve a Description Document 226 by issuing an HTTP GET on a Description URL. This URL is returned in the location header of either an SSDP announcement or an SSDP query response. The HTTP GET must include an accept-language header that is used to request the preferred language of the response. If the requested language is not supported, a Description Document in the default language supported by the Controlled Device or Bridge may be returned. An HTTP GET is used to retrieve sub elements of a Description Document that are expressed as URLs. URL Handling URLs embedded in Description Documents 226 take one of 3 forms: a fully qualified URL or a relative URL. Fully qualified URLs take the form: http://devicename/pathname The devicename part of the URL is a Hostname or IP address and the pathname is a filesystem path or equivalent. A fully qualified URL is used "as is" to establish an HTTP connection to a device. A relative URL does not contain the ":" character and is of the form: pathname /pathname Relative URLS are a compact representation of the location of a resource relative to an absolute base URL. All relative URLs in a Description Document are appended to the value of the Description Document element <URLbase> to form fully qualified URLs. Binary Data Some elements of a Description Document are binary. XML does not directly support the embedding of binary data. In order to include binary data directly in a Description Document, one must convert the data to text using the Base 64 encoding scheme. This tends to increase the size of the data by 25% on the average. Much of this overhead can be eliminated if the binary data is passed by reference instead of by value. To reference binary data, a URL to the data is provided in a Description Document. The binary data can be retrieved by doing a HTTP GET with that URL. As an example, consider the <image> element in the following Description Document: <iconList> <icon> <size>16</size> <imageType>PNG</imageType> <color>1</color> <depth>8</depth> <image> "http://device.local/iconpath/icon.png"/> </icon> </iconList> The icon would be retrieved with an HTTP GET of the following format: GET iconpath/icon.png HTTP 1.1 Host: device.local The HTTP response would look like: HTTP/1.1 200 OK Content-Type: image/png Content-length: ### <binary color icon data in the PNG format> Description Document Layout The basic layout of the Description Document 226 is shown in FIG. 14. The following table lists Description Document elements that are sub-elements to the root element.
Root The XML root element of a UPnP Description Document.
specVersion- The major version of the UPnP Architectural Reference
Major that this Description Document was created against. This
value must be 1.
specVersion- The minor version of the UPnP Architectural Reference that
Major this Description Document was created against. This value
must be 0.
URLBase An optional element used to construct fully qualified URLs.
Relative URLS are appended to the value of <URLBase> to
create fully qualified URLs. If this element is present, it
must agree with the HTTP Base header.
manufacturer A required element that contains a textual manufacturer
name.
manufacturer An optional element containing a URL that points to the
URL Web page of the manufacturer.
modelName A required element containing a textual product name.
model- A required element containing a textual product description.
Description
model- An optional element containing a textual product model
Number number.
modelURL An optional element containing a URL that points to the
Web page of the product.
UPC An optional element containing the product Universal
Product Code (UPC).
serial- An optional element containing a textual item serial
Number number.
The Description Document elements listed in the following table are associated with devices.
rootDevice A required sub element of the root. This element is a
container for one or more service elements and the elements
that describe the rootDevice.
device An optional sub element of the root or another device
element. This element contains the same kinds of elements
as a rootDevice element.
UDN A required sub element of every rootDevice or device
element containing the Unique Device Name.
friendly- A required sub element of every rootDevice or device
Name element containing a textual friendly name. This element
can be updated remotely.
deviceType A required sub element of every rootDevice or device
element containing a standardized Device Type Identifier.
presentation An optional sub element of a rootDevice or device element
URL containing a Presentation URL.
iconList A required sub element of every rootDevice or device
element. This element is a container for one or more icon
elements. UPnP requires a base set of six icons that must
exist in the iconList. All devices must support PNG icon
image formals of three sizes, 16 by 16, 32 by 32 and 48 by
48 pixels in both color and black and white at 8 bit depth.
Additional formats and sizes, including JPEG, GIF, BMP,
ICON and VML, may be supported by adding them to the
list.
icon A required sub element of every iconList element. This
element is a container for the elements that define an icon.
size A required sub element of every icon element. There must
be icon elements with associated size elements with the
values 16, 32 and 48. Other icons may specify other sizes.
color A required sub element of every icon element with value 0
or 1. Each icon of size 16, 32 or 48 must exist in color and
black and white.
depth A required sub element of every icon element. All required
icons must exist with a value of 8.
imageType A required sub element of every icon element that identifies
the format of the binary icon: png, jpeg, vml, gif, bmp, or
ico.
image A required sub element of every icon element that
references a binary icon.
The following elements of the Description Document are associated with Services.
service An optional sub element of the rootDevice or another
device element. This element is a container for
the Service Definition.
serviceType A required sub element of every service element
containing a standardized Service Type Identifier.
controlURL A required sub element of every service containing a
Control URL.
eventSubURL A required sub element of every service containing an
Event Subscription URL.
SCPD A required sub element of every service. The SCPD is a
container for the standardized Service Control Protocol
Declaration associated the Service.
FIG. 15 shows an exemplary icon list in a Description Document 226. Service Control Protocol and SCP Declaration As part of the Service Definition 406 shown in FIG. 7, a Service State Table 230 and Command Set 408 are defined. The SCPD 406 is a representation of the schema of a Service. It is possible to reconstruct the SST 230, Command Set 408 and SCP 402 from the SCPD deterministically. The declaration of such a protocol must specify the list of Variables that can be queried, the set of Commands that can be invoked, as well as the wire protocol (the content and sequence of network. messages) required to carry out these operations. SCPD is specified in two XML documents. The first or Service Control Definition document 404, written in a language called Service Control Protocol Declaration Language (SCPDL), declares the list of state Variables and Commands associated with the Service Type to be controlled by the protocol. The second or Service Control Protocol document 402 declares the wire protocol that will be used to query the values of the state variables and invoke the actions associated with the service. Declaring the Service State Table and Command Set A SCPDL document 404 is used to specify the list of state Variables that a SCP can query and the set of Commands that it can invoke. SCPDL is an XML schema, a set of rules for writing XML documents (Service Control Protocol Declarations). FIG. 16 shows an exemplary SCPDL document. This XML document consists of a root <scpd> element containing two sub-elements, <serviceStateTable> and <actionList>. Within the <serviceStateTable> element is a <stateVariable> element for each state variable associated with the service. The Service in this example is a TV tuner with has only one state variable, currentChannel. The elements within the <stateVariable> element specify the name, data type and allowed values for the state variable. Had the Service more state variables, they would be represented by additional <state Variable> elements within the <deviceState Table> element. The <actionList> element contains an <action> element for every action associated with the Service. The elements within an <action> element specify the name of the action and any arguments the action may take. In this case, the service supports two actions that do not take arguments, ChannelUp and ChannelDown, and another, SetChannel, that takes a new channel number as an argument. The <argument> element and the elements nested within it define the argument. The <relatedStateVariable> element within <argument> specifies the name of one of the state variables to which the argument is related. In the UPnP Device Model, all arguments to actions must correspond directly to some state variable. FIGS. 17 and 18 show an XML schema for the SCPDL. Basic UPnP Eventing Architecture With reference to FIG. 19, the UPnP architecture 200 (FIG. 3) requires that clients of the UPnP API be enabled to receive notifications reliably from UPnP services 210-217 as their states change. Since state changes are relatively common, the eventing subsystem's efficiency and performance is a major consideration in this design. FIG. 19 and the following discussion describe the Basic UPnP Eventing Architecture 600, which encompasses both the controlled device (CD) 106 and user control point (UCP) 104 sides of the eventing service. It also includes the support APIs for both a low-level service interaction and a higher level COM-based wrapper of those APIs. The latter enables automation controllers like Visual Basic and JScript 602 to receive event notifications. What is an event? Property change events are defined as any change in the value of a row of the Device State Table (DST) 230 (FIG. 3) for a service 210-217. This change will be reflected as a property change notification. For example, if a "VCR" device has a "VCR Transport" service, one row in that service's DST may be TapeState and the value could be TapePresent. If the tape is ejected, the new value would be TapeAbsent. This state change would be reflected as a notification sent to all subscribers. What is a notification? A UPnP event notification is an XML message sent over HTTP/TCP to each and every subscriber to a particular UPnP service. The content of the XML is defined below. The important contents of this message are the unique identifier for the subscription, the property name, new value, and property type. Notification Processing In UPnP, the listener to Notifications is the SSDP service itself. SSDP already listens on another multicast address for "alive" and "byebye" messages sent by UPnP devices. The same listener will listen on a TCP port for notifications sent. All subscriptions sent from that UCP contain the same callback URL and so all notifications will be directed to that URL. When a notification arrives the SSDP service will examine the NT header of the message and determine if it is an event notification. If so, the message is parsed further to determine if it should be forwarded on to subscribers (which must exist). GENA defines the format of the HTTP message, what headers can be used, and what they can be used for. GENA GENA is the protocol of communication that, in a preferred embodiment, UPnP devices use to send event notifications. Therefore, UPnP devices that wish to notify UCPs of state changes are recommended to use GENA. Notification subscribers will never be required to interact with a UPnP device directly and so they are not required to use GENA. The eventing API will encapsulate this complexity. Other appropriate event transport protocols may be used, such as publish/subscribe systems. Receiving Notifications Applications written in C (C Application 604) will be able to utilize the SSDP C API 610 to receive callbacks when notifications are processed by the SSDP service. This is analogous to SSDP clients registering for notifications that services have become available. When a UCP registers for a notification, it passes as a parameter the URL of the service for which it is interested in receiving notifications. This URL is obtained from the description document for that service. (When a service is registered on a UPnP device, it uses this same URL to listen for subscription requests). When a notification message is received by the SSDP service listener, the SID header is checked against the list of subscribers it maintains. If a subscriber is found, the callback function for that subscriber is invoked, with one of the parameters being the contents of the notification message. The notification client that implements the callback function can process this message in any appropriate way. Notifications in the UPnP API The UPnP API 410 is a consumer of the basic C interface provided by the SSDP C API 610 component. In order to integrate seamlessly, the registration of notifications is handled by the Service Object 612 inside the UPnP Object Model. Service objects will register for notifications when they are created. This ensures that the DST is maintained by the UPnP API and is kept up to date. They will implement the callback function required by the registration function. If this callback function is invoked, it will pass on that notification to UCPs. The UCPs can be written in C, C++, VB, or script code, so the mechanism for passing on notifications can be different. Script Support A feature of the illustrated eventing system is that it supports script languages such as VBScript and JavaScript 602. For VBScript, this is made possible by providing a property on the Service object that, when set, contains the IDispatch pointer for a VBScript function or subroutine that will be the event handler. When the Service object's notification callback is invoked, it checks to see if this IDispatch pointer was set, and if so, it calls IDispatch::Inovke on DISPID 0 of that interface to call the VBScript subroutine. An equivalent mechanism is implemented for JScript. Eventing Subsystem Terminology UCP--User control point. Any piece of software that searches for devices and controls them. CD--controlled device. A hardware or software device that announces its availability thru SSDP and allows control by UCPs. Subscriber--A UCP who wishes to be notified of event changes. Notifying Resource (or simply "Resource")--For the purposes of this document, this will always be a service contained within a UPnP CD 106. Event Source--a service that provides events. UPnP services are event sources. All notifying resources are event sources and vice versa. Event--message generated when a change in a resource's state occurs. Property--a single entry in the service's state table whose DefaultValue can change. Properties and events always have a one to one correspondence. Subscribing To Resources Integrating With The UPnP API The UPnP API 410 exposes several interfaces with which a consumer can find and enumerate devices, control services, and get properties on devices and services. To allow the integration of events into this model, we add a new property to the IUPnPService interface called EventHandler. When this property is set, it tells the Service object 612 that its client is interested in receiving notifications for that service. The SSDP API RegisterNotification( ) API is called when the Service object is created so that it can maintain a local copy of the DST for that service. The Service object knows the URL of the service and therefore it can provide this as a parameter to RegisterNotification( ). RegisterNotification( ) is also provided a callback function which is a static member of the Service object class. This function will be invoked for each and every notification sent by that particular UPnP service. The Notification Callback The Service object 612 includes a static member function called EventNotifyCallback( ) which is invoked for each notification sent by the UPnP service. The callback is passed the entire HTTP message contents in a structure which is a parameter to the function. The prototype looks like this: static VOID CUPnPService::EventNotifyCallback(SSDP_CALLBACK_TYP E ssdpType, SSDP--MESSAGE *pssdpMsg, LPVOID pcontext); The:ssdpType parameter should always be SSDP_PROPCHANGE. The pssdpMsg parameter contains the relevant information about the event. The key piece of information is the body of the XML message. The body contains information about what property changed, what its new value is and what type it is, among other information. The pContext parameter will always be the this pointer of the Service object. This allows the code to call a method to fire the event to the UCP. The callback will parse the XML body using the XML DOM services. Property changes are iterated and the local DST is updated to reflect these changes. After this processing is done, an event notification may be fired for each property that was changed to the owner of the subscription if one exists. Depending on what environment the owner is written in (C++ or script, etc . . . ), a different mechanism for firing the event may be employed. A special case for this process is the very first notification received after a subscription is established. This notification contains the entire set of properties and their values and is used to locally sync up the DST. Events will not be fired to clients of the UPnP API in this case. Firing Notifications When the EventNotifyCallback( ) function is called, the local copy of the DST for the service is updated. After this, an event needs to be fired if a subscriber exists. A subscriber exists if the put_EventHandler( ) method was called, either from VBScript, C++ code, or another source. To abstract away this complexity, a new interface called IUPnPEvents is needed. This interface currently has one method called NotifyEvent( ) which takes several parameters. When put_EventHandler( ) function is called, its argument is an IUnknown. This pointer is Querylnterface'd( ) for IDispatch first, and if it succeeds, then IDispatch::Invoke( ) is called with DISPID 0 to invoke the default method. This allows VBScript 602 to be called. If that fails, however,it is Queried for IUPnPEvents, and if that succeeds, the NotifyEvent( ) method is called with the same parameters as for Invoke( ). The handles C++ UCPs effectively. Subscribing with C++ To subscribe to a UPnP service from C++, a UCP instantiates a UPnP service object, issues Querylnterface( ) to it for IUPnPEvents, and calls the IUPnPEvents::SetEventCallback( ) function. This function takes 2 parameters, a callback function pointer and a context pointer. Subscribing With VBScript To subscribe to a UPnP service's events, all that needs to be done by a script 602 is to create a function or subroutine as a handler function and set the pointer of that function to the EventHandler property of the Service object. Now, anytime an event is fired, this VBScript function or subroutine will be called. In VBScript, this is written as the following: Dim UPnPAPI Set UPnPAPI=CreateObject("UPnPAPI.1") Devices=UPnPAPI.FindDevices( . . . ) For each device in Devices For each service In devices.services If service.dcpi="clock.v1" Service.EventHandler= GetRef("clock_PropertyChanged") End if Next service Next device Sub clock_PropertyChanged(prop, value) MsgBox "The time has changed. It is now " & value & "." End Sub In this example, the script enumerates all devices, looking for any device that supports the "Clock" interface. When it finds a device that supports that interface, it enumerates that device's services looking for the one that has the "clock.v1" interface. Once it finds that service, it sets that service's EventHandler property to the VBScript subroutine called "clock_PropertyChanged". This name is arbitrary. Sending and Receiving Notifications GENA Client API GENA clients are actually UPnP services. A GENA client creates a new event source when it is initialized. The GENA client API 620 facilitates this. It also provides a way for GENA clients to send their notification messages. It is also important to note that the HTTP server that lives on the UPnP device is also a client of this API. The GENA client API consists of the following functions: RegisterUpnpEventSource( ) The RegisterUpnpEventSource( ) API gives a GENA client the ability to register itself as an event source. The prototype is as follows: BOOL RegisterUpnpEventSource( LPTSTR szRequestUri, DWORD cProps, UPNP_PROPERTY *rgprops ); Parameters: szRequestUri [in] an arbitrary Request-Uri that SUBSCRIBE requests will be sent to. When a SUBSCRIBE request arrives at the given URI, it is acknowledged and the subscriber is added to the list of notification recipients. Note that this URI should match the URI provided in the description for this service. CProps [in] the number of properties that this event source provides. RgProps [in] Array of UPNP_PROPERTY structures which contain information about each property. The property information is derived from the DST for the event source. Return Value: The function returns a TRUE if successful. If the given URL has already been registered as an event source, the return value is FALSE and GetLastError( ) returns ERROR_ALREADY_EXISTS. Notes: The initial state of the event source needs to be given to the API so that it can effectively maintain the up-to-date state of the event source. DeRegisterUpnpEventSource( ) The DeRegisterUpnpEventSource( ) API gives a GENA client the ability to deregister itself as an event source. The prototype is as follows: VOID DeRegisterUpnpEventSource( LPCTSTR szRequestUri ); Parameters: szRequestUri [in] an arbitrary Request-Uri that SUBSCRIBE requests will be sent to. When a SUBSCRIBE request arrives at the given URI, it is acknowledged and the subscriber is added to the list of notification recipients. Note that this URI should match the URI provided in the description for this service. UPNP PROPERTY typedef struct_UPNP_PROPERTY { LPTSTR szName; LPTSTR szvalue; LPTSTR szType; } UPNP_PROPERTY; Where szname is the name of the property, szValue is the current value of property, and szType is the type of property (string, integer, etc . . . ). SubmitUpnpPropertyEvent( ) The SubmitUpnpPropertyEvent( ) API allows the GENA client to submit a UPnP property change event to be sent to subscribers as a notification. The prototype is as follows: BOOL SubmitUpnpPropertyEvent( LPCTSTR szRequestUri, DWORD dwFlags, DWORD cProps, UPNP_PROPERTY *rgProps ); Parameters: "szRequestUri [in]" identifies the event source to which this event belongs. This is the same Request-Uri passed to RegisterUpnpEventSource( ). "DwFlags [in]" is unused. "CProps [in]" is the number of events that are being submitted. "RgProps [in]" is an array of UPNP_PROPERTY structures which contain information about each event. Return Value: If the function fails, the return value is FALSE. The get extended error information, call the GetLastError( ) function. Notes: When a series of properties is submitted for event notification, the local version of the property state for the given event source is updated with the list of properties passed in. SubmitUpnpPropertyEvent( ) calls SubmitEvent( ) after it has generated an XML body. SubmitEvent( ) The SubmitEvent( ) API allows the GENA client to submit an unstructured event to be sent to subscribers as a notification. The prototype is as follows: BOOL SubmitEvent( LPCTSTR szRequestUri, DWORD dwflags, LPCTSTR szHeaders, LPCTSTR szEventBody ); Parameters: SzRequestUri [in] identifies the event source to which this event belongs. This is the same Request-Uri passed to RegisterUpnpEventSource( ). DwFlags [in] Unused. SzHeaders [in] null-terminated text string containing the headers for the event, each separated by CRLF. SzEventBody [in] null-terminated text string containing the body of the event message Return Value: If the function fails, the return value is FALSE. The get extended error information, call the GetLastError( ) function. Notes: If no subscribers exist, the function does nothing. If one or more subscribers exist, a message is sent to each subscriber. SubmitEvent( ) will always send to all subscribers. UPnP Controlled Device Event Architecture In UPnP, every UPnP service 210-211 that supports property change event notifications is to be a GENA client. Therefore, when the service is initialized, it must register itself as a GENA event source. It will do this with the RegisterUpnpEventSource( ) API. This returns a handle which can be used in subsequent APIs. RegisterUpnpEventSource( ) takes a URL and an array of properties as parameters. Inside the API, an entry in an array of structures is initialized and the index is returned as the handle. The structure contains the source URL as one of the members. A second member of the structure, an array of destination URLs, is left uninitialized. This is filled in each time as subscriber is added for that event source. Another member of the structure is the list of properties that this event source provides. This is effectively a cached copy of the DST for the event source. As events are submitted, the local properties are updated. When SubmitUpnpPropertyEvent( ) is called, each property submitted replaces the corresponding property already maintained by the API. If no subscribers exist, the request to submit an event is ignored. If one or more subscribers exist, their callback URLs are looked up in the list of subscribers for the given event source and a NOTIFY message is constructed and sent to each URL, one at a time, in order of subscription. If an event is submitted and no response is received (or a CD-side error occurs), the CD continues to attempt to send to the UCP. If the subscription timeout expires, then the subscription is removed. If the UCP becomes available again, it will re-subscribe because it will notice the sequence numbers are not contiguous. When an HTTP server 626 receives a SUBSCRIBE message, it passes it along to a function which parses the message for the necessary information. The Request-URI identifies the service that is to be subscribed to. The callback URL is obtained from the "Callback" header. Since the Callback header can contain multiple URLs, it picks the first "http://" URL it finds. It then adds the subscriber to the list of subscribers for this event source. A unique subscription identifier is constructed which it will send back to the subscriber in the HTTP response to the SUBSCRIBE request. If no event source matches the Request-URI from the subscription message, the HTTP server should return "404 Not Found". When a subscription is added, the local copy of the DST is sent as a NOTIFY message. This special NOTIFY message contains sequence number 0 which informs the UCP that this is an initial state population event and not a notification where every event has changed. When a CD receives an UNSUBSCRIBE message, it checks the "SID"header to obtain the subscription identifier. It looks up the subscriber ID in the list of subscribers for that event source and removes the destination URL entry associated with it. GENA Server API GENA servers 630 are generally going to be UPnP UCPs. A GENA server is anything that receives and processes NOTIFY messages to handle notifications from resources and sends SUBSCRIBE and UNSUBSCRIBE messages to receive notifications from resources. These APIs leverage the already existing SSDP APIs. The following are the changes to the APIs: RegisterNotification( ) The RegisterNotification( ) allows a UPnP UCP to request notification when an event occurs for a given UPnP service. The prototype is as follows: HANDLE RegisterNotification( NOTIFY_TYPE nt, //SSDP_ALIVE.vertline.SSDP_PROPCHANGE .vertline.?? LPTSTR szResourceType, //based on NOTIFY_TYPE, unused if //SSDP_PROPCHANGE is used. LPTSTR szEventUrl, ServiceCallbackFunc fnCallback, void *pContext ); Parameters: Nt [in] An enumeration that determines the type of notification requested. The values are: SSDP_ALIVE--a service has become available, and SSDP_PROPCHANGE--a property has changed on the service. SzResourceType [in] A null-terminated string specifying the resource type desired. For SSDP_ALIVE, this is the service type, for SSDP_PROPCHANGE this is unused. SzEventUrl [in] A null-terminated string specifying the URL that a subscription request should be sent to. FnCallback [in] A pointer to a function that will be called each time a notification is received. The function pointer is defined in the SSDP spec. PContext [in] This parameter is included as a parameter when invoking the client-supplied callback function. Return Value: If the function succeeds, the return value is a handle used in a subsequent call to the DeregisterEvent_Notification( ) function. If the function fails, the return value is INVALID_HANDLE_VALUE error code. To get extended error information, call GetLastError. ServiceCallbackFunc typedef enum_SSDP_CALLBACK TYPE { SSDP_FOUND=0, SSDP_ALIVE=1, SSDP_BYEBYE=2, SSDP_DONE=3, SSDP_PROPCHANGE=4, 56 SSDP CALLBACK_TYPE, *PSSDP_CALLBACK_TYPE; UPnP UCP Architecture When a UPnP UCP wishes to subscribe to notifications for a particular UPnP service, it calls the RegisterNotification( ) API. It passes to this API a notification type that identifies the type of notification being requested, a URL to which a subscription should be sent, and a callback function and context for use when the notification is received. RegisterNotification( ) will compose a SUBSCRIBE message, using the data passed in, and send that to the URL specified by the caller. The Callback header of the SUBSCRIBE message will be composed on the fly, as an arbitrary URL for notifications to be sent to for this subscription. This callback URL will likely be a constant since the server API will always know how to handle requests sent to this URL. It will then send the SUBSCRIBE message and await a response. RegisterNotification( ) in the SSDP API does not currently send HTTP requests, but it can be modified to do so. It also needs to await a response which it will also be modified to do so. When the response is received, the Subscription-ID header contains a SID which is associated with the callback function specified by the caller. Immediately after the response is received, the UCP should expect an initial NOTIFY message that contains the complete set of properties maintained by the CD. This becomes the local cached DST on the UCP side. From this point on, all modifications to the table are made via NOTIFY messages. This initial NOTIFY message will have sequence number 0 that indicates it is an initial property set and not an update. The UCP can use this information in any way it sees fit. This ensures the UCP's state table is always in sync with the one on the CD. When a message is received by the HTTP server on the UPnP UCP, it is passed to a function which determines the method name and Request-URI. If this is a NOTIFY message, the headers are parsed and packaged up into a structure. The callback function that was specified to RegisterNotification( ) is called with that structure as one of the parameters. UCPS who implement the callback function can find the headers and body of the NOTIFY message and do additional processing based on the notification type. This all requires that the SSDP HTTP server listen on a TCP socket in addition to the UDP multicast port it already listens to. However, once a NOTIFY message is received, it is processed in the same way regardless of from which connection it originated. Handling Failures The following are subscription/notification failures that can occur and their solutions: Leaked Subscriptions To protect against subscriptions that exist on the controlled device, but no longer on the UCP, we institute the timeout feature of GENA subscriptions. The scenario is this: A UCP subscribes to a CD, then the UCP reboots. Meanwhile, the CD is still trying to send notifications to that UCP. If the UCP never comes back, the subscription would be leaked because the UCP never told the CD that it was going away. So to correct this, each subscription request includes an arbitrary timeout value which indicates to the CD that the UCP will be re-subscribing every n seconds indicated in the timeout header of the subscription request. If the timeout expires on the CD, the subscription is removed. The UCP is required to re-subscribe before the timeout period has elapsed. If it fails to do so, the subscription will be terminated by the CD. Some time before the timeout expires on the UCP, a re-subscribe message should be sent. The re-subscribe message is similar to the subscribe message, but it does not contain an NT or Callback header. If the UCP is unable to re-subscribe within the timeout period | ||||||
