server-tutorial.xml

另一 UPNP SDK 支持在UNIX/LINUX上运行。 UPnP是一种网络协议

<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<chapter id="server-tutorial" xmlns:xi="http://www.w3.org/2001/XInclude">
  <title>Writing a UPnP Service</title>

  <simplesect>
    <title>Introduction</title>
    <para>
      This chapter explains how to implement a UPnP service using GUPnP. For
      this example we will create a virtual UPnP-enabled light bulb.
    </para>
    <para>
      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 <ulink
      url="http://upnp.org/standardizeddcps/"/> 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 <ulink
      url="http://upnp.org/standardizeddcps/lighting.asp">Lighting
      Controls</ulink>, so we'll be using the device and service types defined
      there.
    </para>
  </simplesect>

  <simplesect>
    <title>Defining the Device</title>
    <para>
      The first step is to write the <firstterm>device description</firstterm>
      file.  This is a short XML document which describes the device and what
      services it provides (for more details see the <ulink
      url="http://upnp.org/specs/arch/UPnP-DeviceArchitecture-v1.0.pdf">UPnP
      Device Architecture</ulink> specification, section 2.1).  We'll be using
      the <literal>BinaryLight1</literal> device type, but if none of the
      existing device types are suitable a custom device type can be created.
    </para>
    <programlisting><xi:include href="../../examples/BinaryLight1.xml" parse="text"/></programlisting>
    <para>
      The <sgmltag>specVersion</sgmltag> tag defines what version of the UPnP
      Device Architecture the document conforms to.  At the time of writing the
      only version is 1.0.
    </para>
    <para>
      Next there is the root <sgmltag>device</sgmltag> tag.  This contains
      metadata about the device, lists the services it provides and any
      sub-devices present (there are none in this example).  The
      <sgmltag>deviceType</sgmltag> tag specifies the type of the device.
    </para>
    <para>
      Next we have <sgmltag>friendlyName</sgmltag>,
      <sgmltag>manufacturer</sgmltag> and <sgmltag>modelName</sgmltag>.  The
      friendly name is a human-readable name for the device, the manufacturer
      and model name are self-explanatory.
    </para>
    <para>
      Next there is the UDN, or <firstterm>Unique Device Name</firstterm>.  This
      is an identifier which is unique for each device but persistent for each
      particular device.  Although it has to start with <literal>uuid:</literal>
      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.
    </para>
    <para>
      Finally we have the <sgmltag>serviceList</sgmltag> 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 <literal>SwitchPower1</literal> service.  The
      <sgmltag>SCPDURL</sgmltag> field specifies where the <firstterm>Service
      Control Protocol Document</firstterm> 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.
    </para>
  </simplesect>

  <simplesect>
    <title>Defining Services</title>
    <para>
      Becase we are using a standard service we can use the service description
      from the specification.  This is the <literal>SwitchPower1</literal>
      service description file:
    </para>
    <programlisting><xi:include href="../../examples/SwitchPower1.xml" parse="text"/></programlisting>
    <para>
      Again, the <sgmltag>specVersion</sgmltag> tag defines the UPnP version
      that is being used.  The rest of the document consists of an
      <sgmltag>actionList</sgmltag> defining the <glossterm
      linkend="action">actions</glossterm> available and a
      <sgmltag>serviceStateTable</sgmltag> defining the <glossterm
      linkend="state-variable">state variables</glossterm>.
    </para>
    <para>
      Every <sgmltag>action</sgmltag> has a <sgmltag>name</sgmltag> and a list
      of <sgmltag>argument</sgmltag>s.  Arguments also have a name, a direction
      (<literal>in</literal> or <literal>out</literal> for input or output
      arguments) and a related state variable.  The state variable is used to
      determine the type of the argument, and as such is a required element.
      This can lead to the creation of otherwise unused state variables to
      define the type for an argument (the <literal>WANIPConnection</literal>
      service is a good example of this), thanks to the legacy behind UPnP.
    </para>
    <para>
      <sgmltag>stateVariable</sgmltag>s need to specify their
      <sgmltag>name</sgmltag> and <sgmltag>dataType</sgmltag>.  State variables
      by default send notifications when they change, to specify that a variable
      doesn't do this set the <sgmltag>sendEvents</sgmltag> attribute to
      <literal>no</literal>.  Finally there are optional
      <sgmltag>defaultValue</sgmltag>, <sgmltag>allowedValueList</sgmltag> and
      <sgmltag>allowedValueRange</sgmltag> elements which specify what the
      default and valid values for the variable.
    </para>
    <para>
      For the full specification of the service definition file, including a
      complete list of valid <sgmltag>dataType</sgmltag>s, see section 2.3 of
      the <ulink
      url="http://upnp.org/specs/arch/UPnP-DeviceArchitecture-v1.0.pdf">UPnP
      Device Architecture</ulink>.
    </para>
  </simplesect>

  <simplesect>
    <title>Implementing the Device</title>
    <para>
      Before starting to implement the device, some boilerplate code is needed
      to initialise GUPnP.  GLib types and threading needs to be initialised,
      and then a GUPnP context can be created using <link linkend="gupnp-context-new"><function>gupnp_context_new()</function></link>.
    </para>
    <programlisting>GUPnPContext *context;
