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