From a6d2a696cf0df7be8a2c731e441ffdf8ce4dc086 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 3 Dec 2009 16:25:33 -0600 Subject: Putting in comments for the functions. --- libindicator/indicator-service.c | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/libindicator/indicator-service.c b/libindicator/indicator-service.c index 89842bb..003566a 100644 --- a/libindicator/indicator-service.c +++ b/libindicator/indicator-service.c @@ -14,8 +14,16 @@ static gboolean _indicator_service_server_un_watch (IndicatorService * service, #include "dbus-shared.h" /* Private Stuff */ +/** + IndicatorSevicePrivate: + @name: The DBus well known name for the service. + @dbus_proxy: A proxy for talking to the dbus bus manager. + @timeout: The source ID for the timeout event. + @watcher: A list of processes on dbus that are watching us. + @this_service_version: The version to hand out that we're + implementing. May not be set, so we'll send zero (default). +*/ typedef struct _IndicatorServicePrivate IndicatorServicePrivate; - struct _IndicatorServicePrivate { gchar * name; DBusGProxy * dbus_proxy; @@ -113,6 +121,10 @@ indicator_service_class_init (IndicatorServiceClass *klass) return; } +/* This function builds the variables, sets up the dbus + proxy and registers the object on dbus. Importantly, + it does not request a name as we don't know what name + we have yet. */ static void indicator_service_init (IndicatorService *self) { @@ -162,6 +174,8 @@ indicator_service_init (IndicatorService *self) return; } +/* Unrefcounting the proxies and making sure that our + timeout doesn't come to haunt us. */ static void indicator_service_dispose (GObject *object) { @@ -181,6 +195,8 @@ indicator_service_dispose (GObject *object) return; } +/* Freeing the name we're looking for and all of the + information on the watchers we're tracking. */ static void indicator_service_finalize (GObject *object) { @@ -200,6 +216,8 @@ indicator_service_finalize (GObject *object) return; } +/* Either copies a string for the name or it just grabs + the value of the version. */ static void set_property (GObject * object, guint prop_id, const GValue * value, GParamSpec * pspec) { @@ -236,6 +254,8 @@ set_property (GObject * object, guint prop_id, const GValue * value, GParamSpec return; } +/* Copies out the name into a value or the version number. + Probably this is the least useful code in this file. */ static void get_property (GObject * object, guint prop_id, GValue * value, GParamSpec * pspec) { @@ -267,6 +287,9 @@ get_property (GObject * object, guint prop_id, GValue * value, GParamSpec * pspe return; } +/* This is the function that gets executed if we timeout + because there are no watchers. We sent the shutdown + signal and hope someone does something sane with it. */ static gboolean timeout_no_watchers (gpointer data) { @@ -274,6 +297,9 @@ timeout_no_watchers (gpointer data) return FALSE; } +/* The callback from our request to get a well known name + on dbus. If we can't get it we send the shutdown signal. + Else we start the timer to see if anyone cares about us. */ static void try_and_get_name_cb (DBusGProxy * proxy, guint status, GError * error, gpointer data) { @@ -294,6 +320,7 @@ try_and_get_name_cb (DBusGProxy * proxy, guint status, GError * error, gpointer return; } +/* This function sets up the request for the name on dbus. */ static void try_and_get_name (IndicatorService * service) { @@ -310,6 +337,10 @@ try_and_get_name (IndicatorService * service) return; } +/* Here is the function that gets called by the dbus + interface "Watch" function. It is an async function so + that we can get the sender and store that information. We + put them in a list and reset the timeout. */ static gboolean _indicator_service_server_watch (IndicatorService * service, DBusGMethodInvocation * method) { @@ -328,12 +359,18 @@ _indicator_service_server_watch (IndicatorService * service, DBusGMethodInvocati return TRUE; } +/* Mung g_strcmp0 into GCompareFunc */ static gint find_watcher (gconstpointer a, gconstpointer b) { return g_strcmp0((const gchar *)a, (const gchar *)b); } +/* A function connecting into the dbus interface for the + "UnWatch" function. It is also an async function to get + the sender. It then looks the sender up and removes them + from the list of watchers. If there are none left, it then + starts the timer for the shutdown signal. */ static gboolean _indicator_service_server_un_watch (IndicatorService * service, DBusGMethodInvocation * method) { -- cgit v1.2.3 From 5852e0be3e613968ce9f64c20c914024a2613302 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 3 Dec 2009 23:25:57 -0600 Subject: Adding in some comments and a little bit of code cleanup. --- libindicator/indicator-service-manager.c | 54 +++++++++++++++++++++++--------- 1 file changed, 40 insertions(+), 14 deletions(-) diff --git a/libindicator/indicator-service-manager.c b/libindicator/indicator-service-manager.c index a3680c4..b3d9f1c 100644 --- a/libindicator/indicator-service-manager.c +++ b/libindicator/indicator-service-manager.c @@ -10,6 +10,15 @@ #include "dbus-shared.h" /* Private Stuff */ +/** + IndicatorServiceManagerPrivate: + @name: The well known dbus name the service should be on. + @dbus_proxy: A proxy to talk to the dbus daemon. + @service_proxy: The proxy to the service itself. + @connected: Whether we're connected to the service or not. + @this_service_version: The version of the service that we're looking for. + @bus: A reference to the bus so we don't have to keep getting it. +*/ typedef struct _IndicatorServiceManagerPrivate IndicatorServiceManagerPrivate; struct _IndicatorServiceManagerPrivate { gchar * name; @@ -58,6 +67,8 @@ static void start_service (IndicatorServiceManager * service); G_DEFINE_TYPE (IndicatorServiceManager, indicator_service_manager, G_TYPE_OBJECT); +/* Build all of our signals and proxies and tie everything + all together. Lovely. */ static void indicator_service_manager_class_init (IndicatorServiceManagerClass *klass) { @@ -105,6 +116,9 @@ indicator_service_manager_class_init (IndicatorServiceManagerClass *klass) return; } +/* This inits all the variable and sets up the proxy + to dbus. It doesn't look for the service as at this + point we don't know it's name. */ static void indicator_service_manager_init (IndicatorServiceManager *self) { @@ -141,6 +155,10 @@ indicator_service_manager_init (IndicatorServiceManager *self) return; } +/* If we're connected this provides all the signals to say + that we're about to not be. Then it takes down the proxies + and tells the service that we're not interested in being + its friend anymore either. */ static void indicator_service_manager_dispose (GObject *object) { @@ -176,6 +194,7 @@ indicator_service_manager_dispose (GObject *object) return; } +/* Ironically, we don't allocate a lot of memory ourselves. */ static void indicator_service_manager_finalize (GObject *object) { @@ -190,6 +209,8 @@ indicator_service_manager_finalize (GObject *object) return; } +/* Either copies the name into the private variable or + sets the version. Do it wrong and it'll get upset. */ static void set_property (GObject * object, guint prop_id, const GValue * value, GParamSpec * pspec) { @@ -202,16 +223,12 @@ set_property (GObject * object, guint prop_id, const GValue * value, GParamSpec switch (prop_id) { /* *********************** */ case PROP_NAME: - if (G_VALUE_HOLDS_STRING(value)) { - if (priv->name != NULL) { - g_error("Name can not be set twice!"); - return; - } - priv->name = g_value_dup_string(value); - start_service(self); - } else { - g_warning("Name is a string bud."); + if (priv->name != NULL) { + g_error("Name can not be set twice!"); + return; } + priv->name = g_value_dup_string(value); + start_service(self); break; /* *********************** */ case PROP_VERSION: @@ -226,6 +243,8 @@ set_property (GObject * object, guint prop_id, const GValue * value, GParamSpec return; } +/* Grabs the values from the private variables and + puts them into the value. */ static void get_property (GObject * object, guint prop_id, GValue * value, GParamSpec * pspec) { @@ -238,11 +257,7 @@ get_property (GObject * object, guint prop_id, GValue * value, GParamSpec * pspe switch (prop_id) { /* *********************** */ case PROP_NAME: - if (G_VALUE_HOLDS_STRING(value)) { - g_value_set_string(value, priv->name); - } else { - g_warning("Name is a string bud."); - } + g_value_set_string(value, priv->name); break; /* *********************** */ case PROP_VERSION: @@ -257,6 +272,12 @@ get_property (GObject * object, guint prop_id, GValue * value, GParamSpec * pspe return; } +/* A callback from telling a service that we want to watch + it. It gives us the service API version and the version + of the other APIs it supports. We check both of those. + If they don't match then we unwatch it. Otherwise, we + signal a connection change to tell the rest of the world + that we have a service now. */ static void watch_cb (DBusGProxy * proxy, guint service_api_version, guint this_service_version, GError * error, gpointer user_data) { @@ -288,6 +309,10 @@ watch_cb (DBusGProxy * proxy, guint service_api_version, guint this_service_vers return; } +/* The callback after asking the dbus-daemon to start a + service for us. It can return success or failure, on + failure we can't do much. But, with sucess, we start + to build a proxy and tell the service that we're watching. */ static void start_service_cb (DBusGProxy * proxy, guint status, GError * error, gpointer user_data) { @@ -333,6 +358,7 @@ start_service (IndicatorServiceManager * service) INDICATOR_SERVICE_OBJECT, INDICATOR_SERVICE_INTERFACE, &error); + g_object_add_weak_pointer(G_OBJECT(priv->service_proxy), (gpointer *)&(priv->service_proxy)); if (error != NULL) { /* We don't care about the error, just start the service anyway. */ -- cgit v1.2.3 From 59b5bb78ff0b08bed79d4e4dd1811d6dde750a1f Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Fri, 4 Dec 2009 13:39:49 -0600 Subject: More gtk-doc comments. --- libindicator/indicator-service-manager.c | 51 ++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/libindicator/indicator-service-manager.c b/libindicator/indicator-service-manager.c index b3d9f1c..931fbb5 100644 --- a/libindicator/indicator-service-manager.c +++ b/libindicator/indicator-service-manager.c @@ -343,6 +343,10 @@ start_service_cb (DBusGProxy * proxy, guint status, GError * error, gpointer use return; } +/* The function that handles getting us connected to the service. + In many cases it will start the service, but if the service + is already there it just allocates the service proxy and acts + like it was no big deal. */ static void start_service (IndicatorServiceManager * service) { @@ -381,6 +385,19 @@ start_service (IndicatorServiceManager * service) } /* API */ + +/** + indicator_service_manager_new: + @dbus_name: The well known name of the service on DBus + + This creates a new service manager object. If the service + is not running it will start it. No matter what, it will + give a IndicatorServiceManager::connection-changed event + signal when it gets connected. + + Return value: A brand new lovely #IndicatorServiceManager + object. +*/ IndicatorServiceManager * indicator_service_manager_new (gchar * dbus_name) { @@ -391,6 +408,20 @@ indicator_service_manager_new (gchar * dbus_name) return INDICATOR_SERVICE_MANAGER(obj); } +/** + inicator_service_manager_new_version: + @dbus_name: The well known name of the service on DBus + @version: Version of the service we expect + + This creates a new service manager object. It also sets + the version of the service that we're expecting to see. + In general, it behaves similarly to #indicator_service_manager_new() + except that it checks @version against the version returned + by the service. + + Return value: A brand new lovely #IndicatorServiceManager + object. +*/ IndicatorServiceManager * indicator_service_manager_new_version (gchar * dbus_name, guint version) { @@ -402,6 +433,15 @@ indicator_service_manager_new_version (gchar * dbus_name, guint version) return INDICATOR_SERVICE_MANAGER(obj); } +/** + indicator_service_manager_connected: + @sm: #IndicatorServiceManager object to check + + Checks to see if the service manager is connected to a + service. + + Return value: #TRUE if there is a service connceted. +*/ gboolean indicator_service_manager_connected (IndicatorServiceManager * sm) { @@ -409,6 +449,17 @@ indicator_service_manager_connected (IndicatorServiceManager * sm) return FALSE; } +/** + indicator_service_manager_set_refresh: + @sm: #IndicatorServiceManager object to configure + @time_in_ms: The refresh time in milliseconds + + Use this function to set the amount of time between restarting + services that may crash or shutdown. This is mostly useful + for testing and development. + + NOTE: Not yet implemented. +*/ void indicator_service_manager_set_refresh (IndicatorServiceManager * sm, guint time_in_ms) { -- cgit v1.2.3 From 2d3d5b5cde680584f6ca954c7d5b17daaa32610d Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Fri, 4 Dec 2009 13:50:43 -0600 Subject: Implemented the _connected function as it's silly that it wasn't. --- libindicator/indicator-service-manager.c | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/libindicator/indicator-service-manager.c b/libindicator/indicator-service-manager.c index 931fbb5..68f7f6b 100644 --- a/libindicator/indicator-service-manager.c +++ b/libindicator/indicator-service-manager.c @@ -445,8 +445,9 @@ indicator_service_manager_new_version (gchar * dbus_name, guint version) gboolean indicator_service_manager_connected (IndicatorServiceManager * sm) { - - return FALSE; + g_return_val_if_fail(INDICATOR_IS_SERVICE_MANAGER(sm), FALSE); + IndicatorServiceManagerPrivate * priv = INDICATOR_SERVICE_MANAGER_GET_PRIVATE(sm); + return priv->connected; } /** -- cgit v1.2.3 From c1fa836fd6a3a6b38a07bada9f56998d9c5424fe Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Fri, 4 Dec 2009 14:30:44 -0600 Subject: GPLv3 copyright headers. --- libindicator/indicator-service-manager.c | 23 +++++++++++++++++++++++ libindicator/indicator-service-manager.h | 23 +++++++++++++++++++++++ libindicator/indicator-service.c | 23 +++++++++++++++++++++++ libindicator/indicator-service.h | 23 +++++++++++++++++++++++ 4 files changed, 92 insertions(+) diff --git a/libindicator/indicator-service-manager.c b/libindicator/indicator-service-manager.c index 68f7f6b..3f83d5e 100644 --- a/libindicator/indicator-service-manager.c +++ b/libindicator/indicator-service-manager.c @@ -1,3 +1,26 @@ +/* +An object used to manage services. Either start them or +just connect to them. + +Copyright 2009 Canonical Ltd. + +Authors: + Ted Gould + +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +version 3.0 as published by the Free Software Foundation. + +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 General Public License version 3.0 for more details. + +You should have received a copy of the GNU General Public +License along with this library. If not, see +. +*/ + #ifdef HAVE_CONFIG_H #include "config.h" #endif diff --git a/libindicator/indicator-service-manager.h b/libindicator/indicator-service-manager.h index 65a93ea..bf6d1b0 100644 --- a/libindicator/indicator-service-manager.h +++ b/libindicator/indicator-service-manager.h @@ -1,3 +1,26 @@ +/* +An object used to manage services. Either start them or +just connect to them. + +Copyright 2009 Canonical Ltd. + +Authors: + Ted Gould + +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +version 3.0 as published by the Free Software Foundation. + +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 General Public License version 3.0 for more details. + +You should have received a copy of the GNU General Public +License along with this library. If not, see +. +*/ + #ifndef __INDICATOR_SERVICE_MANAGER_H__ #define __INDICATOR_SERVICE_MANAGER_H__ diff --git a/libindicator/indicator-service.c b/libindicator/indicator-service.c index 003566a..e2ec6b2 100644 --- a/libindicator/indicator-service.c +++ b/libindicator/indicator-service.c @@ -1,3 +1,26 @@ +/* +An object used to provide a simple interface for a service +to query version and manage whether it's running. + +Copyright 2009 Canonical Ltd. + +Authors: + Ted Gould + +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +version 3.0 as published by the Free Software Foundation. + +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 General Public License version 3.0 for more details. + +You should have received a copy of the GNU General Public +License along with this library. If not, see +. +*/ + #ifdef HAVE_CONFIG_H #include "config.h" #endif diff --git a/libindicator/indicator-service.h b/libindicator/indicator-service.h index 59c5385..bda9cb7 100644 --- a/libindicator/indicator-service.h +++ b/libindicator/indicator-service.h @@ -1,3 +1,26 @@ +/* +An object used to provide a simple interface for a service +to query version and manage whether it's running. + +Copyright 2009 Canonical Ltd. + +Authors: + Ted Gould + +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +version 3.0 as published by the Free Software Foundation. + +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 General Public License version 3.0 for more details. + +You should have received a copy of the GNU General Public +License along with this library. If not, see +. +*/ + #ifndef __INDICATOR_SERVICE_H__ #define __INDICATOR_SERVICE_H__ -- cgit v1.2.3