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
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
<?xml version='1.0' encoding='UTF-8'?>
<!-- This document was created with Syntext Serna Free. -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="client-tutorial">
<title>Writing an UPnP Client</title>
<simplesect>
<title>Introduction</title>
<para>
This chapter explains how to write an application which fetches the
external IP address from an UPnP-compliant modem. To do this a
<glossterm>Control Point</glossterm> is created, which searches for
services of the type
<literal>urn:schemas-upnp-org:service:WANIPConnection:1</literal> (part of
the <ulink url="http://upnp.org/standardizeddcps/igd.asp">Internet Gateway Device</ulink> specification). As services are discovered
<firstterm>Service Proxy</firstterm> objects are created by GUPnP to allow
interaction with the service, on which we can invoke the action
<function>GetExternalIPAddress</function> to fetch the external IP
address.
</para>
</simplesect>
<simplesect>
<title>Finding Services</title>
<para>
First, we initialize GUPnP and create a control point targeting the
service type. Then we connect a signal handler so that we are notified
when services we are interested in are found.
</para>
<programlisting>#include <libgupnp/gupnp-control-point.h>
static GMainLoop *main_loop;
static void
service_proxy_available_cb (GUPnPControlPoint *cp,
GUPnPServiceProxy *proxy,
gpointer userdata)
{
/* … */
}
int
main (int argc, char **argv)
{
GUPnPContext *context;
GUPnPControlPoint *cp;
/* Create a new GUPnP Context. By here we are using the default GLib main
context, and connecting to the current machine's default IP on an
automatically generated port. */
context = gupnp_context_new (NULL, 0, NULL);
/* Create a Control Point targeting WAN IP Connection services */
cp = gupnp_control_point_new
(context, "urn:schemas-upnp-org:service:WANIPConnection:1");
/* The service-proxy-available signal is emitted when any services which match
our target are found, so connect to it */
g_signal_connect (cp,
"service-proxy-available",
G_CALLBACK (service_proxy_available_cb),
NULL);
/* Tell the Control Point to start searching */
gssdp_resource_browser_set_active (GSSDP_RESOURCE_BROWSER (cp), TRUE);
/* Enter the main loop. This will start the search and result in callbacks to
service_proxy_available_cb. */
main_loop = g_main_loop_new (NULL, FALSE);
g_main_loop_run (main_loop);
/* Clean up */
g_main_loop_unref (main_loop);
g_object_unref (cp);
g_object_unref (context);
return 0;
}</programlisting>
</simplesect>
<simplesect>
<title>Invoking Actions</title>
<para>
Now we have an application which searches for the service we specified and
calls <function>service_proxy_available_cb</function> for each one it
found. To get the external IP address we need to invoke the
<literal>GetExternalIPAddress</literal> action. This action takes no in
arguments, and has a single out argument called "NewExternalIPAddress".
GUPnP has a set of methods to invoke actions (which will be very familiar
to anyone who has used <literal>dbus-glib</literal>) where you pass a
<constant>NULL</constant>-terminated varargs list of (name, GType, value)
tuples for the in arguments, then a <constant>NULL</constant>-terminated
varargs list of (name, GType, return location) tuples for the out
arguments.
</para>
<programlisting>static void
service_proxy_available_cb (GUPnPControlPoint *cp,
GUPnPServiceProxy *proxy,
gpointer userdata)
{
GError *error = NULL;
char *ip = NULL;
GUPnPServiceProxyAction *action = NULL;
action = gupnp_service_proxy_action_new (
/* Action name */
"GetExternalIPAddress",
/* IN args */
NULL);
gupnp_service_proxy_call_action (proxy,
action,
NULL,
&error);
if (error != NULL) {
goto out;
}
gupnp_service_proxy_action_get_result (action,
/* Error location */
&error,
/* OUT args */
"NewExternalIPAddress",
G_TYPE_STRING, &ip,
NULL);
if (error == NULL) {
g_print ("External IP address is %s\n", ip);
g_free (ip);
}
out:
if (error != NULL) {
g_printerr ("Error: %s\n", error->message);
g_error_free (error);
}
gupnp_service_proxy_action_unref (action);
g_main_loop_quit (main_loop);
}</programlisting>
<para>Note that gupnp_service_proxy_call_action() blocks until the service has
replied. If you need to make non-blocking calls then use
gupnp_service_proxy_call_action_async(), which takes a callback that will be
called from the mainloop when the reply is received.
</para>
</simplesect>
<simplesect>
<title>Subscribing to state variable change notifications</title>
<para>
It is possible to get change notifications for the service state variables
that have attribute <literal>sendEvents="yes"</literal>. We'll demonstrate
this by modifying <function>service_proxy_available_cb</function> and using
gupnp_service_proxy_add_notify() to setup a notification callback:
</para>
<programlisting>static void
external_ip_address_changed (GUPnPServiceProxy *proxy,
const char *variable,
GValue *value,
gpointer userdata)
{
g_print ("External IP address changed: %s\n", g_value_get_string (value));
}
static void
service_proxy_available_cb (GUPnPControlPoint *cp,
GUPnPServiceProxy *proxy,
gpointer userdata)
{
g_print ("Found a WAN IP Connection service\n");
gupnp_service_proxy_set_subscribed (proxy, TRUE);
if (!gupnp_service_proxy_add_notify (proxy,
"ExternalIPAddress",
G_TYPE_STRING,
external_ip_address_changed,
NULL)) {
g_printerr ("Failed to add notify");
}
}</programlisting>
</simplesect>
<simplesect>
<title>Generating Wrappers</title>
<para>
Using gupnp_service_proxy_call_action() and gupnp_service_proxy_add_notify ()
can become tedious, because of the requirement to specify the types and deal
with GValues. An
alternative is to use <xref linkend="gupnp-binding-tool"/>, which
generates wrappers that hide the boilerplate code from you. Using a
wrapper generated with prefix 'ipconn' would replace
gupnp_service_proxy_call_action() with this code:
</para>
<programlisting>ipconn_get_external_ip_address (proxy, &ip, &error);</programlisting>
<para>
State variable change notifications are friendlier with wrappers as well:
</para>
<programlisting>static void
external_ip_address_changed (GUPnPServiceProxy *proxy,
const gchar *external_ip_address,
gpointer userdata)
{
g_print ("External IP address changed: '%s'\n", external_ip_address);
}
static void
service_proxy_available_cb (GUPnPControlPoint *cp,
GUPnPServiceProxy *proxy
gpointer userdata)
{
g_print ("Found a WAN IP Connection service\n");
gupnp_service_proxy_set_subscribed (proxy, TRUE);
if (!ipconn_external_ip_address_add_notify (proxy,
external_ip_address_changed,
NULL)) {
g_printerr ("Failed to add notify");
}
}</programlisting>
</simplesect>
</chapter>
|
