[glib] Cleanup and doc GApplicationCommandLine
- From: Ryan Lortie <ryanl src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib] Cleanup and doc GApplicationCommandLine
- Date: Tue, 19 Oct 2010 16:30:07 +0000 (UTC)
commit a327bc51fc3090ed32d7e250dedadb8c35e84aeb
Author: Ryan Lortie <desrt desrt ca>
Date: Tue Oct 19 18:18:13 2010 +0200
Cleanup and doc GApplicationCommandLine
docs/reference/gio/gio-docs.xml | 1 +
docs/reference/gio/gio-sections.txt | 2 -
gio/gapplicationcommandline.c | 406 +++++++++++++++++++++++++----------
gio/gapplicationcommandline.h | 29 +--
gio/tests/gapplication.c | 2 +-
5 files changed, 301 insertions(+), 139 deletions(-)
---
diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml
index d6c8361..ab599f2 100644
--- a/docs/reference/gio/gio-docs.xml
+++ b/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>
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index 8311a27..408c8b0 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/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>
diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c
index af9d7a8..3b28525 100644
--- a/gio/gapplicationcommandline.c
+++ b/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,50 +66,25 @@ struct _GApplicationCommandLinePrivate
gint exit_status;
};
-#define IS_REMOTE(cmdline) ((cmdline)->priv->platform_data != NULL)
-
-void
-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);
-}
+/* All subclasses represent remote invocations of some kind. */
+#define IS_REMOTE(cmdline) (G_TYPE_FROM_INSTANCE (cmdline) != \
+ G_TYPE_APPLICATION_COMMAND_LINE)
-const gchar *
-g_application_command_line_get_cwd (GApplicationCommandLine *cmdline)
+static void
+grok_platform_data (GApplicationCommandLine *cmdline)
{
- if (cmdline->priv->cwd)
- return g_variant_get_bytestring (cmdline->priv->cwd);
- else
- return NULL;
-}
+ GVariantIter iter;
+ const gchar *key;
+ GVariant *value;
-GVariant *
-g_application_command_line_get_cwd_variant (GApplicationCommandLine *cmdline)
-{
- if (cmdline->priv->cwd)
- return g_variant_ref (cmdline->priv->cwd);
- else
- return NULL;
-}
+ g_variant_iter_init (&iter, cmdline->priv->platform_data);
-gboolean
-g_application_command_line_get_is_remote (GApplicationCommandLine *cmdline)
-{
- return IS_REMOTE (cmdline);
+ while (g_variant_iter_loop (&iter, "{&sv}", &key, &value))
+ if (strcmp (key, "cwd") == 0)
+ {
+ if (!cmdline->priv->cwd)
+ cmdline->priv->cwd = g_variant_ref (value);
+ }
}
static void
@@ -81,80 +101,6 @@ g_application_command_line_real_printerr_literal (GApplicationCommandLine *cmdli
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)
-{
- GVariantIter iter;
- const gchar *key;
- GVariant *value;
-
- g_variant_iter_init (&iter, cmdline->priv->platform_data);
-
- while (g_variant_iter_loop (&iter, "{&sv}", &key, &value))
- if (strcmp (key, "cwd") == 0)
- {
- if (!cmdline->priv->cwd)
- cmdline->priv->cwd = g_variant_ref (value);
- }
-}
-
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,
- const GValue *value, GParamSpec *pspec)
+g_application_command_line_set_property (GObject *object,
+ 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;
}
diff --git a/gio/gapplicationcommandline.h b/gio/gapplicationcommandline.h
index f0547b0..7c120a5 100644
--- a/gio/gapplicationcommandline.h
+++ b/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,
- int *argc,
- char ***argv);
-GVariant * g_application_command_line_get_arguments (GApplicationCommandLine *command_line);
+gchar ** g_application_command_line_get_arguments (GApplicationCommandLine *cmdline,
+ int *argc);
-const gchar * g_application_command_line_get_cwd (GApplicationCommandLine *command_line);
-GVariant * g_application_command_line_get_cwd_variant (GApplicationCommandLine *command_line);
+const gchar * g_application_command_line_get_cwd (GApplicationCommandLine *cmdline);
-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,
- gint fd,
- gconstpointer buffer,
- gssize length);
-void g_application_command_line_print (GApplicationCommandLine *command_line,
+void g_application_command_line_print (GApplicationCommandLine *cmdline,
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);
-void g_application_command_line_set_exit_status (GApplicationCommandLine *command_line,
+int g_application_command_line_get_exit_status (GApplicationCommandLine *cmdline);
+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
diff --git a/gio/tests/gapplication.c b/gio/tests/gapplication.c
index 39e9923..453d8d8 100644
--- a/gio/tests/gapplication.c
+++ b/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);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
