Cleanup and doc GApplicationCommandLine

docs/reference/gio/gio-docs.xml

@@ -170,6 +170,7 @@
         <xi:include href="xml/gaction.xml"/>
         <xi:include href="xml/gsimpleaction.xml"/>
         <xi:include href="xml/gapplication.xml"/>
+        <xi:include href="xml/gapplicationcommandline.xml"/>
     </chapter>
     <chapter id="extending">
         <title>Extending GIO</title>

docs/reference/gio/gio-sections.txt

@@ -2710,10 +2710,8 @@ g_application_get_type
 GApplicationCommandLine
 GApplicationCommandLineClass
 <SUBSECTION>
-g_application_command_line_get_argc_argv
 g_application_command_line_get_arguments
 g_application_command_line_get_cwd
-g_application_command_line_get_cwd_variant
 g_application_command_line_get_is_remote
 g_application_command_line_get_platform_data
 <SUBSECTION>

gio/gapplicationcommandline.c

@@ -1,3 +1,24 @@
+/*
+ * Copyright © 2010 Codethink Limited
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * licence or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
+ * USA.
+ *
+ * Authors: Ryan Lortie <desrt@desrt.ca>
+ */
+
 #include "gapplicationcommandline.h"
 
 #include <string.h>
@@ -5,6 +26,30 @@
 
 G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJECT)
 
+/**
+ * SECTION:gapplicationcommandline
+ * @title: GApplicationCommandLine
+ * @short_description: A class representing a command-line invocation of
+ *                     this application.
+ * @see_also: #GApplication
+ *
+ * #GApplicationCommandLine represents a command-line invocation of
+ * containing application.  It is created by #GApplication and emitted
+ * in the <varname>command-line</varname> signal and virtual function.
+ *
+ * The class contains the list of arguments that the program was invoked
+ * with.  It is also possible to query if the commandline invocation was
+ * local (ie: the current process is running in direct response to the
+ * invocation) or remote (ie: some other process forwarded the
+ * commandline to this process).
+ *
+ * The exit status of the originally-invoked process may be set and
+ * messages can be printed to stdout or stderr of that process.  The
+ * lifecycle of the originally-invoked process is tied to the lifecycle
+ * of this object (ie: the process exits when the last reference is
+ * dropped).
+ **/
+
 enum
 {
   PROP_NONE,
@@ -21,122 +66,9 @@ struct _GApplicationCommandLinePrivate
   gint exit_status;
 };
 
-#define IS_REMOTE(cmdline) ((cmdline)->priv->platform_data != NULL)
+/* All subclasses represent remote invocations of some kind. */
-
+#define IS_REMOTE(cmdline) (G_TYPE_FROM_INSTANCE (cmdline) != \
-void
+                            G_TYPE_APPLICATION_COMMAND_LINE)
-g_application_command_line_get_argc_argv (GApplicationCommandLine   *cmdline,
-                                          int                       *argc,
-                                          char                    ***argv)
-{
-  gsize len;
-
-  g_return_if_fail (G_IS_APPLICATION_COMMAND_LINE (cmdline));
-  g_return_if_fail (argc != NULL && argv != NULL);
-
-  *argv = g_variant_dup_bytestring_array (cmdline->priv->arguments, &len);
-  *argc = len;
-}
-
-GVariant *
-g_application_command_line_get_arguments (GApplicationCommandLine *cmdline)
-{
-  return g_variant_ref (cmdline->priv->arguments);
-}
-
-const gchar *
-g_application_command_line_get_cwd (GApplicationCommandLine *cmdline)
-{
-  if (cmdline->priv->cwd)
-    return g_variant_get_bytestring (cmdline->priv->cwd);
-  else
-    return NULL;
-}
-
-GVariant *
-g_application_command_line_get_cwd_variant (GApplicationCommandLine *cmdline)
-{
-  if (cmdline->priv->cwd)
-    return g_variant_ref (cmdline->priv->cwd);
-  else
-    return NULL;
-}
-
-gboolean
-g_application_command_line_get_is_remote (GApplicationCommandLine *cmdline)
-{
-  return IS_REMOTE (cmdline);
-}
-
-static void
-g_application_command_line_real_print_literal (GApplicationCommandLine *cmdline,
-                                               const gchar             *message)
-{
-  g_print ("%s\n", message);
-}
-
-static void
-g_application_command_line_real_printerr_literal (GApplicationCommandLine *cmdline,
-                                                  const gchar             *message)
-{
-  g_printerr ("%s\n", message);
-}
-
-void
-g_application_command_line_print (GApplicationCommandLine *cmdline,
-                                  const gchar             *format,
-                                  ...)
-{
-  gchar *message;
-  va_list ap;
-
-  g_return_if_fail (G_IS_APPLICATION_COMMAND_LINE (cmdline));
-  g_return_if_fail (format != NULL);
-
-  va_start (ap, format);
-  message = g_strdup_vprintf (format, ap);
-  va_end (ap);
-
-  G_APPLICATION_COMMAND_LINE_GET_CLASS (cmdline)
-    ->print_literal (cmdline, message);
-  g_free (message);
-}
-
-void
-g_application_command_line_printerr (GApplicationCommandLine *cmdline,
-                                     const gchar             *format,
-                                     ...)
-{
-  gchar *message;
-  va_list ap;
-
-  g_return_if_fail (G_IS_APPLICATION_COMMAND_LINE (cmdline));
-  g_return_if_fail (format != NULL);
-
-  va_start (ap, format);
-  message = g_strdup_vprintf (format, ap);
-  va_end (ap);
-
-  G_APPLICATION_COMMAND_LINE_GET_CLASS (cmdline)
-    ->printerr_literal (cmdline, message);
-  g_free (message);
-}
-
-void
-g_application_command_line_set_exit_status (GApplicationCommandLine *cmdline,
-                                            int                      exit_status)
-{
-  g_return_if_fail (G_IS_APPLICATION_COMMAND_LINE (cmdline));
-
-  cmdline->priv->exit_status = exit_status;
-}
-
-int
-g_application_command_line_get_exit_status (GApplicationCommandLine *cmdline)
-{
-  g_return_val_if_fail (G_IS_APPLICATION_COMMAND_LINE (cmdline), -1);
-
-  return cmdline->priv->exit_status;
-}
 
 static void
 grok_platform_data (GApplicationCommandLine *cmdline)
