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.75.2">
   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.15.1 (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="id2897295"></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/standardizeddcps/" target="_top">http://upnp.org/standardizeddcps/</a> for the list of standard devices
  36       and services) then the service description is already written for you and
  37       the device description is trivial.  UPnP has standardised <a class="ulink" href="http://upnp.org/standardizeddcps/lighting.asp" target="_top">Lighting
  38       Controls</a>, so we'll be using the device and service types defined
  39       there.
  40     </p>
  41 </div>
  42 <div class="simplesect">
  43 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  44 <a name="id2900786"></a>Defining the Device</h2></div></div></div>
  45 <p>
  46       The first step is to write the <em class="firstterm">device description</em>
  47       file.  This is a short XML document which describes the device and what
  48       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
  49       Device Architecture</a> specification, section 2.1).  We'll be using
  50       the <code class="literal">BinaryLight1</code> device type, but if none of the
  51       existing device types are suitable a custom device type can be created.
  52     </p>
  53 <pre class="programlisting">&lt;?xml version="1.0" encoding="utf-8"?&gt;
  54 &lt;root xmlns="urn:schemas-upnp-org:device-1-0"&gt;
  55   &lt;specVersion&gt;
  56     &lt;major&gt;1&lt;/major&gt;
  57     &lt;minor&gt;0&lt;/minor&gt;
  58   &lt;/specVersion&gt;
  59
  60   &lt;device&gt;
  61     &lt;deviceType&gt;urn:schemas-upnp-org:device:BinaryLight:1&lt;/deviceType&gt;
  62     &lt;friendlyName&gt;Kitchen Lights&lt;/friendlyName&gt;
  63     &lt;manufacturer&gt;OpenedHand&lt;/manufacturer&gt;
  64     &lt;modelName&gt;Virtual Light&lt;/modelName&gt;
  65     &lt;UDN&gt;uuid:cc93d8e6-6b8b-4f60-87ca-228c36b5b0e8&lt;/UDN&gt;
  66
  67     &lt;serviceList&gt;
  68       &lt;service&gt;
  69         &lt;serviceType&gt;urn:schemas-upnp-org:service:SwitchPower:1&lt;/serviceType&gt;
  70         &lt;serviceId&gt;urn:upnp-org:serviceId:SwitchPower:1&lt;/serviceId&gt;
  71         &lt;SCPDURL&gt;/SwitchPower1.xml&lt;/SCPDURL&gt;
  72         &lt;controlURL&gt;/SwitchPower/Control&lt;/controlURL&gt;
  73         &lt;eventSubURL&gt;/SwitchPower/Event&lt;/eventSubURL&gt;
  74       &lt;/service&gt;
  75     &lt;/serviceList&gt;
  76   &lt;/device&gt;
  77 &lt;/root&gt;
  78 </pre>
  79 <p>
  80       The <code class="sgmltag-element">specVersion</code> tag defines what version of the UPnP
  81       Device Architecture the document conforms to.  At the time of writing the
  82       only version is 1.0.
  83     </p>
  84 <p>
  85       Next there is the root <code class="sgmltag-element">device</code> tag.  This contains
  86       metadata about the device, lists the services it provides and any
  87       sub-devices present (there are none in this example).  The
  88       <code class="sgmltag-element">deviceType</code> tag specifies the type of the device.
  89     </p>
  90 <p>
  91       Next we have <code class="sgmltag-element">friendlyName</code>,
  92       <code class="sgmltag-element">manufacturer</code> and <code class="sgmltag-element">modelName</code>.  The
  93       friendly name is a human-readable name for the device, the manufacturer
  94       and model name are self-explanatory.
  95     </p>
  96 <p>
  97       Next there is the UDN, or <em class="firstterm">Unique Device Name</em>.  This
  98       is an identifier which is unique for each device but persistent for each
  99       particular device.  Although it has to start with <code class="literal">uuid:</code>
 100       note that it doesn't have to be an UUID.  There are several alternatives
 101       here: for example it could be computed at built-time if the software will
 102       only be used on a single machine, or it could be calculated using the
 103       device's serial number or MAC address.
 104     </p>
 105 <p>
 106       Finally we have the <code class="sgmltag-element">serviceList</code> which describes the
 107       services this device provides.  Each service has a service type (again
 108       there are types defined for standardised services or you can create your
 109       own), service identifier, and three URLs.  As a service type we're using
 110       the standard <code class="literal">SwitchPower1</code> service.  The
 111       <code class="sgmltag-element">SCPDURL</code> field specifies where the <em class="firstterm">Service
 112       Control Protocol Document</em> can be found, this describes the
 113       service in more detail and will be covered next.  Finally there are the
 114       control and event URLs, which need to be unique on the device and will be
 115       managed by GUPnP.
 116     </p>
 117 </div>
 118 <div class="simplesect">
 119 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 120 <a name="id2913595"></a>Defining Services</h2></div></div></div>
 121 <p>
 122       Becase we are using a standard service we can use the service description
 123       from the specification.  This is the <code class="literal">SwitchPower1</code>
 124       service description file:
 125     </p>
 126 <pre class="programlisting">&lt;?xml version="1.0" encoding="utf-8"?&gt;
 127 &lt;scpd xmlns="urn:schemas-upnp-org:service-1-0"&gt;
 128   &lt;specVersion&gt;
 129     &lt;major&gt;1&lt;/major&gt;
 130     &lt;minor&gt;0&lt;/minor&gt;
 131   &lt;/specVersion&gt;
 132   &lt;actionList&gt;
 133     &lt;action&gt;
 134       &lt;name&gt;SetTarget&lt;/name&gt;
 135       &lt;argumentList&gt;
 136         &lt;argument&gt;
 137           &lt;name&gt;NewTargetValue&lt;/name&gt;
 138           &lt;relatedStateVariable&gt;Target&lt;/relatedStateVariable&gt;
 139           &lt;direction&gt;in&lt;/direction&gt;
 140         &lt;/argument&gt;
 141       &lt;/argumentList&gt;
 142     &lt;/action&gt;
 143     &lt;action&gt;
 144       &lt;name&gt;GetTarget&lt;/name&gt;
 145       &lt;argumentList&gt;
 146         &lt;argument&gt;
 147           &lt;name&gt;RetTargetValue&lt;/name&gt;
 148           &lt;relatedStateVariable&gt;Target&lt;/relatedStateVariable&gt;
 149           &lt;direction&gt;out&lt;/direction&gt;
 150         &lt;/argument&gt;
 151       &lt;/argumentList&gt;
 152     &lt;/action&gt;
 153     &lt;action&gt;
 154       &lt;name&gt;GetStatus&lt;/name&gt;
 155       &lt;argumentList&gt;
 156         &lt;argument&gt;
 157           &lt;name&gt;ResultStatus&lt;/name&gt;
 158           &lt;relatedStateVariable&gt;Status&lt;/relatedStateVariable&gt;
 159           &lt;direction&gt;out&lt;/direction&gt;
 160         &lt;/argument&gt;
 161       &lt;/argumentList&gt;
 162     &lt;/action&gt;
 163   &lt;/actionList&gt;
 164   &lt;serviceStateTable&gt;
 165     &lt;stateVariable sendEvents="no"&gt;
 166       &lt;name&gt;Target&lt;/name&gt;
 167       &lt;dataType&gt;boolean&lt;/dataType&gt;
 168       &lt;defaultValue&gt;0&lt;/defaultValue&gt;
 169     &lt;/stateVariable&gt;
 170     &lt;stateVariable sendEvents="yes"&gt;
 171       &lt;name&gt;Status&lt;/name&gt;
 172       &lt;dataType&gt;boolean&lt;/dataType&gt;
 173       &lt;defaultValue&gt;0&lt;/defaultValue&gt;
 174     &lt;/stateVariable&gt;
 175   &lt;/serviceStateTable&gt;
 176 &lt;/scpd&gt;
 177 </pre>
 178 <p>
 179       Again, the <code class="sgmltag-element">specVersion</code> tag defines the UPnP version
 180       that is being used.  The rest of the document consists of an
 181       <code class="sgmltag-element">actionList</code> defining the <a class="glossterm" href="glossary.html#action"><em class="glossterm">actions</em></a> available and a
 182       <code class="sgmltag-element">serviceStateTable</code> defining the <a class="glossterm" href="glossary.html#state-variable"><em class="glossterm">state variables</em></a>.
 183     </p>
 184 <p>
 185       Every <code class="sgmltag-element">action</code> has a <code class="sgmltag-element">name</code> and a list
 186       of <code class="sgmltag-element">argument</code>s.  Arguments also have a name, a direction
 187       (<code class="literal">in</code> or <code class="literal">out</code> for input or output
 188       arguments) and a related state variable.  The state variable is used to
 189       determine the type of the argument, and as such is a required element.
 190       This can lead to the creation of otherwise unused state variables to
 191       define the type for an argument (the <code class="literal">WANIPConnection</code>
 192       service is a good example of this), thanks to the legacy behind UPnP.
 193     </p>
 194 <p>
 195       <code class="sgmltag-element">stateVariable</code>s need to specify their
 196       <code class="sgmltag-element">name</code> and <code class="sgmltag-element">dataType</code>.  State variables
 197       by default send notifications when they change, to specify that a variable
 198       doesn't do this set the <code class="sgmltag-element">sendEvents</code> attribute to
 199       <code class="literal">no</code>.  Finally there are optional
 200       <code class="sgmltag-element">defaultValue</code>, <code class="sgmltag-element">allowedValueList</code> and
 201       <code class="sgmltag-element">allowedValueRange</code> elements which specify what the
 202       default and valid values for the variable.
 203     </p>
 204 <p>
 205       For the full specification of the service definition file, including a
 206       complete list of valid <code class="sgmltag-element">dataType</code>s, see section 2.3 of
 207       the <a class="ulink" href="http://upnp.org/specs/arch/UPnP-DeviceArchitecture-v1.0.pdf" target="_top">UPnP
 208       Device Architecture</a>.
 209     </p>
 210 </div>
 211 <div class="simplesect">
 212 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 213 <a name="id2909172"></a>Implementing the Device</h2></div></div></div>
 214 <p>
 215       Before starting to implement the device, some boilerplate code is needed
 216       to initialise GUPnP.  GLib types and threading needs to be initialised,
 217       and then a GUPnP context can be created using gupnp_context_new().
 218     </p>
 219 <pre class="programlisting">GUPnPContext *context;
 220 /* Initialize required subsystems */
 221 g_thread_init (NULL);
 222 g_type_init ();
 223 /* Create the GUPnP context with default host and port */
 224 context = gupnp_context_new (NULL, NULL, 0, NULL);</pre>
 225 <p>
 226       UPnP uses HTTP to provide the device and service description files, so
 227       next we tell GUPnP to publish them.  This is done with
 228       gupnp_context_host_path() which takes a local filename to send when a
 229       certain server path is requested.
 230     </p>
 231 <pre class="programlisting">gupnp_context_host_path (context, "BinaryLight1.xml", "/BinaryLight1.xml");
 232 gupnp_context_host_path (context, "SwitchPower1.xml", "/SwitchPower1.xml");</pre>
 233 <p>
 234       Next the root device can be created.
 235     </p>
 236 <pre class="programlisting">GUPnPRootDevice *dev;
 237 /* Create the root device object */
 238 dev = gupnp_root_device_new (context, "/BinaryLight1.xml");
 239 /* Activate the root device, so that it announces itself */
 240 gupnp_root_device_set_available (dev, TRUE);</pre>
 241 <p>
 242       GUPnP scans the device description and any service description files it
 243       refers to, so if the main loop was entered now the device and service
 244       would be available on the network, albeit with no functionality.  The
 245       remaining task is to implement the services.
 246     </p>
 247 </div>
 248 <div class="simplesect">
 249 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 250 <a name="id2851217"></a>Implementing a Service</h2></div></div></div>
 251 <p>
 252       To implement a service we first fetch the #GUPnPService from the root
 253       device using gupnp_device_info_get_service() (#GUPnPRootDevice is a
 254       subclass of #GUPnPDevice, which implements #GUPnPDeviceInfo).  This
 255       returns a #GUPnPServiceInfo which again is an interface, implemented by
 256       #GUPnPService (on the server) and #GUPnPServiceProxy (on the client).
 257     </p>
 258 <pre class="programlisting">GUPnPServiceInfo *service;
 259 service = gupnp_device_info_get_service
 260   (GUPNP_DEVICE_INFO (dev), "urn:schemas-upnp-org:service:SwitchPower:1");</pre>
 261 <p>
 262       #GUPnPService handles interacting with the network itself, leaving the
 263       implementation of the service itself to signal handlers that we need to
 264       connect.  There are two signals: #GUPnPService::action-invoked and
 265       #GUPnPService::query-variable.  #GUPnPService::action-invoked is emitted
 266       when a client invokes an action: the handler is passed a
 267       #GUPnPServiceAction object that identifies which action was invoked, and
 268       is used to return values using gupnp_service_action_set().
 269       #GUPnPService::query-variable is emitted for evented variables when a
 270       control point subscribes to the service (to announce the initial value),
 271       or whenever a client queries the value of a state variable (note that this
 272       is now deprecated behaviour for UPnP control points): the handler is
 273       passed the variable name and a #GValue which should be set to the current
 274       value of the variable.
 275     </p>
 276 <p>
 277       There are two approaches that clients can take to handle these signals.
 278       They can either connect a single handler to #GUPnPService::action-invoked
 279       or #GUPnPService::query-variable and examine the arguments to decide what
 280       action to take.  Alternatively, handlers can be targetted at specific
 281       actions or variables by using the <em class="firstterm">signal detail</em>
 282       when connecting.  For example, this causes
 283       <code class="function">on_get_status_action</code> to be called when the
 284       <code class="function">GetStatus</code> action is invoked:
 285     </p>
 286 <pre class="programlisting">static void on_get_status_action (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data);
 287 …
 288 g_signal_connect (service, "action-invoked::GetStatus", G_CALLBACK (on_get_status_action), NULL);</pre>
 289 <p>
 290       The implementation of action handlers is quite simple.  The handler is
 291       passed a #GUPnPServiceAction object which represents the in-progress
 292       action.  If required it can be queried using
 293       gupnp_service_action_get_name() to identify the action (this isn't
 294       required if detailed signals were connected).  Any
 295       <em class="firstterm">in</em> arguments can be retrieving using
 296       gupnp_service_action_get(), and then return values can be set using
 297       gupnp_service_action_set().  Once the action has been performed, either
 298       gupnp_service_action_return() or gupnp_service_action_return_error()
 299       should be called to either return successfully or return an error code.
 300       If any evented state variables were modified during the action then a
 301       notification should be emitted using gupnp_service_notify().  This is an
 302       example implementation of <code class="function">GetStatus</code> and
 303       <code class="function">SetTarget</code>:
 304     </p>
 305 <pre class="programlisting">static gboolean status;
 306
 307 static void
 308 get_status_cb (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data)
 309 {
 310   gupnp_service_action_set (action,
 311                             "ResultStatus", G_TYPE_BOOLEAN, status,
 312                             NULL);
 313   gupnp_service_action_return (action);
 314 }
 315
 316 void
 317 set_target_cb (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data)
 318 {
 319   gupnp_service_action_get (action,
 320                             "NewTargetValue", G_TYPE_BOOLEAN, &amp;status,
 321                             NULL);
 322   gupnp_service_action_return (action);
 323   gupnp_service_notify (service, "Status", G_TYPE_STRING, status, NULL);
 324 }
 325 …
 326 g_signal_connect (service, "action-invoked::GetStatus", G_CALLBACK (get_status_cb), NULL);
 327 g_signal_connect (service, "action-invoked::SetTarget", G_CALLBACK (set_target_cb), NULL);</pre>
 328 <p>
 329       State variable query handlers are called with the name of the variable and
 330       a #GValue.  This value should be initialized with the relevant type and
 331       then set to the current value.  Again signal detail can be used to connect
 332       handlers to specific state variable callbacks.
 333     </p>
 334 <pre class="programlisting">static gboolean status;
 335
 336 static void
 337 query_status_cb (GUPnPService *service, char *variable, GValue *value, gpointer user_data)
 338 {
 339   g_value_init (value, G_TYPE_BOOLEAN);
 340   g_value_set_boolean (value, status);
 341 }
 342 …
 343 g_signal_connect (service, "query-variable::Status", G_CALLBACK (query_status_cb), NULL);</pre>
 344 <p>
 345       The service is now fully implemented.  To complete it, enter a GLib main
 346       loop and wait for a client to connect.  The complete source code for this
 347       example is available as <code class="filename">examples/light-server.c</code> in
 348       the GUPnP sources.
 349     </p>
 350 <p>
 351       For services which have many actions and variables there is a convenience
 352       method gupnp_service_signals_autoconnect() which will automatically
 353       connect specially named handlers to signals.  See the documentation for
 354       full details on how it works.
 355     </p>
 356 </div>
 357 <div class="simplesect">
 358 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 359 <a name="id2919384"></a>Generating Service-specific Wrappers</h2></div></div></div>
 360 <p>
 361       Using service-specific wrappers can simplify the implementation of a service.
 362       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>
 363       using the option <code class="literal">--mode server</code>.
 364     </p>
 365 <p>
 366       In the following examples the wrapper has been created with <code class="literal">--mode server --prefix switch</code>.
 367     </p>
 368 <pre class="programlisting">static gboolean status;
 369
 370 static void
 371 get_status_cb (GUPnPService *service,
 372                GUPnPServiceAction *action,
 373                gpointer user_data)
 374 {
 375   switch_get_status_action_set (action, status);
 376
 377   gupnp_service_action_return (action);
 378 }
 379
 380 static void
 381 set_target_cb (GUPnPService *service,
 382                GUPnPServiceAction *action,
 383                gpointer user_data)
 384 {
 385   switch_set_target_action_get (action, &amp;status);
 386   switch_status_variable_notify (service, status);
 387
 388   gupnp_service_action_return (action);
 389 }
 390
 391 …
 392
 393 switch_get_status_action_connect (service, G_CALLBACK(get_status_cb), NULL);
 394 switch_set_target_action_connect (service, G_CALLBACK(set_target_cb), NULL);</pre>
 395 <p>
 396       Note how many possible problem situations that were run-time errors are
 397       actually compile-time errors when wrappers are used: Action names,
 398       argument names and argument types are easier to get correct (and available
 399       in editor autocompletion).
 400     </p>
 401 <p>
 402       State variable query handlers are implemented in a similar manner, but
 403       they are even simpler as the return value of the handler is the state
 404       variable value.
 405     </p>
 406 <pre class="programlisting">static gboolean
 407 query_status_cb (GUPnPService *service,
 408                  gpointer user_data)
 409 {
 410   return status;
 411 }
 412
 413 …
 414
 415 switch_status_query_connect (service, query_status_cb, NULL);</pre>
 416 </div>
 417 </div>
 418 <div class="footer">
 419 <hr>
 420           Generated by GTK-Doc V1.15.1</div>
 421 </body>
 422 </html>