/* Initialize required subsystems */
g_thread_init (NULL);
g_type_init ();
/* Create the GUPnP context with default host and port */
context = gupnp_context_new (NULL, NULL, 0, NULL);</programlisting>
    <para>
      UPnP uses HTTP to provide the device and service description files, so
      next we tell GUPnP to publish them.  This is done with
      <link linkend="gupnp-context-host-path"><function>gupnp_context_host_path()</function></link> which takes a local filename to send when a
      certain server path is requested.
    </para>
<programlisting>gupnp_context_host_path (context, "BinaryLight1.xml", "/BinaryLight1.xml");
gupnp_context_host_path (context, "SwitchPower1.xml", "/SwitchPower1.xml");</programlisting>
    <para>
      Next the root device can be created. 
    </para>
    <programlisting>GUPnPRootDevice *dev;
/* Create the root device object */
dev = gupnp_root_device_new (context, "/BinaryLight1.xml");
/* Activate the root device, so that it announces itself */
gupnp_root_device_set_available (dev, TRUE);</programlisting>
    <para>
      GUPnP scans the device description and any service description files it
      refers to, so if the main loop was entered now the device and service
      would be available on the network, albeit with no functionality.  The
      remaining task is to implement the services.
    </para>
  </simplesect>

  <simplesect>
    <title>Implementing a Service</title>
    <para>
      To implement a service we first fetch the <link linkend="GUPnPService"><type>GUPnPService</type></link> from the root
      device using <link linkend="gupnp-device-info-get-service"><function>gupnp_device_info_get_service()</function></link> (<link linkend="GUPnPRootDevice"><type>GUPnPRootDevice</type></link> is a
      subclass of <link linkend="GUPnPDevice"><type>GUPnPDevice</type></link>, which implements <link linkend="GUPnPDeviceInfo"><type>GUPnPDeviceInfo</type></link>).  This
      returns a <link linkend="GUPnPServiceInfo"><type>GUPnPServiceInfo</type></link> which again is an interface, implemented by
      <link linkend="GUPnPService"><type>GUPnPService</type></link> (on the server) and <link linkend="GUPnPServiceProxy"><type>GUPnPServiceProxy</type></link> (on the client).
    </para>
    <programlisting>GUPnPServiceInfo *service;
service = gupnp_device_info_get_service
  (GUPNP_DEVICE_INFO (dev), "urn:schemas-upnp-org:service:SwitchPower:1");</programlisting>
    <para>
      <link linkend="GUPnPService"><type>GUPnPService</type></link> handles interacting with the network itself, leaving the
      implementation of the service itself to signal handlers that we need to
      connect.  There are two signals: <link linkend="GUPnPService-action-invoked"><type>"action-invoked"</type></link> and
      <link linkend="GUPnPService-query-variable"><type>"query-variable"</type></link>.  <link linkend="GUPnPService-action-invoked"><type>"action-invoked"</type></link> is emitted
      when a client invokes an action: the handler is passed a
      <link linkend="GUPnPServiceAction"><type>GUPnPServiceAction</type></link> object that identifies which action was invoked, and
      is used to return values using <link linkend="gupnp-service-action-set"><function>gupnp_service_action_set()</function></link>.
      <link linkend="GUPnPService-query-variable"><type>"query-variable"</type></link> is emitted for evented variables when a
      control point subscribes to the service (to announce the initial value),
      or whenever a client queries the value of a state variable (note that this
      is now deprecated behaviour for UPnP control points): the handler is
      passed the variable name and a <link linkend="GValue"><type>GValue</type></link> which should be set to the current
      value of the variable.
    </para>
    <para>
      There are two approaches that clients can take to handle these signals.
      They can either connect a single handler to <link linkend="GUPnPService-action-invoked"><type>"action-invoked"</type></link>
      or <link linkend="GUPnPService-query-variable"><type>"query-variable"</type></link> and examine the arguments to decide what
      action to take.  Alternatively, handlers can be targetted at specific
      actions or variables by using the <firstterm>signal detail</firstterm>
      when connecting.  For example, this causes
      <function>on_get_status_action</function> to be called when the
      <function>GetStatus</function> action is invoked:
    </para>
    <programlisting>static void on_get_status_action (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data);