@@ -155,6 +87,20 @@ grok_platform_data (GApplicationCommandLine *cmdline)
       }
 }
 
+static void
+g_application_command_line_real_print_literal (GApplicationCommandLine *cmdline,
+                                               const gchar             *message)
+{
+  g_print ("%s\n", message);
+}
+
+static void
+g_application_command_line_real_printerr_literal (GApplicationCommandLine *cmdline,
+                                                  const gchar             *message)
+{
+  g_printerr ("%s\n", message);
+}
+
 static void
 g_application_command_line_get_property (GObject *object, guint prop_id,
                                          GValue *value, GParamSpec *pspec)
@@ -181,8 +127,10 @@ g_application_command_line_get_property (GObject *object, guint prop_id,
 }
 
 static void
-g_application_command_line_set_property (GObject *object, guint prop_id,
+g_application_command_line_set_property (GObject      *object,
-                                         const GValue *value, GParamSpec *pspec)
+                                         guint         prop_id,
+                                         const GValue *value,
+                                         GParamSpec   *pspec)
 {
   GApplicationCommandLine *cmdline = G_APPLICATION_COMMAND_LINE (object);
 
@@ -263,11 +211,233 @@ g_application_command_line_class_init (GApplicationCommandLineClass *class)
   g_type_class_add_private (class, sizeof (GApplicationCommandLinePrivate));
 }
 
