diff options
| author | Jens Georg <mail@jensge.org> | 2022-01-03 11:16:36 +0100 |
|---|---|---|
| committer | Jens Georg <mail@jensge.org> | 2022-01-03 19:10:51 +0100 |
| commit | fac219f8d38969cb364580b66297fa08fc90914c (patch) | |
| tree | 1dc2f0be189b7d4f070a426d4d194e566cd51c76 /doc | |
| parent | 0986455bdf9b01e63bb171f068b13ed2fcd557ee (diff) | |
| download | gupnp-fac219f8d38969cb364580b66297fa08fc90914c.tar.gz | |
doc: Remove old gtk-doc files
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/client-tutorial.xml | 215 | ||||
| -rw-r--r-- | doc/fdl-1.1.xml | 466 | ||||
| -rw-r--r-- | doc/glossary.xml | 173 | ||||
| -rw-r--r-- | doc/gupnp-docs.xml | 189 | ||||
| -rw-r--r-- | doc/gupnp-overrides.txt | 0 | ||||
| -rw-r--r-- | doc/gupnp-sections.txt | 543 | ||||
| -rw-r--r-- | doc/gupnp.types | 26 | ||||
| -rw-r--r-- | doc/overview.xml | 34 | ||||
| -rw-r--r-- | doc/server-tutorial.xml | 323 |
9 files changed, 0 insertions, 1969 deletions
diff --git a/doc/client-tutorial.xml b/doc/client-tutorial.xml deleted file mode 100644 index 98d528c..0000000 --- a/doc/client-tutorial.xml +++ /dev/null @@ -1,215 +0,0 @@ -<?xml version='1.0' encoding='UTF-8'?> -<!-- This document was created with Syntext Serna Free. --> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" []> -<chapter id="client-tutorial"> - <title>Writing an UPnP Client</title> - <simplesect> - <title>Introduction</title> - <para> - This chapter explains how to write an application which fetches the - external IP address from an UPnP-compliant modem. To do this a - <glossterm>Control Point</glossterm> is created, which searches for - services of the type - <literal>urn:schemas-upnp-org:service:WANIPConnection:1</literal> (part of - the <ulink url="http://upnp.org/standardizeddcps/igd.asp">Internet Gateway Device</ulink> specification). As services are discovered - <firstterm>Service Proxy</firstterm> objects are created by GUPnP to allow - interaction with the service, on which we can invoke the action - <function>GetExternalIPAddress</function> to fetch the external IP - address. - </para> - </simplesect> - <simplesect> - <title>Finding Services</title> - <para> - First, we initialize GUPnP and create a control point targeting the - service type. Then we connect a signal handler so that we are notified - when services we are interested in are found. - </para> - <programlisting>#include <libgupnp/gupnp-control-point.h> - -static GMainLoop *main_loop; - -static void -service_proxy_available_cb (GUPnPControlPoint *cp, - GUPnPServiceProxy *proxy, - gpointer userdata) -{ - /* … */ -} - -int -main (int argc, char **argv) -{ - GUPnPContext *context; - GUPnPControlPoint *cp; - - /* Create a new GUPnP Context. By here we are using the default GLib main - context, and connecting to the current machine's default IP on an - automatically generated port. */ - context = gupnp_context_new (NULL, 0, NULL); - - /* Create a Control Point targeting WAN IP Connection services */ - cp = gupnp_control_point_new - (context, "urn:schemas-upnp-org:service:WANIPConnection:1"); - - /* The service-proxy-available signal is emitted when any services which match - our target are found, so connect to it */ - g_signal_connect (cp, - "service-proxy-available", - G_CALLBACK (service_proxy_available_cb), - NULL); - - /* Tell the Control Point to start searching */ - gssdp_resource_browser_set_active (GSSDP_RESOURCE_BROWSER (cp), TRUE); - - /* Enter the main loop. This will start the search and result in callbacks to - service_proxy_available_cb. */ - main_loop = g_main_loop_new (NULL, FALSE); - g_main_loop_run (main_loop); - - /* Clean up */ - g_main_loop_unref (main_loop); - g_object_unref (cp); - g_object_unref (context); - - return 0; -}</programlisting> - </simplesect> - <simplesect> - <title>Invoking Actions</title> - <para> - Now we have an application which searches for the service we specified and - calls <function>service_proxy_available_cb</function> for each one it - found. To get the external IP address we need to invoke the - <literal>GetExternalIPAddress</literal> action. This action takes no in - arguments, and has a single out argument called "NewExternalIPAddress". - GUPnP has a set of methods to invoke actions (which will be very familiar - to anyone who has used <literal>dbus-glib</literal>) where you pass a - <constant>NULL</constant>-terminated varargs list of (name, GType, value) - tuples for the in arguments, then a <constant>NULL</constant>-terminated - varargs list of (name, GType, return location) tuples for the out - arguments. - </para> - <programlisting>static void -service_proxy_available_cb (GUPnPControlPoint *cp, - GUPnPServiceProxy *proxy, - gpointer userdata) -{ - GError *error = NULL; - char *ip = NULL; - GUPnPServiceProxyAction *action = NULL; - - action = gupnp_service_proxy_action_new ( - /* Action name */ - "GetExternalIPAddress", - /* IN args */ - NULL); - gupnp_service_proxy_call_action (proxy, - action, - NULL, - &error); - if (error != NULL) { - goto out; - } - - gupnp_service_proxy_action_get_result (action, - /* Error location */ - &error, - /* OUT args */ - "NewExternalIPAddress", - G_TYPE_STRING, &ip, - NULL); - - if (error == NULL) { - g_print ("External IP address is %s\n", ip); - g_free (ip); - } - -out: - if (error != NULL) { - g_printerr ("Error: %s\n", error->message); - g_error_free (error); - } - - gupnp_service_proxy_action_unref (action); - g_main_loop_quit (main_loop); -}</programlisting> - <para>Note that gupnp_service_proxy_call_action() blocks until the service has - replied. If you need to make non-blocking calls then use - gupnp_service_proxy_call_action_async(), which takes a callback that will be - called from the mainloop when the reply is received. - </para> - </simplesect> - <simplesect> - <title>Subscribing to state variable change notifications</title> - <para> - It is possible to get change notifications for the service state variables - that have attribute <literal>sendEvents="yes"</literal>. We'll demonstrate - this by modifying <function>service_proxy_available_cb</function> and using - gupnp_service_proxy_add_notify() to setup a notification callback: - </para> - <programlisting>static void -external_ip_address_changed (GUPnPServiceProxy *proxy, - const char *variable, - GValue *value, - gpointer userdata) -{ - g_print ("External IP address changed: %s\n", g_value_get_string (value)); -} - -static void -service_proxy_available_cb (GUPnPControlPoint *cp, - GUPnPServiceProxy *proxy, - gpointer userdata) -{ - g_print ("Found a WAN IP Connection service\n"); - - gupnp_service_proxy_set_subscribed (proxy, TRUE); - if (!gupnp_service_proxy_add_notify (proxy, - "ExternalIPAddress", - G_TYPE_STRING, - external_ip_address_changed, - NULL)) { - g_printerr ("Failed to add notify"); - } -}</programlisting> - </simplesect> - <simplesect> - <title>Generating Wrappers</title> - <para> - Using gupnp_service_proxy_call_action() and gupnp_service_proxy_add_notify () - can become tedious, because of the requirement to specify the types and deal - with GValues. An - alternative is to use <xref linkend="gupnp-binding-tool"/>, which - generates wrappers that hide the boilerplate code from you. Using a - wrapper generated with prefix 'ipconn' would replace - gupnp_service_proxy_call_action() with this code: - </para> - <programlisting>ipconn_get_external_ip_address (proxy, &ip, &error);</programlisting> - <para> - State variable change notifications are friendlier with wrappers as well: - </para> - <programlisting>static void -external_ip_address_changed (GUPnPServiceProxy *proxy, - const gchar *external_ip_address, - gpointer userdata) -{ - g_print ("External IP address changed: '%s'\n", external_ip_address); -} - -static void -service_proxy_available_cb (GUPnPControlPoint *cp, - GUPnPServiceProxy *proxy - gpointer userdata) -{ - g_print ("Found a WAN IP Connection service\n"); - - gupnp_service_proxy_set_subscribed (proxy, TRUE); - if (!ipconn_external_ip_address_add_notify (proxy, - external_ip_address_changed, - NULL)) { - g_printerr ("Failed to add notify"); - } -}</programlisting> - </simplesect> -</chapter> diff --git a/doc/fdl-1.1.xml b/doc/fdl-1.1.xml deleted file mode 100644 index 4857ad1..0000000 --- a/doc/fdl-1.1.xml +++ /dev/null @@ -1,466 +0,0 @@ -<appendix id="gfdl"> -<title>GNU Free Documentation License</title> -<!-- - GNU Project - Free Software Foundation (FSF) --> -<!-- LINK REV="made" HREF="mailto:webmasters@gnu.org" --> - - - <!-- sect1> - <title>GNU Free Documentation License</title --> - - <para>Version 1.1, March 2000</para> - - <blockquote id="fsf-copyright"> - <para>Copyright (C) 2000 Free Software Foundation, Inc. -51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed.</para> - </blockquote> - - <sect1 id="gfdl-0"> - <title>PREAMBLE</title> - - <para>The purpose of this License is to make a manual, textbook, - or other written document "free" in the sense of freedom: to - assure everyone the effective freedom to copy and redistribute it, - with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the - author and publisher a way to get credit for their work, while not - being considered responsible for modifications made by - others.</para> - - <para>This License is a kind of "copyleft", which means that - derivative works of the document must themselves be free in the - same sense. It complements the GNU General Public License, which - is a copyleft license designed for free software.</para> - - <para>We have designed this License in order to use it for manuals - for free software, because free software needs free documentation: - a free program should come with manuals providing the same - freedoms that the software does. But this License is not limited - to software manuals; it can be used for any textual work, - regardless of subject matter or whether it is published as a - printed book. We recommend this License principally for works - whose purpose is instruction or reference.</para> - </sect1> - - <sect1 id="gfdl-1"> - <title>APPLICABILITY AND DEFINITIONS</title> - - <para>This License applies to any manual or other work that - contains a notice placed by the copyright holder saying it can be - distributed under the terms of this License. The "Document", - below, refers to any such manual or work. Any member of the - public is a licensee, and is addressed as "you".</para> - - <para>A "Modified Version" of the Document means any work - containing the Document or a portion of it, either copied - verbatim, or with modifications and/or translated into another - language.</para> - - <para>A "Secondary Section" is a named appendix or a front-matter - section of the Document that deals exclusively with the - relationship of the publishers or authors of the Document to the - Document's overall subject (or to related matters) and contains - nothing that could fall directly within that overall subject. - (For example, if the Document is in part a textbook of - mathematics, a Secondary Section may not explain any mathematics.) - The relationship could be a matter of historical connection with - the subject or with related matters, or of legal, commercial, - philosophical, ethical or political position regarding - them.</para> - - <para>The "Invariant Sections" are certain Secondary Sections - whose titles are designated, as being those of Invariant Sections, - in the notice that says that the Document is released under this - License.</para> - - <para>The "Cover Texts" are certain short passages of text that - are listed, as Front-Cover Texts or Back-Cover Texts, in the - notice that says that the Document is released under this - License.</para> - - <para>A "Transparent" copy of the Document means a - machine-readable copy, represented in a format whose specification - is available to the general public, whose contents can be viewed - and edited directly and straightforwardly with generic text - editors or (for images composed of pixels) generic paint programs - or (for drawings) some widely available drawing editor, and that - is suitable for input to text formatters or for automatic - translation to a variety of formats suitable for input to text - formatters. A copy made in an otherwise Transparent file format - whose markup has been designed to thwart or discourage subsequent - modification by readers is not Transparent. A copy that is not - "Transparent" is called "Opaque".</para> - - <para>Examples of suitable formats for Transparent copies include - plain ASCII without markup, Texinfo input format, LaTeX input - format, SGML or XML using a publicly available DTD, and - standard-conforming simple HTML designed for human modification. - Opaque formats include PostScript, PDF, proprietary formats that - can be read and edited only by proprietary word processors, SGML - or XML for which the DTD and/or processing tools are not generally - available, and the machine-generated HTML produced by some word - processors for output purposes only.</para> - - <para>The "Title Page" means, for a printed book, the title page - itself, plus such following pages as are needed to hold, legibly, - the material this License requires to appear in the title page. - For works in formats which do not have any title page as such, - "Title Page" means the text near the most prominent appearance of - the work's title, preceding the beginning of the body of the - text.</para> - </sect1> - - <sect1 id="gfdl-2"> - <title>VERBATIM COPYING</title> - - <para>You may copy and distribute the Document in any medium, - either commercially or noncommercially, provided that this - License, the copyright notices, and the license notice saying this - License applies to the Document are reproduced in all copies, and - that you add no other conditions whatsoever to those of this - License. You may not use technical measures to obstruct or - control the reading or further copying of the copies you make or - distribute. However, you may accept compensation in exchange for - copies. If you distribute a large enough number of copies you - must also follow the conditions in section 3.</para> - - <para>You may also lend copies, under the same conditions stated - above, and you may publicly display copies.</para> - </sect1> - - <sect1 id="gfdl-3"> - <title>COPYING IN QUANTITY</title> - - <para>If you publish printed copies of the Document numbering more - than 100, and the Document's license notice requires Cover Texts, - you must enclose the copies in covers that carry, clearly and - legibly, all these Cover Texts: Front-Cover Texts on the front - cover, and Back-Cover Texts on the back cover. Both covers must - also clearly and legibly identify you as the publisher of these - copies. The front cover must present the full title with all - words of the title equally prominent and visible. You may add - other material on the covers in addition. Copying with changes - limited to the covers, as long as they preserve the title of the - Document and satisfy these conditions, can be treated as verbatim - copying in other respects.</para> - - <para>If the required texts for either cover are too voluminous to - fit legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages.</para> - - <para>If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a - machine-readable Transparent copy along with each Opaque copy, or - state in or with each Opaque copy a publicly-accessible - computer-network location containing a complete Transparent copy - of the Document, free of added material, which the general - network-using public has access to download anonymously at no - charge using public-standard network protocols. If you use the - latter option, you must take reasonably prudent steps, when you - begin distribution of Opaque copies in quantity, to ensure that - this Transparent copy will remain thus accessible at the stated - location until at least one year after the last time you - distribute an Opaque copy (directly or through your agents or - retailers) of that edition to the public.</para> - - <para>It is requested, but not required, that you contact the - authors of the Document well before redistributing any large - number of copies, to give them a chance to provide you with an - updated version of the Document.</para> - </sect1> - - <sect1 id="gfdl-4"> - <title>MODIFICATIONS</title> - - <para>You may copy and distribute a Modified Version of the - Document under the conditions of sections 2 and 3 above, provided - that you release the Modified Version under precisely this - License, with the Modified Version filling the role of the - Document, thus licensing distribution and modification of the - Modified Version to whoever possesses a copy of it. In addition, - you must do these things in the Modified Version:</para> - - <orderedlist numeration="upperalpha"> - <listitem><para>Use in the Title Page - (and on the covers, if any) a title distinct from that of the - Document, and from those of previous versions (which should, if - there were any, be listed in the History section of the - Document). You may use the same title as a previous version if - the original publisher of that version gives permission.</para> - </listitem> - - <listitem><para>List on the Title Page, - as authors, one or more persons or entities responsible for - authorship of the modifications in the Modified Version, - together with at least five of the principal authors of the - Document (all of its principal authors, if it has less than - five).</para> - </listitem> - - <listitem><para>State on the Title page - the name of the publisher of the Modified Version, as the - publisher.</para> - </listitem> - - <listitem><para>Preserve all the - copyright notices of the Document.</para> - </listitem> - - <listitem><para>Add an appropriate - copyright notice for your modifications adjacent to the other - copyright notices.</para> - </listitem> - - <listitem><para>Include, immediately - after the copyright notices, a license notice giving the public - permission to use the Modified Version under the terms of this - License, in the form shown in the Addendum below.</para> - </listitem> - - <listitem><para>Preserve in that license - notice the full lists of Invariant Sections and required Cover - Texts given in the Document's license notice.</para> - </listitem> - - <listitem><para>Include an unaltered - copy of this License.</para> - </listitem> - - <listitem><para>Preserve the section - entitled "History", and its title, and add to it an item stating - at least the title, year, new authors, and publisher of the - Modified Version as given on the Title Page. If there is no - section entitled "History" in the Document, create one stating - the title, year, authors, and publisher of the Document as given - on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence.</para> - </listitem> - - <listitem><para>Preserve the network - location, if any, given in the Document for public access to a - Transparent copy of the Document, and likewise the network - locations given in the Document for previous versions it was - based on. These may be placed in the "History" section. You - may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission.</para> - </listitem> - - <listitem><para>In any section entitled - "Acknowledgements" or "Dedications", preserve the section's - title, and preserve in the section all the substance and tone of - each of the contributor acknowledgements and/or dedications - given therein.</para> - </listitem> - - <listitem><para>Preserve all the - Invariant Sections of the Document, unaltered in their text and - in their titles. Section numbers or the equivalent are not - considered part of the section titles.</para> - </listitem> - - <listitem><para>Delete any section - entitled "Endorsements". Such a section may not be included in - the Modified Version.</para> - </listitem> - - <listitem><para>Do not retitle any - existing section as "Endorsements" or to conflict in title with - any Invariant Section.</para> - </listitem> - </orderedlist> - - <para>If the Modified Version includes new front-matter sections - or appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option - designate some or all of these sections as invariant. To do this, - add their titles to the list of Invariant Sections in the Modified - Version's license notice. These titles must be distinct from any - other section titles.</para> - - <para>You may add a section entitled "Endorsements", provided it - contains nothing but endorsements of your Modified Version by - various parties--for example, statements of peer review or that - the text has been approved by an organization as the authoritative - definition of a standard.</para> - - <para>You may add a passage of up to five words as a Front-Cover - Text, and a passage of up to 25 words as a Back-Cover Text, to the - end of the list of Cover Texts in the Modified Version. Only one - passage of Front-Cover Text and one of Back-Cover Text may be - added by (or through arrangements made by) any one entity. If the - Document already includes a cover text for the same cover, - previously added by you or by arrangement made by the same entity - you are acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous - publisher that added the old one.</para> - - <para>The author(s) and publisher(s) of the Document do not by - this License give permission to use their names for publicity for - or to assert or imply endorsement of any Modified Version.</para> - </sect1> - - <sect1 id="gfdl-5"> - <title>COMBINING DOCUMENTS</title> - - <para>You may combine the Document with other documents released - under this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination - all of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice.</para> - - <para>The combined work need only contain one copy of this - License, and multiple identical Invariant Sections may be replaced - with a single copy. If there are multiple Invariant Sections with - the same name but different contents, make the title of each such - section unique by adding at the end of it, in parentheses, the - name of the original author or publisher of that section if known, - or else a unique number. Make the same adjustment to the section - titles in the list of Invariant Sections in the license notice of - the combined work.</para> - - <para>In the combination, you must combine any sections entitled - "History" in the various original documents, forming one section - entitled "History"; likewise combine any sections entitled - "Acknowledgements", and any sections entitled "Dedications". You - must delete all sections entitled "Endorsements."</para> - </sect1> - - <sect1 id="gfdl-6"> - <title>COLLECTIONS OF DOCUMENTS</title> - - <para>You may make a collection consisting of the Document and - other documents released under this License, and replace the - individual copies of this License in the various documents with a - single copy that is included in the collection, provided that you - follow the rules of this License for verbatim copying of each of - the documents in all other respects.</para> - - <para>You may extract a single document from such a collection, - and distribute it individually under this License, provided you - insert a copy of this License into the extracted document, and - follow this License in all other respects regarding verbatim - copying of that document.</para> - </sect1> - - <sect1 id="gfdl-7"> - <title>AGGREGATION WITH INDEPENDENT WORKS</title> - - <para>A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of - a storage or distribution medium, does not as a whole count as a - Modified Version of the Document, provided no compilation - copyright is claimed for the compilation. Such a compilation is - called an "aggregate", and this License does not apply to the - other self-contained works thus compiled with the Document, on - account of their being thus compiled, if they are not themselves - derivative works of the Document.</para> - - <para>If the Cover Text requirement of section 3 is applicable to - these copies of the Document, then if the Document is less than - one quarter of the entire aggregate, the Document's Cover Texts - may be placed on covers that surround only the Document within the - aggregate. Otherwise they must appear on covers around the whole - aggregate.</para> - </sect1> - - <sect1 id="gfdl-8"> - <title>TRANSLATION</title> - - <para>Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires - special permission from their copyright holders, but you may - include translations of some or all Invariant Sections in addition - to the original versions of these Invariant Sections. You may - include a translation of this License provided that you also - include the original English version of this License. In case of - a disagreement between the translation and the original English - version of this License, the original English version will - prevail.</para> - </sect1> - - <sect1 id="gfdl-9"> - <title>TERMINATION</title> - - <para>You may not copy, modify, sublicense, or distribute the - Document except as expressly provided for under this License. Any - other attempt to copy, modify, sublicense or distribute the - Document is void, and will automatically terminate your rights - under this License. However, parties who have received copies, or - rights, from you under this License will not have their licenses - terminated so long as such parties remain in full - compliance.</para> - </sect1> - - <sect1 id="gfdl-10"> - <title>FUTURE REVISIONS OF THIS LICENSE</title> - - <para>The Free Software Foundation may publish new, revised - versions of the GNU Free Documentation License from time to time. - Such new versions will be similar in spirit to the present - version, but may differ in detail to address new problems or - concerns. See <ulink - url="https://www.gnu.org/licenses/">https://www.gnu.org/licenses/</ulink>.</para> - - <para>Each version of the License is given a distinguishing - version number. If the Document specifies that a particular - numbered version of this License "or any later version" applies to - it, you have the option of following the terms and conditions - either of that specified version or of any later version that has - been published (not as a draft) by the Free Software Foundation. - If the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by the - Free Software Foundation.</para> - </sect1> - - <sect1 id="gfdl-11"> - <title>How to use this License for your documents</title> - - <para>To use this License in a document you have written, include - a copy of the License in the document and put the following - copyright and license notices just after the title page:</para> - -<blockquote id="sample-copyright"><para> - Copyright (c) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - A copy of the license is included in the section entitled "GNU - Free Documentation License". -</para></blockquote> - - <para>If you have no Invariant Sections, write "with no Invariant - Sections" instead of saying which ones are invariant. If you have - no Front-Cover Texts, write "no Front-Cover Texts" instead of - "Front-Cover Texts being LIST"; likewise for Back-Cover - Texts.</para> - - <para>If your document contains nontrivial examples of program - code, we recommend releasing these examples in parallel under your - choice of free software license, such as the GNU General Public - License, to permit their use in free software.</para> - </sect1> - -</appendix> -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:nil -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:2 -sgml-parent-document: ("referenz.sgml" "appendix") -sgml-exposed-tags:nil -sgml-local-ecat-files:nil -sgml-local-catalogs: CATALOG -sgml-validate-command: "nsgmls -s referenz.sgml" -ispell-skip-sgml: t -End: ---> diff --git a/doc/glossary.xml b/doc/glossary.xml deleted file mode 100644 index 7c41f7c..0000000 --- a/doc/glossary.xml +++ /dev/null @@ -1,173 +0,0 @@ -<?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> diff --git a/doc/gupnp-docs.xml b/doc/gupnp-docs.xml deleted file mode 100644 index 1101042..0000000 --- a/doc/gupnp-docs.xml +++ /dev/null @@ -1,189 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> -<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> - <bookinfo> - <title>GUPnP Reference Manual</title> - - <releaseinfo>Version <xi:include href="version.xml" parse="text"/></releaseinfo> - - <copyright> - <year>2007</year> - <year>2008</year> - <year>2009</year> - <holder>OpenedHand Ltd</holder> - <holder>Nokia Corporation</holder> - </copyright> - - <legalnotice> - <para> - Permission is granted to copy, distribute and/or modify this - document under the terms of the <citetitle>GNU Free - Documentation License</citetitle>, Version 1.1 or any later - version published by the Free Software Foundation with no - Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. - </para> - <para> - A copy of the license is included in the section entitled "GNU - Free Documentation License". - </para> - </legalnotice> - </bookinfo> - - <part id="tutorial"> - <title>Tutorial</title> - <xi:include href="overview.xml"/> - <xi:include href="xml/client-tutorial.xml"/> - <xi:include href="xml/server-tutorial.xml"/> - </part> - - <part id="api"> - <title>Reference</title> - - <chapter id="api-device-info"> - <title>Device Information</title> - - <xi:include href="xml/gupnp-device-info.xml"/> - <xi:include href="xml/gupnp-service-info.xml"/> - <xi:include href="xml/gupnp-service-introspection.xml"/> - </chapter> - - <chapter id="api-device-control"> - <title>Device Control</title> - - <xi:include href="xml/gupnp-control-point.xml"/> - <xi:include href="xml/gupnp-device-proxy.xml"/> - <xi:include href="xml/gupnp-service-proxy.xml"/> - </chapter> - - <chapter id="api-device-impl"> - <title>Device Implementation</title> - - <xi:include href="xml/gupnp-device.xml"/> - <xi:include href="xml/gupnp-root-device.xml"/> - <xi:include href="xml/gupnp-service.xml"/> - </chapter> - - <chapter id="api-context"> - <title>Network context handling</title> - - <xi:include href="xml/gupnp-context.xml"/> - <xi:include href="xml/gupnp-context-manager.xml"/> - </chapter> - - <chapter id="api-utility"> - <title>Utility Functions</title> - - <xi:include href="xml/gupnp-acl.xml"/> - <xi:include href="xml/gupnp-white-list.xml"/> - <xi:include href="xml/gupnp-resource-factory.xml"/> - <xi:include href="xml/gupnp-xml-doc.xml"/> - <xi:include href="xml/gupnp-error.xml"/> - <xi:include href="xml/gupnp-types.xml"/> - <xi:include href="xml/gupnp-misc.xml"/> - </chapter> - - <chapter id="api-tools"> - <title>Tools</title> - <xi:include href="gupnp-binding-tool.xml"/> - </chapter> - </part> - - <part id="schemas"> - <title>XML Schemas</title> - <chapter id="schemas-device"> - <title>Device Description</title> - <para> - This is the schema for the UPnP Device Description document, in the - RELAX NG Compact syntax. - </para> - <programlisting><xi:include href="device-description.rnc" parse="text"/></programlisting> - </chapter> - <chapter id="schemas-service"> - <title>Service Description</title> - <para> - This is the schema for the UPnP Service Description document, in the - RELAX NG Compact syntax. - </para> - <programlisting><xi:include href="service-description.rnc" parse="text"/></programlisting> - </chapter> - </part> - - <xi:include href="glossary.xml"/> - - <index id="api-index-full"> - <title>Index of all symbols</title> - <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-index-deprecated" role="deprecated"> - <title>Index of deprecated symbols</title> - <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-index-0-12-3" role="0.12.3"> - <title>Index of new symbols in 0.12.3</title> - <xi:include href="xml/api-index-0.12.3.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-index-0-14-0" role="0.14.0"> - <title>Index of new symbols in 0.14.0</title> - <xi:include href="xml/api-index-0.14.0.xml"><xi:fallback /></xi:include> - </index> - - - <index id="api-index-0-18-0" role="0.18.9"> - <title>Index of new symbols in 0.18.0</title> - <xi:include href="xml/api-index-0.18.0.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-index-0-20-0" role="0.20.0"> - <title>Index of new symbols in 0.20.0</title> - <xi:include href="xml/api-index-0.20.0.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-index-0-20-3" role="0.20.3"> - <title>Index of new symbols in 0.20.3</title> - <xi:include href="xml/api-index-0.20.3.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-index-0-20-4" role="0.20.4"> - <title>Index of new symbols in 0.20.4</title> - <xi:include href="xml/api-index-0.20.4.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-index-0-20-5" role="0.20.5"> - <title>Index of new symbols in 0.20.5</title> - <xi:include href="xml/api-index-0.20.5.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-index-0-20-8" role="0.20.8"> - <title>Index of new symbols in 0.20.8</title> - <xi:include href="xml/api-index-0.20.8.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-index-0-20-9" role="0.20.9"> - <title>Index of new symbols in 0.20.9</title> - <xi:include href="xml/api-index-0.20.9.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-index-0-20-11" role="0.20.11"> - <title>Index of new symbols in 0.20.11</title> - <xi:include href="xml/api-index-0.20.11.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-index-0-20-12" role="0.20.12"> - <title>Index of new symbols in 0.20.12</title> - <xi:include href="xml/api-index-0.20.12.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-index-1-2-0" role="1.2.0"> - <title>Index of new symbols in 1.2.0</title> - <xi:include href="xml/api-index-1.2.0.xml"><xi:fallback /></xi:include> - </index> - - <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> - - <xi:include href="fdl-1.1.xml"><xi:fallback /></xi:include> - -</book> diff --git a/doc/gupnp-overrides.txt b/doc/gupnp-overrides.txt deleted file mode 100644 index e69de29..0000000 --- a/doc/gupnp-overrides.txt +++ /dev/null diff --git a/doc/gupnp-sections.txt b/doc/gupnp-sections.txt deleted file mode 100644 index 05bda68..0000000 --- a/doc/gupnp-sections.txt +++ /dev/null @@ -1,543 +0,0 @@ -<SECTION> -<FILE>gupnp-control-point</FILE> -<TITLE>GUPnPControlPoint</TITLE> -GUPnPControlPoint -gupnp_control_point_new -gupnp_control_point_new_full -gupnp_control_point_get_resource_factory -gupnp_control_point_get_context -gupnp_control_point_list_device_proxies -gupnp_control_point_list_service_proxies -<SUBSECTION Standard> -GUPnPControlPointClass -GUPNP_CONTROL_POINT -GUPNP_IS_CONTROL_POINT -GUPNP_TYPE_CONTROL_POINT -gupnp_control_point_get_type -GUPNP_CONTROL_POINT_CLASS -GUPNP_IS_CONTROL_POINT_CLASS -GUPNP_CONTROL_POINT_GET_CLASS -<SUBSECTION Private> -GUPnPControlPointPrivate -</SECTION> - -<SECTION> -<FILE>gupnp-device-info</FILE> -<TITLE>GUPnPDeviceInfo</TITLE> -GUPnPDeviceInfo -gupnp_device_info_get_resource_factory -gupnp_device_info_get_context -gupnp_device_info_get_location -gupnp_device_info_get_url_base -gupnp_device_info_get_udn -gupnp_device_info_get_device_type -gupnp_device_info_get_friendly_name -gupnp_device_info_get_manufacturer -gupnp_device_info_get_manufacturer_url -gupnp_device_info_get_model_description -gupnp_device_info_get_model_name -gupnp_device_info_get_model_number -gupnp_device_info_get_model_url -gupnp_device_info_get_serial_number -gupnp_device_info_get_presentation_url -gupnp_device_info_get_upc -gupnp_device_info_get_icon_url -gupnp_device_info_list_dlna_capabilities -gupnp_device_info_list_dlna_device_class_identifier -gupnp_device_info_get_description_value -gupnp_device_info_list_devices -gupnp_device_info_list_device_types -gupnp_device_info_get_device -gupnp_device_info_list_services -gupnp_device_info_list_service_types -gupnp_device_info_get_service -<SUBSECTION Standard> -GUPnPDeviceInfoClass -GUPNP_DEVICE_INFO -GUPNP_IS_DEVICE_INFO -GUPNP_TYPE_DEVICE_INFO -gupnp_device_info_get_type -GUPNP_DEVICE_INFO_CLASS -GUPNP_IS_DEVICE_INFO_CLASS -GUPNP_DEVICE_INFO_GET_CLASS -<SUBSECTION Private> -GUPnPDeviceInfoPrivate -</SECTION> - -<SECTION> -<FILE>gupnp-service-proxy</FILE> -<TITLE>GUPnPServiceProxy</TITLE> -GUPnPServiceProxy -GUPnPServiceProxyAction -GUPnPServiceProxyActionCallback -GUPnPServiceProxyNotifyCallback -gupnp_service_proxy_call_action -gupnp_service_proxy_call_action_async -gupnp_service_proxy_call_action_finish -gupnp_service_proxy_send_action -gupnp_service_proxy_send_action_valist -gupnp_service_proxy_send_action_list -gupnp_service_proxy_begin_action -gupnp_service_proxy_begin_action_valist -gupnp_service_proxy_begin_action_list -gupnp_service_proxy_end_action -gupnp_service_proxy_end_action_valist -gupnp_service_proxy_end_action_hash -gupnp_service_proxy_end_action_list -gupnp_service_proxy_cancel_action -gupnp_service_proxy_add_notify -gupnp_service_proxy_add_notify_full -gupnp_service_proxy_add_raw_notify -gupnp_service_proxy_remove_notify -gupnp_service_proxy_remove_raw_notify -gupnp_service_proxy_set_subscribed -gupnp_service_proxy_get_subscribed -<SUBSECTION GUPnPServiceProxyAction> -gupnp_service_proxy_action_new -gupnp_service_proxy_action_new_from_list -gupnp_service_proxy_action_ref -gupnp_service_proxy_action_unref -gupnp_service_proxy_action_set -gupnp_service_proxy_action_get_result -gupnp_service_proxy_action_get_result_hash -gupnp_service_proxy_action_get_result_list -<SUBSECTION Standard> -gupnp_service_proxy_action_get_type -GUPnPServiceProxyClass -GUPNP_SERVICE_PROXY -GUPNP_IS_SERVICE_PROXY -GUPNP_TYPE_SERVICE_PROXY -gupnp_service_proxy_get_type -GUPNP_SERVICE_PROXY_CLASS -GUPNP_IS_SERVICE_PROXY_CLASS -GUPNP_SERVICE_PROXY_GET_CLASS -<SUBSECTION Private> -GUPnPServiceProxyPrivate -OUT_HASH_TABLE_TO_VAR_ARGS -VALUE_LCOPY_SKIP -VAR_ARGS_TO_IN_LIST -VAR_ARGS_TO_OUT_HASH_TABLE -</SECTION> - -<SECTION> -<FILE>gupnp-service</FILE> -<TITLE>GUPnPService</TITLE> -GUPnPService -GUPnPServiceAction -gupnp_service_action_get_name -gupnp_service_action_get_locales -gupnp_service_action_get -gupnp_service_action_get_valist -gupnp_service_action_get_value -gupnp_service_action_get_gvalue -gupnp_service_action_get_values -gupnp_service_action_set -gupnp_service_action_set_valist -gupnp_service_action_set_value -gupnp_service_action_set_values -gupnp_service_action_return -gupnp_service_action_return_error -gupnp_service_action_get_message -gupnp_service_action_get_argument_count -gupnp_service_notify -gupnp_service_notify_valist -gupnp_service_notify_value -gupnp_service_freeze_notify -gupnp_service_thaw_notify -gupnp_service_signals_autoconnect -<SUBSECTION Standard> -GUPnPServiceClass -GUPNP_SERVICE -GUPNP_IS_SERVICE -GUPNP_TYPE_SERVICE -gupnp_service_get_type -GUPNP_SERVICE_CLASS -GUPNP_IS_SERVICE_CLASS -GUPNP_SERVICE_GET_CLASS -GUPNP_TYPE_SERVICE_ACTION -gupnp_service_action_get_type -<SUBSECTION Private> -GUPnPServicePrivate -</SECTION> - -<SECTION> -<FILE>gupnp-root-device</FILE> -<TITLE>GUPnPRootDevice</TITLE> -GUPnPRootDevice -gupnp_root_device_new -gupnp_root_device_new_full -gupnp_root_device_set_available -gupnp_root_device_get_available -gupnp_root_device_get_relative_location -gupnp_root_device_get_description_dir -gupnp_root_device_get_description_path -gupnp_root_device_get_ssdp_resource_group -<SUBSECTION Standard> -GUPnPRootDeviceClass -GUPNP_ROOT_DEVICE -GUPNP_IS_ROOT_DEVICE -GUPNP_TYPE_ROOT_DEVICE -gupnp_root_device_get_type -GUPNP_ROOT_DEVICE_CLASS -GUPNP_IS_ROOT_DEVICE_CLASS -GUPNP_ROOT_DEVICE_GET_CLASS -GUPNP_TYPE_CONTROL_ERROR -GUPNP_TYPE_EVENTING_ERROR -GUPNP_TYPE_ROOTDEVICE_ERROR -GUPNP_TYPE_SERVER_ERROR -GUPnPRootdeviceError -<SUBSECTION Private> -GUPnPRootDevicePrivate -gupnp_control_error_get_type -gupnp_eventing_error_get_type -gupnp_rootdevice_error_get_type -gupnp_rootdevice_error_quark -gupnp_server_error_get_type -</SECTION> - -<SECTION> -<FILE>gupnp-context</FILE> -<TITLE>GUPnPContext</TITLE> -GUPnPContext -gupnp_context_new -gupnp_context_get_port -gupnp_context_get_server -gupnp_context_get_session -gupnp_context_set_subscription_timeout -gupnp_context_get_subscription_timeout -gupnp_context_get_default_language -gupnp_context_set_default_language -gupnp_context_add_server_handler -gupnp_context_remove_server_handler -gupnp_context_host_path -gupnp_context_host_path_for_agent -gupnp_context_unhost_path -gupnp_context_get_acl -gupnp_context_set_acl -gupnp_context_rewrite_uri -<SUBSECTION Standard> -GUPnPContextClass -GUPNP_CONTEXT -GUPNP_IS_CONTEXT -GUPNP_TYPE_CONTEXT -gupnp_context_get_type -GUPNP_CONTEXT_CLASS -GUPNP_IS_CONTEXT_CLASS -GUPNP_CONTEXT_GET_CLASS -<SUBSECTION Private> -GUPnPContextPrivate -</SECTION> - -<SECTION> -<FILE>gupnp-context-manager</FILE> -<TITLE>GUPnPContextManager</TITLE> -GUPnPContextManager -gupnp_context_manager_create -gupnp_context_manager_create_full -gupnp_context_manager_rescan_control_points -gupnp_context_manager_manage_control_point -gupnp_context_manager_manage_root_device -gupnp_context_manager_get_port -gupnp_context_manager_get_white_list -gupnp_context_manager_get_socket_family -gupnp_context_manager_get_uda_version -<SUBSECTION Standard> -GUPnPContextManagerClass -GUPNP_CONTEXT_MANAGER -GUPNP_IS_CONTEXT_MANAGER -GUPNP_TYPE_CONTEXT_MANAGER -gupnp_context_manager_get_type -GUPNP_CONTEXT_MANAGER_CLASS -GUPNP_IS_CONTEXT_MANAGER_CLASS -GUPNP_CONTEXT_MANAGER_GET_CLASS -<SUBSECTION Private> -GUPnPContextManagerPrivate -</SECTION> - -<SECTION> -<FILE>gupnp-device</FILE> -<TITLE>GUPnPDevice</TITLE> -GUPnPDevice -<SUBSECTION Standard> -GUPnPDeviceClass -GUPNP_DEVICE -GUPNP_IS_DEVICE -GUPNP_TYPE_DEVICE -gupnp_device_get_type -GUPNP_DEVICE_CLASS -GUPNP_IS_DEVICE_CLASS -GUPNP_DEVICE_GET_CLASS -<SUBSECTION Private> -GUPnPDevicePrivate -</SECTION> - -<SECTION> -<FILE>gupnp-service-introspection</FILE> -GUPnPServiceActionArgDirection -GUPnPServiceActionArgInfo -GUPnPServiceActionInfo -GUPnPServiceStateVariableInfo -<TITLE>GUPnPServiceIntrospection</TITLE> -GUPnPServiceIntrospection -gupnp_service_introspection_list_action_names -gupnp_service_introspection_list_actions -gupnp_service_introspection_get_action -gupnp_service_introspection_list_state_variable_names -gupnp_service_introspection_list_state_variables -gupnp_service_introspection_get_state_variable -<SUBSECTION Standard> -GUPnPServiceIntrospectionClass -GUPNP_SERVICE_INTROSPECTION -GUPNP_IS_SERVICE_INTROSPECTION -GUPNP_TYPE_SERVICE_INTROSPECTION -gupnp_service_introspection_get_type -GUPNP_SERVICE_INTROSPECTION_CLASS -GUPNP_IS_SERVICE_INTROSPECTION_CLASS -GUPNP_SERVICE_INTROSPECTION_GET_CLASS -GUPNP_TYPE_SERVICE_ACTION_ARG_DIRECTION -GUPNP_TYPE_SERVICE_ACTION_ARG_INFO -GUPNP_TYPE_SERVICE_ACTION_INFO -gupnp_service_action_arg_direction_get_type -gupnp_service_action_arg_info_get_type -gupnp_service_action_info_get_type -gupnp_service_info_introspect_async -gupnp_service_info_introspect_finish -gupnp_service_state_variable_info_get_type -</SECTION> - -<SECTION> -<FILE>gupnp-service-info</FILE> -<TITLE>GUPnPServiceInfo</TITLE> -GUPnPServiceInfo -GUPnPServiceIntrospectionCallback -gupnp_service_info_get_context -gupnp_service_info_get_location -gupnp_service_info_get_url_base -gupnp_service_info_get_udn -gupnp_service_info_get_service_type -gupnp_service_info_get_id -gupnp_service_info_get_scpd_url -gupnp_service_info_get_control_url -gupnp_service_info_get_event_subscription_url -gupnp_service_info_get_introspection_async -gupnp_service_info_get_introspection_async_full -<SUBSECTION Standard> -GUPnPServiceInfoClass -GUPNP_SERVICE_INFO -GUPNP_IS_SERVICE_INFO -GUPNP_TYPE_SERVICE_INFO -gupnp_service_info_get_type -GUPNP_SERVICE_INFO_CLASS -GUPNP_IS_SERVICE_INFO_CLASS -GUPNP_SERVICE_INFO_GET_CLASS -<SUBSECTION Private> -GUPnPServiceInfoPrivate -</SECTION> - -<SECTION> -<FILE>gupnp-device-proxy</FILE> -<TITLE>GUPnPDeviceProxy</TITLE> -GUPnPDeviceProxy -<SUBSECTION Standard> -GUPnPDeviceProxyClass -GUPNP_DEVICE_PROXY -GUPNP_IS_DEVICE_PROXY -GUPNP_TYPE_DEVICE_PROXY -gupnp_device_proxy_get_type -GUPNP_DEVICE_PROXY_CLASS -GUPNP_IS_DEVICE_PROXY_CLASS -GUPNP_DEVICE_PROXY_GET_CLASS -<SUBSECTION Private> -GUPnPDeviceProxyPrivate -</SECTION> - -<SECTION> -<FILE>gupnp-resource-factory</FILE> -<TITLE>GUPnPResourceFactory</TITLE> -GUPnPResourceFactory -gupnp_resource_factory_new -gupnp_resource_factory_get_default -gupnp_resource_factory_register_resource_type -gupnp_resource_factory_unregister_resource_type -gupnp_resource_factory_register_resource_proxy_type -gupnp_resource_factory_unregister_resource_proxy_type -<SUBSECTION Standard> -GUPnPResourceFactoryClass -GUPNP_RESOURCE_FACTORY -GUPNP_IS_RESOURCE_FACTORY -GUPNP_TYPE_RESOURCE_FACTORY -gupnp_resource_factory_get_type -GUPNP_RESOURCE_FACTORY_CLASS -GUPNP_IS_RESOURCE_FACTORY_CLASS -GUPNP_RESOURCE_FACTORY_GET_CLASS -<SUBSECTION Private> -GUPnPResourceFactoryPrivate -</SECTION> - -<SECTION> -<FILE>gupnp-xml-doc</FILE> -<TITLE>GUPnPXMLDoc</TITLE> -GUPnPXMLDoc -gupnp_xml_doc_new -gupnp_xml_doc_new_from_path -gupnp_xml_doc_get_doc -<SUBSECTION Standard> -GUPnPXMLDocClass -GUPNP_XML_DOC -GUPNP_IS_XML_DOC -GUPNP_TYPE_XML_DOC -gupnp_xml_doc_get_type -GUPNP_XML_DOC_CLASS -GUPNP_IS_XML_DOC_CLASS -GUPNP_XML_DOC_GET_CLASS -GUPNP_TYPE_XML_ERROR -gupnp_xml_error_get_type -</SECTION> - -<SECTION> -<FILE>gupnp-types</FILE> -<TITLE>Special UPnP types</TITLE> -GUPNP_TYPE_BIN_BASE64 -GUPNP_TYPE_BIN_HEX -GUPNP_TYPE_DATE -GUPNP_TYPE_DATE_TIME -GUPNP_TYPE_DATE_TIME_TZ -GUPNP_TYPE_TIME -GUPNP_TYPE_TIME_TZ -GUPNP_TYPE_URI -GUPNP_TYPE_UUID -<SUBSECTION Private> -gupnp_bin_base64_get_type -gupnp_bin_hex_get_type -gupnp_date_get_type -gupnp_date_time_get_type -gupnp_date_time_tz_get_type -gupnp_time_get_type -gupnp_time_tz_get_type -gupnp_uri_get_type -gupnp_uuid_get_type -gupnp_value_get_string -gupnp_value_get_xml_node -</SECTION> - -<SECTION> -<FILE>gupnp-error</FILE> -<TITLE>Error codes</TITLE> -GUPNP_SERVER_ERROR -GUPnPServerError -GUPNP_EVENTING_ERROR -GUPnPEventingError -GUPNP_CONTROL_ERROR -GUPnPControlError -GUPNP_XML_ERROR -GUPnPXMLError -<SUBSECTION Private> -gupnp_server_error_quark -gupnp_eventing_error_quark -gupnp_control_error_quark -gupnp_xml_error_quark -</SECTION> - -<SECTION> -<FILE>gupnp-connman-manager</FILE> -<SUBSECTION Private> -GUPNP_CONNMAN_MANAGER -GUPNP_CONNMAN_MANAGER_CLASS -GUPNP_CONNMAN_MANAGER_GET_CLASS -GUPNP_IS_CONNMAN_MANAGER -GUPNP_IS_CONNMAN_MANAGER_CLASS -GUPNP_TYPE_CONNMAN_MANAGER -GUPnPConnmanManager -GUPnPConnmanManagerClass -GUPnPConnmanManagerPrivate -</SECTION> - -<SECTION> -<FILE>gupnp-simple-context-manager</FILE> -<SUBSECTION Private> -GUPNP_IS_SIMPLE_CONTEXT_MANAGER -GUPNP_IS_SIMPLE_CONTEXT_MANAGER_CLASS -GUPNP_SIMPLE_CONTEXT_MANAGER -GUPNP_SIMPLE_CONTEXT_MANAGER_CLASS -GUPNP_SIMPLE_CONTEXT_MANAGER_GET_CLASS -GUPNP_TYPE_SIMPLE_CONTEXT_MANAGER -GUPnPSimpleContextManager -GUPnPSimpleContextManagerClass -GUPnPSimpleContextManagerPrivate -</SECTION> - -<SECTION> -<FILE>gupnp-windows-context-manager</FILE> -<SUBSECTION Private> -GUPNP_IS_WINDOWS_CONTEXT_MANAGER -GUPNP_IS_WINDOWS_CONTEXT_MANAGER_CLASS -GUPNP_TYPE_WINDOWS_CONTEXT_MANAGER -GUPNP_WINDOWS_CONTEXT_MANAGER -GUPNP_WINDOWS_CONTEXT_MANAGER_CLASS -GUPNP_WINDOWS_CONTEXT_MANAGER_GET_CLASS -GUPnPWindowsContextManager -GUPnPWindowsContextManagerClass -gupnp_windows_context_manager_get_type -</SECTION> - -<SECTION> -<FILE>gupnp-unix-context-manager</FILE> -</SECTION> - -<SECTION> -<FILE>gupnp-linux-context-manager</FILE> -</SECTION> - -<SECTION> -<FILE>gupnp-network-manager</FILE> -</SECTION> - -<SECTION> -<FILE>gupnp-white-list</FILE> -<TITLE>GUPnPWhiteList</TITLE> -GUPnPWhiteList -gupnp_white_list_add_entry -gupnp_white_list_add_entryv -gupnp_white_list_check_context -gupnp_white_list_clear -gupnp_white_list_set_enabled -gupnp_white_list_get_entries -gupnp_white_list_is_empty -gupnp_white_list_get_enabled -gupnp_white_list_new -gupnp_white_list_remove_entry -<SUBSECTION Standard> -gupnp_white_list_get_type -GUPNP_IS_WHITE_LIST -GUPNP_IS_WHITE_LIST_CLASS -GUPNP_TYPE_WHITE_LIST -GUPNP_WHITE_LIST -GUPNP_WHITE_LIST_CLASS -GUPNP_WHITE_LIST_GET_CLASS -GUPnPWhiteListClass -<SUBSECTION Private> -GUPnPWhiteListPrivate -</SECTION> - -<SECTION> -<FILE>gupnp-acl</FILE> -<TITLE>GUPnPAcl</TITLE> -GUPnPAcl -GUPnPAclInterface -gupnp_acl_can_sync -gupnp_acl_is_allowed -gupnp_acl_is_allowed_async -gupnp_acl_is_allowed_finish -<SUBSECTION Standard> -gupnp_acl_get_type -GUPNP_ACL -GUPNP_ACL_GET_INTERFACE -GUPNP_IS_ACL -GUPNP_TYPE_ACL -</SECTION> - -<SECTION> -<FILE>gupnp-misc</FILE> -<TITLE>Utility functions</TITLE> -gupnp_get_uuid -</SECTION> diff --git a/doc/gupnp.types b/doc/gupnp.types deleted file mode 100644 index 8b74d27..0000000 --- a/doc/gupnp.types +++ /dev/null @@ -1,26 +0,0 @@ -#include <libgupnp/gupnp.h> - -gupnp_acl_get_type -gupnp_context_get_type -gupnp_context_manager_get_type -gupnp_control_point_get_type -gupnp_device_get_type -gupnp_device_info_get_type -gupnp_device_proxy_get_type -gupnp_resource_factory_get_type -gupnp_root_device_get_type -gupnp_service_get_type -gupnp_service_info_get_type -gupnp_service_introspection_get_type -gupnp_service_proxy_get_type -gupnp_service_proxy_action_get_type -gupnp_bin_base64_get_type -gupnp_bin_hex_get_type -gupnp_date_get_type -gupnp_date_time_get_type -gupnp_date_time_tz_get_type -gupnp_time_get_type -gupnp_time_tz_get_type -gupnp_uri_get_type -gupnp_uuid_get_type -gupnp_white_list_get_type diff --git a/doc/overview.xml b/doc/overview.xml deleted file mode 100644 index 8f71427..0000000 --- a/doc/overview.xml +++ /dev/null @@ -1,34 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> - -<chapter id="overview"> - <title>Overview</title> - <para> - <ulink url="http://www.gupnp.org">GUPnP</ulink> is a library for - implementing both <ulink url="http://www.upnp.org">UPnP</ulink> clients and - services in C, using <ulink url="http://www.gtk.org/">GObject</ulink> and - <ulink url="http://live.gnome.org/LibSoup">LibSoup</ulink>. It allows for - fully asynchronous use without using threads and so cleanly integrates - naturally into main-loop based applications, and supports all of the UPnP - features. - </para> - <para> - This documentation assumes some familiarity with the UPnP model and - concepts. If the reader doesn't have any prior understanding of UPnP, then - we can recommend <ulink - url="http://www.intel.com/intelpress/sum_upnp.htm"><citetitle>UPnP Design By - Example</citetitle></ulink> by Intel Press. For a very basic overview of - UPnP, see <glossterm linkend="device">Device</glossterm>, <glossterm - linkend="service">Service</glossterm>, and <glossterm - linkend="controlpoint">Control Point</glossterm> in the glossary. - </para> - <para> - The canonical reference for UPnP is <citetitle>UPnP Device - Architecture</citetitle> by - <ulink url="http://www.upnp.org">UPnP Forum</ulink>. GUPnP also - follows the <citetitle>DLNA Networked Device Interoperability - Guidelines</citetitle> by <ulink url="">Digital Living Network alliance</ulink> - (to the extent that the guidelines are applicable to a UPnP protocol - implementation). - </para> -</chapter> diff --git a/doc/server-tutorial.xml b/doc/server-tutorial.xml deleted file mode 100644 index d1579e3..0000000 --- a/doc/server-tutorial.xml +++ /dev/null @@ -1,323 +0,0 @@ -<?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/sdcps-and-certification/standards/sdcps/"/> 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/specs/ha/lighting/">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-arch-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"><xi:fallback /></xi:include></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> - Because 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"><xi:fallback /></xi:include></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-arch-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 gupnp_context_new(). - </para> - <programlisting>GUPnPContext *context; -/* Initialize required subsystems */ -#if !GLIB_CHECK_VERSION(2,35,0) - g_type_init (); -#endif -/* Create the GUPnP context with default host and port */ -context = gupnp_context_new (NULL, NULL, 0, NULL);</programlisting> - <para> - Next the root device can be created. The name of the device description - file can be passed as an absolute file path or a relative path to the - second parameter of gupnp_root_device_new(). The service description - files referenced in the device description are expected to be at the path - given there as well. - </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 #GUPnPService from the root - device using gupnp_device_info_get_service() (#GUPnPRootDevice is a - subclass of #GUPnPDevice, which implements #GUPnPDeviceInfo). This - returns a #GUPnPServiceInfo which again is an interface, implemented by - #GUPnPService (on the server) and #GUPnPServiceProxy (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> - #GUPnPService 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: #GUPnPService::action-invoked and - #GUPnPService::query-variable. #GUPnPService::action-invoked is emitted - when a client invokes an action: the handler is passed a - #GUPnPServiceAction object that identifies which action was invoked, and - is used to return values using gupnp_service_action_set(). - #GUPnPService::query-variable 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 #GValue which should be set to the current - value of the variable. - </para> - <para> - Handlers should 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); -… -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 #GUPnPServiceAction object which represents the in-progress - action. If required it can be queried using - gupnp_service_action_get_name() to identify the action (this isn't - required if detailed signals were connected). Any - <firstterm>in</firstterm> arguments can be retrieving using - gupnp_service_action_get(), and then return values can be set using - gupnp_service_action_set(). Once the action has been performed, either - gupnp_service_action_return() or gupnp_service_action_return_error() - 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 gupnp_service_notify(). 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, &status, - NULL); - gupnp_service_action_return (action); - gupnp_service_notify (service, "Status", G_TYPE_STRING, status, NULL); -} -… -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 #GValue. 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); -} -… -g_signal_connect (service, "query-variable::Status", G_CALLBACK (query_status_cb), NULL);</programlisting> - <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> - <para> - For services which have many actions and variables there is a convenience - method gupnp_service_signals_autoconnect() which will automatically - connect specially named handlers to signals. See the documentation for - full details on how it works. - </para> - </simplesect> - <simplesect> - <title>Generating Service-specific Wrappers</title> - <para> - Using service-specific wrappers can simplify the implementation of a service. - Wrappers can be generated with <xref linkend="gupnp-binding-tool"/> - using the option <literal>--mode server</literal>. - </para> - <para> - In the following examples the wrapper has been created with - <literal>--mode server --prefix switch</literal>. Please note that the callback handlers - (<literal>get_status_cb</literal> and <literal>set_target_cb</literal>) are not automatically - generated by <xref linkend="gupnp-binding-tool"/> for you. - </para> - <programlisting>static gboolean status; - -static void -get_status_cb (GUPnPService *service, - GUPnPServiceAction *action, - gpointer user_data) -{ - switch_get_status_action_set (action, status); - - gupnp_service_action_return (action); -} - -static void -set_target_cb (GUPnPService *service, - GUPnPServiceAction *action, - gpointer user_data) -{ - switch_set_target_action_get (action, &status); - switch_status_variable_notify (service, status); - - gupnp_service_action_return (action); -} - -… - -switch_get_status_action_connect (service, G_CALLBACK(get_status_cb), NULL); -switch_set_target_action_connect (service, G_CALLBACK(set_target_cb), NULL);</programlisting> - <para> - Note how many possible problem situations that were run-time errors are - actually compile-time errors when wrappers are used: Action names, - argument names and argument types are easier to get correct (and available - in editor autocompletion). - </para> - <para> - State variable query handlers are implemented in a similar manner, but - they are even simpler as the return value of the handler is the state - variable value. - </para> - <programlisting>static gboolean -query_status_cb (GUPnPService *service, - gpointer user_data) -{ - return status; -} - -… - -switch_status_query_connect (service, query_status_cb, NULL);</programlisting> - </simplesect> -</chapter> |