dbus/dbus-bus.c

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