doc/gupnp-binding-tool.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   3
   4 <refentry id="gupnp-binding-tool" xmlns:xi="http://www.w3.org/2003/XInclude">
   5   <refmeta>
   6     <refentrytitle>gupnp-binding-tool</refentrytitle>
   7     <manvolnum>1</manvolnum>
   8     <refmiscinfo class="source">GUPnP</refmiscinfo>
   9     <refmiscinfo class="version"><xi:include href="version.xml" parse="text"/></refmiscinfo>
  10   </refmeta>
  11
  12   <refnamediv>
  13     <refname>gupnp-binding-tool</refname>
  14     <refpurpose>creates C convenience wrappers for UPnP services</refpurpose>
  15   </refnamediv>
  16
  17   <refsynopsisdiv>
  18     <cmdsynopsis>
  19       <command>gupnp-binding-tool</command>
  20       <arg choice="opt">--prefix <arg choice="req">PREFIX</arg></arg>
  21       <arg choice="opt">--mode <arg choice="req">client|server</arg></arg>
  22       <arg choice="req">SCPD file</arg>
  23     </cmdsynopsis>
  24   </refsynopsisdiv>
  25
  26   <refsect1>
  27     <title>Description</title>
  28     <para>
  29       <command>gupnp-binding-tool</command> takes a <glossterm
  30       linkend="scpd">SCPD file</glossterm> and generates convenience C functions
  31       which call the actual GUPnP functions. The client-side bindings can be seen
  32       as a service-specific version of the GUPnPServiceProxy API and the
  33       service-side bindings are the same for GUPnPService.
  34     </para>
  35     <para>
  36       These generated functions are less verbose and also safer as function call
  37       parameters are correctly typed. Action, variable and query names are easier
  38       to get correct with bindings (or at least the errors will be compile-time
  39       errors instead of run-time), and are also available in editor
  40       autocompletion.
  41     </para>
  42   </refsect1>
  43   <refsect1>
  44     <title>Client side bindings</title>
  45     <para>
  46       As an example, this action:
  47     </para>
  48     <programlisting><![CDATA[<action>
  49   <name>DeletePortMapping</name>
  50   <argumentList>
  51     <argument>
  52       <name>NewRemoteHost</name>
  53       <direction>in</direction>
  54       <relatedStateVariable>RemoteHost</relatedStateVariable>
  55     </argument>
  56     <argument>
  57       <name>NewExternalPort</name>
  58       <direction>in</direction>
  59       <relatedStateVariable>ExternalPort</relatedStateVariable>
  60     </argument>
  61     <argument>
  62       <name>NewProtocol</name>
  63       <direction>in</direction>
  64       <relatedStateVariable>PortMappingProtocol</relatedStateVariable>
  65     </argument>
  66   </argumentList>
  67 </action>]]></programlisting>
  68     <para>
  69       Will generate the following synchronous client-side (control point)
  70       function:
  71     </para>
  72     <programlisting>static inline gboolean
  73 igd_delete_port_mapping (GUPnPServiceProxy *proxy,
  74                          const gchar *in_new_remote_host,
  75                          const guint in_new_external_port,
  76                          const gchar *in_new_protocol,
  77                          GError **error);
  78 </programlisting>
  79     <para>
  80       As can be seen, the arguments have the correct types and are prefixed with
  81       the argument direction.
  82     </para>
  83     <para>
  84       <command>gupnp-binding-tool</command> generates both synchronous and
  85       asynchronous wrappers.  The <function>igd_delete_port_mapping</function> example
  86       above is the synchronous form, the asynchronous form is as follows:
  87     </para>
  88     <programlisting>typedef void (*igd_delete_port_mapping_reply) (GUPnPServiceProxy *proxy,
  89                                                GError *error,
  90                                                gpointer userdata);
  91
  92 static inline GUPnPServiceProxyAction *
  93 igd_delete_port_mapping_async (GUPnPServiceProxy *proxy,
  94                                const gchar *in_new_remote_host,
  95                                const guint in_new_external_port,
  96                                const gchar *in_new_protocol,
  97                                igd_delete_port_mapping_reply callback,
  98                                gpointer userdata);</programlisting>
  99     <para>
 100       The asynchronous form (implemented using
 101       <function>gupnp_service_proxy_begin_action()</function> and
 102       <function>gupnp_service_proxy_end_action()</function>) will return without
 103       blocking and later invoke the callback from the main loop when the reply
 104       is received.
 105     </para>
 106     <para>
 107       The tool also creates bindings for state variable notifications. This state
 108       variable definition:
 109     </para>
 110     <programlisting><![CDATA[<stateVariable sendEvents="yes">
 111   <name>ExternalIPAddress</name>
 112   <dataType>string</dataType>
 113 </stateVariable>]]></programlisting>
 114     <para>
 115       will create this client binding that can be used to get notifications on
 116       "ExternalIPAddress" changes:
 117     </para>
 118     <programlisting>typedef void
 119 (*igd_external_ip_address_changed_callback) (GUPnPServiceProxy *proxy,
 120                                              const gchar *external_ip_address,
 121                                              gpointer userdata);
 122
 123 static inline gboolean
 124 igd_external_ip_address_add_notify (GUPnPServiceProxy *proxy,
 125                                     igd_external_ip_address_changed_callback callback,
 126                                     gpointer userdata);</programlisting>
 127
 128     <para>
 129       All of the examples were produced with <filename>gupnp-binding-tool
 130       --prefix igd --mode client WANIPConnection.xml</filename>.
 131     </para>
 132   </refsect1>
 133   <refsect1>
 134     <title>Server side bindings</title>
 135     <para>
 136       The corresponding server bindings for the same UPnP action
 137       (DeletePortMapping) look like this:
 138     </para>
 139     <programlisting>void
 140 igd_delete_port_mapping_action_get (GUPnPServiceAction *action,
 141                                     gchar **in_new_remote_host,
 142                                     guint *in_new_external_port,
 143                                     gchar **in_new_protocol);
 144
 145 gulong
 146 igd_delete_port_mapping_action_connect (GUPnPService *service,
 147                                         GCallback callback,
 148                                         gpointer userdata);</programlisting>
 149     <para>
 150       The generated *_action_connect() function can be used to connect the action
 151       handler. The *_action_get() and *_action_set() functions can then
 152       be used inside the action handler to get/set action variables. If notified
 153       variables are modified, the *_variable_notify() should be used to send
 154       the notifications (see below).
 155     </para>
 156     <programlisting>typedef gchar *(*igd_external_ip_address_query_callback) (GUPnPService *service,
 157                                                           gpointer userdata);
 158
 159 gulong
 160 igd_external_ip_address_query_connect (GUPnPService *service,
 161                                        igd_external_ip_address_query_callback callback,
 162                                        gpointer userdata);
 163 void
 164 igd_external_ip_address_variable_notify (GUPnPService *service,
 165                                          const gchar *external_ip_address);</programlisting>
 166     <para>
 167       The *_query_connect() function can be used to connect the service-specific
 168       query handler. The return value of the handler is the returned state
 169       variable value.
 170     </para>
 171     <para>
 172       All of the examples were produced with <filename>gupnp-binding-tool
 173       --prefix igd --mode server WANIPConnection.xml</filename>.
 174     </para>
 175   </refsect1>
 176 </refentry>