libindicator

Merge lp://qastaging/~ted/libindicator/docs-and-licenses into lp://qastaging/libindicator/0.4

  1. docs-and-licenses
  2. Merge into trunk
Proposed by Ted Gould
Status: Merged
Merged at revision: not available
Proposed branch: lp://qastaging/~ted/libindicator/docs-and-licenses
Merge into: lp://qastaging/libindicator/0.4
Prerequisite: lp://qastaging/~ted/libindicator/service-version-number
Diff against target: 473 lines (+224/-17)
4 files modified
libindicator/indicator-service-manager.c (+117/-16)
libindicator/indicator-service-manager.h (+23/-0)
libindicator/indicator-service.c (+61/-1)
libindicator/indicator-service.h (+23/-0)
To merge this branch: bzr merge lp://qastaging/~ted/libindicator/docs-and-licenses
Reviewer Review Type Date Requested Status
Cody Russell (community) Approve
Review via email: mp+15673@code.qastaging.launchpad.net
To post a comment you must log in.
Revision history for this message
Ted Gould (ted) wrote :

Mostly documentation and licenses, but also includes a couple of small code cleanups that I noticed while going through the code.

Revision history for this message
Cody Russell (bratsche) :
review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'libindicator/indicator-service-manager.c'
2--- libindicator/indicator-service-manager.c 2009-12-04 20:35:23 +0000
3+++ libindicator/indicator-service-manager.c 2009-12-04 20:35:23 +0000
4@@ -1,3 +1,26 @@
5+/*
6+An object used to manage services. Either start them or
7+just connect to them.
8+
9+Copyright 2009 Canonical Ltd.
10+
11+Authors:
12+ Ted Gould <ted@canonical.com>
13+
14+This library is free software; you can redistribute it and/or
15+modify it under the terms of the GNU General Public License
16+version 3.0 as published by the Free Software Foundation.
17+
18+This library is distributed in the hope that it will be useful,
19+but WITHOUT ANY WARRANTY; without even the implied warranty of
20+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21+GNU General Public License version 3.0 for more details.
22+
23+You should have received a copy of the GNU General Public
24+License along with this library. If not, see
25+<http://www.gnu.org/licenses/>.
26+*/
27+
28 #ifdef HAVE_CONFIG_H
29 #include "config.h"
30 #endif
31@@ -10,6 +33,15 @@
32 #include "dbus-shared.h"
33
34 /* Private Stuff */
35+/**
36+ IndicatorServiceManagerPrivate:
37+ @name: The well known dbus name the service should be on.
38+ @dbus_proxy: A proxy to talk to the dbus daemon.
39+ @service_proxy: The proxy to the service itself.
40+ @connected: Whether we're connected to the service or not.
41+ @this_service_version: The version of the service that we're looking for.
42+ @bus: A reference to the bus so we don't have to keep getting it.
43+*/
44 typedef struct _IndicatorServiceManagerPrivate IndicatorServiceManagerPrivate;
45 struct _IndicatorServiceManagerPrivate {
46 gchar * name;
47@@ -58,6 +90,8 @@
48
49 G_DEFINE_TYPE (IndicatorServiceManager, indicator_service_manager, G_TYPE_OBJECT);
50
51+/* Build all of our signals and proxies and tie everything
52+ all together. Lovely. */
53 static void
54 indicator_service_manager_class_init (IndicatorServiceManagerClass *klass)
55 {
56@@ -105,6 +139,9 @@
57 return;
58 }
59
60+/* This inits all the variable and sets up the proxy
61+ to dbus. It doesn't look for the service as at this
62+ point we don't know it's name. */
63 static void
64 indicator_service_manager_init (IndicatorServiceManager *self)
65 {
66@@ -141,6 +178,10 @@
67 return;
68 }
69
70+/* If we're connected this provides all the signals to say
71+ that we're about to not be. Then it takes down the proxies
72+ and tells the service that we're not interested in being
73+ its friend anymore either. */
74 static void
75 indicator_service_manager_dispose (GObject *object)
76 {
77@@ -176,6 +217,7 @@
78 return;
79 }
80
81+/* Ironically, we don't allocate a lot of memory ourselves. */
82 static void
83 indicator_service_manager_finalize (GObject *object)
84 {
85@@ -190,6 +232,8 @@
86 return;
87 }
88
89+/* Either copies the name into the private variable or
90+ sets the version. Do it wrong and it'll get upset. */
91 static void
92 set_property (GObject * object, guint prop_id, const GValue * value, GParamSpec * pspec)
93 {
94@@ -202,16 +246,12 @@
95 switch (prop_id) {
96 /* *********************** */
97 case PROP_NAME:
98- if (G_VALUE_HOLDS_STRING(value)) {
99- if (priv->name != NULL) {
100- g_error("Name can not be set twice!");
101- return;
102- }
103- priv->name = g_value_dup_string(value);
104- start_service(self);
105- } else {
106- g_warning("Name is a string bud.");
107+ if (priv->name != NULL) {
108+ g_error("Name can not be set twice!");
109+ return;
110 }
111+ priv->name = g_value_dup_string(value);
112+ start_service(self);
113 break;
114 /* *********************** */
115 case PROP_VERSION:
116@@ -226,6 +266,8 @@
117 return;
118 }
119
120+/* Grabs the values from the private variables and
121+ puts them into the value. */
122 static void
123 get_property (GObject * object, guint prop_id, GValue * value, GParamSpec * pspec)
124 {
125@@ -238,11 +280,7 @@
126 switch (prop_id) {
127 /* *********************** */
128 case PROP_NAME:
129- if (G_VALUE_HOLDS_STRING(value)) {
130- g_value_set_string(value, priv->name);
131- } else {
132- g_warning("Name is a string bud.");
133- }
134+ g_value_set_string(value, priv->name);
135 break;
136 /* *********************** */
137 case PROP_VERSION:
138@@ -257,6 +295,12 @@
139 return;
140 }
141
142+/* A callback from telling a service that we want to watch
143+ it. It gives us the service API version and the version
144+ of the other APIs it supports. We check both of those.
145+ If they don't match then we unwatch it. Otherwise, we
146+ signal a connection change to tell the rest of the world
147+ that we have a service now. */
148 static void
149 watch_cb (DBusGProxy * proxy, guint service_api_version, guint this_service_version, GError * error, gpointer user_data)
150 {
151@@ -288,6 +332,10 @@
152 return;
153 }
154
155+/* The callback after asking the dbus-daemon to start a
156+ service for us. It can return success or failure, on
157+ failure we can't do much. But, with sucess, we start
158+ to build a proxy and tell the service that we're watching. */
159 static void
160 start_service_cb (DBusGProxy * proxy, guint status, GError * error, gpointer user_data)
161 {
162@@ -318,6 +366,10 @@
163 return;
164 }
165
166+/* The function that handles getting us connected to the service.
167+ In many cases it will start the service, but if the service
168+ is already there it just allocates the service proxy and acts
169+ like it was no big deal. */
170 static void
171 start_service (IndicatorServiceManager * service)
172 {
173@@ -333,6 +385,7 @@
174 INDICATOR_SERVICE_OBJECT,
175 INDICATOR_SERVICE_INTERFACE,
176 &error);
177+ g_object_add_weak_pointer(G_OBJECT(priv->service_proxy), (gpointer *)&(priv->service_proxy));
178
179 if (error != NULL) {
180 /* We don't care about the error, just start the service anyway. */
181@@ -355,6 +408,19 @@
182 }
183
184 /* API */
185+
186+/**
187+ indicator_service_manager_new:
188+ @dbus_name: The well known name of the service on DBus
189+
190+ This creates a new service manager object. If the service
191+ is not running it will start it. No matter what, it will
192+ give a IndicatorServiceManager::connection-changed event
193+ signal when it gets connected.
194+
195+ Return value: A brand new lovely #IndicatorServiceManager
196+ object.
197+*/
198 IndicatorServiceManager *
199 indicator_service_manager_new (gchar * dbus_name)
200 {
201@@ -365,6 +431,20 @@
202 return INDICATOR_SERVICE_MANAGER(obj);
203 }
204
205+/**
206+ inicator_service_manager_new_version:
207+ @dbus_name: The well known name of the service on DBus
208+ @version: Version of the service we expect
209+
210+ This creates a new service manager object. It also sets
211+ the version of the service that we're expecting to see.
212+ In general, it behaves similarly to #indicator_service_manager_new()
213+ except that it checks @version against the version returned
214+ by the service.
215+
216+ Return value: A brand new lovely #IndicatorServiceManager
217+ object.
218+*/
219 IndicatorServiceManager *
220 indicator_service_manager_new_version (gchar * dbus_name, guint version)
221 {
222@@ -376,13 +456,34 @@
223 return INDICATOR_SERVICE_MANAGER(obj);
224 }
225
226+/**
227+ indicator_service_manager_connected:
228+ @sm: #IndicatorServiceManager object to check
229+
230+ Checks to see if the service manager is connected to a
231+ service.
232+
233+ Return value: #TRUE if there is a service connceted.
234+*/
235 gboolean
236 indicator_service_manager_connected (IndicatorServiceManager * sm)
237 {
238-
239- return FALSE;
240+ g_return_val_if_fail(INDICATOR_IS_SERVICE_MANAGER(sm), FALSE);
241+ IndicatorServiceManagerPrivate * priv = INDICATOR_SERVICE_MANAGER_GET_PRIVATE(sm);
242+ return priv->connected;
243 }
244
245+/**
246+ indicator_service_manager_set_refresh:
247+ @sm: #IndicatorServiceManager object to configure
248+ @time_in_ms: The refresh time in milliseconds
249+
250+ Use this function to set the amount of time between restarting
251+ services that may crash or shutdown. This is mostly useful
252+ for testing and development.
253+
254+ NOTE: Not yet implemented.
255+*/
256 void
257 indicator_service_manager_set_refresh (IndicatorServiceManager * sm, guint time_in_ms)
258 {
259
260=== modified file 'libindicator/indicator-service-manager.h'
261--- libindicator/indicator-service-manager.h 2009-12-04 20:35:23 +0000
262+++ libindicator/indicator-service-manager.h 2009-12-04 20:35:23 +0000
263@@ -1,3 +1,26 @@
264+/*
265+An object used to manage services. Either start them or
266+just connect to them.
267+
268+Copyright 2009 Canonical Ltd.
269+
270+Authors:
271+ Ted Gould <ted@canonical.com>
272+
273+This library is free software; you can redistribute it and/or
274+modify it under the terms of the GNU General Public License
275+version 3.0 as published by the Free Software Foundation.
276+
277+This library is distributed in the hope that it will be useful,
278+but WITHOUT ANY WARRANTY; without even the implied warranty of
279+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
280+GNU General Public License version 3.0 for more details.
281+
282+You should have received a copy of the GNU General Public
283+License along with this library. If not, see
284+<http://www.gnu.org/licenses/>.
285+*/
286+
287 #ifndef __INDICATOR_SERVICE_MANAGER_H__
288 #define __INDICATOR_SERVICE_MANAGER_H__
289
290
291=== modified file 'libindicator/indicator-service.c'
292--- libindicator/indicator-service.c 2009-12-04 20:35:23 +0000
293+++ libindicator/indicator-service.c 2009-12-04 20:35:23 +0000
294@@ -1,3 +1,26 @@
295+/*
296+An object used to provide a simple interface for a service
297+to query version and manage whether it's running.
298+
299+Copyright 2009 Canonical Ltd.
300+
301+Authors:
302+ Ted Gould <ted@canonical.com>
303+
304+This library is free software; you can redistribute it and/or
305+modify it under the terms of the GNU General Public License
306+version 3.0 as published by the Free Software Foundation.
307+
308+This library is distributed in the hope that it will be useful,
309+but WITHOUT ANY WARRANTY; without even the implied warranty of
310+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
311+GNU General Public License version 3.0 for more details.
312+
313+You should have received a copy of the GNU General Public
314+License along with this library. If not, see
315+<http://www.gnu.org/licenses/>.
316+*/
317+
318 #ifdef HAVE_CONFIG_H
319 #include "config.h"
320 #endif
321@@ -14,8 +37,16 @@
322 #include "dbus-shared.h"
323
324 /* Private Stuff */
325+/**
326+ IndicatorSevicePrivate:
327+ @name: The DBus well known name for the service.
328+ @dbus_proxy: A proxy for talking to the dbus bus manager.
329+ @timeout: The source ID for the timeout event.
330+ @watcher: A list of processes on dbus that are watching us.
331+ @this_service_version: The version to hand out that we're
332+ implementing. May not be set, so we'll send zero (default).
333+*/
334 typedef struct _IndicatorServicePrivate IndicatorServicePrivate;
335-
336 struct _IndicatorServicePrivate {
337 gchar * name;
338 DBusGProxy * dbus_proxy;
339@@ -113,6 +144,10 @@
340 return;
341 }
342
343+/* This function builds the variables, sets up the dbus
344+ proxy and registers the object on dbus. Importantly,
345+ it does not request a name as we don't know what name
346+ we have yet. */
347 static void
348 indicator_service_init (IndicatorService *self)
349 {
350@@ -162,6 +197,8 @@
351 return;
352 }
353
354+/* Unrefcounting the proxies and making sure that our
355+ timeout doesn't come to haunt us. */
356 static void
357 indicator_service_dispose (GObject *object)
358 {
359@@ -181,6 +218,8 @@
360 return;
361 }
362
363+/* Freeing the name we're looking for and all of the
364+ information on the watchers we're tracking. */
365 static void
366 indicator_service_finalize (GObject *object)
367 {
368@@ -200,6 +239,8 @@
369 return;
370 }
371
372+/* Either copies a string for the name or it just grabs
373+ the value of the version. */
374 static void
375 set_property (GObject * object, guint prop_id, const GValue * value, GParamSpec * pspec)
376 {
377@@ -236,6 +277,8 @@
378 return;
379 }
380
381+/* Copies out the name into a value or the version number.
382+ Probably this is the least useful code in this file. */
383 static void
384 get_property (GObject * object, guint prop_id, GValue * value, GParamSpec * pspec)
385 {
386@@ -267,6 +310,9 @@
387 return;
388 }
389
390+/* This is the function that gets executed if we timeout
391+ because there are no watchers. We sent the shutdown
392+ signal and hope someone does something sane with it. */
393 static gboolean
394 timeout_no_watchers (gpointer data)
395 {
396@@ -274,6 +320,9 @@
397 return FALSE;
398 }
399
400+/* The callback from our request to get a well known name
401+ on dbus. If we can't get it we send the shutdown signal.
402+ Else we start the timer to see if anyone cares about us. */
403 static void
404 try_and_get_name_cb (DBusGProxy * proxy, guint status, GError * error, gpointer data)
405 {
406@@ -294,6 +343,7 @@
407 return;
408 }
409
410+/* This function sets up the request for the name on dbus. */
411 static void
412 try_and_get_name (IndicatorService * service)
413 {
414@@ -310,6 +360,10 @@
415 return;
416 }
417
418+/* Here is the function that gets called by the dbus
419+ interface "Watch" function. It is an async function so
420+ that we can get the sender and store that information. We
421+ put them in a list and reset the timeout. */
422 static gboolean
423 _indicator_service_server_watch (IndicatorService * service, DBusGMethodInvocation * method)
424 {
425@@ -328,12 +382,18 @@
426 return TRUE;
427 }
428
429+/* Mung g_strcmp0 into GCompareFunc */
430 static gint
431 find_watcher (gconstpointer a, gconstpointer b)
432 {
433 return g_strcmp0((const gchar *)a, (const gchar *)b);
434 }
435
436+/* A function connecting into the dbus interface for the
437+ "UnWatch" function. It is also an async function to get
438+ the sender. It then looks the sender up and removes them
439+ from the list of watchers. If there are none left, it then
440+ starts the timer for the shutdown signal. */
441 static gboolean
442 _indicator_service_server_un_watch (IndicatorService * service, DBusGMethodInvocation * method)
443 {
444
445=== modified file 'libindicator/indicator-service.h'
446--- libindicator/indicator-service.h 2009-12-04 20:35:23 +0000
447+++ libindicator/indicator-service.h 2009-12-04 20:35:23 +0000
448@@ -1,3 +1,26 @@
449+/*
450+An object used to provide a simple interface for a service
451+to query version and manage whether it's running.
452+
453+Copyright 2009 Canonical Ltd.
454+
455+Authors:
456+ Ted Gould <ted@canonical.com>
457+
458+This library is free software; you can redistribute it and/or
459+modify it under the terms of the GNU General Public License
460+version 3.0 as published by the Free Software Foundation.
461+
462+This library is distributed in the hope that it will be useful,
463+but WITHOUT ANY WARRANTY; without even the implied warranty of
464+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
465+GNU General Public License version 3.0 for more details.
466+
467+You should have received a copy of the GNU General Public
468+License along with this library. If not, see
469+<http://www.gnu.org/licenses/>.
470+*/
471+
472 #ifndef __INDICATOR_SERVICE_H__
473 #define __INDICATOR_SERVICE_H__
474

Subscribers

People subscribed via source and target branches