Intel® SDK for UPnP™ Devices
Programming Guide
Intel® SDK for UPnP™ Devices Version 1.2.1
November 2002
ii Intel® SDK for UPnP™ Devices Version 1.2.1
Notice
Disclaimer
INTEL CORPORATION MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS
MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. INTEL
CORPORATION ASSUMES NO RESPONSIBILITY FOR ANY ERRORS THAT MAY APPEAR
IN THIS DOCUMENT. INTEL CORPORATION MAKES NO COMMITMENT TO UPDATE OR
TO KEEP CURRENT THE INFORMATION CONTAINED IN THIS DOCUMENT.
THIS SPECIFICATION IS COPYRIGHTED BY AND SHALL REMAIN THE PROPERTY OF
INTEL CORPORATION. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR
OTHERWISE TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED HEREIN.
INTEL DISCLAIMS ALL LIABILITY, INCLUDING LIABILITY FOR INFRINGEMENT OF
ANY PROPRIETARY RIGHTS, RELATING TO IMPLEMENTATION OF INFORMATION IN
THIS SPECIFICATION. INTEL DOES NOT WARRANT OR REPRESENT THAT SUCH
IMPLEMENTATIONS WILL NOT INFRINGE SUCH RIGHTS.
NO PART OF THIS DOCUMENT MAY BE COPIED OR REPRODUCED IN ANY FORM OR BY
ANY MEANS WITHOUT PRIOR WRITTEN CONSENT OF INTEL CORPORATION.
INTEL CORPORATION RETAINS THE RIGHT TO MAKE CHANGES TO THESE
SPECIFICATIONS AT ANY TIME, WITHOUT NOTICE.
Legal Notices
Intel UPnP software products are copyrighted by, and shall remain the property of, Intel
Corporation. Use, duplication or disclosure is subject to restrictions stated in Intel's Software
License Agreement, or in the case of software delivered to the government, in accordance with
the software license agreement as defined in FAR 52.227-7013.
Copyright© 2002 Intel Corporation. All rights reserved.
Intel Corporation, 5200 N.E. Elam Young Parkway, Hillsboro, OR 97124-6497
§
Other brands and names are the property of their respective owners.
Intel® SDK for UPnP™ Devices Version 1.2.1 iii
Contents
1 Overview.................................................................................................................................... 1
1.1 UPnP Overview................................................................................................................1
1.1.1 Discovery.............................................................................................................1
1.1.2 Description...........................................................................................................2
1.1.3 Control................................................................................................................2
1.1.4 Eventing ..............................................................................................................2
1.1.5 Presentation .........................................................................................................3
1.1.6 Control Point and Device Interaction .....................................................................3
1.2 SDK Architecture.............................................................................................................5
1.2.1 Device/Control Point Application ..........................................................................5
1.2.2 SDK API.............................................................................................................5
1.2.3 SSDP...................................................................................................................6
1.2.4 Mini Web Server..................................................................................................6
1.2.5 GENA .................................................................................................................6
1.2.6 SOAP..................................................................................................................6
1.2.7 HTTP ..................................................................................................................6
1.2.8 Mini Server..........................................................................................................6
1.2.9 ThreadUtil Library................................................................................................7
1.2.10 XML Parser.........................................................................................................7
1.2.11 BSD Socket Layer................................................................................................7
1.3 Virtual Directories............................................................................................................8
2 Writing a UPnP Device............................................................................................................ 10
2.1 Setup and Initialization ...................................................................................................10
2.1.1 Initializing the SDK............................................................................................10
2.1.2 Setting a Root Directory......................................................................................11
2.1.3 Registering a Root Device...................................................................................11
2.1.4 Device Specific Initialization...............................................................................12
2.1.5 Advertising the Device........................................................................................12
2.2 Handling Requests..........................................................................................................12
2.2.1 Subscription Requests.........................................................................................13
2.2.2 Get Variable Requests.........................................................................................14
2.2.3 Action Requests .................................................................................................16
2.3 Sending Events...............................................................................................................17
2.4 Shutting Down...............................................................................................................18
3 Writing a UPnP Control Point................................................................................................. 19
3.1 Setup and Initialization ...................................................................................................19
3.1.1 SDK Initialization...............................................................................................19
3.1.2 Control Point Application Specific Initia lization...................................................20
3.1.3 Control Point Registration...................................................................................20
3.2 Searching for Something Interesting ................................................................................20
3.3 Retrieving Descriptions...................................................................................................22
3.4 Watching for Events .......................................................................................................23
iv Intel® SDK for UPnP™ Devices Version 1.2.1
3.5 Invoking Actions ............................................................................................................24
3.6 Shutting Down...............................................................................................................26
Intel® SDK for UPnP™ Devices Version 1.2.1 1
1 Overview
UPnP allows automatic discovery and control of services available on the network from other devices without
user intervention. Devices that act as servers can advertise their services to clients. Client systems, known as
control points, can search for specific services on the network. When they find the devices with the desired
services, the control points can retrieve detailed descriptions of the devices and services and interact from that
point on.
This document provides an overview of UPnP and provides examples of how to write a UPnP device and control
point. For a complete description of the Intel® SDK for UPnP Devices API functions, refer to the Intel® SDK for
UPnP™ Devices v1.2 API Reference included with the SDK.
The SDK also includes sample control point and device applications. For details on building and running the
samples, see the README file in the sample directory of the SDK distribution.
1.1 UPnP Overview
This section provides a brief description of UPnP. For more information, refer to the document Universal Plug
and Play Device Architecture, available from the UPnP Forum at http://www.upnp.org/resources/documents.asp.
UPnP includes five basic phases:
1. Discovery. In this first phase, control points search for devices and services. Similarly, devices multicast
announcements of services they offer.
2. Description. Once a control point finds an interesting device or service, it requests from the device a
complete description of the device, its component devices, and services.
3. Control. This phase allows control points to control one or more of the services contained in a device by
enacting changes in the state of the device.
4. Eventing. This phase allows control points to keep in sync with the state of services in which it is
interested. Control points subscribe to the event server for a particular service and receive event
notifications when that service’s state changes.
5. Presentation. The presentation phase allows a device to host a document, written in standard HTML,
which can be a user interface for that device.
The following sections describe each of these phases.
1.1.1 Discovery
In the discovery phase control points find devices and services, and devices announce their presence to control
points using the Simple Service Discovery Protocol (SSDP). SSDP uses a variant of HTTP that operates over
multicast UDP for broadcasts and another variant of HTTP that operates over unicast UDP for replies.
A device may consist of other devices, each with its own services. Devices are identified both by type and by a
unique identifier. Services are identified by their type.
To search for devices or services on the network, control points use the HTTP M-SEARCH command multicast to
the address 239.255.255.250:1900 over UDP. Any device on the network that matches the criteria the control
point is searching for issues a unicast UDP reply that includes the URL to its description document (see section
1.1.2). If a control point receives one or more acceptable replies, it moves into the description phase.
When a control point sends out a search request, it includes the amount of time it is willing to wait in an SSDP
header. Matching devices will wait a random time between zero and the number of seconds the control point
indicated before responding. If the control point does not receive any replies when its search time has expired, it
can assume that there are currently no matching devices on the network.
