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  * @todo right now the default address of the system bus is hardcoded,
  40  * so if you change it in the global config file suddenly you have to
  41  * set DBUS_SYSTEM_BUS_ADDRESS env variable.  Might be nice if the
  42  * client lib somehow read the config file, or if the bus on startup
  43  * somehow wrote out its address to a well-known spot, but might also
  44  * not be worth it.
  45  */
  46
  47 /**
  48  * @defgroup DBusBusInternals Message bus APIs internals
  49  * @ingroup DBusInternals
  50  * @brief Internals of functions for communicating with the message bus
  51  *
  52  * @{
  53  */
  54
  55 /**
  56  * Block of message-bus-related data we attach to each
  57  * #DBusConnection used with these convenience functions.
  58  *
  59  */
  60 typedef struct
  61 {
  62   DBusConnection *connection; /**< Connection we're associated with */
  63   char *unique_name; /**< Unique name of this connection */
  64
  65   unsigned int is_well_known : 1; /**< Is one of the well-known connections in our global array */
  66 } BusData;
  67
  68 /** The slot we have reserved to store BusData.
  69  */
  70 static dbus_int32_t bus_data_slot = -1;
  71
  72 /** Number of bus types */
  73 #define N_BUS_TYPES 3
  74
  75 static DBusConnection *bus_connections[N_BUS_TYPES];
  76 static char *bus_connection_addresses[N_BUS_TYPES] = { NULL, NULL, NULL };
  77
  78 static DBusBusType activation_bus_type = DBUS_BUS_STARTER;
  79
  80 static dbus_bool_t initialized = FALSE;
  81
  82 /**
  83  * Lock for globals in this file
  84  */
  85 _DBUS_DEFINE_GLOBAL_LOCK (bus);
  86
  87 static void
  88 addresses_shutdown_func (void *data)
  89 {
  90   int i;
  91
  92   i = 0;
  93   while (i < N_BUS_TYPES)
  94     {
  95       if (bus_connections[i] != NULL)
  96         _dbus_warn ("dbus_shutdown() called but connections were still live!");
  97
  98       dbus_free (bus_connection_addresses[i]);
  99       bus_connection_addresses[i] = NULL;
 100       ++i;
 101     }
 102
 103   activation_bus_type = DBUS_BUS_STARTER;
 104 }
 105
 106 static dbus_bool_t
 107 get_from_env (char           **connection_p,
 108               const char      *env_var)
 109 {
 110   const char *s;
 111
 112   _dbus_assert (*connection_p == NULL);
 113
 114   s = _dbus_getenv (env_var);
 115   if (s == NULL || *s == '\0')
 116     return TRUE; /* successfully didn't use the env var */
 117   else
 118     {
 119       *connection_p = _dbus_strdup (s);
 120       return *connection_p != NULL;
 121     }
 122 }
 123
 124 static dbus_bool_t
 125 init_connections_unlocked (void)
 126 {
 127   if (!initialized)
 128     {
 129       const char *s;
 130       int i;
 131
 132       i = 0;
 133       while (i < N_BUS_TYPES)
 134         {
 135           bus_connections[i] = NULL;
 136           ++i;
 137         }
 138
 139       /* Don't init these twice, we may run this code twice if
 140        * init_connections_unlocked() fails midway through.
 141        * In practice, each block below should contain only one
 142        * "return FALSE" or running through twice may not
 143        * work right.
 144        */
 145
 146        if (bus_connection_addresses[DBUS_BUS_SYSTEM] == NULL)
 147          {
 148            _dbus_verbose ("Filling in system bus address...\n");
 149
 150            if (!get_from_env (&bus_connection_addresses[DBUS_BUS_SYSTEM],
 151                               "DBUS_SYSTEM_BUS_ADDRESS"))
 152              return FALSE;
 153          }
 154
 155
 156        if (bus_connection_addresses[DBUS_BUS_SYSTEM] == NULL)
 157          {
 158            /* Use default system bus address if none set in environment */
 159            bus_connection_addresses[DBUS_BUS_SYSTEM] =
 160              _dbus_strdup (DBUS_SYSTEM_BUS_DEFAULT_ADDRESS);
 161            if (bus_connection_addresses[DBUS_BUS_SYSTEM] == NULL)
 162              return FALSE;
 163
 164            _dbus_verbose ("  used default system bus \"%s\"\n",
 165                           bus_connection_addresses[DBUS_BUS_SYSTEM]);
 166          }
 167        else
 168          _dbus_verbose ("  used env var system bus \"%s\"\n",
 169                         bus_connection_addresses[DBUS_BUS_SYSTEM]);
 170
 171       if (bus_connection_addresses[DBUS_BUS_SESSION] == NULL)
 172         {
 173           _dbus_verbose ("Filling in session bus address...\n");
 174
 175           if (!get_from_env (&bus_connection_addresses[DBUS_BUS_SESSION],
 176                              "DBUS_SESSION_BUS_ADDRESS"))
 177             return FALSE;
 178
 179           if (bus_connection_addresses[DBUS_BUS_SESSION] == NULL)
 180             bus_connection_addresses[DBUS_BUS_SESSION] =
 181               _dbus_strdup (DBUS_SESSION_BUS_DEFAULT_ADDRESS);
 182            if (bus_connection_addresses[DBUS_BUS_SESSION] == NULL)
 183              return FALSE;
 184
 185           _dbus_verbose ("  \"%s\"\n", bus_connection_addresses[DBUS_BUS_SESSION] ?
 186                          bus_connection_addresses[DBUS_BUS_SESSION] : "none set");
 187         }
 188
 189       if (bus_connection_addresses[DBUS_BUS_STARTER] == NULL)
 190         {
 191           _dbus_verbose ("Filling in activation bus address...\n");
 192
 193           if (!get_from_env (&bus_connection_addresses[DBUS_BUS_STARTER],
 194                              "DBUS_STARTER_ADDRESS"))
 195             return FALSE;
 196
 197           _dbus_verbose ("  \"%s\"\n", bus_connection_addresses[DBUS_BUS_STARTER] ?
 198                          bus_connection_addresses[DBUS_BUS_STARTER] : "none set");
 199         }
 200
 201
 202       if (bus_connection_addresses[DBUS_BUS_STARTER] != NULL)
 203         {
 204           s = _dbus_getenv ("DBUS_STARTER_BUS_TYPE");
 205
 206           if (s != NULL)
 207             {
 208               _dbus_verbose ("Bus activation type was set to \"%s\"\n", s);
 209
 210               if (strcmp (s, "system") == 0)
 211                 activation_bus_type = DBUS_BUS_SYSTEM;
 212               else if (strcmp (s, "session") == 0)
 213                 activation_bus_type = DBUS_BUS_SESSION;
 214             }
 215         }
 216       else
 217         {
 218           /* Default to the session bus instead if available */
 219           if (bus_connection_addresses[DBUS_BUS_SESSION] != NULL)
 220             {
 221               bus_connection_addresses[DBUS_BUS_STARTER] =
 222                 _dbus_strdup (bus_connection_addresses[DBUS_BUS_SESSION]);
 223               if (bus_connection_addresses[DBUS_BUS_STARTER] == NULL)
 224                 return FALSE;
 225             }
 226         }
 227
 228       /* If we return FALSE we have to be sure that restarting
 229        * the above code will work right
 230        */
 231
 232       if (!_dbus_setenv ("DBUS_ACTIVATION_ADDRESS", NULL))
 233         return FALSE;
 234
 235       if (!_dbus_setenv ("DBUS_ACTIVATION_BUS_TYPE", NULL))
 236         return FALSE;
 237
 238       if (!_dbus_register_shutdown_func (addresses_shutdown_func,
 239                                          NULL))
 240         return FALSE;
 241
 242       initialized = TRUE;
 243     }
 244
 245   return initialized;
 246 }
 247
 248 static void
 249 bus_data_free (void *data)
 250 {
 251   BusData *bd = data;
 252
 253   if (bd->is_well_known)
 254     {
 255       int i;
 256       _DBUS_LOCK (bus);
 257       /* We may be stored in more than one slot */
 258       i = 0;
 259       while (i < N_BUS_TYPES)
 260         {
 261           if (bus_connections[i] == bd->connection)
 262             bus_connections[i] = NULL;
 263
 264           ++i;
 265         }
 266       _DBUS_UNLOCK (bus);
 267     }
 268
 269   dbus_free (bd->unique_name);
 270   dbus_free (bd);
 271
 272   dbus_connection_free_data_slot (&bus_data_slot);
 273 }
 274
 275 static BusData*
 276 ensure_bus_data (DBusConnection *connection)
 277 {
 278   BusData *bd;
 279
 280   if (!dbus_connection_allocate_data_slot (&bus_data_slot))
 281     return NULL;
 282
 283   bd = dbus_connection_get_data (connection, bus_data_slot);
 284   if (bd == NULL)
 285     {
 286       bd = dbus_new0 (BusData, 1);
 287       if (bd == NULL)
 288         {
 289           dbus_connection_free_data_slot (&bus_data_slot);
 290           return NULL;
 291         }
 292
 293       bd->connection = connection;
 294
 295       if (!dbus_connection_set_data (connection, bus_data_slot, bd,
 296                                      bus_data_free))
 297         {
 298           dbus_free (bd);
 299           dbus_connection_free_data_slot (&bus_data_slot);
 300           return NULL;
 301         }
 302
 303       /* Data slot refcount now held by the BusData */
 304     }
 305   else
 306     {
 307       dbus_connection_free_data_slot (&bus_data_slot);
 308     }
 309
 310   return bd;
 311 }
 312
 313 /* internal function that checks to see if this
 314    is a shared connection owned by the bus and if it is unref it */
 315 void
 316 _dbus_bus_check_connection_and_unref_unlocked (DBusConnection *connection)
 317 {
 318   _DBUS_LOCK (bus);
 319
 320   if (bus_connections[DBUS_BUS_SYSTEM] == connection)
 321     {
 322       bus_connections[DBUS_BUS_SYSTEM] = NULL;
 323       _dbus_connection_unref_unlocked (connection);
 324     }
 325   else if (bus_connections[DBUS_BUS_SESSION] == connection)
 326     {
 327       bus_connections[DBUS_BUS_SESSION] = NULL;
 328       _dbus_connection_unref_unlocked (connection);
 329     }
 330   else if (bus_connections[DBUS_BUS_STARTER] == connection)
 331     {
 332       bus_connections[DBUS_BUS_STARTER] = NULL;
 333       _dbus_connection_unref_unlocked (connection);
 334     }
 335
 336   _DBUS_UNLOCK (bus);
 337 }
 338
 339 static DBusConnection *
 340 internal_bus_get (DBusBusType  type,
 341                   dbus_bool_t  private,
 342                   DBusError   *error)
 343 {
 344   const char *address;
 345   DBusConnection *connection;
 346   BusData *bd;
 347   DBusBusType address_type;
 348
 349   _dbus_return_val_if_fail (type >= 0 && type < N_BUS_TYPES, NULL);
 350   _dbus_return_val_if_error_is_set (error, NULL);
 351
 352   _DBUS_LOCK (bus);
 353
 354   if (!init_connections_unlocked ())
 355     {
 356       _DBUS_UNLOCK (bus);
 357       _DBUS_SET_OOM (error);
 358       return NULL;
 359     }
 360
 361   /* We want to use the activation address even if the
 362    * activating bus is the session or system bus,
 363    * per the spec.
 364    */
 365   address_type = type;
 366
 367   /* Use the real type of the activation bus for getting its
 368    * connection, but only if the real type's address is available. (If
 369    * the activating bus isn't a well-known bus then
 370    * activation_bus_type == DBUS_BUS_STARTER)
 371    */
 372   if (type == DBUS_BUS_STARTER &&
 373       bus_connection_addresses[activation_bus_type] != NULL)
 374     type = activation_bus_type;
 375
 376   if (!private && bus_connections[type] != NULL)
 377     {
 378       connection = bus_connections[type];
 379       dbus_connection_ref (connection);
 380
 381       _DBUS_UNLOCK (bus);
 382       return connection;
 383     }
 384
 385   address = bus_connection_addresses[address_type];
 386   if (address == NULL)
 387     {
 388       dbus_set_error (error, DBUS_ERROR_FAILED,
 389                       "Unable to determine the address of the message bus (try 'man dbus-launch' and 'man dbus-daemon' for help)");
 390       _DBUS_UNLOCK (bus);
 391       return NULL;
 392     }
 393
 394   if (private)
 395     connection = dbus_connection_open_private(address, error);
 396   else
 397     connection = dbus_connection_open (address, error);
 398
 399   if (!connection)
 400     {
 401       _DBUS_ASSERT_ERROR_IS_SET (error);
 402       _DBUS_UNLOCK (bus);
 403       return NULL;
 404     }
 405
 406   /* By default we're bound to the lifecycle of
 407    * the message bus.
 408    */
 409   dbus_connection_set_exit_on_disconnect (connection,
 410                                           TRUE);
 411
 412   if (!dbus_bus_register (connection, error))
 413     {
 414       _DBUS_ASSERT_ERROR_IS_SET (error);
 415       _dbus_connection_close_internal (connection);
 416       dbus_connection_unref (connection);
 417
 418       _DBUS_UNLOCK (bus);
 419       return NULL;
 420     }
 421
 422   if (!private)
 423     {
 424       /* get a hard ref to the connection */
 425       bus_connections[type] = connection;
 426       dbus_connection_ref (bus_connections[type]);
 427     }
 428
 429   bd = ensure_bus_data (connection);
 430   _dbus_assert (bd != NULL);
 431
 432   bd->is_well_known = TRUE;
 433
 434   _DBUS_UNLOCK (bus);
 435   return connection;
 436 }
 437
 438
 439 /** @} */ /* end of implementation details docs */
 440
 441 /**
 442  * @addtogroup DBusBus
 443  * @{
 444  */
 445
 446 /**
 447  * Connects to a bus daemon and registers the client with it.  If a
 448  * connection to the bus already exists, then that connection is
 449  * returned.  Caller owns a reference to the bus.
 450  *
 451  * @param type bus type
 452  * @param error address where an error can be returned.
 453  * @returns a DBusConnection with new ref
 454  */
 455 DBusConnection *
 456 dbus_bus_get (DBusBusType  type,
 457               DBusError   *error)
 458 {
 459   return internal_bus_get (type, FALSE, error);
 460 }
 461
 462 /**
 463  * Connects to a bus daemon and registers the client with it.  Unlike
 464  * dbus_bus_get(), always creates a new connection. This connection
 465  * will not be saved or recycled by libdbus. Caller owns a reference
 466  * to the bus.
 467  *
 468  * @param type bus type
 469  * @param error address where an error can be returned.
 470  * @returns a DBusConnection with new ref
 471  */
 472 DBusConnection *
 473 dbus_bus_get_private (DBusBusType  type,
 474                       DBusError   *error)
 475 {
 476   return internal_bus_get (type, TRUE, error);
 477 }
 478
 479 /**
 480  * Registers a connection with the bus. This must be the first
 481  * thing an application does when connecting to the message bus.
 482  * If registration succeeds, the unique name will be set,
 483  * and can be obtained using dbus_bus_get_unique_name().
 484  *
 485  * @param connection the connection
 486  * @param error place to store errors
 487  * @returns #TRUE on success
 488  */
 489 dbus_bool_t
 490 dbus_bus_register (DBusConnection *connection,
 491                    DBusError      *error)
 492 {
 493   DBusMessage *message, *reply;
 494   char *name;
 495   BusData *bd;
 496   dbus_bool_t retval;
 497
 498   _dbus_return_val_if_fail (connection != NULL, FALSE);
 499   _dbus_return_val_if_error_is_set (error, FALSE);
 500
 501   retval = FALSE;
 502
 503   bd = ensure_bus_data (connection);
 504   if (bd == NULL)
 505     {
 506       _DBUS_SET_OOM (error);
 507       return FALSE;
 508     }
 509
 510   if (bd->unique_name != NULL)
 511     {
 512       _dbus_warn ("Attempt to register the same DBusConnection with the message bus, but it is already registered\n");
 513       /* This isn't an error, it's a programming bug. We'll be nice
 514        * and not _dbus_assert_not_reached()
 515        */
 516       return TRUE;
 517     }
 518
 519   message = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
 520                                           DBUS_PATH_DBUS,
 521                                           DBUS_INTERFACE_DBUS,
 522                                           "Hello");
 523
 524   if (!message)
 525     {
 526       _DBUS_SET_OOM (error);
 527       return FALSE;
 528     }
 529
 530   reply = dbus_connection_send_with_reply_and_block (connection, message, -1, error);
 531
 532   dbus_message_unref (message);
 533
 534   if (reply == NULL)
 535     goto out;
 536   else if (dbus_set_error_from_message (error, reply))
 537     goto out;
 538   else if (!dbus_message_get_args (reply, error,
 539                                    DBUS_TYPE_STRING, &name,
 540                                    DBUS_TYPE_INVALID))
 541     goto out;
 542
 543   bd->unique_name = _dbus_strdup (name);
 544   if (bd->unique_name == NULL)
 545     {
 546       _DBUS_SET_OOM (error);
 547       goto out;
 548     }
 549
 550   retval = TRUE;
 551
 552  out:
 553   if (reply)
 554     dbus_message_unref (reply);
 555
 556   if (!retval)
 557     _DBUS_ASSERT_ERROR_IS_SET (error);
 558
 559   return retval;
 560 }
 561
 562
 563 /**
 564  * Sets the unique name of the connection.  Can only be used if you
 565  * registered with the bus manually (i.e. if you did not call
 566  * dbus_bus_register()). Can only be called once per connection.
 567  *
 568  * @param connection the connection
 569  * @param unique_name the unique name
 570  * @returns #FALSE if not enough memory
 571  */
 572 dbus_bool_t
 573 dbus_bus_set_unique_name (DBusConnection *connection,
 574                           const char     *unique_name)
 575 {
 576   BusData *bd;
 577
 578   _dbus_return_val_if_fail (connection != NULL, FALSE);
 579   _dbus_return_val_if_fail (unique_name != NULL, FALSE);
 580
 581   bd = ensure_bus_data (connection);
 582   if (bd == NULL)
 583     return FALSE;
 584
 585   _dbus_assert (bd->unique_name == NULL);
 586
 587   bd->unique_name = _dbus_strdup (unique_name);
 588   return bd->unique_name != NULL;
 589 }
 590
 591 /**
 592  * Gets the unique name of the connection.  Only possible after the
 593  * connection has been registered with the message bus.
 594  *
 595  * The name remains valid for the duration of the connection and
 596  * should not be freed by the caller.
 597  *
 598  * @param connection the connection
 599  * @returns the unique name or NULL on error
 600  */
 601 const char*
 602 dbus_bus_get_unique_name (DBusConnection *connection)
 603 {
 604   BusData *bd;
 605
 606   _dbus_return_val_if_fail (connection != NULL, NULL);
 607
 608   bd = ensure_bus_data (connection);
 609   if (bd == NULL)
 610     return NULL;
 611
 612   return bd->unique_name;
 613 }
 614
 615 /**
 616  * Asks the bus to return the uid of the named
 617  * connection.
 618  *
 619  * Not going to work on Windows, the bus should return
 620  * an error then.
 621  *
 622  * @param connection the connection
 623  * @param name a name owned by the connection
 624  * @param error location to store the error
 625  * @returns a result code, -1 if error is set
 626  */
 627 unsigned long
 628 dbus_bus_get_unix_user (DBusConnection *connection,
 629                         const char     *name,
 630                         DBusError      *error)
 631 {
 632   DBusMessage *message, *reply;
 633   dbus_uint32_t uid;
 634
 635   _dbus_return_val_if_fail (connection != NULL, DBUS_UID_UNSET);
 636   _dbus_return_val_if_fail (name != NULL, DBUS_UID_UNSET);
 637   _dbus_return_val_if_fail (_dbus_check_is_valid_bus_name (name), DBUS_UID_UNSET);
 638   _dbus_return_val_if_error_is_set (error, DBUS_UID_UNSET);
 639
 640   message = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
 641                                           DBUS_PATH_DBUS,
 642                                           DBUS_INTERFACE_DBUS,
 643                                           "GetConnectionUnixUser");
 644
 645   if (message == NULL)
 646     {
 647       _DBUS_SET_OOM (error);
 648       return DBUS_UID_UNSET;
 649     }
 650
 651   if (!dbus_message_append_args (message,
 652                                  DBUS_TYPE_STRING, &name,
 653                                  DBUS_TYPE_INVALID))
 654     {
 655       dbus_message_unref (message);
 656       _DBUS_SET_OOM (error);
 657       return DBUS_UID_UNSET;
 658     }
 659
 660   reply = dbus_connection_send_with_reply_and_block (connection, message, -1,
 661                                                      error);
 662
 663   dbus_message_unref (message);
 664
 665   if (reply == NULL)
 666     {
 667       _DBUS_ASSERT_ERROR_IS_SET (error);
 668       return DBUS_UID_UNSET;
 669     }
 670
 671   if (dbus_set_error_from_message (error, reply))
 672     {
 673       _DBUS_ASSERT_ERROR_IS_SET (error);
 674       dbus_message_unref (reply);
 675       return DBUS_UID_UNSET;
 676     }
 677
 678   if (!dbus_message_get_args (reply, error,
 679                               DBUS_TYPE_UINT32, &uid,
 680                               DBUS_TYPE_INVALID))
 681     {
 682       _DBUS_ASSERT_ERROR_IS_SET (error);
 683       dbus_message_unref (reply);
 684       return DBUS_UID_UNSET;
 685     }
 686
 687   dbus_message_unref (reply);
 688
 689   return (unsigned long) uid;
 690 }
 691
 692
 693 /**
 694  * Asks the bus to assign the given name to this connection by invoking
 695  * the RequestName method on the bus. This method is fully documented
 696  * in the D-Bus specification. For quick reference, the flags and
 697  * result codes are discussed here, but the specification is the
 698  * canonical version of this information.
 699  *
 700  * The #DBUS_NAME_FLAG_ALLOW_REPLACEMENT flag indicates that the caller
 701  * will allow other services to take over the name from the current owner.
 702  *
 703  * The #DBUS_NAME_FLAG_REPLACE_EXISTING flag indicates that the caller
 704  * would like to take over the name from the current owner.
 705  * If the current name owner did not use #DBUS_NAME_FLAG_ALLOW_REPLACEMENT
 706  * then this flag indicates that the caller would like to be placed
 707  * in the queue to own the name when the current owner lets go.
 708  *
 709  * If no flags are given, an application will receive the requested
 710  * name only if the name is currently unowned; it will NOT give
 711  * up the name if another application asks to take it over using
 712  * #DBUS_NAME_FLAG_REPLACE_EXISTING.
 713  *
 714  * This function returns a result code. The possible result codes
 715  * are as follows.
 716  *
 717  * #DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER means that the name had no
 718  * existing owner, and the caller is now the primary owner; or that
 719  * the name had an owner, and the caller specified
 720  * #DBUS_NAME_FLAG_REPLACE_EXISTING, and the current owner
 721  * specified #DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
 722  *
 723  * #DBUS_REQUEST_NAME_REPLY_IN_QUEUE happens only if the caller does NOT
 724  * specify #DBUS_NAME_FLAG_DO_NOT_QUEUE and either the current owner
 725  * did NOT specify #DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the caller did NOT
 726  * specify #DBUS_NAME_FLAG_REPLACE_EXISTING. In this case the caller ends up
 727  * in a queue to own the name after the current owner gives it up.
 728  *
 729  * #DBUS_REQUEST_NAME_REPLY_EXISTS happens if the name has an owner
 730  * already and the caller specifies #DBUS_NAME_FLAG_DO_NOT_QUEUE
 731  * and either the current owner has NOT specified
 732  * #DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the caller did NOT specify
 733  * #DBUS_NAME_FLAG_REPLACE_EXISTING.
 734  *
 735  * #DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER happens if an application
 736  * requests a name it already owns.
 737  *
 738  * When a service represents an application, say "text editor," then
 739  * it should specify #DBUS_NAME_FLAG_ALLOW_REPLACEMENT if it wants
 740  * the last editor started to be the user's editor vs. the first one
 741  * started.  Then any editor that can be the user's editor should
 742  * specify #DBUS_NAME_FLAG_REPLACE_EXISTING to either take over
 743  * (last-started-wins) or be queued up (first-started-wins) according
 744  * to whether #DBUS_NAME_FLAG_ALLOW_REPLACEMENT was given.
 745  *
 746  * @param connection the connection
 747  * @param name the name to request
 748  * @param flags flags
 749  * @param error location to store the error
 750  * @returns a result code, -1 if error is set
 751  */
 752 int
 753 dbus_bus_request_name (DBusConnection *connection,
 754                        const char     *name,
 755                        unsigned int    flags,
 756                        DBusError      *error)
 757 {
 758   DBusMessage *message, *reply;
 759   dbus_uint32_t result;
 760
 761   _dbus_return_val_if_fail (connection != NULL, 0);
 762   _dbus_return_val_if_fail (name != NULL, 0);
 763   _dbus_return_val_if_fail (_dbus_check_is_valid_bus_name (name), 0);
 764   _dbus_return_val_if_error_is_set (error, 0);
 765
 766   message = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
 767                                           DBUS_PATH_DBUS,
 768                                           DBUS_INTERFACE_DBUS,
 769                                           "RequestName");
 770
 771   if (message == NULL)
 772     {
 773       _DBUS_SET_OOM (error);
 774       return -1;
 775     }
 776
 777   if (!dbus_message_append_args (message,
 778                                  DBUS_TYPE_STRING, &name,
 779                                  DBUS_TYPE_UINT32, &flags,
 780                                  DBUS_TYPE_INVALID))
 781     {
 782       dbus_message_unref (message);
 783       _DBUS_SET_OOM (error);
 784       return -1;
 785     }
 786
 787   reply = dbus_connection_send_with_reply_and_block (connection, message, -1,
 788                                                      error);
 789
 790   dbus_message_unref (message);
 791
 792   if (reply == NULL)
 793     {
 794       _DBUS_ASSERT_ERROR_IS_SET (error);
 795       return -1;
 796     }
 797
 798   if (dbus_set_error_from_message (error, reply))
 799     {
 800       _DBUS_ASSERT_ERROR_IS_SET (error);
 801       dbus_message_unref (reply);
 802       return -1;
 803     }
 804
 805   if (!dbus_message_get_args (reply, error,
 806                               DBUS_TYPE_UINT32, &result,
 807                               DBUS_TYPE_INVALID))
 808     {
 809       _DBUS_ASSERT_ERROR_IS_SET (error);
 810       dbus_message_unref (reply);
 811       return -1;
 812     }
 813
 814   dbus_message_unref (reply);
 815
 816   return result;
 817 }
 818
 819
 820 /**
 821  * Asks the bus to unassign the given name to this connection by invoking
 822  * the ReleaseName method on the bus. This method is fully documented
 823  * in the D-Bus specification.
 824  *
 825  * @param connection the connection
 826  * @param name the name to remove
 827  * @param error location to store the error
 828  * @returns a result code, -1 if error is set
 829  */
 830 int
 831 dbus_bus_release_name (DBusConnection *connection,
 832                        const char     *name,
 833                        DBusError      *error)
 834 {
 835   DBusMessage *message, *reply;
 836   dbus_uint32_t result;
 837
 838   _dbus_return_val_if_fail (connection != NULL, 0);
 839   _dbus_return_val_if_fail (name != NULL, 0);
 840   _dbus_return_val_if_fail (_dbus_check_is_valid_bus_name (name), 0);
 841   _dbus_return_val_if_error_is_set (error, 0);
 842
 843   message = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
 844                                           DBUS_PATH_DBUS,
 845                                           DBUS_INTERFACE_DBUS,
 846                                           "ReleaseName");
 847
 848   if (message == NULL)
 849     {
 850       _DBUS_SET_OOM (error);
 851       return -1;
 852     }
 853
 854   if (!dbus_message_append_args (message,
 855                                  DBUS_TYPE_STRING, &name,
 856                                  DBUS_TYPE_INVALID))
 857     {
 858       dbus_message_unref (message);
 859       _DBUS_SET_OOM (error);
 860       return -1;
 861     }
 862
 863   reply = dbus_connection_send_with_reply_and_block (connection, message, -1,
 864                                                      error);
 865
 866   dbus_message_unref (message);
 867
 868   if (reply == NULL)
 869     {
 870       _DBUS_ASSERT_ERROR_IS_SET (error);
 871       return -1;
 872     }
 873
 874   if (dbus_set_error_from_message (error, reply))
 875     {
 876       _DBUS_ASSERT_ERROR_IS_SET (error);
 877       dbus_message_unref (reply);
 878       return -1;
 879     }
 880
 881   if (!dbus_message_get_args (reply, error,
 882                               DBUS_TYPE_UINT32, &result,
 883                               DBUS_TYPE_INVALID))
 884     {
 885       _DBUS_ASSERT_ERROR_IS_SET (error);
 886       dbus_message_unref (reply);
 887       return -1;
 888     }
 889
 890   dbus_message_unref (reply);
 891
 892   return result;
 893 }
 894
 895 /**
 896  * Checks whether a certain name has an owner.
 897  *
 898  * @param connection the connection
 899  * @param name the name
 900  * @param error location to store any errors
 901  * @returns #TRUE if the name exists, #FALSE if not or on error
 902  */
 903 dbus_bool_t
 904 dbus_bus_name_has_owner (DBusConnection *connection,
 905                          const char     *name,
 906                          DBusError      *error)
 907 {
 908   DBusMessage *message, *reply;
 909   dbus_bool_t exists;
 910
 911   _dbus_return_val_if_fail (connection != NULL, FALSE);
 912   _dbus_return_val_if_fail (name != NULL, FALSE);
 913   _dbus_return_val_if_fail (_dbus_check_is_valid_bus_name (name), FALSE);
 914   _dbus_return_val_if_error_is_set (error, FALSE);
 915
 916   message = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
 917                                           DBUS_PATH_DBUS,
 918                                           DBUS_INTERFACE_DBUS,
 919                                           "NameHasOwner");
 920   if (message == NULL)
 921     {
 922       _DBUS_SET_OOM (error);
 923       return FALSE;
 924     }
 925
 926   if (!dbus_message_append_args (message,
 927                                  DBUS_TYPE_STRING, &name,
 928                                  DBUS_TYPE_INVALID))
 929     {
 930       dbus_message_unref (message);
 931       _DBUS_SET_OOM (error);
 932       return FALSE;
 933     }
 934
 935   reply = dbus_connection_send_with_reply_and_block (connection, message, -1, error);
 936   dbus_message_unref (message);
 937
 938   if (reply == NULL)
 939     {
 940       _DBUS_ASSERT_ERROR_IS_SET (error);
 941       return FALSE;
 942     }
 943
 944   if (!dbus_message_get_args (reply, error,
 945                               DBUS_TYPE_BOOLEAN, &exists,
 946                               DBUS_TYPE_INVALID))
 947     {
 948       _DBUS_ASSERT_ERROR_IS_SET (error);
 949       dbus_message_unref (reply);
 950       return FALSE;
 951     }
 952
 953   dbus_message_unref (reply);
 954   return exists;
 955 }
 956
 957 /**
 958  * Starts a service that will request ownership of the given name.
 959  * The returned result will be one of be one of
 960  * #DBUS_START_REPLY_SUCCESS or #DBUS_START_REPLY_ALREADY_RUNNING if
 961  * successful.  Pass #NULL if you don't care about the result.
 962  *
 963  * The flags parameter is for future expansion, currently you should
 964  * specify 0.
 965  *
 966  * @param connection the connection
 967  * @param name the name we want the new service to request
 968  * @param flags the flags (should always be 0 for now)
 969  * @param result a place to store the result or #NULL
 970  * @param error location to store any errors
 971  * @returns #TRUE if the activation succeeded, #FALSE if not
 972  */
 973 dbus_bool_t
 974 dbus_bus_start_service_by_name (DBusConnection *connection,
 975                                 const char     *name,
 976                                 dbus_uint32_t   flags,
 977                                 dbus_uint32_t  *result,
 978                                 DBusError      *error)
 979 {
 980   DBusMessage *msg;
 981   DBusMessage *reply;
 982
 983   _dbus_return_val_if_fail (connection != NULL, FALSE);
 984   _dbus_return_val_if_fail (_dbus_check_is_valid_bus_name (name), FALSE);
 985
 986   msg = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
 987                                       DBUS_PATH_DBUS,
 988                                       DBUS_INTERFACE_DBUS,
 989                                       "StartServiceByName");
 990
 991   if (!dbus_message_append_args (msg, DBUS_TYPE_STRING, &name,
 992                                  DBUS_TYPE_UINT32, &flags, DBUS_TYPE_INVALID))
 993     {
 994       dbus_message_unref (msg);
 995       _DBUS_SET_OOM (error);
 996       return FALSE;
 997     }
 998
 999   reply = dbus_connection_send_with_reply_and_block (connection, msg,
1000                                                      -1, error);
1001   dbus_message_unref (msg);
1002
1003   if (reply == NULL)
1004     {
1005       _DBUS_ASSERT_ERROR_IS_SET (error);
1006       return FALSE;
1007     }
1008
1009   if (dbus_set_error_from_message (error, reply))
1010     {
1011       _DBUS_ASSERT_ERROR_IS_SET (error);
1012       dbus_message_unref (reply);
1013       return FALSE;
1014     }
1015
1016   if (result != NULL &&
1017       !dbus_message_get_args (reply, error, DBUS_TYPE_UINT32,
1018                               result, DBUS_TYPE_INVALID))
1019     {
1020       _DBUS_ASSERT_ERROR_IS_SET (error);
1021       dbus_message_unref (reply);
1022       return FALSE;
1023     }
1024
1025   dbus_message_unref (reply);
1026   return TRUE;
1027 }
1028
1029 static void
1030 send_no_return_values (DBusConnection *connection,
1031                        DBusMessage    *msg,
1032                        DBusError      *error)
1033 {
1034   if (error)
1035     {
1036       /* Block to check success codepath */
1037       DBusMessage *reply;
1038
1039       reply = dbus_connection_send_with_reply_and_block (connection, msg,
1040                                                          -1, error);
1041
1042       if (reply == NULL)
1043         _DBUS_ASSERT_ERROR_IS_SET (error);
1044       else
1045         dbus_message_unref (reply);
1046     }
1047   else
1048     {
1049       /* Silently-fail nonblocking codepath */
1050       dbus_message_set_no_reply (msg, TRUE);
1051       dbus_connection_send (connection, msg, NULL);
1052     }
1053 }
1054
1055 /**
1056  * Adds a match rule to match messages going through the message bus.
1057  * The "rule" argument is the string form of a match rule.
1058  *
1059  * If you pass #NULL for the error, this function will not
1060  * block; the match thus won't be added until you flush the
1061  * connection, and if there's an error adding the match
1062  * (only possible error is lack of resources in the bus),
1063  * you won't find out about it.
1064  *
1065  * If you pass non-#NULL for the error this function will
1066  * block until it gets a reply.
1067  *
1068  * Normal API conventions would have the function return
1069  * a boolean value indicating whether the error was set,
1070  * but that would require blocking always to determine
1071  * the return value.
1072  *
1073  * The AddMatch method is fully documented in the D-Bus
1074  * specification. For quick reference, the format of the
1075  * match rules is discussed here, but the specification
1076  * is the canonical version of this information.
1077  *
1078  * Rules are specified as a string of comma separated
1079  * key/value pairs. An example is
1080  * "type='signal',sender='org.freedesktop.DBus',
1081  * interface='org.freedesktop.DBus',member='Foo',
1082  * path='/bar/foo',destination=':452345.34'"
1083  *
1084  * Possible keys you can match on are type, sender,
1085  * interface, member, path, destination and the special
1086  * arg keys.  Excluding a key from the rule indicates
1087  * a wildcard match.  For instance excluding the
1088  * the member from a match rule but adding a sender would
1089  * let all messages from that sender through.
1090  *
1091  * Matches are inclusive not exclusive so as long as one
1092  * rule matches the message will get through.  It is important
1093  * to note this because every time a message is received the
1094  * application will be paged into memory to process it.  This
1095  * can cause performance problems such as draining batteries
1096  * on embedded platforms.
1097  *
1098  * The special arg keys are used for further restricting the
1099  * match based on the parameters sent by the signal or method.
1100  * For instance arg1='foo' will check the first argument,
1101  * arg2='bar' the second and so on.  For performance reasons
1102  * there is a set limit on the highest number parameter that
1103  * can be checked which is set in dbus-protocol.h
1104  *
1105  * @param connection connection to the message bus
1106  * @param rule textual form of match rule
1107  * @param error location to store any errors
1108  */
1109 void
1110 dbus_bus_add_match (DBusConnection *connection,
1111                     const char     *rule,
1112                     DBusError      *error)
1113 {
1114   DBusMessage *msg;
1115
1116   _dbus_return_if_fail (rule != NULL);
1117
1118   msg = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
1119                                       DBUS_PATH_DBUS,
1120                                       DBUS_INTERFACE_DBUS,
1121                                       "AddMatch");
1122
1123   if (msg == NULL)
1124     {
1125       _DBUS_SET_OOM (error);
1126       return;
1127     }
1128
1129   if (!dbus_message_append_args (msg, DBUS_TYPE_STRING, &rule,
1130                                  DBUS_TYPE_INVALID))
1131     {
1132       dbus_message_unref (msg);
1133       _DBUS_SET_OOM (error);
1134       return;
1135     }
1136
1137   send_no_return_values (connection, msg, error);
1138
1139   dbus_message_unref (msg);
1140 }
1141
1142 /**
1143  * Removes a previously-added match rule "by value" (the most
1144  * recently-added identical rule gets removed).  The "rule" argument
1145  * is the string form of a match rule.
1146  *
1147  * If you pass #NULL for the error, this function will not
1148  * block; otherwise it will. See detailed explanation in
1149  * docs for dbus_bus_add_match().
1150  *
1151  * @param connection connection to the message bus
1152  * @param rule textual form of match rule
1153  * @param error location to store any errors
1154  */
1155 void
1156 dbus_bus_remove_match (DBusConnection *connection,
1157                        const char     *rule,
1158                        DBusError      *error)
1159 {
1160   DBusMessage *msg;
1161
1162   _dbus_return_if_fail (rule != NULL);
1163
1164   msg = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
1165                                       DBUS_PATH_DBUS,
1166                                       DBUS_INTERFACE_DBUS,
1167                                       "RemoveMatch");
1168
1169   if (!dbus_message_append_args (msg, DBUS_TYPE_STRING, &rule,
1170                                  DBUS_TYPE_INVALID))
1171     {
1172       dbus_message_unref (msg);
1173       _DBUS_SET_OOM (error);
1174       return;
1175     }
1176
1177   send_no_return_values (connection, msg, error);
1178
1179   dbus_message_unref (msg);
1180 }
1181
1182 /** @} */