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