doc/html/server-tutorial.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Writing a UPnP Service</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.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.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  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="2"><tr valign="middle">
  16 <td><a accesskey="p" href="client-tutorial.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="tutorial.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  18 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  19 <th width="100%" align="center">GUPnP Reference Manual</th>
  20 <td><a accesskey="n" href="api.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="chapter">
  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="idp5609200"></a>Introduction</h2></div></div></div>
  28 <p>
  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.
  31     </p>
  32 <p>
  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
  40       there.
  41     </p>
  42 </div>
  43 <div class="simplesect">
  44 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  45 <a name="idp7391456"></a>Defining the Device</h2></div></div></div>
  46 <p>
  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.
  53     </p>
  54 <pre class="programlisting">&lt;?xml version="1.0" encoding="utf-8"?&gt;
  55 &lt;root xmlns="urn:schemas-upnp-org:device-1-0"&gt;
  56   &lt;specVersion&gt;
  57     &lt;major&gt;1&lt;/major&gt;
  58     &lt;minor&gt;0&lt;/minor&gt;
  59   &lt;/specVersion&gt;
  60
  61   &lt;device&gt;
  62     &lt;deviceType&gt;urn:schemas-upnp-org:device:BinaryLight:1&lt;/deviceType&gt;
  63     &lt;friendlyName&gt;Kitchen Lights&lt;/friendlyName&gt;
  64     &lt;manufacturer&gt;OpenedHand&lt;/manufacturer&gt;
  65     &lt;modelName&gt;Virtual Light&lt;/modelName&gt;
  66     &lt;UDN&gt;uuid:cc93d8e6-6b8b-4f60-87ca-228c36b5b0e8&lt;/UDN&gt;
  67
  68     &lt;serviceList&gt;
  69       &lt;service&gt;
  70         &lt;serviceType&gt;urn:schemas-upnp-org:service:SwitchPower:1&lt;/serviceType&gt;
  71         &lt;serviceId&gt;urn:upnp-org:serviceId:SwitchPower:1&lt;/serviceId&gt;
  72         &lt;SCPDURL&gt;/SwitchPower1.xml&lt;/SCPDURL&gt;
  73         &lt;controlURL&gt;/SwitchPower/Control&lt;/controlURL&gt;
  74         &lt;eventSubURL&gt;/SwitchPower/Event&lt;/eventSubURL&gt;
  75       &lt;/service&gt;
  76     &lt;/serviceList&gt;
  77   &lt;/device&gt;
  78 &lt;/root&gt;
  79 </pre>
  80 <p>
  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
  83       only version is 1.0.
  84     </p>
  85 <p>
  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.
  90     </p>
  91 <p>
  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.
  96     </p>
  97 <p>
  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.
 105     </p>
 106 <p>
 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
 116       managed by GUPnP.
 117     </p>
 118 </div>
 119 <div class="simplesect">
 120 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 121 <a name="idm8096"></a>Defining Services</h2></div></div></div>
 122 <p>
 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:
 126     </p>
 127 <pre class="programlisting">&lt;?xml version="1.0" encoding="utf-8"?&gt;
 128 &lt;scpd xmlns="urn:schemas-upnp-org:service-1-0"&gt;
 129   &lt;specVersion&gt;
 130     &lt;major&gt;1&lt;/major&gt;
 131     &lt;minor&gt;0&lt;/minor&gt;
 132   &lt;/specVersion&gt;
 133   &lt;actionList&gt;
 134     &lt;action&gt;
 135       &lt;name&gt;SetTarget&lt;/name&gt;
 136       &lt;argumentList&gt;
 137         &lt;argument&gt;
 138           &lt;name&gt;NewTargetValue&lt;/name&gt;
 139           &lt;relatedStateVariable&gt;Target&lt;/relatedStateVariable&gt;
 140           &lt;direction&gt;in&lt;/direction&gt;
 141         &lt;/argument&gt;
 142       &lt;/argumentList&gt;
 143     &lt;/action&gt;
 144     &lt;action&gt;
 145       &lt;name&gt;GetTarget&lt;/name&gt;
 146       &lt;argumentList&gt;
 147         &lt;argument&gt;
 148           &lt;name&gt;RetTargetValue&lt;/name&gt;
 149           &lt;relatedStateVariable&gt;Target&lt;/relatedStateVariable&gt;
 150           &lt;direction&gt;out&lt;/direction&gt;
 151         &lt;/argument&gt;
 152       &lt;/argumentList&gt;
 153     &lt;/action&gt;
 154     &lt;action&gt;
 155       &lt;name&gt;GetStatus&lt;/name&gt;
 156       &lt;argumentList&gt;
 157         &lt;argument&gt;
 158           &lt;name&gt;ResultStatus&lt;/name&gt;
 159           &lt;relatedStateVariable&gt;Status&lt;/relatedStateVariable&gt;
 160           &lt;direction&gt;out&lt;/direction&gt;
 161         &lt;/argument&gt;
 162       &lt;/argumentList&gt;
 163     &lt;/action&gt;
 164   &lt;/actionList&gt;
 165   &lt;serviceStateTable&gt;
 166     &lt;stateVariable sendEvents="no"&gt;
 167       &lt;name&gt;Target&lt;/name&gt;
 168       &lt;dataType&gt;boolean&lt;/dataType&gt;
 169       &lt;defaultValue&gt;0&lt;/defaultValue&gt;
 170     &lt;/stateVariable&gt;
 171     &lt;stateVariable sendEvents="yes"&gt;
 172       &lt;name&gt;Status&lt;/name&gt;
 173       &lt;dataType&gt;boolean&lt;/dataType&gt;
 174       &lt;defaultValue&gt;0&lt;/defaultValue&gt;
 175     &lt;/stateVariable&gt;
 176   &lt;/serviceStateTable&gt;
 177 &lt;/scpd&gt;
 178 </pre>
 179 <p>
 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>.
 184     </p>
 185 <p>
 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.
 194     </p>
 195 <p>
 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.
 204     </p>
 205 <p>
 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>.
 210     </p>
 211 </div>
 212 <div class="simplesect">
 213 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 214 <a name="idp6387216"></a>Implementing the Device</h2></div></div></div>
 215 <p>
 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 gupnp_context_new().
 219     </p>
 220 <pre class="programlisting">GUPnPContext *context;
 221 /* Initialize required subsystems */
 222 #if !GLIB_CHECK_VERSION(2,35,0)
 223   g_type_init ();
 224 #endif
 225 /* Create the GUPnP context with default host and port */
 226 context = gupnp_context_new (NULL, NULL, 0, NULL);</pre>
 227 <p>
 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 gupnp_root_device_new(). The service description
 231       files referenced in the device description are expected to be at the path
 232       given there as well.
 233     </p>
 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>
 239 <p>
 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.
 244     </p>
 245 </div>
 246 <div class="simplesect">
 247 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 248 <a name="idp8436720"></a>Implementing a Service</h2></div></div></div>
 249 <p>
 250       To implement a service we first fetch the #GUPnPService from the root
 251       device using gupnp_device_info_get_service() (#GUPnPRootDevice is a
 252       subclass of #GUPnPDevice, which implements #GUPnPDeviceInfo).  This
 253       returns a #GUPnPServiceInfo which again is an interface, implemented by
 254       #GUPnPService (on the server) and #GUPnPServiceProxy (on the client).
 255     </p>
 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>
 259 <p>
 260       #GUPnPService 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: #GUPnPService::action-invoked and
 263       #GUPnPService::query-variable.  #GUPnPService::action-invoked is emitted
 264       when a client invokes an action: the handler is passed a
 265       #GUPnPServiceAction object that identifies which action was invoked, and
 266       is used to return values using gupnp_service_action_set().
 267       #GUPnPService::query-variable 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 #GValue which should be set to the current
 272       value of the variable.
 273     </p>
 274 <p>
 275       There are two approaches that clients can take to handle these signals.
 276       They can either connect a single handler to #GUPnPService::action-invoked
 277       or #GUPnPService::query-variable and examine the arguments to decide what
 278       action to take.  Alternatively, handlers can be targetted at specific
 279       actions or variables by using the <em class="firstterm">signal detail</em>
 280       when connecting.  For example, this causes
 281       <code class="function">on_get_status_action</code> to be called when the
 282       <code class="function">GetStatus</code> action is invoked:
 283     </p>
 284 <pre class="programlisting">static void on_get_status_action (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data);
 285 …
 286 g_signal_connect (service, "action-invoked::GetStatus", G_CALLBACK (on_get_status_action), NULL);</pre>
 287 <p>
 288       The implementation of action handlers is quite simple.  The handler is
 289       passed a #GUPnPServiceAction object which represents the in-progress
 290       action.  If required it can be queried using
 291       gupnp_service_action_get_name() to identify the action (this isn't
 292       required if detailed signals were connected).  Any
 293       <em class="firstterm">in</em> arguments can be retrieving using
 294       gupnp_service_action_get(), and then return values can be set using
 295       gupnp_service_action_set().  Once the action has been performed, either
 296       gupnp_service_action_return() or gupnp_service_action_return_error()
 297       should be called to either return successfully or return an error code.
 298       If any evented state variables were modified during the action then a
 299       notification should be emitted using gupnp_service_notify().  This is an
 300       example implementation of <code class="function">GetStatus</code> and
 301       <code class="function">SetTarget</code>:
 302     </p>
 303 <pre class="programlisting">static gboolean status;
 304
 305 static void
 306 get_status_cb (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data)
 307 {
 308   gupnp_service_action_set (action,
 309                             "ResultStatus", G_TYPE_BOOLEAN, status,
 310                             NULL);
 311   gupnp_service_action_return (action);
 312 }
 313
 314 void
 315 set_target_cb (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data)
 316 {
 317   gupnp_service_action_get (action,
 318                             "NewTargetValue", G_TYPE_BOOLEAN, &amp;status,
 319                             NULL);
 320   gupnp_service_action_return (action);
 321   gupnp_service_notify (service, "Status", G_TYPE_STRING, status, NULL);
 322 }
 323 …
 324 g_signal_connect (service, "action-invoked::GetStatus", G_CALLBACK (get_status_cb), NULL);
 325 g_signal_connect (service, "action-invoked::SetTarget", G_CALLBACK (set_target_cb), NULL);</pre>
 326 <p>
 327       State variable query handlers are called with the name of the variable and
 328       a #GValue.  This value should be initialized with the relevant type and
 329       then set to the current value.  Again signal detail can be used to connect
 330       handlers to specific state variable callbacks.
 331     </p>
 332 <pre class="programlisting">static gboolean status;
 333
 334 static void
 335 query_status_cb (GUPnPService *service, char *variable, GValue *value, gpointer user_data)
 336 {
 337   g_value_init (value, G_TYPE_BOOLEAN);
 338   g_value_set_boolean (value, status);
 339 }
 340 …
 341 g_signal_connect (service, "query-variable::Status", G_CALLBACK (query_status_cb), NULL);</pre>
 342 <p>
 343       The service is now fully implemented.  To complete it, enter a GLib main
 344       loop and wait for a client to connect.  The complete source code for this
 345       example is available as <code class="filename">examples/light-server.c</code> in
 346       the GUPnP sources.
 347     </p>
 348 <p>
 349       For services which have many actions and variables there is a convenience
 350       method gupnp_service_signals_autoconnect() which will automatically
 351       connect specially named handlers to signals.  See the documentation for
 352       full details on how it works.
 353     </p>
 354 </div>
 355 <div class="simplesect">
 356 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 357 <a name="idp9527792"></a>Generating Service-specific Wrappers</h2></div></div></div>
 358 <p>
 359       Using service-specific wrappers can simplify the implementation of a service.
 360       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>
 361       using the option <code class="literal">--mode server</code>.
 362     </p>
 363 <p>
 364       In the following examples the wrapper has been created with
 365       <code class="literal">--mode server --prefix switch</code>. Please note that the callback handlers
 366       (<code class="literal">get_status_cb</code> and <code class="literal">set_target_cb</code>) are not automatically
 367       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.
 368     </p>
 369 <pre class="programlisting">static gboolean status;
 370
 371 static void
 372 get_status_cb (GUPnPService *service,
 373                GUPnPServiceAction *action,
 374                gpointer user_data)
 375 {
 376   switch_get_status_action_set (action, status);
 377
 378   gupnp_service_action_return (action);
 379 }
 380
 381 static void
 382 set_target_cb (GUPnPService *service,
 383                GUPnPServiceAction *action,
 384                gpointer user_data)
 385 {
 386   switch_set_target_action_get (action, &amp;status);
 387   switch_status_variable_notify (service, status);
 388
 389   gupnp_service_action_return (action);
 390 }
 391
 392 …
 393
 394 switch_get_status_action_connect (service, G_CALLBACK(get_status_cb), NULL);
 395 switch_set_target_action_connect (service, G_CALLBACK(set_target_cb), NULL);</pre>
 396 <p>
 397       Note how many possible problem situations that were run-time errors are
 398       actually compile-time errors when wrappers are used: Action names,
 399       argument names and argument types are easier to get correct (and available
 400       in editor autocompletion).
 401     </p>
 402 <p>
 403       State variable query handlers are implemented in a similar manner, but
 404       they are even simpler as the return value of the handler is the state
 405       variable value.
 406     </p>
 407 <pre class="programlisting">static gboolean
 408 query_status_cb (GUPnPService *service,
 409                  gpointer user_data)
 410 {
 411   return status;
 412 }
 413
 414 …
 415
 416 switch_status_query_connect (service, query_status_cb, NULL);</pre>
 417 </div>
 418 </div>
 419 <div class="footer">
 420 <hr>
 421           Generated by GTK-Doc V1.18</div>
 422 </body>
 423 </html>