+
+/**
+ * g_application_command_line_get_arguments:
+ * @cmdline: a #GApplicationCommandLine
+ * @argc: the length of the arguments array, or %NULL
+ *
+ * Gets the list of arguments that was passed on the command line.
+ *
+ * The strings in the array may contain non-utf8 data.
+ *
+ * The return value is %NULL-terminated and should be freed using
+ * g_strfreev().
+ *
+ * Returns: the string array containing the arguments (the argv)
+ *
+ * Since: 2.28
+ **/
+gchar **
+g_application_command_line_get_arguments (GApplicationCommandLine   *cmdline,
+                                          int                       *argc)
+{
+  gchar **argv;
+  gsize len;
+
+  g_return_val_if_fail (G_IS_APPLICATION_COMMAND_LINE (cmdline), NULL);
+
+  argv = g_variant_dup_bytestring_array (cmdline->priv->arguments, &len);
+
+  if (argc)
+    *argc = len;
+
+  return argv;
+}
+
+/**
+ * g_application_command_line_get_cwd:
+ * @cmdline: a #GApplicationCommandLine
+ * 
+ * Gets the working directory of the command line invocation.  The
+ * string may contain non-utf8 data.
+ *
+ * It is possible that the remote application did not send a working
+ * directory, so this may be %NULL.
+ *
+ * The return value should not be modified or freed and is valid for as
+ * long as @cmdline exists.
+ *
+ * Returns: the current directory, or %NULL
+ *
+ * Since: 2.28
+ **/
+const gchar *
+g_application_command_line_get_cwd (GApplicationCommandLine *cmdline)
+{
+  if (cmdline->priv->cwd)
+    return g_variant_get_bytestring (cmdline->priv->cwd);
+  else
+    return NULL;
+}
+
+/**
+ * g_application_command_line_get_is_remote:
+ * @cmdline: a #GApplicationCommandLine
+ *
+ * Determines if @cmdline represents a remote invocation.
+ *
+ * Returns: %TRUE if the invocation was remote
+ *
+ * Since: 2.28
+ **/
+gboolean
+g_application_command_line_get_is_remote (GApplicationCommandLine *cmdline)
+{
+  return IS_REMOTE (cmdline);
+}
+
+/**
+ * g_application_command_line_print:
+ * @cmdline: a #GApplicationCommandLine
+ * @format: a printf-style format string
+ * @...: arguments, as per @format
+ *
+ * Formats a message and prints it using the stdout print handler in the
+ * invoking process.
+ *
+ * If @cmdline is a local invocation then this is exactly equivalent to
+ * g_print().  If @cmdline is remote then this is equivalent to calling
+ * g_print() in the invoking process.
+ *
+ * Since: 2.28
+ **/
+void
+g_application_command_line_print (GApplicationCommandLine *cmdline,
+                                  const gchar             *format,
+                                  ...)
+{
+  gchar *message;
+  va_list ap;
+
+  g_return_if_fail (G_IS_APPLICATION_COMMAND_LINE (cmdline));
+  g_return_if_fail (format != NULL);
+
+  va_start (ap, format);
+  message = g_strdup_vprintf (format, ap);
+  va_end (ap);
+
+  G_APPLICATION_COMMAND_LINE_GET_CLASS (cmdline)
+    ->print_literal (cmdline, message);
+  g_free (message);
+}
+
+/**
+ * g_application_command_line_printerr:
+ * @cmdline: a #GApplicationCommandLine
+ * @format: a printf-style format string
+ * @...: arguments, as per @format
+ *
+ * Formats a message and prints it using the stderr print handler in the
+ * invoking process.
+ *
+ * If @cmdline is a local invocation then this is exactly equivalent to
+ * g_printerr().  If @cmdline is remote then this is equivalent to
+ * calling g_printerr() in the invoking process.
+ *
+ * Since: 2.28
+ **/
+void
+g_application_command_line_printerr (GApplicationCommandLine *cmdline,
+                                     const gchar             *format,
+                                     ...)
+{
+  gchar *message;
+  va_list ap;
+
+  g_return_if_fail (G_IS_APPLICATION_COMMAND_LINE (cmdline));
+  g_return_if_fail (format != NULL);
+
+  va_start (ap, format);
+  message = g_strdup_vprintf (format, ap);
+  va_end (ap);
+
+  G_APPLICATION_COMMAND_LINE_GET_CLASS (cmdline)
+    ->printerr_literal (cmdline, message);
+  g_free (message);
+}
+
+/**
+ * g_application_command_line_set_exit_status:
+ * @cmdline: a #GApplicationCommandLine
+ * @exit_status: the exit status
+ *
+ * Sets the exit status that will be used when the invoking process
+ * exits.
+ *
+ * The return value of the <varname>command-line</varname> signal is
+ * passed to this function when the handler returns.  This is the usual
+ * way of setting the exit status.
+ *
+ * In the event that you want the remote invocation to continue running
+ * and want to decide on the exit status in the future, you can use this
+ * call.  For the case of a remote invocation, the remote process will
+ * typically exit when the last reference is dropped on @cmdline.  The
+ * exit status of the remote process will be equal to the last value
+ * that was set with this function.
+ *
+ * In the case that the commandline invocation is local, the situation
+ * is slightly more complicated.  If the commandline invocation results
+ * in the mainloop running (ie: because the use-count of the application
+ * increased to a non-zero value) then the application is considered to
+ * have been 'successful' in a certain sense, and the exit status is
+ * always zero.  If the application use count is zero, though, the exit
+ * status of the local #GApplicationCommandLine is used.
+ *
+ * Since: 2.28
+ **/
+void
+g_application_command_line_set_exit_status (GApplicationCommandLine *cmdline,
+                                            int                      exit_status)
+{
+  g_return_if_fail (G_IS_APPLICATION_COMMAND_LINE (cmdline));
+
+  cmdline->priv->exit_status = exit_status;
+}
+
+/**
+ * g_application_command_line_get_exit_status:
+ * @cmdline: a #GApplicationCommandLine
+ *
+ * Gets the exit status of @cmdline.  See
+ * g_application_command_line_set_exit_status() for more information.
+ *
+ * Returns: the exit status
+ *
+ * Since: 2.28
+ **/
+int
+g_application_command_line_get_exit_status (GApplicationCommandLine *cmdline)
+{
+  g_return_val_if_fail (G_IS_APPLICATION_COMMAND_LINE (cmdline), -1);
+
+  return cmdline->priv->exit_status;
+}
+
+/**
+ * g_application_command_line_get_platform_data:
+ * @cmdline: #GApplicationCommandLine
+ *
+ * Gets the platform data associated with the invocation of @cmdline.
+ *
+ * This is a #GVariant dictionary containing information about the
+ * context in which the invocation occured.  It typically contains
+ * information like the current working directory and the startup
+ * notification ID.
+ *
+ * For local invocation, it will be %NULL.
+ *
+ * Returns: the platform data, or %NULL
+ *
+ * Since: 2.28
+ **/
 GVariant *
 g_application_command_line_get_platform_data (GApplicationCommandLine *cmdline)
 {
   g_return_val_if_fail (G_IS_APPLICATION_COMMAND_LINE (cmdline), NULL);
-  g_return_val_if_fail (IS_REMOTE (cmdline), NULL);
 
-  return g_variant_ref (cmdline->priv->platform_data);
+  if (cmdline->priv->platform_data)
+    return g_variant_ref (cmdline->priv->platform_data);
+  else
+      return NULL;
 }

