This file is indexed.

/usr/share/gtk-doc/html/gupnp/gupnp-binding-tool.html is in libgupnp-doc 0.20.10-1ubuntu1.

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
188
<!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 Reference Manual: gupnp-binding-tool</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.78.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.20 (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="10"><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.6.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">SCPD file</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.6.2.5"></a><h2>Client side bindings</h2>
<p>
      As an example, this action:
    </p>
<pre class="programlisting">&lt;action&gt;
  &lt;name&gt;DeletePortMapping&lt;/name&gt;
  &lt;argumentList&gt;
    &lt;argument&gt;
      &lt;name&gt;NewRemoteHost&lt;/name&gt;
      &lt;direction&gt;in&lt;/direction&gt;
      &lt;relatedStateVariable&gt;RemoteHost&lt;/relatedStateVariable&gt;
    &lt;/argument&gt;
    &lt;argument&gt;
      &lt;name&gt;NewExternalPort&lt;/name&gt;
      &lt;direction&gt;in&lt;/direction&gt;
      &lt;relatedStateVariable&gt;ExternalPort&lt;/relatedStateVariable&gt;
    &lt;/argument&gt;
    &lt;argument&gt;
      &lt;name&gt;NewProtocol&lt;/name&gt;
      &lt;direction&gt;in&lt;/direction&gt;
      &lt;relatedStateVariable&gt;PortMappingProtocol&lt;/relatedStateVariable&gt;
    &lt;/argument&gt;
  &lt;/argumentList&gt;
&lt;/action&gt;</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">&lt;stateVariable sendEvents="yes"&gt;
  &lt;name&gt;ExternalIPAddress&lt;/name&gt;
  &lt;dataType&gt;string&lt;/dataType&gt;
&lt;/stateVariable&gt;</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.6.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.20</div>
</body>
</html>