server-tutorial.html

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

          <name>NewTargetValue</name>
          <relatedStateVariable>Target</relatedStateVariable>
          <direction>in</direction>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>GetTarget</name>
      <argumentList>
        <argument>
          <name>RetTargetValue</name>
          <relatedStateVariable>Target</relatedStateVariable>
          <direction>out</direction>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>GetStatus</name>
      <argumentList>
        <argument>
          <name>ResultStatus</name>
          <relatedStateVariable>Status</relatedStateVariable>
          <direction>out</direction>
        </argument>
      </argumentList>
    </action>
  </actionList>
  <serviceStateTable>
    <stateVariable sendEvents="no">
      <name>Target</name>
      <dataType>boolean</dataType>
      <defaultValue>0</defaultValue>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>Status</name>
      <dataType>boolean</dataType>
      <defaultValue>0</defaultValue>
    </stateVariable>
  </serviceStateTable>
</scpd>
</pre>
<p>
      Again, the <code class="sgmltag-element">specVersion</code> tag defines the UPnP version
      that is being used.  The rest of the document consists of an
      <code class="sgmltag-element">actionList</code> defining the <a class="glossterm" href="glossary.html#action"><em class="glossterm">actions</em></a> available and a
      <code class="sgmltag-element">serviceStateTable</code> defining the <a class="glossterm" href="glossary.html#state-variable"><em class="glossterm">state variables</em></a>.
    </p>
<p>
      Every <code class="sgmltag-element">action</code> has a <code class="sgmltag-element">name</code> and a list
      of <code class="sgmltag-element">argument</code>s.  Arguments also have a name, a direction
      (<code class="literal">in</code> or <code class="literal">out</code> 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 <code class="literal">WANIPConnection</code>
      service is a good example of this), thanks to the legacy behind UPnP.
    </p>
<p>
      <code class="sgmltag-element">stateVariable</code>s need to specify their
      <code class="sgmltag-element">name</code> and <code class="sgmltag-element">dataType</code>.  State variables
      by default send notifications when they change, to specify that a variable
      doesn't do this set the <code class="sgmltag-element">sendEvents</code> attribute to
      <code class="literal">no</code>.  Finally there are optional
      <code class="sgmltag-element">defaultValue</code>, <code class="sgmltag-element">allowedValueList</code> and
      <code class="sgmltag-element">allowedValueRange</code> elements which specify what the
      default and valid values for the variable.
    </p>
<p>
      For the full specification of the service definition file, including a
      complete list of valid <code class="sgmltag-element">dataType</code>s, see section 2.3 of
      the <a class="ulink" href="http://upnp.org/specs/arch/UPnP-DeviceArchitecture-v1.0.pdf" target="_top">UPnP
      Device Architecture</a>.
    </p>
</div>
<div class="simplesect" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id2623799"></a>Implementing the Device</h2></div></div></div>
<p>
      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 <a class="link" href="GUPnPContext.html#gupnp-context-new" title="gupnp_context_new ()"><code class="function">gupnp_context_new()</code></a>.
    </p>
<pre class="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);</pre>
<p>
      UPnP uses HTTP to provide the device and service description files, so
      next we tell GUPnP to publish them.  This is done with
      <a class="link" href="GUPnPContext.html#gupnp-context-host-path" title="gupnp_context_host_path ()"><code class="function">gupnp_context_host_path()</code></a> which takes a local filename to send when a
      certain server path is requested.
    </p>
<pre class="programlisting">gupnp_context_host_path (context, "BinaryLight1.xml", "/BinaryLight1.xml");
gupnp_context_host_path (context, "SwitchPower1.xml", "/SwitchPower1.xml");</pre>
<p>
      Next the root device can be created. 
    </p>
<pre class="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);</pre>
<p>
      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.
    </p>
</div>
<div class="simplesect" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id2586848"></a>Implementing a Service</h2></div></div></div>
<p>
      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
      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
      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
      returns a <a class="link" href="GUPnPServiceInfo.html" title="GUPnPServiceInfo"><span class="type">GUPnPServiceInfo</span></a> which again is an interface, implemented by
      <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).
    </p>
<pre class="programlisting">GUPnPServiceInfo *service;
service = gupnp_device_info_get_service
  (GUPNP_DEVICE_INFO (dev), "urn:schemas-upnp-org:service:SwitchPower:1");</pre>
<p>
      <a class="link" href="GUPnPService.html" title="GUPnPService"><span class="type">GUPnPService</span></a> 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: <a class="link" href="GUPnPService.html#GUPnPService-action-invoked" title='The "action-invoked" signal'><span class="type">"action-invoked"</span></a> and
      <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
      when a client invokes an action: the handler is passed a
      <a class="link" href="GUPnPService.html#GUPnPServiceAction" title="GUPnPServiceAction"><span class="type">GUPnPServiceAction</span></a> object that identifies which action was invoked, and
      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>.
      <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
      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 <span class="type">GValue</span> which should be set to the current
      value of the variable.
    </p>
<p>
      There are two approaches that clients can take to handle these signals.
      They can either connect a single handler to <a class="link" href="GUPnPService.html#GUPnPService-action-invoked" title='The "action-invoked" signal'><span class="type">"action-invoked"</span></a>
      or <a class="link" href="GUPnPService.html#GUPnPService-query-variable" title='The "query-variable" signal'><span class="type">"query-variable"</span></a> and examine the arguments to decide what
      action to take.  Alternatively, handlers can be targetted at specific
      actions or variables by using the <em class="firstterm">signal detail</em>
      when connecting.  For example, this causes
      <code class="function">on_get_status_action</code> to be called when the
      <code class="function">GetStatus</code> action is invoked:
    </p>
<pre class="programlisting">static void on_get_status_action (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data);
鈥