1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>GUPnP Reference Manual: Writing a UPnP Service</title>
6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
7 <link rel="home" href="index.html" title="GUPnP Reference Manual">
8 <link rel="up" href="tutorial.html" title="Part I. Tutorial">
9 <link rel="prev" href="client-tutorial.html" title="Writing a UPnP Client">
10 <link rel="next" href="api.html" title="Part II. Reference">
11 <meta name="generator" content="GTK-Doc V1.20 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle">
16 <td width="100%" align="left" class="shortcuts"></td>
17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
18 <td><a accesskey="u" href="tutorial.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
19 <td><a accesskey="p" href="client-tutorial.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
20 <td><a accesskey="n" href="api.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
23 <div class="titlepage"><div><div><h2 class="title">
24 <a name="server-tutorial"></a>Writing a UPnP Service</h2></div></div></div>
25 <div class="simplesect">
26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
27 <a name="id-1.2.4.2"></a>Introduction</h2></div></div></div>
29 This chapter explains how to implement a UPnP service using GUPnP. For
30 this example we will create a virtual UPnP-enabled light bulb.
33 Before any code can be written, the device and services that it implement
34 need to be described in XML. Although this can be frustrating, if you are
35 implementing a standardised service (see <a class="ulink" href="http://upnp.org/sdcps-and-certification/standards/sdcps/" target="_top">http://upnp.org/sdcps-and-certification/standards/sdcps/</a> for the
36 list of standard devices and services) then the service description is
37 already written for you and the device description is trivial. UPnP has
38 standardised <a class="ulink" href="http://upnp.org/specs/ha/lighting/" target="_top">Lighting
39 Controls</a>, so we'll be using the device and service types defined
43 <div class="simplesect">
44 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
45 <a name="id-1.2.4.3"></a>Defining the Device</h2></div></div></div>
47 The first step is to write the <em class="firstterm">device description</em>
48 file. This is a short XML document which describes the device and what
49 services it provides (for more details see the <a class="ulink" href="http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.0.pdf" target="_top">UPnP
50 Device Architecture</a> specification, section 2.1). We'll be using
51 the <code class="literal">BinaryLight1</code> device type, but if none of the
52 existing device types are suitable a custom device type can be created.
54 <pre class="programlisting"><?xml version="1.0" encoding="utf-8"?>
55 <root xmlns="urn:schemas-upnp-org:device-1-0">
57 <major>1</major>
58 <minor>0</minor>
62 <deviceType>urn:schemas-upnp-org:device:BinaryLight:1</deviceType>
63 <friendlyName>Kitchen Lights</friendlyName>
64 <manufacturer>OpenedHand</manufacturer>
65 <modelName>Virtual Light</modelName>
66 <UDN>uuid:cc93d8e6-6b8b-4f60-87ca-228c36b5b0e8</UDN>
70 <serviceType>urn:schemas-upnp-org:service:SwitchPower:1</serviceType>
71 <serviceId>urn:upnp-org:serviceId:SwitchPower:1</serviceId>
72 <SCPDURL>/SwitchPower1.xml</SCPDURL>
73 <controlURL>/SwitchPower/Control</controlURL>
74 <eventSubURL>/SwitchPower/Event</eventSubURL>
81 The <code class="sgmltag-element">specVersion</code> tag defines what version of the UPnP
82 Device Architecture the document conforms to. At the time of writing the
86 Next there is the root <code class="sgmltag-element">device</code> tag. This contains
87 metadata about the device, lists the services it provides and any
88 sub-devices present (there are none in this example). The
89 <code class="sgmltag-element">deviceType</code> tag specifies the type of the device.
92 Next we have <code class="sgmltag-element">friendlyName</code>,
93 <code class="sgmltag-element">manufacturer</code> and <code class="sgmltag-element">modelName</code>. The
94 friendly name is a human-readable name for the device, the manufacturer
95 and model name are self-explanatory.
98 Next there is the UDN, or <em class="firstterm">Unique Device Name</em>. This
99 is an identifier which is unique for each device but persistent for each
100 particular device. Although it has to start with <code class="literal">uuid:</code>
101 note that it doesn't have to be an UUID. There are several alternatives
102 here: for example it could be computed at built-time if the software will
103 only be used on a single machine, or it could be calculated using the
104 device's serial number or MAC address.
107 Finally we have the <code class="sgmltag-element">serviceList</code> which describes the
108 services this device provides. Each service has a service type (again
109 there are types defined for standardised services or you can create your
110 own), service identifier, and three URLs. As a service type we're using
111 the standard <code class="literal">SwitchPower1</code> service. The
112 <code class="sgmltag-element">SCPDURL</code> field specifies where the <em class="firstterm">Service
113 Control Protocol Document</em> can be found, this describes the
114 service in more detail and will be covered next. Finally there are the
115 control and event URLs, which need to be unique on the device and will be
119 <div class="simplesect">
120 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
121 <a name="id-1.2.4.4"></a>Defining Services</h2></div></div></div>
123 Because we are using a standard service we can use the service description
124 from the specification. This is the <code class="literal">SwitchPower1</code>
125 service description file:
127 <pre class="programlisting"><?xml version="1.0" encoding="utf-8"?>
128 <scpd xmlns="urn:schemas-upnp-org:service-1-0">
130 <major>1</major>
131 <minor>0</minor>
135 <name>SetTarget</name>
138 <name>NewTargetValue</name>
139 <relatedStateVariable>Target</relatedStateVariable>
140 <direction>in</direction>
142 </argumentList>
145 <name>GetTarget</name>
148 <name>RetTargetValue</name>
149 <relatedStateVariable>Target</relatedStateVariable>
150 <direction>out</direction>
152 </argumentList>
155 <name>GetStatus</name>
158 <name>ResultStatus</name>
159 <relatedStateVariable>Status</relatedStateVariable>
160 <direction>out</direction>
162 </argumentList>
165 <serviceStateTable>
166 <stateVariable sendEvents="no">
167 <name>Target</name>
168 <dataType>boolean</dataType>
169 <defaultValue>0</defaultValue>
170 </stateVariable>
171 <stateVariable sendEvents="yes">
172 <name>Status</name>
173 <dataType>boolean</dataType>
174 <defaultValue>0</defaultValue>
175 </stateVariable>
176 </serviceStateTable>
180 Again, the <code class="sgmltag-element">specVersion</code> tag defines the UPnP version
181 that is being used. The rest of the document consists of an
182 <code class="sgmltag-element">actionList</code> defining the <a class="glossterm" href="glossary.html#action"><em class="glossterm">actions</em></a> available and a
183 <code class="sgmltag-element">serviceStateTable</code> defining the <a class="glossterm" href="glossary.html#state-variable"><em class="glossterm">state variables</em></a>.
186 Every <code class="sgmltag-element">action</code> has a <code class="sgmltag-element">name</code> and a list
187 of <code class="sgmltag-element">argument</code>s. Arguments also have a name, a direction
188 (<code class="literal">in</code> or <code class="literal">out</code> for input or output
189 arguments) and a related state variable. The state variable is used to
190 determine the type of the argument, and as such is a required element.
191 This can lead to the creation of otherwise unused state variables to
192 define the type for an argument (the <code class="literal">WANIPConnection</code>
193 service is a good example of this), thanks to the legacy behind UPnP.
196 <code class="sgmltag-element">stateVariable</code>s need to specify their
197 <code class="sgmltag-element">name</code> and <code class="sgmltag-element">dataType</code>. State variables
198 by default send notifications when they change, to specify that a variable
199 doesn't do this set the <code class="sgmltag-element">sendEvents</code> attribute to
200 <code class="literal">no</code>. Finally there are optional
201 <code class="sgmltag-element">defaultValue</code>, <code class="sgmltag-element">allowedValueList</code> and
202 <code class="sgmltag-element">allowedValueRange</code> elements which specify what the
203 default and valid values for the variable.
206 For the full specification of the service definition file, including a
207 complete list of valid <code class="sgmltag-element">dataType</code>s, see section 2.3 of
208 the <a class="ulink" href="http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.0.pdf" target="_top">UPnP
209 Device Architecture</a>.
212 <div class="simplesect">
213 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
214 <a name="id-1.2.4.5"></a>Implementing the Device</h2></div></div></div>
216 Before starting to implement the device, some boilerplate code is needed
217 to initialise GUPnP. GLib types and threading needs to be initialised,
218 and then a GUPnP context can be created using <a class="link" href="GUPnPContext.html#gupnp-context-new" title="gupnp_context_new ()"><code class="function">gupnp_context_new()</code></a>.
220 <pre class="programlisting">GUPnPContext *context;
221 /* Initialize required subsystems */
222 #if !GLIB_CHECK_VERSION(2,35,0)
225 /* Create the GUPnP context with default host and port */
226 context = gupnp_context_new (NULL, NULL, 0, NULL);</pre>
228 Next the root device can be created. The name of the device description
229 file can be passed as an absolute file path or a relative path to the
230 second parameter of <a class="link" href="GUPnPRootDevice.html#gupnp-root-device-new" title="gupnp_root_device_new ()"><code class="function">gupnp_root_device_new()</code></a>. The service description
231 files referenced in the device description are expected to be at the path
234 <pre class="programlisting">GUPnPRootDevice *dev;
235 /* Create the root device object */
236 dev = gupnp_root_device_new (context, "BinaryLight1.xml", ".");
237 /* Activate the root device, so that it announces itself */
238 gupnp_root_device_set_available (dev, TRUE);</pre>
240 GUPnP scans the device description and any service description files it
241 refers to, so if the main loop was entered now the device and service
242 would be available on the network, albeit with no functionality. The
243 remaining task is to implement the services.
246 <div class="simplesect">
247 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
248 <a name="id-1.2.4.6"></a>Implementing a Service</h2></div></div></div>
250 To implement a service we first fetch the <a class="link" href="GUPnPService.html" title="GUPnPService"><span class="type">GUPnPService</span></a> from the root
251 device using <a class="link" href="GUPnPDeviceInfo.html#gupnp-device-info-get-service" title="gupnp_device_info_get_service ()"><code class="function">gupnp_device_info_get_service()</code></a> (<a class="link" href="GUPnPRootDevice.html" title="GUPnPRootDevice"><span class="type">GUPnPRootDevice</span></a> is a
252 subclass of <a class="link" href="GUPnPDevice.html" title="GUPnPDevice"><span class="type">GUPnPDevice</span></a>, which implements <a class="link" href="GUPnPDeviceInfo.html" title="GUPnPDeviceInfo"><span class="type">GUPnPDeviceInfo</span></a>). This
253 returns a <a class="link" href="GUPnPServiceInfo.html" title="GUPnPServiceInfo"><span class="type">GUPnPServiceInfo</span></a> which again is an interface, implemented by
254 <a class="link" href="GUPnPService.html" title="GUPnPService"><span class="type">GUPnPService</span></a> (on the server) and <a class="link" href="GUPnPServiceProxy.html" title="GUPnPServiceProxy"><span class="type">GUPnPServiceProxy</span></a> (on the client).
256 <pre class="programlisting">GUPnPServiceInfo *service;
257 service = gupnp_device_info_get_service
258 (GUPNP_DEVICE_INFO (dev), "urn:schemas-upnp-org:service:SwitchPower:1");</pre>
260 <a class="link" href="GUPnPService.html" title="GUPnPService"><span class="type">GUPnPService</span></a> handles interacting with the network itself, leaving the
261 implementation of the service itself to signal handlers that we need to
262 connect. There are two signals: <a class="link" href="GUPnPService.html#GUPnPService-action-invoked" title="The “action-invoked” signal"><span class="type">“action-invoked”</span></a> and
263 <a class="link" href="GUPnPService.html#GUPnPService-query-variable" title="The “query-variable” signal"><span class="type">“query-variable”</span></a>. <a class="link" href="GUPnPService.html#GUPnPService-action-invoked" title="The “action-invoked” signal"><span class="type">“action-invoked”</span></a> is emitted
264 when a client invokes an action: the handler is passed a
265 <a class="link" href="GUPnPService.html#GUPnPServiceAction"><span class="type">GUPnPServiceAction</span></a> object that identifies which action was invoked, and
266 is used to return values using <a class="link" href="GUPnPService.html#gupnp-service-action-set" title="gupnp_service_action_set ()"><code class="function">gupnp_service_action_set()</code></a>.
267 <a class="link" href="GUPnPService.html#GUPnPService-query-variable" title="The “query-variable” signal"><span class="type">“query-variable”</span></a> is emitted for evented variables when a
268 control point subscribes to the service (to announce the initial value),
269 or whenever a client queries the value of a state variable (note that this
270 is now deprecated behaviour for UPnP control points): the handler is
271 passed the variable name and a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> which should be set to the current
272 value of the variable.
275 Handlers should be targetted at specific actions or variables by using
276 the <em class="firstterm">signal detail</em> when connecting. For example,
277 this causes <code class="function">on_get_status_action</code> to be called when
278 the <code class="function">GetStatus</code> action is invoked:
280 <pre class="programlisting">static void on_get_status_action (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data);
282 g_signal_connect (service, "action-invoked::GetStatus", G_CALLBACK (on_get_status_action), NULL);</pre>
284 The implementation of action handlers is quite simple. The handler is
285 passed a <a class="link" href="GUPnPService.html#GUPnPServiceAction"><span class="type">GUPnPServiceAction</span></a> object which represents the in-progress
286 action. If required it can be queried using
287 <a class="link" href="GUPnPService.html#gupnp-service-action-get-name" title="gupnp_service_action_get_name ()"><code class="function">gupnp_service_action_get_name()</code></a> to identify the action (this isn't
288 required if detailed signals were connected). Any
289 <em class="firstterm">in</em> arguments can be retrieving using
290 <a class="link" href="GUPnPService.html#gupnp-service-action-get" title="gupnp_service_action_get ()"><code class="function">gupnp_service_action_get()</code></a>, and then return values can be set using
291 <a class="link" href="GUPnPService.html#gupnp-service-action-set" title="gupnp_service_action_set ()"><code class="function">gupnp_service_action_set()</code></a>. Once the action has been performed, either
292 <a class="link" href="GUPnPService.html#gupnp-service-action-return" title="gupnp_service_action_return ()"><code class="function">gupnp_service_action_return()</code></a> or <a class="link" href="GUPnPService.html#gupnp-service-action-return-error" title="gupnp_service_action_return_error ()"><code class="function">gupnp_service_action_return_error()</code></a>
293 should be called to either return successfully or return an error code.
294 If any evented state variables were modified during the action then a
295 notification should be emitted using <a class="link" href="GUPnPService.html#gupnp-service-notify" title="gupnp_service_notify ()"><code class="function">gupnp_service_notify()</code></a>. This is an
296 example implementation of <code class="function">GetStatus</code> and
297 <code class="function">SetTarget</code>:
299 <pre class="programlisting">static gboolean status;
302 get_status_cb (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data)
304 gupnp_service_action_set (action,
305 "ResultStatus", G_TYPE_BOOLEAN, status,
307 gupnp_service_action_return (action);
311 set_target_cb (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data)
313 gupnp_service_action_get (action,
314 "NewTargetValue", G_TYPE_BOOLEAN, &status,
316 gupnp_service_action_return (action);
317 gupnp_service_notify (service, "Status", G_TYPE_STRING, status, NULL);
320 g_signal_connect (service, "action-invoked::GetStatus", G_CALLBACK (get_status_cb), NULL);
321 g_signal_connect (service, "action-invoked::SetTarget", G_CALLBACK (set_target_cb), NULL);</pre>
323 State variable query handlers are called with the name of the variable and
324 a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a>. This value should be initialized with the relevant type and
325 then set to the current value. Again signal detail can be used to connect
326 handlers to specific state variable callbacks.
328 <pre class="programlisting">static gboolean status;
331 query_status_cb (GUPnPService *service, char *variable, GValue *value, gpointer user_data)
333 g_value_init (value, G_TYPE_BOOLEAN);
334 g_value_set_boolean (value, status);
337 g_signal_connect (service, "query-variable::Status", G_CALLBACK (query_status_cb), NULL);</pre>
339 The service is now fully implemented. To complete it, enter a GLib main
340 loop and wait for a client to connect. The complete source code for this
341 example is available as <code class="filename">examples/light-server.c</code> in
345 For services which have many actions and variables there is a convenience
346 method <a class="link" href="GUPnPService.html#gupnp-service-signals-autoconnect" title="gupnp_service_signals_autoconnect ()"><code class="function">gupnp_service_signals_autoconnect()</code></a> which will automatically
347 connect specially named handlers to signals. See the documentation for
348 full details on how it works.
351 <div class="simplesect">
352 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
353 <a name="id-1.2.4.7"></a>Generating Service-specific Wrappers</h2></div></div></div>
355 Using service-specific wrappers can simplify the implementation of a service.
356 Wrappers can be generated with <a class="xref" href="gupnp-binding-tool.html" title="gupnp-binding-tool"><span class="refentrytitle">gupnp-binding-tool</span>(1)</a>
357 using the option <code class="literal">--mode server</code>.
360 In the following examples the wrapper has been created with
361 <code class="literal">--mode server --prefix switch</code>. Please note that the callback handlers
362 (<code class="literal">get_status_cb</code> and <code class="literal">set_target_cb</code>) are not automatically
363 generated by <a class="xref" href="gupnp-binding-tool.html" title="gupnp-binding-tool"><span class="refentrytitle">gupnp-binding-tool</span>(1)</a> for you.
365 <pre class="programlisting">static gboolean status;
368 get_status_cb (GUPnPService *service,
369 GUPnPServiceAction *action,
372 switch_get_status_action_set (action, status);
374 gupnp_service_action_return (action);
378 set_target_cb (GUPnPService *service,
379 GUPnPServiceAction *action,
382 switch_set_target_action_get (action, &status);
383 switch_status_variable_notify (service, status);
385 gupnp_service_action_return (action);
390 switch_get_status_action_connect (service, G_CALLBACK(get_status_cb), NULL);
391 switch_set_target_action_connect (service, G_CALLBACK(set_target_cb), NULL);</pre>
393 Note how many possible problem situations that were run-time errors are
394 actually compile-time errors when wrappers are used: Action names,
395 argument names and argument types are easier to get correct (and available
396 in editor autocompletion).
399 State variable query handlers are implemented in a similar manner, but
400 they are even simpler as the return value of the handler is the state
403 <pre class="programlisting">static gboolean
404 query_status_cb (GUPnPService *service,
412 switch_status_query_connect (service, query_status_cb, NULL);</pre>
417 Generated by GTK-Doc V1.20</div>