&hellip;
g_signal_connect (service, "action-invoked::GetStatus", G_CALLBACK (on_get_status_action), NULL);</programlisting>
    <para>
      The implementation of action handlers is quite simple.  The handler is
      passed a <link linkend="GUPnPServiceAction"><type>GUPnPServiceAction</type></link> object which represents the in-progress
      action.  If required it can be queried using
      <link linkend="gupnp-service-action-get-name"><function>gupnp_service_action_get_name()</function></link> to identify the action (this isn't
      required if detailed signals were connected).  Any
      <firstterm>in</firstterm> arguments can be retrieving using
      <link linkend="gupnp-service-action-get"><function>gupnp_service_action_get()</function></link>, and then return values can be set using
      <link linkend="gupnp-service-action-set"><function>gupnp_service_action_set()</function></link>.  Once the action has been performed, either
      <link linkend="gupnp-service-action-return"><function>gupnp_service_action_return()</function></link> or <link linkend="gupnp-service-action-return-error"><function>gupnp_service_action_return_error()</function></link>
      should be called to either return successfully or return an error code.
      If any evented state variables were modified during the action then a
      notification should be emitted using <link linkend="gupnp-service-notify"><function>gupnp_service_notify()</function></link>.  This is an
      example implementation of <function>GetStatus</function> and
      <function>SetTarget</function>:
    </para>
    <programlisting>static gboolean status;

static void
get_status_cb (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data)
{
  gupnp_service_action_set (action,
                            "ResultStatus", G_TYPE_BOOLEAN, status,
                            NULL);
  gupnp_service_action_return (action);
}

void
set_target_cb (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data)
{
  gupnp_service_action_get (action,
                            "NewTargetValue", G_TYPE_BOOLEAN, &amp;status,
                            NULL);
  gupnp_service_action_return (action);
  gupnp_service_notify (service, "Status", G_TYPE_STRING, status, NULL);
}
&hellip;
g_signal_connect (service, "action-invoked::GetStatus", G_CALLBACK (get_status_cb), NULL);
g_signal_connect (service, "action-invoked::SetTarget", G_CALLBACK (set_target_cb), NULL);</programlisting>
    <para>
      State variable query handlers are called with the name of the variable and
      a <link linkend="GValue"><type>GValue</type></link>.  This value should be initialized with the relevant type and
      then set to the current value.  Again signal detail can be used to connect
      handlers to specific state variable callbacks.
    </para>
    <programlisting>static gboolean status;

static void
query_status_cb (GUPnPService *service, char *variable, GValue *value, gpointer user_data)
{
  g_value_init (value, G_TYPE_BOOLEAN);
  g_value_set_boolean (value, status);
}
&hellip;
g_signal_connect (service, "query-variable::Status", G_CALLBACK (query_status_cb), NULL);</programlisting>
    <para>
      For services which have many actions and variables there is a convenience
      method <link linkend="gupnp-service-signals-autoconnect"><function>gupnp_service_signals_autoconnect()</function></link> which will automatically
      connect specially named handlers to signals.  See the documentation for
      full details on how it works.
    </para>
    <para>
      The service is now fully implemented.  To complete it, enter a GLib main
      loop and wait for a client to connect.  The complete source code for this
      example is available as <filename>examples/light-server.c</filename> in
      the GUPnP sources.
    </para>
  </simplesect>
</chapter>