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