doc/html/gupnp-binding-tool.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>gupnp-binding-tool</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="GUPnP Reference Manual">
   8 <link rel="up" href="api-tools.html" title="Tools">
   9 <link rel="prev" href="api-tools.html" title="Tools">
  10 <link rel="next" href="schemas.html" title="Part III. XML Schemas">
  11 <meta name="generator" content="GTK-Doc V1.15.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  16 <td><a accesskey="p" href="api-tools.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="api-tools.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  18 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  19 <th width="100%" align="center">GUPnP Reference Manual</th>
  20 <td><a accesskey="n" href="schemas.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="refentry">
  23 <a name="gupnp-binding-tool"></a><div class="titlepage"></div>
  24 <div class="refnamediv"><table width="100%"><tr>
  25 <td valign="top">
  26 <h2><span class="refentrytitle">gupnp-binding-tool</span></h2>
  27 <p>gupnp-binding-tool — creates C convenience wrappers for UPnP services</p>
  28 </td>
  29 <td valign="top" align="right"></td>
  30 </tr></table></div>
  31 <div class="refsynopsisdiv">
  32 <h2>Synopsis</h2>
  33 <div class="cmdsynopsis"><p><code class="command">gupnp-binding-tool</code>  [--prefix {PREFIX}] [--mode {client|server}] {SCPD file}</p></div>
  34 </div>
  35 <div class="refsect1">
  36 <a name="id2902926"></a><h2>Description</h2>
  37 <p>
  38       <span class="command"><strong>gupnp-binding-tool</strong></span> takes a <a class="glossterm" href="glossary.html#scpd"><em class="glossterm">SCPD file</em></a> and generates convenience C functions
  39       which call the actual GUPnP functions. The client-side bindings can be seen
  40       as a service-specific version of the GUPnPServiceProxy API and the
  41       service-side bindings are the same for GUPnPService.
  42     </p>
  43 <p>
  44       These generated functions are less verbose and also safer as function call
  45       parameters are correctly typed. Action, variable and query names are easier
  46       to get correct with bindings (or at least the errors will be compile-time
  47       errors instead of run-time), and are also available in editor
  48       autocompletion.
  49     </p>
  50 </div>
  51 <div class="refsect1">
  52 <a name="id2947308"></a><h2>Client side bindings</h2>
  53 <p>
  54       As an example, this action:
  55     </p>
  56 <pre class="programlisting">&lt;action&gt;
  57   &lt;name&gt;DeletePortMapping&lt;/name&gt;
  58   &lt;argumentList&gt;
  59     &lt;argument&gt;
  60       &lt;name&gt;NewRemoteHost&lt;/name&gt;
  61       &lt;direction&gt;in&lt;/direction&gt;
  62       &lt;relatedStateVariable&gt;RemoteHost&lt;/relatedStateVariable&gt;
  63     &lt;/argument&gt;
  64     &lt;argument&gt;
  65       &lt;name&gt;NewExternalPort&lt;/name&gt;
  66       &lt;direction&gt;in&lt;/direction&gt;
  67       &lt;relatedStateVariable&gt;ExternalPort&lt;/relatedStateVariable&gt;
  68     &lt;/argument&gt;
  69     &lt;argument&gt;
  70       &lt;name&gt;NewProtocol&lt;/name&gt;
  71       &lt;direction&gt;in&lt;/direction&gt;
  72       &lt;relatedStateVariable&gt;PortMappingProtocol&lt;/relatedStateVariable&gt;
  73     &lt;/argument&gt;
  74   &lt;/argumentList&gt;
  75 &lt;/action&gt;</pre>
  76 <p>
  77       Will generate the following synchronous client-side (control point)
  78       function:
  79     </p>
  80 <pre class="programlisting">static inline gboolean
  81 igd_delete_port_mapping (GUPnPServiceProxy *proxy,
  82                          const gchar *in_new_remote_host,
  83                          const guint in_new_external_port,
  84                          const gchar *in_new_protocol,
  85                          GError **error);
  86 </pre>
  87 <p>
  88       As can be seen, the arguments have the correct types and are prefixed with
  89       the argument direction.
  90     </p>
  91 <p>
  92       <span class="command"><strong>gupnp-binding-tool</strong></span> generates both synchronous and
  93       asynchronous wrappers.  The <code class="function">igd_delete_port_mapping</code> example
  94       above is the synchronous form, the asynchronous form is as follows:
  95     </p>
  96 <pre class="programlisting">typedef void (*igd_delete_port_mapping_reply) (GUPnPServiceProxy *proxy,
  97                                                GError *error,
  98                                                gpointer userdata);
  99
 100 static inline GUPnPServiceProxyAction *
 101 igd_delete_port_mapping_async (GUPnPServiceProxy *proxy,
 102                                const gchar *in_new_remote_host,
 103                                const guint in_new_external_port,
 104                                const gchar *in_new_protocol,
 105                                igd_delete_port_mapping_reply callback,
 106                                gpointer userdata);</pre>
 107 <p>
 108       The asynchronous form (implemented using
 109       <code class="function">gupnp_service_proxy_begin_action()</code> and
 110       <code class="function">gupnp_service_proxy_end_action()</code>) will return without
 111       blocking and later invoke the callback from the main loop when the reply
 112       is received.
 113     </p>
 114 <p>
 115       The tool also creates bindings for state variable notifications. This state
 116       variable definition:
 117     </p>
 118 <pre class="programlisting">&lt;stateVariable sendEvents="yes"&gt;
 119   &lt;name&gt;ExternalIPAddress&lt;/name&gt;
 120   &lt;dataType&gt;string&lt;/dataType&gt;
 121 &lt;/stateVariable&gt;</pre>
 122 <p>
 123       will create this client binding that can be used to get notifications on
 124       "ExternalIPAddress" changes:
 125     </p>
 126 <pre class="programlisting">typedef void
 127 (*igd_external_ip_address_changed_callback) (GUPnPServiceProxy *proxy,
 128                                              const gchar *external_ip_address,
 129                                              gpointer userdata);
 130
 131 static inline gboolean
 132 igd_external_ip_address_add_notify (GUPnPServiceProxy *proxy,
 133                                     igd_external_ip_address_changed_callback callback,
 134                                     gpointer userdata);</pre>
 135 <p>
 136       All of the examples were produced with <code class="filename">gupnp-binding-tool
 137       --prefix igd --mode client WANIPConnection.xml</code>.
 138     </p>
 139 </div>
 140 <div class="refsect1">
 141 <a name="id2947449"></a><h2>Server side bindings</h2>
 142 <p>
 143       The corresponding server bindings for the same UPnP action
 144       (DeletePortMapping) look like this:
 145     </p>
 146 <pre class="programlisting">void
 147 igd_delete_port_mapping_action_get (GUPnPServiceAction *action,
 148                                     gchar **in_new_remote_host,
 149                                     guint *in_new_external_port,
 150                                     gchar **in_new_protocol);
 151
 152 gulong
 153 igd_delete_port_mapping_action_connect (GUPnPService *service,
 154                                         GCallback callback,
 155                                         gpointer userdata);</pre>
 156 <p>
 157       The generated *_action_connect() function can be used to connect the action
 158       handler. The *_action_get() and *_action_set() functions can then
 159       be used inside the action handler to get/set action variables. If notified
 160       variables are modified, the *_variable_notify() should be used to send
 161       the notifications (see below).
 162     </p>
 163 <pre class="programlisting">typedef gchar *(*igd_external_ip_address_query_callback) (GUPnPService *service,
 164                                                           gpointer userdata);
 165
 166 gulong
 167 igd_external_ip_address_query_connect (GUPnPService *service,
 168                                        igd_external_ip_address_query_callback callback,
 169                                        gpointer userdata);
 170 void
 171 igd_external_ip_address_variable_notify (GUPnPService *service,
 172                                          const gchar *external_ip_address);</pre>
 173 <p>
 174       The *_query_connect() function can be used to connect the service-specific
 175       query handler. The return value of the handler is the returned state
 176       variable value.
 177     </p>
 178 <p>
 179       All of the examples were produced with <code class="filename">gupnp-binding-tool
 180       --prefix igd --mode server WANIPConnection.xml</code>.
 181     </p>
 182 </div>
 183 </div>
 184 <div class="footer">
 185 <hr>
 186           Generated by GTK-Doc V1.15.1</div>
 187 </body>
 188 </html>