service-proxy: Add new API for calling actions

2 files changed, 65 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&apos;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, &quot;urn:schemas-upnp-org:service:WANIPConnection:1&quot;);
 
   /* 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);
+      &quot;service-proxy-available&quot;,
+      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 &quot;NewExternalIPAddress&quot;.
       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", &amp;error,
-				   /* IN args */
-				   NULL,
-				   /* OUT args */
-				   "NewExternalIPAddress",
-				   G_TYPE_STRING, &amp;ip,
-				   NULL);
+  action = gupnp_service_proxy_action_new (
+       /* Action name */
+       &quot;GetExternalIPAddress&quot;,
+       /* IN args */
+       NULL);
+  gupnp_service_proxy_call_action (proxy,
+                                   action,
+                                   NULL,
+                                   &amp;error);
+  if (error != NULL) {
+    goto out;
+  }
+
+  gupnp_service_proxy_action_get_result (action,
+       /* Error location */
+       &amp;error,
+       /* OUT args */
+       &quot;NewExternalIPAddress&quot;,
+       G_TYPE_STRING, &amp;ip,
+       NULL);
   
   if (error == NULL) {
-    g_print ("External IP address is %s\n", ip);
+    g_print (&quot;External IP address is %s\n&quot;, ip);
     g_free (ip);
-  } else {
-    g_printerr ("Error: %s\n", error-&gt;message);
+  }
+
+out:
+  if (error != NULL) {
+    g_printerr (&quot;Error: %s\n&quot;, error-&gt;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=&quot;yes&quot;</literal>. We&apos;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 (&quot;External IP address changed: %s\n&quot;, 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 (&quot;Found a WAN IP Connection service\n&quot;);
   
   gupnp_service_proxy_set_subscribed (proxy, TRUE);
   if (!gupnp_service_proxy_add_notify (proxy,
-                                       "ExternalIPAddress",
+                                       &quot;ExternalIPAddress&quot;,
                                        G_TYPE_STRING,
                                        external_ip_address_changed,
                                        NULL)) {
-    g_printerr ("Failed to add notify");
+    g_printerr (&quot;Failed to add notify&quot;);
   }
 }</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 &apos;ipconn&apos; would replace
+      gupnp_service_proxy_call_action() with this code:
     </para>
     <programlisting>ipconn_get_external_ip_address (proxy, &amp;ip, &amp;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 (&quot;External IP address changed: &apos;%s&apos;\n&quot;, 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 (&quot;Found a WAN IP Connection service\n&quot;);
   
   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 (&quot;Failed to add notify&quot;);
   }
 }</programlisting>
   </simplesect>
diff --git a/doc/gupnp-sections.txt b/doc/gupnp-sections.txt
index f548ba5..0eca13d 100644
--- a/doc/gupnp-sections.txt
+++ b/doc/gupnp-sections.txt
@@ -71,6 +71,9 @@ GUPnPServiceProxy
 GUPnPServiceProxyAction
 GUPnPServiceProxyActionCallback
 GUPnPServiceProxyNotifyCallback
+gupnp_service_proxy_call_action
+gupnp_service_proxy_call_action_async
+gupnp_service_proxy_call_action_finish
 gupnp_service_proxy_send_action
 gupnp_service_proxy_send_action_valist
 gupnp_service_proxy_send_action_list
@@ -89,6 +92,14 @@ gupnp_service_proxy_remove_notify
 gupnp_service_proxy_remove_raw_notify
 gupnp_service_proxy_set_subscribed
 gupnp_service_proxy_get_subscribed
+gupnp_service_proxy_action_get_result
+gupnp_service_proxy_action_get_result_hash
+gupnp_service_proxy_action_get_result_list
+gupnp_service_proxy_action_get_type
+gupnp_service_proxy_action_new
+gupnp_service_proxy_action_new_from_list
+gupnp_service_proxy_action_ref
+gupnp_service_proxy_action_unref
 <SUBSECTION Standard>
 GUPnPServiceProxyClass
 GUPNP_SERVICE_PROXY