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