« back to all changes in this revision
Viewing changes to doc/xml/gupnp-simple-igd.xml
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Matthew Walker
- Date: 2009-03-23 19:36:45 UTC
- Revision ID: matthew@matthew-desktop-20090323193645-r4z27ojffzc9fuoy
initial checkin
- files added:
- DEBIAN
- doc
- doc/html
- doc/tmpl
- doc/xml
- libgupnp-igd
- libgupnp-igd/.deps
- libgupnp-igd/.libs
- libgupnp-igd/.libs/libgupnp-igd-1.0.la
- libgupnp-igd/.libs/libgupnp-igd-1.0.so.1
- tests
- tests/examples
- tests/examples/.deps
- tests/examples/.libs
- tests/gtest
- tests/gtest/.deps
added
removed
doc/xml/gupnp-simple-igd.xml
1
<?xml version="1.0"?>
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4
<!ENTITY version SYSTEM "version.xml">
5
]>
6
<refentry id="GUPnPSimpleIgd">
7
<refmeta>
8
<refentrytitle role="top_of_page" id="GUPnPSimpleIgd.top_of_page">GUPnPSimpleIgd</refentrytitle>
9
<manvolnum>3</manvolnum>
10
<refmiscinfo>GUPNP-IGD Library</refmiscinfo>
11
</refmeta>
12
13
<refnamediv>
14
<refname>GUPnPSimpleIgd</refname>
15
<refpurpose>A simple class to map ports on UPnP routers</refpurpose>
16
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
17
</refnamediv>
18
19
<refsynopsisdiv id="GUPnPSimpleIgd.synopsis" role="synopsis">
20
<title role="synopsis.title">Synopsis</title>
21
22
<synopsis>
23
<link linkend="GUPnPSimpleIgd-struct">GUPnPSimpleIgd</link>;
24
<link linkend="GUPnPSimpleIgdClass">GUPnPSimpleIgdClass</link>;
25
#define <link linkend="GUPNP-SIMPLE-IGD-ERROR:CAPS">GUPNP_SIMPLE_IGD_ERROR</link>
26
enum <link linkend="GUPnPSimpleIgdError">GUPnPSimpleIgdError</link>;
27
<link linkend="GUPnPSimpleIgd">GUPnPSimpleIgd</link>* <link linkend="gupnp-simple-igd-new">gupnp_simple_igd_new</link> (<link linkend="GMainContext">GMainContext</link> *main_context);
28
<link linkend="void">void</link> <link linkend="gupnp-simple-igd-add-port">gupnp_simple_igd_add_port</link> (<link linkend="GUPnPSimpleIgd">GUPnPSimpleIgd</link> *self,
29
const <link linkend="gchar">gchar</link> *protocol,
30
<link linkend="guint16">guint16</link> external_port,
31
const <link linkend="gchar">gchar</link> *local_ip,
32
<link linkend="guint16">guint16</link> local_port,
33
<link linkend="guint32">guint32</link> lease_duration,
34
const <link linkend="gchar">gchar</link> *description);
35
<link linkend="void">void</link> <link linkend="gupnp-simple-igd-remove-port">gupnp_simple_igd_remove_port</link> (<link linkend="GUPnPSimpleIgd">GUPnPSimpleIgd</link> *self,
36
const <link linkend="gchar">gchar</link> *protocol,
37
<link linkend="guint">guint</link> external_port);
38
</synopsis>
39
</refsynopsisdiv>
40
41
<refsect1 id="GUPnPSimpleIgd.object-hierarchy" role="object_hierarchy">
42
<title role="object_hierarchy.title">Object Hierarchy</title>
43
<synopsis>
44
<link linkend="GObject">GObject</link>
45
+----GUPnPSimpleIgd
46
+----<link linkend="GUPnPSimpleIgdThread">GUPnPSimpleIgdThread</link>
47
</synopsis>
48
49
</refsect1>
50
51
52
53
54
55
<refsect1 id="GUPnPSimpleIgd.properties" role="properties">
56
<title role="properties.title">Properties</title>
57
<synopsis>
58
"<link linkend="GUPnPSimpleIgd--main-context">main-context</link>" <link linkend="gpointer">gpointer</link> : Read / Write / Construct Only
59
"<link linkend="GUPnPSimpleIgd--request-timeout">request-timeout</link>" <link linkend="guint">guint</link> : Read / Write
60
</synopsis>
61
</refsect1>
62
63
<refsect1 id="GUPnPSimpleIgd.signals" role="signal_proto">
64
<title role="signal_proto.title">Signals</title>
65
<synopsis>
66
"<link linkend="GUPnPSimpleIgd-error-mapping-port">error-mapping-port</link>" : Run Last / Has Details
67
"<link linkend="GUPnPSimpleIgd-mapped-external-port">mapped-external-port</link>" : Run Last
68
</synopsis>
69
</refsect1>
70
71
72
<refsect1 id="GUPnPSimpleIgd.description" role="desc">
73
<title role="desc.title">Description</title>
74
<para>
75
This simple class allows applications to map ports on UPnP routers.
76
It implements the basic functionalities to map ports to external ports.
77
It also allows implementations to know the external port from the router's
78
perspective.</para>
79
<para>
80
81
</para>
82
</refsect1>
83
84
<refsect1 id="GUPnPSimpleIgd.details" role="details">
85
<title role="details.title">Details</title>
86
<refsect2 id="GUPnPSimpleIgd-struct" role="struct">
87
<title>GUPnPSimpleIgd</title>
88
<indexterm zone="GUPnPSimpleIgd-struct"><primary>GUPnPSimpleIgd</primary></indexterm><programlisting>typedef struct _GUPnPSimpleIgd GUPnPSimpleIgd;</programlisting>
89
<para>
90
All members are private, access them using methods and properties</para>
91
<para>
92
93
</para></refsect2>
94
<refsect2 id="GUPnPSimpleIgdClass" role="struct">
95
<title>GUPnPSimpleIgdClass</title>
96
<indexterm zone="GUPnPSimpleIgdClass"><primary>GUPnPSimpleIgdClass</primary></indexterm><programlisting>typedef struct {
97
GObjectClass parent_class;
98
99
/*virtual functions */
100
101
void (*add_port) (GUPnPSimpleIgd *self,
102
const gchar *protocol,
103
guint16 external_port,
104
const gchar *local_ip,
105
guint16 local_port,
106
guint32 lease_duration,
107
const gchar *description);
108
109
void (*remove_port) (GUPnPSimpleIgd *self,
110
const gchar *protocol,
111
guint external_port);
112
} GUPnPSimpleIgdClass;
113
</programlisting>
114
<para>
115
The Raw UDP component transmitter class</para>
116
<para>
117
118
</para><variablelist role="struct">
119
<varlistentry>
120
<term><link linkend="GObjectClass">GObjectClass</link> <structfield>parent_class</structfield>;</term>
121
<listitem><simpara> Our parent
122
</simpara></listitem>
123
</varlistentry>
124
<varlistentry>
125
<term><structfield>add_port</structfield> ()</term>
126
<listitem><simpara> An implementation of the add_port function
127
</simpara></listitem>
128
</varlistentry>
129
<varlistentry>
130
<term><structfield>remove_port</structfield> ()</term>
131
<listitem><simpara> An implementation of the delete_port function
132
</simpara></listitem>
133
</varlistentry>
134
</variablelist></refsect2>
135
<refsect2 id="GUPNP-SIMPLE-IGD-ERROR:CAPS" role="macro">
136
<title>GUPNP_SIMPLE_IGD_ERROR</title>
137
<indexterm zone="GUPNP-SIMPLE-IGD-ERROR:CAPS"><primary>GUPNP_SIMPLE_IGD_ERROR</primary></indexterm><programlisting>#define GUPNP_SIMPLE_IGD_ERROR (gupnp_simple_igd_get_error_domain ())
138
</programlisting>
139
<para>
140
The <link linkend="GError"><type>GError</type></link> domain for error coming out of GUPnpSimpleIGD</para>
141
<para>
142
143
</para></refsect2>
144
<refsect2 id="GUPnPSimpleIgdError" role="enum">
145
<title>enum GUPnPSimpleIgdError</title>
146
<indexterm zone="GUPnPSimpleIgdError"><primary>GUPnPSimpleIgdError</primary></indexterm><programlisting>typedef enum {
147
GUPNP_SIMPLE_IGD_ERROR_EXTERNAL_ADDRESS,
148
GUPNP_SIMPLE_IGD_ERROR_TIMEOUT
149
} GUPnPSimpleIgdError;
150
</programlisting>
151
<para>
152
Errors coming out of the GUPnPSimpleIGD object.</para>
153
<para>
154
155
</para><variablelist role="enum">
156
<varlistentry id="GUPNP-SIMPLE-IGD-ERROR-EXTERNAL-ADDRESS:CAPS" role="constant">
157
<term><literal>GUPNP_SIMPLE_IGD_ERROR_EXTERNAL_ADDRESS</literal></term>
158
<listitem><simpara> Error getting the external
159
address of the router
160
</simpara></listitem>
161
</varlistentry>
162
<varlistentry id="GUPNP-SIMPLE-IGD-ERROR-TIMEOUT:CAPS" role="constant">
163
<term><literal>GUPNP_SIMPLE_IGD_ERROR_TIMEOUT</literal></term>
164
<listitem><simpara> Add a timeout while mapping a port
165
</simpara></listitem>
166
</varlistentry>
167
</variablelist></refsect2>
168
<refsect2 id="gupnp-simple-igd-new" role="function">
169
<title>gupnp_simple_igd_new ()</title>
170
<indexterm zone="gupnp-simple-igd-new"><primary>gupnp_simple_igd_new</primary></indexterm><programlisting><link linkend="GUPnPSimpleIgd">GUPnPSimpleIgd</link>* gupnp_simple_igd_new (<link linkend="GMainContext">GMainContext</link> *main_context);</programlisting>
171
<para>
172
This creates a new <link linkend="GUPnpSimpleIgd"><type>GUPnpSimpleIgd</type></link> object using the special GMainContext</para>
173
<para>
174
175
</para><variablelist role="params">
176
<varlistentry><term><parameter>main_context</parameter> :</term>
177
<listitem><simpara> the <link linkend="GMainContext"><type>GMainContext</type></link> to use (may be NULL for the default
178
main context)
179
</simpara></listitem></varlistentry>
180
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a new <link linkend="GUPnPSimpleIgd"><type>GUPnPSimpleIgd</type></link>
181
</simpara></listitem></varlistentry>
182
</variablelist></refsect2>
183
<refsect2 id="gupnp-simple-igd-add-port" role="function">
184
<title>gupnp_simple_igd_add_port ()</title>
185
<indexterm zone="gupnp-simple-igd-add-port"><primary>gupnp_simple_igd_add_port</primary></indexterm><programlisting><link linkend="void">void</link> gupnp_simple_igd_add_port (<link linkend="GUPnPSimpleIgd">GUPnPSimpleIgd</link> *self,
186
const <link linkend="gchar">gchar</link> *protocol,
187
<link linkend="guint16">guint16</link> external_port,
188
const <link linkend="gchar">gchar</link> *local_ip,
189
<link linkend="guint16">guint16</link> local_port,
190
<link linkend="guint32">guint32</link> lease_duration,
191
const <link linkend="gchar">gchar</link> *description);</programlisting>
192
<para>
193
This adds a port to the router's forwarding table. The mapping will
194
be automatically refreshed by this object until it is either removed with
195
<link linkend="gupnp-simple-igd-remove-port"><function>gupnp_simple_igd_remove_port()</function></link> or the object disapears.
196
</para>
197
<para>
198
If there is a problem, the <link linkend="GUPnPSimpleIgd-error-mapping-port"><type>"error-mapping-port"</type></link> signal will
199
be emitted. If a router is found and a port is mapped correctly,
200
<link linkend="GUPnPSimpleIgd-mapped-external-port"><type>"mapped-external-port"</type></link> will be emitted. These signals may
201
be emitted multiple times if there are multiple routers present.</para>
202
<para>
203
204
</para><variablelist role="params">
205
<varlistentry><term><parameter>self</parameter> :</term>
206
<listitem><simpara> The <link linkend="GUPnPSimpleIgd"><type>GUPnPSimpleIgd</type></link> object
207
</simpara></listitem></varlistentry>
208
<varlistentry><term><parameter>protocol</parameter> :</term>
209
<listitem><simpara> the protocol "UDP" or "TCP"
210
</simpara></listitem></varlistentry>
211
<varlistentry><term><parameter>external_port</parameter> :</term>
212
<listitem><simpara> The port to try to open on the external device
213
</simpara></listitem></varlistentry>
214
<varlistentry><term><parameter>local_ip</parameter> :</term>
215
<listitem><simpara> The IP address to forward packets to (most likely the local ip address)
216
</simpara></listitem></varlistentry>
217
<varlistentry><term><parameter>local_port</parameter> :</term>
218
<listitem><simpara> The local port to forward packets to
219
</simpara></listitem></varlistentry>
220
<varlistentry><term><parameter>lease_duration</parameter> :</term>
221
<listitem><simpara> The duration of the lease (it will be auto-renewed before it expires). This is in seconds.
222
</simpara></listitem></varlistentry>
223
<varlistentry><term><parameter>description</parameter> :</term>
224
<listitem><simpara> The description that will appear in the router's table
225
</simpara></listitem></varlistentry>
226
</variablelist></refsect2>
227
<refsect2 id="gupnp-simple-igd-remove-port" role="function">
228
<title>gupnp_simple_igd_remove_port ()</title>
229
<indexterm zone="gupnp-simple-igd-remove-port"><primary>gupnp_simple_igd_remove_port</primary></indexterm><programlisting><link linkend="void">void</link> gupnp_simple_igd_remove_port (<link linkend="GUPnPSimpleIgd">GUPnPSimpleIgd</link> *self,
230
const <link linkend="gchar">gchar</link> *protocol,
231
<link linkend="guint">guint</link> external_port);</programlisting>
232
<para>
233
This tries to remove a port entry from the routers that was previously added
234
with <link linkend="gupnp-simple-igd-add-port"><function>gupnp_simple_igd_add_port()</function></link>. There is no indicated of success or failure
235
it is a best effort mechanism. If it fails, the bindings will disapears after
236
the lease duration set when the port where added.</para>
237
<para>
238
239
</para><variablelist role="params">
240
<varlistentry><term><parameter>self</parameter> :</term>
241
<listitem><simpara> The <link linkend="GUPnPSimpleIgd"><type>GUPnPSimpleIgd</type></link> object
242
</simpara></listitem></varlistentry>
243
<varlistentry><term><parameter>protocol</parameter> :</term>
244
<listitem><simpara> the protocol "UDP" or "TCP" as given to
245
<link linkend="gupnp-simple-igd-add-port"><function>gupnp_simple_igd_add_port()</function></link>
246
</simpara></listitem></varlistentry>
247
<varlistentry><term><parameter>external_port</parameter> :</term>
248
<listitem><simpara> The port to try to open on the external device as given to
249
<link linkend="gupnp-simple-igd-add-port"><function>gupnp_simple_igd_add_port()</function></link>
250
</simpara></listitem></varlistentry>
251
</variablelist></refsect2>
252
253
</refsect1>
254
<refsect1 id="GUPnPSimpleIgd.property-details" role="property_details">
255
<title role="property_details.title">Property Details</title>
256
<refsect2 id="GUPnPSimpleIgd--main-context"><title>The <literal>"main-context"</literal> property</title>
257
<indexterm zone="GUPnPSimpleIgd--main-context"><primary>GUPnPSimpleIgd:main-context</primary></indexterm><programlisting> "main-context" <link linkend="gpointer">gpointer</link> : Read / Write / Construct Only</programlisting>
258
<para>This GMainContext will be used for all async activities.</para></refsect2>
259
<refsect2 id="GUPnPSimpleIgd--request-timeout"><title>The <literal>"request-timeout"</literal> property</title>
260
<indexterm zone="GUPnPSimpleIgd--request-timeout"><primary>GUPnPSimpleIgd:request-timeout</primary></indexterm><programlisting> "request-timeout" <link linkend="guint">guint</link> : Read / Write</programlisting>
261
<para>After this timeout, the request is considered to have failed andis dropped (in seconds).</para><para>Default value: 5</para>
262
</refsect2>
263
264
</refsect1>
265
266
<refsect1 id="GUPnPSimpleIgd.signal-details" role="signals">
267
<title role="signals.title">Signal Details</title>
268
<refsect2 id="GUPnPSimpleIgd-error-mapping-port"><title>The <literal>"error-mapping-port"</literal> signal</title>
269
<indexterm zone="GUPnPSimpleIgd-error-mapping-port"><primary>GUPnPSimpleIgd::error-mapping-port</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="GUPnPSimpleIgd">GUPnPSimpleIgd</link> *self,
270
<link linkend="gpointer">gpointer</link> error,
271
<link linkend="gchar">gchar</link> *proto,
272
<link linkend="guint">guint</link> external_port,
273
<link linkend="gchar">gchar</link> *description,
274
<link linkend="gpointer">gpointer</link> user_data) : Run Last / Has Details</programlisting>
275
<para>
276
This means that mapping a port on a specific IGD has failed (it may still
277
succeed on other IGDs on the network).</para>
278
<para>
279
280
</para><variablelist role="params">
281
<varlistentry><term><parameter>self</parameter> :</term>
282
<listitem><simpara> <link linkend="GUPnPSimpleIgd"><type>GUPnPSimpleIgd</type></link> that emitted the signal
283
</simpara></listitem></varlistentry>
284
<varlistentry><term><parameter>error</parameter> :</term>
285
<listitem><simpara> a <link linkend="GError"><type>GError</type></link>
286
</simpara></listitem></varlistentry>
287
<varlistentry><term><parameter>proto</parameter> :</term>
288
<listitem><simpara> The requested protocol
289
</simpara></listitem></varlistentry>
290
<varlistentry><term><parameter>external_port</parameter> :</term>
291
<listitem><simpara> the requested external port
292
</simpara></listitem></varlistentry>
293
<varlistentry><term><parameter>description</parameter> :</term>
294
<listitem><simpara> the passed description
295
</simpara></listitem></varlistentry>
296
<varlistentry><term><parameter>user_data</parameter> :</term>
297
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
298
</variablelist></refsect2><refsect2 id="GUPnPSimpleIgd-mapped-external-port"><title>The <literal>"mapped-external-port"</literal> signal</title>
299
<indexterm zone="GUPnPSimpleIgd-mapped-external-port"><primary>GUPnPSimpleIgd::mapped-external-port</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="GUPnPSimpleIgd">GUPnPSimpleIgd</link> *self,
300
<link linkend="gchar">gchar</link> *proto,
301
<link linkend="gchar">gchar</link> *external_ip,
302
<link linkend="gchar">gchar</link> *replaces_external_ip,
303
<link linkend="guint">guint</link> external_port,
304
<link linkend="gchar">gchar</link> *local_ip,
305
<link linkend="guint">guint</link> local_port,
306
<link linkend="gchar">gchar</link> *description,
307
<link linkend="gpointer">gpointer</link> user_data) : Run Last</programlisting>
308
<para>
309
This signal means that an IGD has been found that that adding a port
310
mapping has succeeded.</para>
311
<para>
312
313
</para><variablelist role="params">
314
<varlistentry><term><parameter>self</parameter> :</term>
315
<listitem><simpara> <link linkend="GUPnPSimpleIgd"><type>GUPnPSimpleIgd</type></link> that emitted the signal
316
</simpara></listitem></varlistentry>
317
<varlistentry><term><parameter>proto</parameter> :</term>
318
<listitem><simpara> the requested protocol ("UDP" or "TCP")
319
</simpara></listitem></varlistentry>
320
<varlistentry><term><parameter>external_ip</parameter> :</term>
321
<listitem><simpara> the external IP
322
</simpara></listitem></varlistentry>
323
<varlistentry><term><parameter>replaces_external_ip</parameter> :</term>
324
<listitem><simpara> if this mapping replaces another mapping,
325
this is the old external IP
326
</simpara></listitem></varlistentry>
327
<varlistentry><term><parameter>external_port</parameter> :</term>
328
<listitem><simpara> the external port
329
</simpara></listitem></varlistentry>
330
<varlistentry><term><parameter>local_ip</parameter> :</term>
331
<listitem><simpara> internal ip this is forwarded to
332
</simpara></listitem></varlistentry>
333
<varlistentry><term><parameter>local_port</parameter> :</term>
334
<listitem><simpara> the local port
335
</simpara></listitem></varlistentry>
336
<varlistentry><term><parameter>description</parameter> :</term>
337
<listitem><simpara> the user's selected description
338
</simpara></listitem></varlistentry>
339
<varlistentry><term><parameter>user_data</parameter> :</term>
340
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
341
</variablelist></refsect2>
342
</refsect1>
343
344
345
346
</refentry>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1