Merge branch 'dbus-1.6'
[platform/upstream/dbus.git] / dbus / dbus-bus.c
1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2 /* dbus-bus.c  Convenience functions for communicating with the bus.
3  *
4  * Copyright (C) 2003  CodeFactory AB
5  * Copyright (C) 2003  Red Hat, Inc.
6  *
7  * Licensed under the Academic Free License version 2.1
8  * 
9  * This program is free software; you can redistribute it and/or modify
10  * it under the terms of the GNU General Public License as published by
11  * the Free Software Foundation; either version 2 of the License, or
12  * (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU General Public License for more details.
18  * 
19  * You should have received a copy of the GNU General Public License
20  * along with this program; if not, write to the Free Software
21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
22  *
23  */
24
25 #include <config.h>
26 #include "dbus-bus.h"
27 #include "dbus-protocol.h"
28 #include "dbus-internals.h"
29 #include "dbus-message.h"
30 #include "dbus-marshal-validate.h"
31 #include "dbus-threads-internal.h"
32 #include "dbus-connection-internal.h"
33 #include "dbus-string.h"
34
35 /**
36  * @defgroup DBusBus Message bus APIs
37  * @ingroup DBus
38  * @brief Functions for communicating with the message bus
39  *
40  * dbus_bus_get() allows all modules and libraries in a given
41  * process to share the same connection to the bus daemon by storing
42  * the connection globally.
43  *
44  * All other functions in this module are just convenience functions;
45  * most of them invoke methods on the bus daemon, by sending method
46  * call messages to #DBUS_SERVICE_DBUS. These convenience functions
47  * often make blocking method calls. If you don't want to block,
48  * you can send the method call messages manually in the same way
49  * you would any other method call message.
50  *
51  * This module is the only one in libdbus that's specific to
52  * communicating with the message bus daemon. The rest of the API can
53  * also be used for connecting to another application directly.
54  * 
55  * @todo right now the default address of the system bus is hardcoded,
56  * so if you change it in the global config file suddenly you have to
57  * set DBUS_SYSTEM_BUS_ADDRESS env variable.  Might be nice if the
58  * client lib somehow read the config file, or if the bus on startup
59  * somehow wrote out its address to a well-known spot, but might also
60  * not be worth it.
61  */
62
63 /**
64  * @defgroup DBusBusInternals Message bus APIs internals
65  * @ingroup DBusInternals
66  * @brief Internals of functions for communicating with the message bus
67  *
68  * @{
69  */
70
71 /**
72  * Block of message-bus-related data we attach to each
73  * #DBusConnection used with these convenience functions.
74  *
75  */
76 typedef struct
77 {
78   DBusConnection *connection; /**< Connection we're associated with */
79   char *unique_name; /**< Unique name of this connection */
80
81   unsigned int is_well_known : 1; /**< Is one of the well-known connections in our global array */
82 } BusData;
83
84 /** The slot we have reserved to store BusData.
85  */
86 static dbus_int32_t bus_data_slot = -1;
87
88 /** Number of bus types */
89 #define N_BUS_TYPES 3
90
91 static DBusConnection *bus_connections[N_BUS_TYPES];
92 static char *bus_connection_addresses[N_BUS_TYPES] = { NULL, NULL, NULL };
93
94 static DBusBusType activation_bus_type = DBUS_BUS_STARTER;
95
96 static dbus_bool_t initialized = FALSE;
97
98 /**
99  * Lock for globals in this file
100  */
101 _DBUS_DEFINE_GLOBAL_LOCK (bus);
102
103 /**
104  * Global lock covering all BusData on any connection. The bet is
105  * that some lock contention is better than more memory
106  * for a per-connection lock, but it's tough to imagine it mattering
107  * either way.
108  */
109 _DBUS_DEFINE_GLOBAL_LOCK (bus_datas);
110
111 static void
112 addresses_shutdown_func (void *data)
113 {
114   int i;
115
116   i = 0;
117   while (i < N_BUS_TYPES)
118     {
119       if (bus_connections[i] != NULL)
120         _dbus_warn_check_failed ("dbus_shutdown() called but connections were still live. This probably means the application did not drop all its references to bus connections.\n");
121       
122       dbus_free (bus_connection_addresses[i]);
123       bus_connection_addresses[i] = NULL;
124       ++i;
125     }
126
127   activation_bus_type = DBUS_BUS_STARTER;
128
129   initialized = FALSE;
130 }
131
132 static dbus_bool_t
133 get_from_env (char           **connection_p,
134               const char      *env_var)
135 {
136   const char *s;
137   
138   _dbus_assert (*connection_p == NULL);
139   
140   s = _dbus_getenv (env_var);
141   if (s == NULL || *s == '\0')
142     return TRUE; /* successfully didn't use the env var */
143   else
144     {
145       *connection_p = _dbus_strdup (s);
146       return *connection_p != NULL;
147     }
148 }
149
150 static dbus_bool_t
151 init_session_address (void)
152 {
153   dbus_bool_t retval;
154  
155   retval = FALSE;
156
157   /* First, look in the environment.  This is the normal case on 
158    * freedesktop.org/Unix systems. */
159   get_from_env (&bus_connection_addresses[DBUS_BUS_SESSION],
160                      "DBUS_SESSION_BUS_ADDRESS");
161   if (bus_connection_addresses[DBUS_BUS_SESSION] == NULL)
162     {
163       dbus_bool_t supported;
164       DBusString addr;
165       DBusError error = DBUS_ERROR_INIT;
166
167       if (!_dbus_string_init (&addr))
168         return FALSE;
169
170       supported = FALSE;
171       /* So it's not in the environment - let's try a platform-specific method.
172        * On MacOS, this involves asking launchd.  On Windows (not specified yet)
173        * we might do a COM lookup.
174        * Ignore errors - if we failed, fall back to autolaunch. */
175       retval = _dbus_lookup_session_address (&supported, &addr, &error);
176       if (supported && retval)
177         {
178           retval =_dbus_string_steal_data (&addr, &bus_connection_addresses[DBUS_BUS_SESSION]);
179         }
180       else if (supported && !retval)
181         {
182           if (dbus_error_is_set(&error))
183             _dbus_warn ("Dynamic session lookup supported but failed: %s\n", error.message);
184           else
185             _dbus_warn ("Dynamic session lookup supported but failed silently\n");
186         }
187       _dbus_string_free (&addr);
188     }
189   else
190     retval = TRUE;
191
192   if (!retval)
193     return FALSE;
194
195   /* We have a hard-coded (but compile-time-configurable) fallback address for
196    * the session bus. */
197   if (bus_connection_addresses[DBUS_BUS_SESSION] == NULL)
198     bus_connection_addresses[DBUS_BUS_SESSION] =
199       _dbus_strdup (DBUS_SESSION_BUS_CONNECT_ADDRESS);
200
201   if (bus_connection_addresses[DBUS_BUS_SESSION] == NULL)
202     return FALSE;
203
204   return TRUE;
205 }
206
207 static dbus_bool_t
208 init_connections_unlocked (void)
209 {
210   if (!initialized)
211     {
212       const char *s;
213       int i;
214
215       i = 0;
216       while (i < N_BUS_TYPES)
217         {
218           bus_connections[i] = NULL;
219           ++i;
220         }
221
222       /* Don't init these twice, we may run this code twice if
223        * init_connections_unlocked() fails midway through.
224        * In practice, each block below should contain only one
225        * "return FALSE" or running through twice may not
226        * work right.
227        */
228       
229        if (bus_connection_addresses[DBUS_BUS_SYSTEM] == NULL)
230          {
231            _dbus_verbose ("Filling in system bus address...\n");
232            
233            if (!get_from_env (&bus_connection_addresses[DBUS_BUS_SYSTEM],
234                               "DBUS_SYSTEM_BUS_ADDRESS"))
235              return FALSE;
236          }
237
238                   
239        if (bus_connection_addresses[DBUS_BUS_SYSTEM] == NULL)
240          {
241            /* Use default system bus address if none set in environment */
242            bus_connection_addresses[DBUS_BUS_SYSTEM] =
243              _dbus_strdup (DBUS_SYSTEM_BUS_DEFAULT_ADDRESS);
244
245            if (bus_connection_addresses[DBUS_BUS_SYSTEM] == NULL)
246              return FALSE;
247            
248            _dbus_verbose ("  used default system bus \"%s\"\n",
249                           bus_connection_addresses[DBUS_BUS_SYSTEM]);
250          }
251        else
252          _dbus_verbose ("  used env var system bus \"%s\"\n",
253                         bus_connection_addresses[DBUS_BUS_SYSTEM]);
254           
255       if (bus_connection_addresses[DBUS_BUS_SESSION] == NULL)
256         {
257           _dbus_verbose ("Filling in session bus address...\n");
258           
259           if (!init_session_address ())
260             return FALSE;
261
262           _dbus_verbose ("  \"%s\"\n", bus_connection_addresses[DBUS_BUS_SESSION] ?
263                          bus_connection_addresses[DBUS_BUS_SESSION] : "none set");
264         }
265
266       if (bus_connection_addresses[DBUS_BUS_STARTER] == NULL)
267         {
268           _dbus_verbose ("Filling in activation bus address...\n");
269           
270           if (!get_from_env (&bus_connection_addresses[DBUS_BUS_STARTER],
271                              "DBUS_STARTER_ADDRESS"))
272             return FALSE;
273           
274           _dbus_verbose ("  \"%s\"\n", bus_connection_addresses[DBUS_BUS_STARTER] ?
275                          bus_connection_addresses[DBUS_BUS_STARTER] : "none set");
276         }
277
278
279       if (bus_connection_addresses[DBUS_BUS_STARTER] != NULL)
280         {
281           s = _dbus_getenv ("DBUS_STARTER_BUS_TYPE");
282               
283           if (s != NULL)
284             {
285               _dbus_verbose ("Bus activation type was set to \"%s\"\n", s);
286                   
287               if (strcmp (s, "system") == 0)
288                 activation_bus_type = DBUS_BUS_SYSTEM;
289               else if (strcmp (s, "session") == 0)
290                 activation_bus_type = DBUS_BUS_SESSION;
291             }
292         }
293       else
294         {
295           /* Default to the session bus instead if available */
296           if (bus_connection_addresses[DBUS_BUS_SESSION] != NULL)
297             {
298               bus_connection_addresses[DBUS_BUS_STARTER] =
299                 _dbus_strdup (bus_connection_addresses[DBUS_BUS_SESSION]);
300               if (bus_connection_addresses[DBUS_BUS_STARTER] == NULL)
301                 return FALSE;
302             }
303         }
304       
305       /* If we return FALSE we have to be sure that restarting
306        * the above code will work right
307        */
308       
309       if (!_dbus_setenv ("DBUS_ACTIVATION_ADDRESS", NULL))
310         return FALSE;
311
312       if (!_dbus_setenv ("DBUS_ACTIVATION_BUS_TYPE", NULL))
313         return FALSE;
314       
315       if (!_dbus_register_shutdown_func (addresses_shutdown_func,
316                                          NULL))
317         return FALSE;
318       
319       initialized = TRUE;
320     }
321
322   return initialized;
323 }
324
325 static void
326 bus_data_free (void *data)
327 {
328   BusData *bd = data;
329   
330   if (bd->is_well_known)
331     {
332       int i;
333       _DBUS_LOCK (bus);
334       /* We may be stored in more than one slot */
335       /* This should now be impossible - these slots are supposed to
336        * be cleared on disconnect, so should not need to be cleared on
337        * finalize
338        */
339       i = 0;
340       while (i < N_BUS_TYPES)
341         {
342           if (bus_connections[i] == bd->connection)
343             bus_connections[i] = NULL;
344           
345           ++i;
346         }
347       _DBUS_UNLOCK (bus);
348     }
349   
350   dbus_free (bd->unique_name);
351   dbus_free (bd);
352
353   dbus_connection_free_data_slot (&bus_data_slot);
354 }
355
356 static BusData*
357 ensure_bus_data (DBusConnection *connection)
358 {
359   BusData *bd;
360
361   if (!dbus_connection_allocate_data_slot (&bus_data_slot))
362     return NULL;
363
364   bd = dbus_connection_get_data (connection, bus_data_slot);
365   if (bd == NULL)
366     {      
367       bd = dbus_new0 (BusData, 1);
368       if (bd == NULL)
369         {
370           dbus_connection_free_data_slot (&bus_data_slot);
371           return NULL;
372         }
373
374       bd->connection = connection;
375       
376       if (!dbus_connection_set_data (connection, bus_data_slot, bd,
377                                      bus_data_free))
378         {
379           dbus_free (bd);
380           dbus_connection_free_data_slot (&bus_data_slot);
381           return NULL;
382         }
383
384       /* Data slot refcount now held by the BusData */
385     }
386   else
387     {
388       dbus_connection_free_data_slot (&bus_data_slot);
389     }
390
391   return bd;
392 }
393
394 /**
395  * Internal function that checks to see if this
396  * is a shared connection owned by the bus and if it is unref it.
397  *
398  * @param connection a connection that has been disconnected.
399  */
400 void
401 _dbus_bus_notify_shared_connection_disconnected_unlocked (DBusConnection *connection)
402 {
403   int i;
404   
405   _DBUS_LOCK (bus);
406
407   /* We are expecting to have the connection saved in only one of these
408    * slots, but someone could in a pathological case set system and session
409    * bus to the same bus or something. Or set one of them to the starter
410    * bus without setting the starter bus type in the env variable.
411    * So we don't break the loop as soon as we find a match.
412    */
413   for (i = 0; i < N_BUS_TYPES; ++i)
414     {
415       if (bus_connections[i] == connection)
416         {
417           bus_connections[i] = NULL;
418         }
419     }
420
421   _DBUS_UNLOCK (bus);
422 }
423
424 static DBusConnection *
425 internal_bus_get (DBusBusType  type,
426                   dbus_bool_t  private,
427                   DBusError   *error)
428 {
429   const char *address;
430   DBusConnection *connection;
431   BusData *bd;
432   DBusBusType address_type;
433
434   _dbus_return_val_if_fail (type >= 0 && type < N_BUS_TYPES, NULL);
435   _dbus_return_val_if_error_is_set (error, NULL);
436
437   connection = NULL;
438
439   _DBUS_LOCK (bus);
440
441   if (!init_connections_unlocked ())
442     {
443       _DBUS_SET_OOM (error);
444       goto out;
445     }
446
447   /* We want to use the activation address even if the
448    * activating bus is the session or system bus,
449    * per the spec.
450    */
451   address_type = type;
452   
453   /* Use the real type of the activation bus for getting its
454    * connection, but only if the real type's address is available. (If
455    * the activating bus isn't a well-known bus then
456    * activation_bus_type == DBUS_BUS_STARTER)
457    */
458   if (type == DBUS_BUS_STARTER &&
459       bus_connection_addresses[activation_bus_type] != NULL)
460     type = activation_bus_type;
461   
462   if (!private && bus_connections[type] != NULL)
463     {
464       connection = bus_connections[type];
465       dbus_connection_ref (connection);
466       goto out;
467     }
468
469   address = bus_connection_addresses[address_type];
470   if (address == NULL)
471     {
472       dbus_set_error (error, DBUS_ERROR_FAILED,
473                       "Unable to determine the address of the message bus (try 'man dbus-launch' and 'man dbus-daemon' for help)");
474       goto out;
475     }
476
477   if (private)
478     connection = dbus_connection_open_private (address, error);
479   else
480     connection = dbus_connection_open (address, error);
481   
482   if (!connection)
483     {
484       goto out;
485     }
486
487   if (!dbus_bus_register (connection, error))
488     {
489       _dbus_connection_close_possibly_shared (connection);
490       dbus_connection_unref (connection);
491       connection = NULL;
492       goto out;
493     }
494
495   if (!private)
496     {
497       /* store a weak ref to the connection (dbus-connection.c is
498        * supposed to have a strong ref that it drops on disconnect,
499        * since this is a shared connection)
500        */
501       bus_connections[type] = connection;
502     }
503
504   /* By default we're bound to the lifecycle of
505    * the message bus.
506    */
507   dbus_connection_set_exit_on_disconnect (connection,
508                                           TRUE);
509  
510   _DBUS_LOCK (bus_datas);
511   bd = ensure_bus_data (connection);
512   _dbus_assert (bd != NULL); /* it should have been created on
513                                 register, so OOM not possible */
514   bd->is_well_known = TRUE;
515   _DBUS_UNLOCK (bus_datas);
516
517 out:
518   /* Return a reference to the caller, or NULL with error set. */
519   if (connection == NULL)
520     _DBUS_ASSERT_ERROR_IS_SET (error);
521
522   _DBUS_UNLOCK (bus);
523   return connection;
524 }
525
526
527 /** @} */ /* end of implementation details docs */
528
529 /**
530  * @addtogroup DBusBus
531  * @{
532  */
533
534 /**
535  * Connects to a bus daemon and registers the client with it.  If a
536  * connection to the bus already exists, then that connection is
537  * returned.  The caller of this function owns a reference to the bus.
538  *
539  * The caller may NOT call dbus_connection_close() on this connection;
540  * see dbus_connection_open() and dbus_connection_close() for details
541  * on that.
542  *
543  * If this function obtains a new connection object never before
544  * returned from dbus_bus_get(), it will call
545  * dbus_connection_set_exit_on_disconnect(), so the application
546  * will exit if the connection closes. You can undo this
547  * by calling dbus_connection_set_exit_on_disconnect() yourself
548  * after you get the connection.
549  *
550  * dbus_bus_get() calls dbus_bus_register() for you.
551  * 
552  * If returning a newly-created connection, this function will block
553  * until authentication and bus registration are complete.
554  * 
555  * @param type bus type
556  * @param error address where an error can be returned.
557  * @returns a #DBusConnection with new ref
558  */
559 DBusConnection *
560 dbus_bus_get (DBusBusType  type,
561               DBusError   *error)
562 {
563   return internal_bus_get (type, FALSE, error);
564 }
565
566 /**
567  * Connects to a bus daemon and registers the client with it as with
568  * dbus_bus_register().  Unlike dbus_bus_get(), always creates a new
569  * connection. This connection will not be saved or recycled by
570  * libdbus. Caller owns a reference to the bus and must either close
571  * it or know it to be closed prior to releasing this reference.
572  *
573  * See dbus_connection_open_private() for more details on when to
574  * close and unref this connection.
575  *
576  * This function calls
577  * dbus_connection_set_exit_on_disconnect() on the new connection, so the application
578  * will exit if the connection closes. You can undo this
579  * by calling dbus_connection_set_exit_on_disconnect() yourself
580  * after you get the connection.
581  *
582  * dbus_bus_get_private() calls dbus_bus_register() for you.
583  *
584  * This function will block until authentication and bus registration
585  * are complete.
586  *
587  * @param type bus type
588  * @param error address where an error can be returned.
589  * @returns a DBusConnection with new ref
590  */
591 DBusConnection *
592 dbus_bus_get_private (DBusBusType  type,
593                       DBusError   *error)
594 {
595   return internal_bus_get (type, TRUE, error);
596 }
597
598 /**
599  * Registers a connection with the bus. This must be the first
600  * thing an application does when connecting to the message bus.
601  * If registration succeeds, the unique name will be set,
602  * and can be obtained using dbus_bus_get_unique_name().
603  *
604  * This function will block until registration is complete.
605  *
606  * If the connection has already registered with the bus
607  * (determined by checking whether dbus_bus_get_unique_name()
608  * returns a non-#NULL value), then this function does nothing.
609  *
610  * If you use dbus_bus_get() or dbus_bus_get_private() this
611  * function will be called for you.
612  * 
613  * @note Just use dbus_bus_get() or dbus_bus_get_private() instead of
614  * dbus_bus_register() and save yourself some pain. Using
615  * dbus_bus_register() manually is only useful if you have your
616  * own custom message bus not found in #DBusBusType.
617  *
618  * If you open a bus connection with dbus_connection_open() or
619  * dbus_connection_open_private() you will have to dbus_bus_register()
620  * yourself, or make the appropriate registration method calls
621  * yourself. If you send the method calls yourself, call
622  * dbus_bus_set_unique_name() with the unique bus name you get from
623  * the bus.
624  *
625  * For shared connections (created with dbus_connection_open()) in a
626  * multithreaded application, you can't really make the registration
627  * calls yourself, because you don't know whether some other thread is
628  * also registering, and the bus will kick you off if you send two
629  * registration messages.
630  *
631  * If you use dbus_bus_register() however, there is a lock that
632  * keeps both apps from registering at the same time.
633  *
634  * The rule in a multithreaded app, then, is that dbus_bus_register()
635  * must be used to register, or you need to have your own locks that
636  * all threads in the app will respect.
637  *
638  * In a single-threaded application you can register by hand instead
639  * of using dbus_bus_register(), as long as you check
640  * dbus_bus_get_unique_name() to see if a unique name has already been
641  * stored by another thread before you send the registration messages.
642  * 
643  * @param connection the connection
644  * @param error place to store errors
645  * @returns #TRUE on success
646  */
647 dbus_bool_t
648 dbus_bus_register (DBusConnection *connection,
649                    DBusError      *error)
650 {
651   DBusMessage *message, *reply;
652   char *name;
653   BusData *bd;
654   dbus_bool_t retval;
655
656   _dbus_return_val_if_fail (connection != NULL, FALSE);
657   _dbus_return_val_if_error_is_set (error, FALSE);
658
659   retval = FALSE;
660   message = NULL;
661   reply = NULL;
662
663   _DBUS_LOCK (bus_datas);
664
665   bd = ensure_bus_data (connection);
666   if (bd == NULL)
667     {
668       _DBUS_SET_OOM (error);
669       goto out;
670     }
671
672   if (bd->unique_name != NULL)
673     {
674       _dbus_verbose ("Ignoring attempt to register the same DBusConnection %s with the message bus a second time.\n",
675                      bd->unique_name);
676       /* Success! */
677       retval = TRUE;
678       goto out;
679     }
680   
681   message = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
682                                           DBUS_PATH_DBUS,
683                                           DBUS_INTERFACE_DBUS,
684                                           "Hello"); 
685
686   if (!message)
687     {
688       _DBUS_SET_OOM (error);
689       goto out;
690     }
691   
692   reply = dbus_connection_send_with_reply_and_block (connection, message, -1, error);
693
694   if (reply == NULL)
695     goto out;
696   else if (dbus_set_error_from_message (error, reply))
697     goto out;
698   else if (!dbus_message_get_args (reply, error,
699                                    DBUS_TYPE_STRING, &name,
700                                    DBUS_TYPE_INVALID))
701     goto out;
702   
703   bd->unique_name = _dbus_strdup (name);
704   if (bd->unique_name == NULL)
705     {
706       _DBUS_SET_OOM (error);
707       goto out;
708     }
709   
710   retval = TRUE;
711   
712  out:
713   _DBUS_UNLOCK (bus_datas);
714
715   if (message)
716     dbus_message_unref (message);
717
718   if (reply)
719     dbus_message_unref (reply);
720
721   if (!retval)
722     _DBUS_ASSERT_ERROR_IS_SET (error);
723
724   return retval;
725 }
726
727
728 /**
729  * Sets the unique name of the connection, as assigned by the message
730  * bus.  Can only be used if you registered with the bus manually
731  * (i.e. if you did not call dbus_bus_register()). Can only be called
732  * once per connection.  After the unique name is set, you can get it
733  * with dbus_bus_get_unique_name().
734  *
735  * The only reason to use this function is to re-implement the
736  * equivalent of dbus_bus_register() yourself. One (probably unusual)
737  * reason to do that might be to do the bus registration call
738  * asynchronously instead of synchronously.
739  *
740  * @note Just use dbus_bus_get() or dbus_bus_get_private(), or worst
741  * case dbus_bus_register(), instead of messing with this
742  * function. There's really no point creating pain for yourself by
743  * doing things manually.
744  *
745  * It's hard to use this function safely on shared connections
746  * (created by dbus_connection_open()) in a multithreaded application,
747  * because only one registration attempt can be sent to the bus. If
748  * two threads are both sending the registration message, there is no
749  * mechanism in libdbus itself to avoid sending it twice.
750  *
751  * Thus, you need a way to coordinate which thread sends the
752  * registration attempt; which also means you know which thread
753  * will call dbus_bus_set_unique_name(). If you don't know
754  * about all threads in the app (for example, if some libraries
755  * you're using might start libdbus-using threads), then you
756  * need to avoid using this function on shared connections.
757  *
758  * @param connection the connection
759  * @param unique_name the unique name
760  * @returns #FALSE if not enough memory
761  */
762 dbus_bool_t
763 dbus_bus_set_unique_name (DBusConnection *connection,
764                           const char     *unique_name)
765 {
766   BusData *bd;
767   dbus_bool_t success = FALSE;
768
769   _dbus_return_val_if_fail (connection != NULL, FALSE);
770   _dbus_return_val_if_fail (unique_name != NULL, FALSE);
771
772   _DBUS_LOCK (bus_datas);
773   
774   bd = ensure_bus_data (connection);
775   if (bd == NULL)
776     goto out;
777
778   _dbus_assert (bd->unique_name == NULL);
779   
780   bd->unique_name = _dbus_strdup (unique_name);
781   success = bd->unique_name != NULL;
782
783 out:
784   _DBUS_UNLOCK (bus_datas);
785   
786   return success;
787 }
788
789 /**
790  * Gets the unique name of the connection as assigned by the message
791  * bus. Only possible after the connection has been registered with
792  * the message bus. All connections returned by dbus_bus_get() or
793  * dbus_bus_get_private() have been successfully registered.
794  *
795  * The name remains valid until the connection is freed, and
796  * should not be freed by the caller.
797  *
798  * Other than dbus_bus_get(), there are two ways to set the unique
799  * name; one is dbus_bus_register(), the other is
800  * dbus_bus_set_unique_name().  You are responsible for calling
801  * dbus_bus_set_unique_name() if you register by hand instead of using
802  * dbus_bus_register().
803  * 
804  * @param connection the connection
805  * @returns the unique name or #NULL on error
806  */
807 const char*
808 dbus_bus_get_unique_name (DBusConnection *connection)
809 {
810   BusData *bd;
811   const char *unique_name = NULL;
812
813   _dbus_return_val_if_fail (connection != NULL, NULL);
814
815   _DBUS_LOCK (bus_datas);
816   
817   bd = ensure_bus_data (connection);
818   if (bd == NULL)
819     goto out;
820
821   unique_name = bd->unique_name;
822
823 out:
824   _DBUS_UNLOCK (bus_datas);
825
826   return unique_name;
827 }
828
829 /**
830  * Asks the bus to return the UID the named connection authenticated
831  * as, if any.  Only works on UNIX; only works for connections on the
832  * same machine as the bus. If you are not on the same machine as the
833  * bus, then calling this is probably a bad idea, since the UID will
834  * mean little to your application.
835  *
836  * For the system message bus you're guaranteed to be on the same
837  * machine since it only listens on a UNIX domain socket (at least,
838  * as shipped by default).
839  *
840  * This function only works for connections that authenticated as
841  * a UNIX user, right now that includes all bus connections, but
842  * it's very possible to have connections with no associated UID.
843  * So check for errors and do something sensible if they happen.
844  * 
845  * This function will always return an error on Windows.
846  * 
847  * @param connection the connection
848  * @param name a name owned by the connection
849  * @param error location to store the error
850  * @returns the unix user id, or ((unsigned)-1) if error is set
851  */ 
852 unsigned long
853 dbus_bus_get_unix_user (DBusConnection *connection,
854                         const char     *name,
855                         DBusError      *error)
856 {
857   DBusMessage *message, *reply;
858   dbus_uint32_t uid;
859
860   _dbus_return_val_if_fail (connection != NULL, DBUS_UID_UNSET);
861   _dbus_return_val_if_fail (name != NULL, DBUS_UID_UNSET);
862   _dbus_return_val_if_fail (_dbus_check_is_valid_bus_name (name), DBUS_UID_UNSET);
863   _dbus_return_val_if_error_is_set (error, DBUS_UID_UNSET);
864   
865   message = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
866                                           DBUS_PATH_DBUS,
867                                           DBUS_INTERFACE_DBUS,
868                                           "GetConnectionUnixUser");
869
870   if (message == NULL)
871     {
872       _DBUS_SET_OOM (error);
873       return DBUS_UID_UNSET;
874     }
875  
876   if (!dbus_message_append_args (message,
877                                  DBUS_TYPE_STRING, &name,
878                                  DBUS_TYPE_INVALID))
879     {
880       dbus_message_unref (message);
881       _DBUS_SET_OOM (error);
882       return DBUS_UID_UNSET;
883     }
884   
885   reply = dbus_connection_send_with_reply_and_block (connection, message, -1,
886                                                      error);
887   
888   dbus_message_unref (message);
889   
890   if (reply == NULL)
891     {
892       _DBUS_ASSERT_ERROR_IS_SET (error);
893       return DBUS_UID_UNSET;
894     }  
895
896   if (dbus_set_error_from_message (error, reply))
897     {
898       _DBUS_ASSERT_ERROR_IS_SET (error);
899       dbus_message_unref (reply);
900       return DBUS_UID_UNSET;
901     }
902   
903   if (!dbus_message_get_args (reply, error,
904                               DBUS_TYPE_UINT32, &uid,
905                               DBUS_TYPE_INVALID))
906     {
907       _DBUS_ASSERT_ERROR_IS_SET (error);
908       dbus_message_unref (reply);
909       return DBUS_UID_UNSET;
910     }
911
912   dbus_message_unref (reply);
913   
914   return (unsigned long) uid;
915 }
916
917 /**
918  * Asks the bus to return its globally unique ID, as described in the
919  * D-Bus specification. For the session bus, this is useful as a way
920  * to uniquely identify each user session. For the system bus,
921  * probably the bus ID is not useful; instead, use the machine ID
922  * since it's accessible without necessarily connecting to the bus and
923  * may be persistent beyond a single bus instance (across reboots for
924  * example). See dbus_get_local_machine_id().
925  *
926  * In addition to an ID for each bus and an ID for each machine, there is
927  * an ID for each address that the bus is listening on; that can
928  * be retrieved with dbus_connection_get_server_id(), though it is
929  * probably not very useful.
930  * 
931  * @param connection the connection
932  * @param error location to store the error
933  * @returns the bus ID or #NULL if error is set
934  */ 
935 char*
936 dbus_bus_get_id (DBusConnection *connection,
937                  DBusError      *error)
938 {
939   DBusMessage *message, *reply;
940   char *id;
941   const char *v_STRING;
942
943   _dbus_return_val_if_fail (connection != NULL, NULL);
944   _dbus_return_val_if_error_is_set (error, NULL);
945   
946   message = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
947                                           DBUS_PATH_DBUS,
948                                           DBUS_INTERFACE_DBUS,
949                                           "GetId");
950   
951   if (message == NULL)
952     {
953       _DBUS_SET_OOM (error);
954       return NULL;
955     }
956   
957   reply = dbus_connection_send_with_reply_and_block (connection, message, -1,
958                                                      error);
959   
960   dbus_message_unref (message);
961   
962   if (reply == NULL)
963     {
964       _DBUS_ASSERT_ERROR_IS_SET (error);
965       return NULL;
966     }  
967
968   if (dbus_set_error_from_message (error, reply))
969     {
970       _DBUS_ASSERT_ERROR_IS_SET (error);
971       dbus_message_unref (reply);
972       return NULL;
973     }
974
975   v_STRING = NULL;
976   if (!dbus_message_get_args (reply, error,
977                               DBUS_TYPE_STRING, &v_STRING,
978                               DBUS_TYPE_INVALID))
979     {
980       _DBUS_ASSERT_ERROR_IS_SET (error);
981       dbus_message_unref (reply);
982       return NULL;
983     }
984
985   id = _dbus_strdup (v_STRING); /* may be NULL */
986   
987   dbus_message_unref (reply);
988
989   if (id == NULL)
990     _DBUS_SET_OOM (error);
991
992   /* FIXME it might be nice to cache the ID locally */
993   
994   return id;
995 }
996
997 /**
998  * Asks the bus to assign the given name to this connection by invoking
999  * the RequestName method on the bus. This method is fully documented
1000  * in the D-Bus specification. For quick reference, the flags and
1001  * result codes are discussed here, but the specification is the
1002  * canonical version of this information.
1003  *
1004  * First you should know that for each bus name, the bus stores
1005  * a queue of connections that would like to own it. Only
1006  * one owns it at a time - called the primary owner. If the primary
1007  * owner releases the name or disconnects, then the next owner in the
1008  * queue atomically takes over.
1009  *
1010  * So for example if you have an application org.freedesktop.TextEditor
1011  * and multiple instances of it can be run, you can have all of them
1012  * sitting in the queue. The first one to start up will receive messages
1013  * sent to org.freedesktop.TextEditor, but if that one exits another
1014  * will become the primary owner and receive messages.
1015  *
1016  * The queue means you don't need to manually watch for the current owner to
1017  * disappear and then request the name again.
1018  *
1019  * When requesting a name, you can specify several flags.
1020  * 
1021  * #DBUS_NAME_FLAG_ALLOW_REPLACEMENT and #DBUS_NAME_FLAG_DO_NOT_QUEUE
1022  * are properties stored by the bus for this connection with respect to
1023  * each requested bus name. These properties are stored even if the
1024  * connection is queued and does not become the primary owner.
1025  * You can update these flags by calling RequestName again (even if
1026  * you already own the name).
1027  *
1028  * #DBUS_NAME_FLAG_ALLOW_REPLACEMENT means that another requestor of the
1029  * name can take it away from you by specifying #DBUS_NAME_FLAG_REPLACE_EXISTING.
1030  *
1031  * #DBUS_NAME_FLAG_DO_NOT_QUEUE means that if you aren't the primary owner,
1032  * you don't want to be queued up - you only care about being the
1033  * primary owner.
1034  *
1035  * Unlike the other two flags, #DBUS_NAME_FLAG_REPLACE_EXISTING is a property
1036  * of the individual RequestName call, i.e. the bus does not persistently
1037  * associate it with the connection-name pair. If a RequestName call includes
1038  * the #DBUS_NAME_FLAG_REPLACE_EXISTING flag, and the current primary
1039  * owner has #DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, then the current primary
1040  * owner will be kicked off.
1041  *
1042  * If no flags are given, an application will receive the requested
1043  * name only if the name is currently unowned; and it will NOT give
1044  * up the name if another application asks to take it over using
1045  * #DBUS_NAME_FLAG_REPLACE_EXISTING.
1046  *
1047  * This function returns a result code. The possible result codes
1048  * are as follows.
1049  * 
1050  * #DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER means that the name had no
1051  * existing owner, and the caller is now the primary owner; or that
1052  * the name had an owner, and the caller specified
1053  * #DBUS_NAME_FLAG_REPLACE_EXISTING, and the current owner
1054  * specified #DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
1055  *
1056  * #DBUS_REQUEST_NAME_REPLY_IN_QUEUE happens only if the caller does NOT
1057  * specify #DBUS_NAME_FLAG_DO_NOT_QUEUE and either the current owner
1058  * did NOT specify #DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the caller did NOT
1059  * specify #DBUS_NAME_FLAG_REPLACE_EXISTING. In this case the caller ends up 
1060  * in a queue to own the name after the current owner gives it up.
1061  *
1062  * #DBUS_REQUEST_NAME_REPLY_EXISTS happens if the name has an owner
1063  * already and the caller specifies #DBUS_NAME_FLAG_DO_NOT_QUEUE
1064  * and either the current owner has NOT specified 
1065  * #DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the caller did NOT specify 
1066  * #DBUS_NAME_FLAG_REPLACE_EXISTING.
1067  *
1068  * #DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER happens if an application
1069  * requests a name it already owns. (Re-requesting a name is useful if
1070  * you want to change the #DBUS_NAME_FLAG_ALLOW_REPLACEMENT or
1071  * #DBUS_NAME_FLAG_DO_NOT_QUEUE settings.)
1072  *
1073  * When a service represents an application, say "text editor," then
1074  * it should specify #DBUS_NAME_FLAG_ALLOW_REPLACEMENT if it wants
1075  * the last editor started to be the user's editor vs. the first one
1076  * started.  Then any editor that can be the user's editor should
1077  * specify #DBUS_NAME_FLAG_REPLACE_EXISTING to either take over
1078  * (last-started-wins) or be queued up (first-started-wins) according
1079  * to whether #DBUS_NAME_FLAG_ALLOW_REPLACEMENT was given.
1080  *
1081  * Conventionally, single-instance applications often offer a command
1082  * line option called --replace which means to replace the current
1083  * instance.  To implement this, always set
1084  * #DBUS_NAME_FLAG_ALLOW_REPLACEMENT when you request your
1085  * application's bus name.  When you lose ownership of your bus name,
1086  * you need to exit.  Look for the signal "NameLost" from
1087  * #DBUS_SERVICE_DBUS and #DBUS_INTERFACE_DBUS (the signal's first
1088  * argument is the bus name that was lost).  If starting up without
1089  * --replace, do not specify #DBUS_NAME_FLAG_REPLACE_EXISTING, and
1090  * exit if you fail to become the bus name owner. If --replace is
1091  * given, ask to replace the old owner.
1092  *
1093  * @param connection the connection
1094  * @param name the name to request
1095  * @param flags flags
1096  * @param error location to store the error
1097  * @returns a result code, -1 if error is set
1098  */ 
1099 int
1100 dbus_bus_request_name (DBusConnection *connection,
1101                        const char     *name,
1102                        unsigned int    flags,
1103                        DBusError      *error)
1104 {
1105   DBusMessage *message, *reply;
1106   dbus_uint32_t result;
1107
1108   _dbus_return_val_if_fail (connection != NULL, 0);
1109   _dbus_return_val_if_fail (name != NULL, 0);
1110   _dbus_return_val_if_fail (_dbus_check_is_valid_bus_name (name), 0);
1111   _dbus_return_val_if_error_is_set (error, 0);
1112   
1113   message = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
1114                                           DBUS_PATH_DBUS,
1115                                           DBUS_INTERFACE_DBUS,
1116                                           "RequestName");
1117
1118   if (message == NULL)
1119     {
1120       _DBUS_SET_OOM (error);
1121       return -1;
1122     }
1123  
1124   if (!dbus_message_append_args (message,
1125                                  DBUS_TYPE_STRING, &name,
1126                                  DBUS_TYPE_UINT32, &flags,
1127                                  DBUS_TYPE_INVALID))
1128     {
1129       dbus_message_unref (message);
1130       _DBUS_SET_OOM (error);
1131       return -1;
1132     }
1133   
1134   reply = dbus_connection_send_with_reply_and_block (connection, message, -1,
1135                                                      error);
1136   
1137   dbus_message_unref (message);
1138   
1139   if (reply == NULL)
1140     {
1141       _DBUS_ASSERT_ERROR_IS_SET (error);
1142       return -1;
1143     }  
1144
1145   if (dbus_set_error_from_message (error, reply))
1146     {
1147       _DBUS_ASSERT_ERROR_IS_SET (error);
1148       dbus_message_unref (reply);
1149       return -1;
1150     }
1151   
1152   if (!dbus_message_get_args (reply, error,
1153                               DBUS_TYPE_UINT32, &result,
1154                               DBUS_TYPE_INVALID))
1155     {
1156       _DBUS_ASSERT_ERROR_IS_SET (error);
1157       dbus_message_unref (reply);
1158       return -1;
1159     }
1160
1161   dbus_message_unref (reply);
1162   
1163   return result;
1164 }
1165
1166
1167 /**
1168  * Asks the bus to unassign the given name from this connection by
1169  * invoking the ReleaseName method on the bus. The "ReleaseName"
1170  * method is canonically documented in the D-Bus specification.
1171  *
1172  * Possible results are: #DBUS_RELEASE_NAME_REPLY_RELEASED
1173  * which means you owned the name or were in the queue to own it,
1174  * and and now you don't own it and aren't in the queue.
1175  * #DBUS_RELEASE_NAME_REPLY_NOT_OWNER which means someone else
1176  * owns the name so you can't release it.
1177  * #DBUS_RELEASE_NAME_REPLY_NON_EXISTENT
1178  * which means nobody owned the name.
1179  * 
1180  * @param connection the connection
1181  * @param name the name to remove 
1182  * @param error location to store the error
1183  * @returns a result code, -1 if error is set
1184  */ 
1185 int
1186 dbus_bus_release_name (DBusConnection *connection,
1187                        const char     *name,
1188                        DBusError      *error)
1189 {
1190   DBusMessage *message, *reply;
1191   dbus_uint32_t result;
1192
1193   _dbus_return_val_if_fail (connection != NULL, 0);
1194   _dbus_return_val_if_fail (name != NULL, 0);
1195   _dbus_return_val_if_fail (_dbus_check_is_valid_bus_name (name), 0);
1196   _dbus_return_val_if_error_is_set (error, 0);
1197
1198   message = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
1199                                           DBUS_PATH_DBUS,
1200                                           DBUS_INTERFACE_DBUS,
1201                                           "ReleaseName");
1202
1203   if (message == NULL)
1204     {
1205       _DBUS_SET_OOM (error);
1206       return -1;
1207     }
1208
1209   if (!dbus_message_append_args (message,
1210                                  DBUS_TYPE_STRING, &name,
1211                                  DBUS_TYPE_INVALID))
1212     {
1213       dbus_message_unref (message);
1214       _DBUS_SET_OOM (error);
1215       return -1;
1216     }
1217
1218   reply = dbus_connection_send_with_reply_and_block (connection, message, -1,
1219                                                      error);
1220
1221   dbus_message_unref (message);
1222
1223   if (reply == NULL)
1224     {
1225       _DBUS_ASSERT_ERROR_IS_SET (error);
1226       return -1;
1227     }
1228
1229   if (dbus_set_error_from_message (error, reply))
1230     {
1231       _DBUS_ASSERT_ERROR_IS_SET (error);
1232       dbus_message_unref (reply);
1233       return -1;
1234     }
1235
1236   if (!dbus_message_get_args (reply, error,
1237                               DBUS_TYPE_UINT32, &result,
1238                               DBUS_TYPE_INVALID))
1239     {
1240       _DBUS_ASSERT_ERROR_IS_SET (error);
1241       dbus_message_unref (reply);
1242       return -1;
1243     }
1244
1245   dbus_message_unref (reply);
1246
1247   return result;
1248 }
1249
1250 /**
1251  * Asks the bus whether a certain name has an owner.
1252  *
1253  * Using this can easily result in a race condition,
1254  * since an owner can appear or disappear after you
1255  * call this.
1256  *
1257  * If you want to request a name, just request it;
1258  * if you want to avoid replacing a current owner,
1259  * don't specify #DBUS_NAME_FLAG_REPLACE_EXISTING and
1260  * you will get an error if there's already an owner.
1261  * 
1262  * @param connection the connection
1263  * @param name the name
1264  * @param error location to store any errors
1265  * @returns #TRUE if the name exists, #FALSE if not or on error
1266  */
1267 dbus_bool_t
1268 dbus_bus_name_has_owner (DBusConnection *connection,
1269                          const char     *name,
1270                          DBusError      *error)
1271 {
1272   DBusMessage *message, *reply;
1273   dbus_bool_t exists;
1274
1275   _dbus_return_val_if_fail (connection != NULL, FALSE);
1276   _dbus_return_val_if_fail (name != NULL, FALSE);
1277   _dbus_return_val_if_fail (_dbus_check_is_valid_bus_name (name), FALSE);
1278   _dbus_return_val_if_error_is_set (error, FALSE);
1279   
1280   message = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
1281                                           DBUS_PATH_DBUS,
1282                                           DBUS_INTERFACE_DBUS,
1283                                           "NameHasOwner");
1284   if (message == NULL)
1285     {
1286       _DBUS_SET_OOM (error);
1287       return FALSE;
1288     }
1289   
1290   if (!dbus_message_append_args (message,
1291                                  DBUS_TYPE_STRING, &name,
1292                                  DBUS_TYPE_INVALID))
1293     {
1294       dbus_message_unref (message);
1295       _DBUS_SET_OOM (error);
1296       return FALSE;
1297     }
1298   
1299   reply = dbus_connection_send_with_reply_and_block (connection, message, -1, error);
1300   dbus_message_unref (message);
1301
1302   if (reply == NULL)
1303     {
1304       _DBUS_ASSERT_ERROR_IS_SET (error);
1305       return FALSE;
1306     }
1307
1308   if (!dbus_message_get_args (reply, error,
1309                               DBUS_TYPE_BOOLEAN, &exists,
1310                               DBUS_TYPE_INVALID))
1311     {
1312       _DBUS_ASSERT_ERROR_IS_SET (error);
1313       dbus_message_unref (reply);
1314       return FALSE;
1315     }
1316   
1317   dbus_message_unref (reply);
1318   return exists;
1319 }
1320
1321 /**
1322  * Starts a service that will request ownership of the given name.
1323  * The returned result will be one of be one of
1324  * #DBUS_START_REPLY_SUCCESS or #DBUS_START_REPLY_ALREADY_RUNNING if
1325  * successful.  Pass #NULL if you don't care about the result.
1326  * 
1327  * The flags parameter is for future expansion, currently you should
1328  * specify 0.
1329  *
1330  * It's often easier to avoid explicitly starting services, and
1331  * just send a method call to the service's bus name instead.
1332  * Method calls start a service to handle them by default
1333  * unless you call dbus_message_set_auto_start() to disable this
1334  * behavior.
1335  * 
1336  * @param connection the connection
1337  * @param name the name we want the new service to request
1338  * @param flags the flags (should always be 0 for now)
1339  * @param result a place to store the result or #NULL
1340  * @param error location to store any errors
1341  * @returns #TRUE if the activation succeeded, #FALSE if not
1342  */
1343 dbus_bool_t
1344 dbus_bus_start_service_by_name (DBusConnection *connection,
1345                                 const char     *name,
1346                                 dbus_uint32_t   flags,
1347                                 dbus_uint32_t  *result,
1348                                 DBusError      *error)
1349 {
1350   DBusMessage *msg;
1351   DBusMessage *reply;
1352
1353   _dbus_return_val_if_fail (connection != NULL, FALSE);
1354   _dbus_return_val_if_fail (_dbus_check_is_valid_bus_name (name), FALSE);
1355   
1356   msg = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
1357                                       DBUS_PATH_DBUS,
1358                                       DBUS_INTERFACE_DBUS,
1359                                       "StartServiceByName");
1360
1361   if (!dbus_message_append_args (msg, DBUS_TYPE_STRING, &name,
1362                                  DBUS_TYPE_UINT32, &flags, DBUS_TYPE_INVALID))
1363     {
1364       dbus_message_unref (msg);
1365       _DBUS_SET_OOM (error);
1366       return FALSE;
1367     }
1368
1369   reply = dbus_connection_send_with_reply_and_block (connection, msg,
1370                                                      -1, error);
1371   dbus_message_unref (msg);
1372
1373   if (reply == NULL)
1374     {
1375       _DBUS_ASSERT_ERROR_IS_SET (error);
1376       return FALSE;
1377     }
1378
1379   if (dbus_set_error_from_message (error, reply))
1380     {
1381       _DBUS_ASSERT_ERROR_IS_SET (error);
1382       dbus_message_unref (reply);
1383       return FALSE;
1384     }
1385
1386   if (result != NULL &&
1387       !dbus_message_get_args (reply, error, DBUS_TYPE_UINT32,
1388                               result, DBUS_TYPE_INVALID))
1389     {
1390       _DBUS_ASSERT_ERROR_IS_SET (error);
1391       dbus_message_unref (reply);
1392       return FALSE;
1393     }
1394   
1395   dbus_message_unref (reply);
1396   return TRUE;
1397 }
1398
1399 static void
1400 send_no_return_values (DBusConnection *connection,
1401                        DBusMessage    *msg,
1402                        DBusError      *error)
1403 {
1404   if (error)
1405     {
1406       /* Block to check success codepath */
1407       DBusMessage *reply;
1408       
1409       reply = dbus_connection_send_with_reply_and_block (connection, msg,
1410                                                          -1, error);
1411       
1412       if (reply == NULL)
1413         _DBUS_ASSERT_ERROR_IS_SET (error);
1414       else
1415         dbus_message_unref (reply);
1416     }
1417   else
1418     {
1419       /* Silently-fail nonblocking codepath */
1420       dbus_message_set_no_reply (msg, TRUE);
1421       dbus_connection_send (connection, msg, NULL);
1422     }
1423 }
1424
1425 /**
1426  * Adds a match rule to match messages going through the message bus.
1427  * The "rule" argument is the string form of a match rule.
1428  *
1429  * If you pass #NULL for the error, this function will not
1430  * block; the match thus won't be added until you flush the
1431  * connection, and if there's an error adding the match
1432  * you won't find out about it. This is generally acceptable, since the
1433  * possible errors (including a lack of resources in the bus, the connection
1434  * having exceeded its quota of active match rules, or the match rule being
1435  * unparseable) are generally unrecoverable.
1436  *
1437  * If you pass non-#NULL for the error this function will
1438  * block until it gets a reply. This may be useful when using match rule keys
1439  * introduced in recent versions of D-Bus, like 'arg0namespace', to allow the
1440  * application to fall back to less efficient match rules supported by older
1441  * versions of the daemon if the running version is not new enough; or when
1442  * using user-supplied rules rather than rules hard-coded at compile time.
1443  *
1444  * Normal API conventions would have the function return
1445  * a boolean value indicating whether the error was set,
1446  * but that would require blocking always to determine
1447  * the return value.
1448  *
1449  * The AddMatch method is fully documented in the D-Bus 
1450  * specification. For quick reference, the format of the 
1451  * match rules is discussed here, but the specification 
1452  * is the canonical version of this information.
1453  *
1454  * Rules are specified as a string of comma separated 
1455  * key/value pairs. An example is 
1456  * "type='signal',sender='org.freedesktop.DBus',
1457  * interface='org.freedesktop.DBus',member='Foo',
1458  * path='/bar/foo',destination=':452345.34'"
1459  *
1460  * Possible keys you can match on are type, sender, 
1461  * interface, member, path, destination and numbered
1462  * keys to match message args (keys are 'arg0', 'arg1', etc.).
1463  * Omitting a key from the rule indicates 
1464  * a wildcard match.  For instance omitting
1465  * the member from a match rule but adding a sender would
1466  * let all messages from that sender through regardless of
1467  * the member.
1468  *
1469  * Matches are inclusive not exclusive so as long as one 
1470  * rule matches the message will get through.  It is important
1471  * to note this because every time a message is received the 
1472  * application will be paged into memory to process it.  This
1473  * can cause performance problems such as draining batteries
1474  * on embedded platforms.
1475  *
1476  * If you match message args ('arg0', 'arg1', and so forth)
1477  * only string arguments will match. That is, arg0='5' means
1478  * match the string "5" not the integer 5.
1479  *
1480  * Currently there is no way to match against non-string arguments.
1481  *
1482  * A specialised form of wildcard matching on arguments is
1483  * supported for path-like namespaces.  If your argument match has
1484  * a 'path' suffix (eg: "arg0path='/some/path/'") then it is
1485  * considered a match if the argument exactly matches the given
1486  * string or if one of them ends in a '/' and is a prefix of the
1487  * other.
1488  *
1489  * Matching on interface is tricky because method call
1490  * messages only optionally specify the interface.
1491  * If a message omits the interface, then it will NOT match
1492  * if the rule specifies an interface name. This means match
1493  * rules on method calls should not usually give an interface.
1494  *
1495  * However, signal messages are required to include the interface
1496  * so when matching signals usually you should specify the interface
1497  * in the match rule.
1498  * 
1499  * For security reasons, you can match arguments only up to
1500  * #DBUS_MAXIMUM_MATCH_RULE_ARG_NUMBER.
1501  *
1502  * Match rules have a maximum length of #DBUS_MAXIMUM_MATCH_RULE_LENGTH
1503  * bytes.
1504  *
1505  * Both of these maximums are much higher than you're likely to need,
1506  * they only exist because the D-Bus bus daemon has fixed limits on
1507  * all resource usage.
1508  *
1509  * @param connection connection to the message bus
1510  * @param rule textual form of match rule
1511  * @param error location to store any errors
1512  */
1513 void
1514 dbus_bus_add_match (DBusConnection *connection,
1515                     const char     *rule,
1516                     DBusError      *error)
1517 {
1518   DBusMessage *msg;
1519
1520   _dbus_return_if_fail (rule != NULL);
1521
1522   msg = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
1523                                       DBUS_PATH_DBUS,
1524                                       DBUS_INTERFACE_DBUS,
1525                                       "AddMatch");
1526
1527   if (msg == NULL)
1528     {
1529       _DBUS_SET_OOM (error);
1530       return;
1531     }
1532
1533   if (!dbus_message_append_args (msg, DBUS_TYPE_STRING, &rule,
1534                                  DBUS_TYPE_INVALID))
1535     {
1536       dbus_message_unref (msg);
1537       _DBUS_SET_OOM (error);
1538       return;
1539     }
1540
1541   send_no_return_values (connection, msg, error);
1542
1543   dbus_message_unref (msg);
1544 }
1545
1546 /**
1547  * Removes a previously-added match rule "by value" (the most
1548  * recently-added identical rule gets removed).  The "rule" argument
1549  * is the string form of a match rule.
1550  *
1551  * The bus compares match rules semantically, not textually, so
1552  * whitespace and ordering don't have to be identical to
1553  * the rule you passed to dbus_bus_add_match().
1554  * 
1555  * If you pass #NULL for the error, this function will not
1556  * block; otherwise it will. See detailed explanation in
1557  * docs for dbus_bus_add_match().
1558  * 
1559  * @param connection connection to the message bus
1560  * @param rule textual form of match rule
1561  * @param error location to store any errors
1562  */
1563 void
1564 dbus_bus_remove_match (DBusConnection *connection,
1565                        const char     *rule,
1566                        DBusError      *error)
1567 {
1568   DBusMessage *msg;
1569
1570   _dbus_return_if_fail (rule != NULL);
1571   
1572   msg = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
1573                                       DBUS_PATH_DBUS,
1574                                       DBUS_INTERFACE_DBUS,
1575                                       "RemoveMatch");
1576
1577   if (!dbus_message_append_args (msg, DBUS_TYPE_STRING, &rule,
1578                                  DBUS_TYPE_INVALID))
1579     {
1580       dbus_message_unref (msg);
1581       _DBUS_SET_OOM (error);
1582       return;
1583     }
1584
1585   send_no_return_values (connection, msg, error);
1586
1587   dbus_message_unref (msg);
1588 }
1589
1590 /** @} */