1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
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.76.1">
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.18 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
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>
22 <div class="refentry">
23 <a name="gupnp-binding-tool"></a><div class="titlepage"></div>
24 <div class="refnamediv"><table width="100%"><tr>
26 <h2><span class="refentrytitle">gupnp-binding-tool</span></h2>
27 <p>gupnp-binding-tool — creates C convenience wrappers for UPnP services</p>
29 <td valign="top" align="right"></td>
31 <div class="refsynopsisdiv">
33 <div class="cmdsynopsis"><p><code class="command">gupnp-binding-tool</code> [--prefix {PREFIX}] [--mode {client|server}] {SCPD file}</p></div>
35 <div class="refsect1">
36 <a name="idp6198416"></a><h2>Description</h2>
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.
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
51 <div class="refsect1">
52 <a name="idp13153104"></a><h2>Client side bindings</h2>
54 As an example, this action:
56 <pre class="programlisting"><action>
57 <name>DeletePortMapping</name>
60 <name>NewRemoteHost</name>
61 <direction>in</direction>
62 <relatedStateVariable>RemoteHost</relatedStateVariable>
65 <name>NewExternalPort</name>
66 <direction>in</direction>
67 <relatedStateVariable>ExternalPort</relatedStateVariable>
70 <name>NewProtocol</name>
71 <direction>in</direction>
72 <relatedStateVariable>PortMappingProtocol</relatedStateVariable>
77 Will generate the following synchronous client-side (control point)
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,
88 As can be seen, the arguments have the correct types and are prefixed with
89 the argument direction.
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:
96 <pre class="programlisting">typedef void (*igd_delete_port_mapping_reply) (GUPnPServiceProxy *proxy,
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>
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
115 The tool also creates bindings for state variable notifications. This state
118 <pre class="programlisting"><stateVariable sendEvents="yes">
119 <name>ExternalIPAddress</name>
120 <dataType>string</dataType>
121 </stateVariable></pre>
123 will create this client binding that can be used to get notifications on
124 "ExternalIPAddress" changes:
126 <pre class="programlisting">typedef void
127 (*igd_external_ip_address_changed_callback) (GUPnPServiceProxy *proxy,
128 const gchar *external_ip_address,
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>
136 All of the examples were produced with <code class="filename">gupnp-binding-tool
137 --prefix igd --mode client WANIPConnection.xml</code>.
140 <div class="refsect1">
141 <a name="idp13166992"></a><h2>Server side bindings</h2>
143 The corresponding server bindings for the same UPnP action
144 (DeletePortMapping) look like this:
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);
153 igd_delete_port_mapping_action_connect (GUPnPService *service,
155 gpointer userdata);</pre>
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).
163 <pre class="programlisting">typedef gchar *(*igd_external_ip_address_query_callback) (GUPnPService *service,
167 igd_external_ip_address_query_connect (GUPnPService *service,
168 igd_external_ip_address_query_callback callback,
171 igd_external_ip_address_variable_notify (GUPnPService *service,
172 const gchar *external_ip_address);</pre>
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
179 All of the examples were produced with <code class="filename">gupnp-binding-tool
180 --prefix igd --mode server WANIPConnection.xml</code>.
186 Generated by GTK-Doc V1.18</div>