gio/gapplicationcommandline.h

@@ -78,9 +78,9 @@ struct _GApplicationCommandLineClass
   /*< private >*/
   GObjectClass parent_class;
 
-  void (* print_literal)    (GApplicationCommandLine *command_line,
+  void (* print_literal)    (GApplicationCommandLine *cmdline,
                              const gchar             *message);
-  void (* printerr_literal) (GApplicationCommandLine *command_line,
+  void (* printerr_literal) (GApplicationCommandLine *cmdline,
                              const gchar             *message);
 
   gpointer padding[12];
@@ -88,32 +88,25 @@ struct _GApplicationCommandLineClass
 
 GType                   g_application_command_line_get_type             (void) G_GNUC_CONST;
 
-void                    g_application_command_line_get_argc_argv        (GApplicationCommandLine   *command_line,
+gchar **                g_application_command_line_get_arguments        (GApplicationCommandLine   *cmdline,
-                                                                         int                       *argc,
+                                                                         int                       *argc);
-                                                                         char                    ***argv);
-GVariant *              g_application_command_line_get_arguments        (GApplicationCommandLine   *command_line);
 
-const gchar *           g_application_command_line_get_cwd              (GApplicationCommandLine   *command_line);
+const gchar *           g_application_command_line_get_cwd              (GApplicationCommandLine   *cmdline);
-GVariant *              g_application_command_line_get_cwd_variant      (GApplicationCommandLine   *command_line);
 
-gboolean                g_application_command_line_get_is_remote        (GApplicationCommandLine   *command_line);
+gboolean                g_application_command_line_get_is_remote        (GApplicationCommandLine   *cmdline);
 
-void                    g_application_command_line_output               (GApplicationCommandLine   *command_line,
+void                    g_application_command_line_print                (GApplicationCommandLine   *cmdline,
-                                                                         gint                       fd,
-                                                                         gconstpointer              buffer,
-                                                                         gssize                     length);
-void                    g_application_command_line_print                (GApplicationCommandLine   *command_line,
                                                                          const gchar               *format,
                                                                          ...);
-void                    g_application_command_line_printerr             (GApplicationCommandLine   *command_line,
+void                    g_application_command_line_printerr             (GApplicationCommandLine   *cmdline,
                                                                          const gchar               *format,
                                                                          ...);
 
-int                     g_application_command_line_get_exit_status      (GApplicationCommandLine   *command_line);
+int                     g_application_command_line_get_exit_status      (GApplicationCommandLine   *cmdline);
-void                    g_application_command_line_set_exit_status      (GApplicationCommandLine   *command_line,
+void                    g_application_command_line_set_exit_status      (GApplicationCommandLine   *cmdline,
                                                                          int                        exit_status);
 
-GVariant *              g_application_command_line_get_platform_data    (GApplicationCommandLine   *command_line);
+GVariant *              g_application_command_line_get_platform_data    (GApplicationCommandLine   *cmdline);
 
 G_END_DECLS
 

gio/tests/gapplication.c

@@ -40,7 +40,7 @@ command_line (GApplication            *application,
   gchar **argv;
   gint argc;
 
-  g_application_command_line_get_argc_argv (cmdline, &argc, &argv);
+  argv = g_application_command_line_get_arguments (cmdline, &argc);
 
   g_application_command_line_print (cmdline, "%d + %d = %d\n", 40, 2, 42);