[gupnp/wip/phako/new-api: 16/17] wip: doc: Update client-tutorial for new functions
- From: Jens Georg <jensgeorg src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gupnp/wip/phako/new-api: 16/17] wip: doc: Update client-tutorial for new functions
- Date: Sun, 13 Jan 2019 18:14:34 +0000 (UTC)
commit 95a78fa9ed8a21a9c7d00c039b155b606d309216
Author: Jens Georg <mail jensge org>
Date: Sun Jan 13 18:08:28 2019 +0100
wip: doc: Update client-tutorial for new functions
doc/client-tutorial.xml | 103 +++++++++++++++++++++++++-----------------------
1 file changed, 54 insertions(+), 49 deletions(-)
---
diff --git a/doc/client-tutorial.xml b/doc/client-tutorial.xml
index 0373d68..98d528c 100644
--- a/doc/client-tutorial.xml
+++ b/doc/client-tutorial.xml
@@ -1,9 +1,8 @@
-<?xml version="1.0"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd";>
-
+<?xml version='1.0' encoding='UTF-8'?>
+<!-- This document was created with Syntext Serna Free. -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; []>
<chapter id="client-tutorial">
- <title>Writing a UPnP Client</title>
-
+ <title>Writing an UPnP Client</title>
<simplesect>
<title>Introduction</title>
<para>
@@ -12,15 +11,13 @@
<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
+ 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>
@@ -45,27 +42,22 @@ main (int argc, char **argv)
{
GUPnPContext *context;
GUPnPControlPoint *cp;
-
- /* Required initialisation */
- #if !GLIB_CHECK_VERSION(2,35,0)
- g_type_init ();
- #endif
/* 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
+ context, and connecting to the current machine's default IP on an
automatically generated port. */
- context = gupnp_context_new (NULL, NULL, 0, NULL);
+ 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");
+ (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);
+ "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);
@@ -83,7 +75,6 @@ main (int argc, char **argv)
return 0;
}</programlisting>
</simplesect>
-
<simplesect>
<title>Invoking Actions</title>
<para>
@@ -91,7 +82,7 @@ main (int argc, char **argv)
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".
+ 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)
@@ -106,39 +97,54 @@ service_proxy_available_cb (GUPnPControlPoint *cp,
{
GError *error = NULL;
char *ip = NULL;
+ GUPnPServiceProxyAction *action = NULL;
- gupnp_service_proxy_send_action (proxy,
- /* Action name and error location */
- "GetExternalIPAddress", &error,
- /* IN args */
- NULL,
- /* OUT args */
- "NewExternalIPAddress",
- G_TYPE_STRING, &ip,
- 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_print ("External IP address is %s\n", ip);
g_free (ip);
- } else {
- g_printerr ("Error: %s\n", error->message);
+ }
+
+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_send_action() blocks until the service has
+ <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_begin_action(), which takes a callback that will be
+ 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
+ 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>
@@ -148,7 +154,7 @@ external_ip_address_changed (GUPnPServiceProxy *proxy,
GValue *value,
gpointer userdata)
{
- g_print ("External IP address changed: %s\n", g_value_get_string (value));
+ g_print ("External IP address changed: %s\n", g_value_get_string (value));
}
static void
@@ -156,29 +162,28 @@ service_proxy_available_cb (GUPnPControlPoint *cp,
GUPnPServiceProxy *proxy,
gpointer userdata)
{
- g_print ("Found a WAN IP Connection service\n");
+ g_print ("Found a WAN IP Connection service\n");
gupnp_service_proxy_set_subscribed (proxy, TRUE);
if (!gupnp_service_proxy_add_notify (proxy,
- "ExternalIPAddress",
+ "ExternalIPAddress",
G_TYPE_STRING,
external_ip_address_changed,
NULL)) {
- g_printerr ("Failed to add notify");
+ g_printerr ("Failed to add notify");
}
}</programlisting>
</simplesect>
-
<simplesect>
<title>Generating Wrappers</title>
<para>
- Using gupnp_service_proxy_send_action() and gupnp_service_proxy_add_notify ()
+ 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_send_action() with this code:
+ 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>
@@ -189,7 +194,7 @@ external_ip_address_changed (GUPnPServiceProxy *proxy,
const gchar *external_ip_address,
gpointer userdata)
{
- g_print ("External IP address changed: '%s'\n", external_ip_address);
+ g_print ("External IP address changed: '%s'\n", external_ip_address);
}
static void
@@ -197,13 +202,13 @@ service_proxy_available_cb (GUPnPControlPoint *cp,
GUPnPServiceProxy *proxy
gpointer userdata)
{
- g_print ("Found a WAN IP Connection service\n");
+ 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");
+ g_printerr ("Failed to add notify");
}
}</programlisting>
</simplesect>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
