[glib/wip/gapplication] Document application ID, validate it

[Colin Walters <walters src gnome org>]

commit c4417874fea3c9126d907678504300a2c537b5b8
Author: Colin Walters <walters verbum org>
Date:   Tue May 25 16:38:33 2010 -0400

    Document application ID, validate it

 gio/gapplication.c |   46 ++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 44 insertions(+), 2 deletions(-)
---
diff --git a/gio/gapplication.c b/gio/gapplication.c
index 82fb91c..f306871 100644
--- a/gio/gapplication.c
+++ b/gio/gapplication.c
@@ -36,8 +36,24 @@
  * @title: GApplication
  * @short_description: Core application class
  *
- * A #GApplication is the foundation of an application. There can be at most
- * one instance of this class.
+ * A #GApplication is the foundation of an application, unique for
+ * a given application identifier.  The #GApplication wraps some
+ * low-level platform-specific services; it's expected that most
+ * software will use a higher-level application class such as
+ * #GtkApplication.
+ *
+ * Before using #GApplication, you must choose an "application identifier".
+ * The expected form of an application identifier is very close to that of
+ * of a <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface";>DBus bus name</ulink>.
+ * Examples include: "com.example.MyApp" "org.example.internal-apps.Calculator"
+ * For convenience, the restrictions on application identifiers are reproduced
+ * here:
+ * <itemizedlist>
+ *   <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-" and must not begin with a digit.</listitem>
+ *   <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least two elements).</listitem>
+ *   <listitem>Application identifiers must not begin with a '.' (period) character.</listitem>
+ *   <listitem>Application identifiers must not exceed 255 characters.</listitem>
+ * </itemizedlist>
  *
  * Since: 2.24
  */
@@ -101,6 +117,31 @@ static void     _g_application_platform_on_actions_changed      (GApplication  *
 #include "gunixapplication.c"
 #endif
 
+static gboolean
+_g_application_validate_id (const char *id)
+{
+  gboolean allow_dot;
+
+  if (strlen (id) > 255)
+    return FALSE;
+
+  if (!g_ascii_isalpha (*id))
+    return FALSE;
+
+  id++;
+  allow_dot = FALSE;
+  for (; *id; id++)
+    {
+      if (g_ascii_isalnum (*id) || (*id == '-') || (*id == '_'))
+	allow_dot = TRUE;
+      else if (allow_dot && *id == '.')
+	allow_dot = FALSE;	
+      else
+	return FALSE;
+    }
+  return TRUE;
+}
+
 static gpointer
 init_appid_statics (gpointer data)
 {
@@ -595,6 +636,7 @@ g_application_set_property (GObject      *object,
   switch (prop_id)
     {
     case PROP_APPID:
+      g_return_if_fail (_g_application_validate_id (g_value_get_string (value)));
       app->priv->appid = g_value_dup_string (value);
       break;