1 /* -*- mode: C; c-file-style: "gnu" -*- */
2 /* dbus-bus.c Convenience functions for communicating with the bus.
4 * Copyright (C) 2003 CodeFactory AB
5 * Copyright (C) 2003 Red Hat, Inc.
7 * Licensed under the Academic Free License version 1.2
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.
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.
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
26 #include "dbus-protocol.h"
27 #include "dbus-internals.h"
28 #include "dbus-message.h"
32 * @defgroup DBusBus Message bus APIs
34 * @brief Functions for communicating with the message bus
37 * @todo get rid of most of these; they should be done
38 * with DBusGProxy and the Qt equivalent, i.e. the same
39 * way any other interface would be used.
44 * @defgroup DBusBusInternals Message bus APIs internals
45 * @ingroup DBusInternals
46 * @brief Internals of functions for communicating with the message bus
52 * Block of message-bus-related data we attach to each
53 * #DBusConnection used with these convenience functions.
58 DBusConnection *connection; /**< Connection we're associated with */
59 char *base_service; /**< Base service name of this connection */
61 unsigned int is_well_known : 1; /**< Is one of the well-known connections in our global array */
64 /** The slot we have reserved to store BusData.
66 static dbus_int32_t bus_data_slot = -1;
68 /** Number of bus types */
71 static DBusConnection *bus_connections[N_BUS_TYPES];
72 static char *bus_connection_addresses[N_BUS_TYPES] = { NULL, NULL, NULL };
74 static DBusBusType activation_bus_type = DBUS_BUS_ACTIVATION;
76 static dbus_bool_t initialized = FALSE;
79 * Lock for globals in this file
81 _DBUS_DEFINE_GLOBAL_LOCK (bus);
84 addresses_shutdown_func (void *data)
89 while (i < N_BUS_TYPES)
91 if (bus_connections[i] != NULL)
92 _dbus_warn ("dbus_shutdown() called but connections were still live!");
94 dbus_free (bus_connection_addresses[i]);
95 bus_connection_addresses[i] = NULL;
99 activation_bus_type = DBUS_BUS_ACTIVATION;
103 get_from_env (char **connection_p,
108 _dbus_assert (*connection_p == NULL);
110 s = _dbus_getenv (env_var);
111 if (s == NULL || *s == '\0')
112 return TRUE; /* successfully didn't use the env var */
115 *connection_p = _dbus_strdup (s);
116 return *connection_p != NULL;
121 init_connections_unlocked (void)
129 while (i < N_BUS_TYPES)
131 bus_connections[i] = NULL;
135 /* Don't init these twice, we may run this code twice if
136 * init_connections_unlocked() fails midway through.
139 if (bus_connection_addresses[DBUS_BUS_SYSTEM] == NULL)
141 if (!get_from_env (&bus_connection_addresses[DBUS_BUS_SYSTEM],
142 "DBUS_SYSTEM_BUS_ADDRESS"))
145 if (bus_connection_addresses[DBUS_BUS_SYSTEM] == NULL)
147 /* Use default system bus address if none set in environment */
148 bus_connection_addresses[DBUS_BUS_SYSTEM] =
149 _dbus_strdup ("unix:path=" DBUS_SYSTEM_BUS_PATH);
150 if (bus_connection_addresses[DBUS_BUS_SYSTEM] == NULL)
155 if (bus_connection_addresses[DBUS_BUS_SESSION] == NULL)
157 if (!get_from_env (&bus_connection_addresses[DBUS_BUS_SESSION],
158 "DBUS_SESSION_BUS_ADDRESS"))
162 if (bus_connection_addresses[DBUS_BUS_ACTIVATION] == NULL)
164 if (!get_from_env (&bus_connection_addresses[DBUS_BUS_ACTIVATION],
165 "DBUS_ACTIVATION_ADDRESS"))
169 s = _dbus_getenv ("DBUS_ACTIVATION_BUS_TYPE");
173 if (strcmp (s, "system") == 0)
174 activation_bus_type = DBUS_BUS_SYSTEM;
175 else if (strcmp (s, "session") == 0)
176 activation_bus_type = DBUS_BUS_SESSION;
179 /* If we return FALSE we have to be sure that restarting
180 * the above code will work right
183 if (!_dbus_setenv ("DBUS_ACTIVATION_ADDRESS", NULL))
186 if (!_dbus_setenv ("DBUS_ACTIVATION_BUS_TYPE", NULL))
189 if (!_dbus_register_shutdown_func (addresses_shutdown_func,
200 bus_data_free (void *data)
204 if (bd->is_well_known)
208 /* We may be stored in more than one slot */
210 while (i < N_BUS_TYPES)
212 if (bus_connections[i] == bd->connection)
213 bus_connections[i] = NULL;
220 dbus_free (bd->base_service);
223 dbus_connection_free_data_slot (&bus_data_slot);
227 ensure_bus_data (DBusConnection *connection)
231 if (!dbus_connection_allocate_data_slot (&bus_data_slot))
234 bd = dbus_connection_get_data (connection, bus_data_slot);
237 bd = dbus_new0 (BusData, 1);
240 dbus_connection_free_data_slot (&bus_data_slot);
244 bd->connection = connection;
246 if (!dbus_connection_set_data (connection, bus_data_slot, bd,
250 dbus_connection_free_data_slot (&bus_data_slot);
254 /* Data slot refcount now held by the BusData */
258 dbus_connection_free_data_slot (&bus_data_slot);
264 /** @} */ /* end of implementation details docs */
267 * @addtogroup DBusBus
272 * Connects to a bus daemon and registers the client with it.
273 * If a connection to the bus already exists, then that connection is returned.
275 * @todo alex thinks we should nullify the connection when we get a disconnect-message.
277 * @param type bus type
278 * @param error address where an error can be returned.
279 * @returns a DBusConnection
282 dbus_bus_get (DBusBusType type,
286 DBusConnection *connection;
288 DBusBusType address_type;
290 _dbus_return_val_if_fail (type >= 0 && type < N_BUS_TYPES, NULL);
291 _dbus_return_val_if_error_is_set (error, NULL);
295 if (!init_connections_unlocked ())
298 dbus_set_error (error, DBUS_ERROR_NO_MEMORY, NULL);
302 /* We want to use the activation address even if the
303 * activating bus is the session or system bus,
308 /* Use the real type of the activation bus for getting its
309 * connection. (If the activating bus isn't a well-known
310 * bus then activation_bus_type == DBUS_BUS_ACTIVATION)
312 if (type == DBUS_BUS_ACTIVATION)
313 type = activation_bus_type;
315 if (bus_connections[type] != NULL)
317 connection = bus_connections[type];
318 dbus_connection_ref (connection);
324 address = bus_connection_addresses[address_type];
327 dbus_set_error (error, DBUS_ERROR_FAILED,
328 "Unable to determine the address of the message bus");
333 connection = dbus_connection_open (address, error);
337 _DBUS_ASSERT_ERROR_IS_SET (error);
342 /* By default we're bound to the lifecycle of
345 dbus_connection_set_exit_on_disconnect (connection,
348 if (!dbus_bus_register (connection, error))
350 _DBUS_ASSERT_ERROR_IS_SET (error);
351 dbus_connection_disconnect (connection);
352 dbus_connection_unref (connection);
358 bus_connections[type] = connection;
359 bd = ensure_bus_data (connection);
360 _dbus_assert (bd != NULL);
362 bd->is_well_known = TRUE;
370 * Registers a connection with the bus. This must be the first
371 * thing an application does when connecting to the message bus.
372 * If registration succeeds, the base service name will be set,
373 * and can be obtained using dbus_bus_get_base_service().
375 * @todo if we get an error reply, it has to be converted into
376 * DBusError and returned
378 * @param connection the connection
379 * @param error place to store errors
380 * @returns #TRUE on success
383 dbus_bus_register (DBusConnection *connection,
386 DBusMessage *message, *reply;
391 _dbus_return_val_if_fail (connection != NULL, FALSE);
392 _dbus_return_val_if_error_is_set (error, FALSE);
396 bd = ensure_bus_data (connection);
399 _DBUS_SET_OOM (error);
403 if (bd->base_service != NULL)
405 _dbus_warn ("Attempt to register the same DBusConnection with the message bus, but it is already registered\n");
406 /* This isn't an error, it's a programming bug. We'll be nice
407 * and not _dbus_assert_not_reached()
412 message = dbus_message_new_method_call (DBUS_SERVICE_ORG_FREEDESKTOP_DBUS,
413 DBUS_PATH_ORG_FREEDESKTOP_DBUS,
414 DBUS_INTERFACE_ORG_FREEDESKTOP_DBUS,
419 _DBUS_SET_OOM (error);
423 reply = dbus_connection_send_with_reply_and_block (connection, message, -1, error);
425 dbus_message_unref (message);
429 else if (dbus_set_error_from_message (error, reply))
431 else if (!dbus_message_get_args (reply, error,
432 DBUS_TYPE_STRING, &name,
436 bd->base_service = name;
442 dbus_message_unref (reply);
445 _DBUS_ASSERT_ERROR_IS_SET (error);
452 * Sets the base service name of the connection.
453 * Can only be used if you registered with the
454 * bus manually (i.e. if you did not call
455 * dbus_bus_register()). Can only be called
456 * once per connection.
458 * @param connection the connection
459 * @param base_service the base service name
460 * @returns #FALSE if not enough memory
463 dbus_bus_set_base_service (DBusConnection *connection,
464 const char *base_service)
468 _dbus_return_val_if_fail (connection != NULL, FALSE);
469 _dbus_return_val_if_fail (base_service != NULL, FALSE);
471 bd = ensure_bus_data (connection);
475 _dbus_assert (bd->base_service == NULL);
477 bd->base_service = _dbus_strdup (base_service);
478 return bd->base_service != NULL;
482 * Gets the base service name of the connection.
483 * Only possible after the connection has been registered
484 * with the message bus.
486 * @param connection the connection
487 * @returns the base service name
490 dbus_bus_get_base_service (DBusConnection *connection)
494 _dbus_return_val_if_fail (connection != NULL, NULL);
496 bd = ensure_bus_data (connection);
500 return bd->base_service;
504 * Asks the bus to try to acquire a certain service.
506 * @todo these docs are not complete, need to document the
507 * return value and flags
509 * @todo if we get an error reply, it has to be converted into
510 * DBusError and returned
512 * @param connection the connection
513 * @param service_name the service name
515 * @param error location to store the error
516 * @returns a result code, -1 if error is set
519 dbus_bus_acquire_service (DBusConnection *connection,
520 const char *service_name,
524 DBusMessage *message, *reply;
525 dbus_uint32_t service_result;
527 _dbus_return_val_if_fail (connection != NULL, 0);
528 _dbus_return_val_if_fail (service_name != NULL, 0);
529 _dbus_return_val_if_error_is_set (error, 0);
531 message = dbus_message_new_method_call (DBUS_SERVICE_ORG_FREEDESKTOP_DBUS,
532 DBUS_PATH_ORG_FREEDESKTOP_DBUS,
533 DBUS_INTERFACE_ORG_FREEDESKTOP_DBUS,
538 _DBUS_SET_OOM (error);
542 if (!dbus_message_append_args (message,
543 DBUS_TYPE_STRING, service_name,
544 DBUS_TYPE_UINT32, flags,
547 dbus_message_unref (message);
548 _DBUS_SET_OOM (error);
552 reply = dbus_connection_send_with_reply_and_block (connection, message, -1,
555 dbus_message_unref (message);
559 _DBUS_ASSERT_ERROR_IS_SET (error);
563 if (dbus_set_error_from_message (error, reply))
565 _DBUS_ASSERT_ERROR_IS_SET (error);
566 dbus_message_unref (reply);
570 if (!dbus_message_get_args (reply, error,
571 DBUS_TYPE_UINT32, &service_result,
574 _DBUS_ASSERT_ERROR_IS_SET (error);
575 dbus_message_unref (reply);
579 dbus_message_unref (reply);
581 return service_result;
585 * Checks whether a certain service exists.
587 * @todo the SERVICE_EXISTS message should use BOOLEAN not UINT32
589 * @param connection the connection
590 * @param service_name the service name
591 * @param error location to store any errors
592 * @returns #TRUE if the service exists, #FALSE if not or on error
595 dbus_bus_service_exists (DBusConnection *connection,
596 const char *service_name,
599 DBusMessage *message, *reply;
602 _dbus_return_val_if_fail (connection != NULL, FALSE);
603 _dbus_return_val_if_fail (service_name != NULL, FALSE);
604 _dbus_return_val_if_error_is_set (error, FALSE);
606 message = dbus_message_new_method_call (DBUS_SERVICE_ORG_FREEDESKTOP_DBUS,
607 DBUS_PATH_ORG_FREEDESKTOP_DBUS,
608 DBUS_INTERFACE_ORG_FREEDESKTOP_DBUS,
612 _DBUS_SET_OOM (error);
616 if (!dbus_message_append_args (message,
617 DBUS_TYPE_STRING, service_name,
620 dbus_message_unref (message);
621 _DBUS_SET_OOM (error);
625 reply = dbus_connection_send_with_reply_and_block (connection, message, -1, error);
626 dbus_message_unref (message);
630 _DBUS_ASSERT_ERROR_IS_SET (error);
634 if (!dbus_message_get_args (reply, error,
635 DBUS_TYPE_UINT32, &exists,
638 _DBUS_ASSERT_ERROR_IS_SET (error);
642 return (exists != FALSE);
646 * Activates a given service
648 * @param connection the connection
649 * @param service_name the service name
650 * @param flags the flags
651 * @param result a place to store the result of the activation, which will
652 * be one of DBUS_ACTIVATION_REPLY_ACTIVATED or
653 * DBUS_ACTIVATION_REPLY_ALREADY_ACTIVE if successful. Pass NULL if you
654 * don't care about the result.
655 * @param error location to store any errors
656 * @returns #TRUE if the activation succeeded, #FALSE if not
658 * @todo document what the flags do
661 dbus_bus_activate_service (DBusConnection *connection,
662 const char *service_name,
664 dbus_uint32_t *result,
670 msg = dbus_message_new_method_call (DBUS_SERVICE_ORG_FREEDESKTOP_DBUS,
671 DBUS_PATH_ORG_FREEDESKTOP_DBUS,
672 DBUS_INTERFACE_ORG_FREEDESKTOP_DBUS,
675 if (!dbus_message_append_args (msg, DBUS_TYPE_STRING, service_name,
676 DBUS_TYPE_UINT32, flags, DBUS_TYPE_INVALID))
678 dbus_message_unref (msg);
679 _DBUS_SET_OOM (error);
683 reply = dbus_connection_send_with_reply_and_block (connection, msg,
685 dbus_message_unref (msg);
689 _DBUS_ASSERT_ERROR_IS_SET (error);
693 if (dbus_set_error_from_message (error, reply))
695 _DBUS_ASSERT_ERROR_IS_SET (error);
696 dbus_message_unref (reply);
700 if (result != NULL &&
701 !dbus_message_get_args (reply, error, DBUS_TYPE_UINT32,
702 result, DBUS_TYPE_INVALID))
704 _DBUS_ASSERT_ERROR_IS_SET (error);
705 dbus_message_unref (reply);
709 dbus_message_unref (reply);