📄 server-tutorial.html
字号:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Writing a UPnP Service</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="GUPnP Reference Manual"><link rel="up" href="tutorial.html" title="Part聽I.聽Tutorial"><link rel="prev" href="client-tutorial.html" title="Writing a UPnP Client"><link rel="next" href="api.html" title="Part聽II.聽Reference"><meta name="generator" content="GTK-Doc V1.10 (XML mode)"><link rel="stylesheet" href="style.css" type="text/css"><link rel="part" href="tutorial.html" title="Part聽I.聽Tutorial"><link rel="chapter" href="overview.html" title="Overview"><link rel="chapter" href="client-tutorial.html" title="Writing a UPnP Client"><link rel="chapter" href="server-tutorial.html" title="Writing a UPnP Service"><link rel="part" href="api.html" title="Part聽II.聽Reference"><link rel="chapter" href="api-device-info.html" title="Device Information"><link rel="chapter" href="api-device-control.html" title="Device Control"><link rel="chapter" href="api-device-impl.html" title="Device Implementation"><link rel="chapter" href="api-utility.html" title="Utility Functions"><link rel="chapter" href="api-tools.html" title="Tools"><link rel="part" href="schemas.html" title="Part聽III.聽XML Schemas"><link rel="chapter" href="schemas-device.html" title="Device Description"><link rel="chapter" href="schemas-service.html" title="Service Description"><link rel="glossary" href="glossary.html" title="Glossary"><link rel="index" href="ix01.html" title="Index"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"><td><a accesskey="p" href="client-tutorial.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td><td><a accesskey="u" href="tutorial.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td><td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td><th width="100%" align="center">GUPnP Reference Manual</th><td><a accesskey="n" href="api.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td></tr></table><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="server-tutorial"></a>Writing a UPnP Service</h2></div></div></div><div class="simplesect" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2582304"></a>Introduction</h2></div></div></div><p> This chapter explains how to implement a UPnP service using GUPnP. For this example we will create a virtual UPnP-enabled light bulb. </p><p> Before any code can be written, the device and services that it implement need to be described in XML. Although this can be frustrating, if you are implementing a standardised service (see <a class="ulink" href="http://upnp.org/standardizeddcps/" target="_top">http://upnp.org/standardizeddcps/</a> for the list of standard devices and services) then the service description is already written for you and the device description is trivial. UPnP has standardised <a class="ulink" href="http://upnp.org/standardizeddcps/lighting.asp" target="_top">Lighting Controls</a>, so we'll be using the device and service types defined there. </p></div><div class="simplesect" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2605390"></a>Defining the Device</h2></div></div></div><p> The first step is to write the <em class="firstterm">device description</em> file. This is a short XML document which describes the device and what services it provides (for more details see the <a class="ulink" href="http://upnp.org/specs/arch/UPnP-DeviceArchitecture-v1.0.pdf" target="_top">UPnP Device Architecture</a> specification, section 2.1). We'll be using the <code class="literal">BinaryLight1</code> device type, but if none of the existing device types are suitable a custom device type can be created. </p><pre class="programlisting"><?xml version="1.0" encoding="utf-8"?><root xmlns="urn:schemas-upnp-org:device-1-0"> <specVersion> <major>1</major> <minor>0</minor> </specVersion> <device> <deviceType>urn:schemas-upnp-org:device:BinaryLight:1</deviceType> <friendlyName>Kitchen Lights</friendlyName> <manufacturer>OpenedHand</manufacturer> <modelName>Virtual Light</modelName> <UDN>uuid:cc93d8e6-6b8b-4f60-87ca-228c36b5b0e8</UDN> <serviceList> <service> <serviceType>urn:schemas-upnp-org:service:SwitchPower:1</serviceType> <serviceId>urn:upnp-org:serviceId:SwitchPower:1</serviceId> <SCPDURL>/SwitchPower1.xml</SCPDURL> <controlURL>/SwitchPower/Control</controlURL> <eventSubURL>/SwitchPower/Event</eventSubURL> </service> </serviceList> </device></root></pre><p> The <code class="sgmltag-element">specVersion</code> tag defines what version of the UPnP Device Architecture the document conforms to. At the time of writing the only version is 1.0. </p><p> Next there is the root <code class="sgmltag-element">device</code> tag. This contains metadata about the device, lists the services it provides and any sub-devices present (there are none in this example). The <code class="sgmltag-element">deviceType</code> tag specifies the type of the device. </p><p> Next we have <code class="sgmltag-element">friendlyName</code>, <code class="sgmltag-element">manufacturer</code> and <code class="sgmltag-element">modelName</code>. The friendly name is a human-readable name for the device, the manufacturer and model name are self-explanatory. </p><p> Next there is the UDN, or <em class="firstterm">Unique Device Name</em>. This is an identifier which is unique for each device but persistent for each particular device. Although it has to start with <code class="literal">uuid:</code> note that it doesn't have to be an UUID. There are several alternatives here: for example it could be computed at built-time if the software will only be used on a single machine, or it could be calculated using the device's serial number or MAC address. </p><p> Finally we have the <code class="sgmltag-element">serviceList</code> which describes the services this device provides. Each service has a service type (again there are types defined for standardised services or you can create your own), service identifier, and three URLs. As a service type we're using the standard <code class="literal">SwitchPower1</code> service. The <code class="sgmltag-element">SCPDURL</code> field specifies where the <em class="firstterm">Service Control Protocol Document</em> can be found, this describes the service in more detail and will be covered next. Finally there are the control and event URLs, which need to be unique on the device and will be managed by GUPnP. </p></div><div class="simplesect" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2626610"></a>Defining Services</h2></div></div></div><p> Becase we are using a standard service we can use the service description from the specification. This is the <code class="literal">SwitchPower1</code> service description file: </p><pre class="programlisting"><?xml version="1.0" encoding="utf-8"?><scpd xmlns="urn:schemas-upnp-org:service-1-0"> <specVersion> <major>1</major> <minor>0</minor> </specVersion> <actionList> <action> <name>SetTarget</name> <argumentList> <argument>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -