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

<glossary id="glossary">

  <glossentry id="action"><glossterm>Action</glossterm>
  <glossdef>
    <para>
      An <firstterm>Action</firstterm> is a method call on a
      <glossterm>Service</glossterm>, which encapsulated a single piece of
      functionality.  Actions can have multiple input and output arguments, and
      can return error codes.  UPnP allows one of the output arguments to be
      marked as the <firstterm>return value</firstterm>, but GUPnP doesn't treat
      return values specially.
    </para>
    <para>
      Every action argument has a related <glossterm>State Variable</glossterm>,
      which determines the type of the argument.  Note that even if the argument
      wouldn't need a state variable it is still required, due to historical
      reasons.
    </para>
  </glossdef>
  </glossentry>

  <glossentry id="controlpoint"><glossterm>Control Point</glossterm>
  <glossdef>
    <para>
      A <firstterm>Control Point</firstterm> is an entity on the network which
      communicates with other <glossterm>Devices</glossterm> and
      <glossterm>Services</glossterm>.  In the client/server model the control
      point is a client and the <glossterm>Service</glossterm> is a server,
      although it is common for devices to also be a control point because
      whilst a single control point/service connection is client/server, the
      UPnP network as whole is peer-to-peer.
    </para>
  </glossdef>
  </glossentry>

  <glossentry id="device"><glossterm>Device</glossterm>
  <glossdef>
    <para>
      A <firstterm>Device</firstterm> is an entity on the network which
      communicates using the UPnP standards.  This can be a dedicated physical
      device such as a router or printer, or a PC which is running software
      implementing the UPnP standards.
    </para>
    <para>
      A Device can contain sub-devices, for example a combination
      printer/scanner could appear as a general device with a printer
      sub-device and a scanner sub-device.
    </para>
    <para>
      Every device has zero or more <glossterm>Services</glossterm>.  UPnP defines many standard
      device types, which specify services which are required to be implemented.
      Alternatively, a non-standard device type could be used.  Examples of
      standard device types are <literal>MediaRenderer</literal> or
      <literal>InternetGatewayDevice</literal>.
    </para>
    <glossseealso otherterm="service"/>
  </glossdef>
  </glossentry>

  <glossentry>
    <glossterm>DIDL-Lite</glossterm>
    <glosssee otherterm="didllite"/>
  </glossentry>

  <glossentry id="didllite"><glossterm>Digital Item Declaration Language - Lite</glossterm>
  <acronym>DIDL-Lite</acronym>
  <glossdef>
    <para>
      An XML schema used to represent digital content metadata. Defined by
      the UPnP Forum.
    </para>
  </glossdef>
  </glossentry>

  <glossentry>
    <glossterm>SCPD</glossterm>
    <glosssee otherterm="scpd"/>
  </glossentry>

  <glossentry id="service"><glossterm>Service</glossterm>
  <glossdef>
    <para>
      A <firstterm>Service</firstterm> is a collection of related methods
      (called <glossterm>Actions</glossterm>) and public variables (called
      <glossterm>State Variables</glossterm>) which together form a logical
      interface.
    </para>
    <para>
      UPnP defines standard services that define actions and variables which
      must be present and their semantics.  Examples of these are
      <literal>AVTransport</literal> and <literal>WANIPConnection</literal>.
    </para>
    <glossseealso otherterm="action"/>
    <glossseealso otherterm="device"/>
    <glossseealso otherterm="state-variable"/>
  </glossdef>
  </glossentry>

  <glossentry id="scpd">
    <glossterm>Service Control Protocol Document</glossterm>
    <acronym>SCPD</acronym>
    <glossdef>
      <para>
        An XML document which defines the set of <glossterm>Actions</glossterm>
        and <glossterm>State Variables</glossterm> that a
        <glossterm>Service</glossterm> implements.
      </para>
      <glossseealso otherterm="service"/>
      <glossseealso otherterm="action"/>
      <glossseealso otherterm="state-variable"/>
    </glossdef>
  </glossentry>

  <glossentry id="ssdp">
    <glossterm>Simple Service Discovery Protocol</glossterm>
    <acronym>SSDP</acronym>
    <glossdef>
      <para>
        UPnP device discovery protocol. Specifies how <glossterm>Devices</glossterm> 
        advertise their <glossterm>Services</glossterm> in the network and also how 
        <glossterm>Control Points</glossterm> search for
        services and devices respond.
      </para>
      <glossseealso otherterm="device"/>
      <glossseealso otherterm="controlpoint"/>
      <glossseealso otherterm="service"/>
    </glossdef>
  </glossentry>
  
  <glossentry>
    <glossterm>SSDP</glossterm>
    <glosssee otherterm="ssdp"/>
  </glossentry>

  <glossentry id="state-variable"><glossterm>State Variable</glossterm>
  <glossdef>
    <para>
      A <firstterm>State Variable</firstterm> is a public variable exposing some
      aspect of the service's state.  State variables are typed and optionally
      are <firstterm>evented</firstterm>, which means that any changes will be
      notified.  Control points are said to <firstterm>subscribe</firstterm> to
      a state variable to receive change notifications.
    </para>
  </glossdef>
  </glossentry>

  <glossentry>
    <glossterm>UDN</glossterm>
    <glosssee otherterm="udn"/>
  </glossentry>

  <glossentry id="udn">
    <glossterm>Unique Device Name</glossterm>
    <acronym>UDN</acronym>
    <glossdef>
      <para>
        A a unique identifier which is <emphasis>unique</emphasis> for every
        device but <emphasis>never changes</emphasis> for each particular
        device.
      </para>
      <para>
        A common practise is to generate a unique UDN on first boot from a
        random seed, or use some unique and persistent property such as the
        device's MAC address to create the UDN.
      </para>
      <glossseealso otherterm="device"/>
    </glossdef>
  </glossentry>

</glossary>