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 if (!dbus_bus_register (connection, error))
344 _DBUS_ASSERT_ERROR_IS_SET (error);
345 dbus_connection_disconnect (connection);
346 dbus_connection_unref (connection);
352 bus_connections[type] = connection;
353 bd = ensure_bus_data (connection);
354 _dbus_assert (bd != NULL);
356 bd->is_well_known = TRUE;
364 * Registers a connection with the bus. This must be the first
365 * thing an application does when connecting to the message bus.
366 * If registration succeeds, the base service name will be set,
367 * and can be obtained using dbus_bus_get_base_service().
369 * @todo if we get an error reply, it has to be converted into
370 * DBusError and returned
372 * @param connection the connection
373 * @param error place to store errors
374 * @returns #TRUE on success
377 dbus_bus_register (DBusConnection *connection,
380 DBusMessage *message, *reply;
385 _dbus_return_val_if_fail (connection != NULL, FALSE);
386 _dbus_return_val_if_error_is_set (error, FALSE);
390 bd = ensure_bus_data (connection);
393 _DBUS_SET_OOM (error);
397 if (bd->base_service != NULL)
399 _dbus_warn ("Attempt to register the same DBusConnection with the message bus, but it is already registered\n");
400 /* This isn't an error, it's a programming bug. We'll be nice
401 * and not _dbus_assert_not_reached()
406 message = dbus_message_new_method_call (DBUS_SERVICE_ORG_FREEDESKTOP_DBUS,
407 DBUS_PATH_ORG_FREEDESKTOP_DBUS,
408 DBUS_INTERFACE_ORG_FREEDESKTOP_DBUS,
413 _DBUS_SET_OOM (error);
417 reply = dbus_connection_send_with_reply_and_block (connection, message, -1, error);
419 dbus_message_unref (message);
423 else if (dbus_set_error_from_message (error, reply))
425 else if (!dbus_message_get_args (reply, error,
426 DBUS_TYPE_STRING, &name,
430 bd->base_service = name;
436 dbus_message_unref (reply);
439 _DBUS_ASSERT_ERROR_IS_SET (error);
446 * Sets the base service name of the connection.
447 * Can only be used if you registered with the
448 * bus manually (i.e. if you did not call
449 * dbus_bus_register()). Can only be called
450 * once per connection.
452 * @param connection the connection
453 * @param base_service the base service name
454 * @returns #FALSE if not enough memory
457 dbus_bus_set_base_service (DBusConnection *connection,
458 const char *base_service)
462 _dbus_return_val_if_fail (connection != NULL, FALSE);
463 _dbus_return_val_if_fail (base_service != NULL, FALSE);
465 bd = ensure_bus_data (connection);
469 _dbus_assert (bd->base_service == NULL);
471 bd->base_service = _dbus_strdup (base_service);
472 return bd->base_service != NULL;
476 * Gets the base service name of the connection.
477 * Only possible after the connection has been registered
478 * with the message bus.
480 * @param connection the connection
481 * @returns the base service name
484 dbus_bus_get_base_service (DBusConnection *connection)
488 _dbus_return_val_if_fail (connection != NULL, NULL);
490 bd = ensure_bus_data (connection);
494 return bd->base_service;
498 * Asks the bus to try to acquire a certain service.
500 * @todo these docs are not complete, need to document the
501 * return value and flags
503 * @todo if we get an error reply, it has to be converted into
504 * DBusError and returned
506 * @param connection the connection
507 * @param service_name the service name
509 * @param error location to store the error
510 * @returns a result code, -1 if error is set
513 dbus_bus_acquire_service (DBusConnection *connection,
514 const char *service_name,
518 DBusMessage *message, *reply;
519 dbus_uint32_t service_result;
521 _dbus_return_val_if_fail (connection != NULL, 0);
522 _dbus_return_val_if_fail (service_name != NULL, 0);
523 _dbus_return_val_if_error_is_set (error, 0);
525 message = dbus_message_new_method_call (DBUS_SERVICE_ORG_FREEDESKTOP_DBUS,
526 DBUS_PATH_ORG_FREEDESKTOP_DBUS,
527 DBUS_INTERFACE_ORG_FREEDESKTOP_DBUS,
532 _DBUS_SET_OOM (error);
536 if (!dbus_message_append_args (message,
537 DBUS_TYPE_STRING, service_name,
538 DBUS_TYPE_UINT32, flags,
541 dbus_message_unref (message);
542 _DBUS_SET_OOM (error);
546 reply = dbus_connection_send_with_reply_and_block (connection, message, -1,
549 dbus_message_unref (message);
553 _DBUS_ASSERT_ERROR_IS_SET (error);
557 if (dbus_set_error_from_message (error, reply))
559 _DBUS_ASSERT_ERROR_IS_SET (error);
560 dbus_message_unref (reply);
564 if (!dbus_message_get_args (reply, error,
565 DBUS_TYPE_UINT32, &service_result,
568 _DBUS_ASSERT_ERROR_IS_SET (error);
569 dbus_message_unref (reply);
573 dbus_message_unref (reply);
575 return service_result;
579 * Checks whether a certain service exists.
581 * @todo the SERVICE_EXISTS message should use BOOLEAN not UINT32
583 * @param connection the connection
584 * @param service_name the service name
585 * @param error location to store any errors
586 * @returns #TRUE if the service exists, #FALSE if not or on error
589 dbus_bus_service_exists (DBusConnection *connection,
590 const char *service_name,
593 DBusMessage *message, *reply;
596 _dbus_return_val_if_fail (connection != NULL, FALSE);
597 _dbus_return_val_if_fail (service_name != NULL, FALSE);
598 _dbus_return_val_if_error_is_set (error, FALSE);
600 message = dbus_message_new_method_call (DBUS_SERVICE_ORG_FREEDESKTOP_DBUS,
601 DBUS_PATH_ORG_FREEDESKTOP_DBUS,
602 DBUS_INTERFACE_ORG_FREEDESKTOP_DBUS,
606 _DBUS_SET_OOM (error);
610 if (!dbus_message_append_args (message,
611 DBUS_TYPE_STRING, service_name,
614 dbus_message_unref (message);
615 _DBUS_SET_OOM (error);
619 reply = dbus_connection_send_with_reply_and_block (connection, message, -1, error);
620 dbus_message_unref (message);
624 _DBUS_ASSERT_ERROR_IS_SET (error);
628 if (!dbus_message_get_args (reply, error,
629 DBUS_TYPE_UINT32, &exists,
632 _DBUS_ASSERT_ERROR_IS_SET (error);
636 return (exists != FALSE);
640 * Activates a given service
642 * @param connection the connection
643 * @param service_name the service name
644 * @param flags the flags
645 * @param result a place to store the result of the activation, which will
646 * be one of DBUS_ACTIVATION_REPLY_ACTIVATED or
647 * DBUS_ACTIVATION_REPLY_ALREADY_ACTIVE if successful. Pass NULL if you
648 * don't care about the result.
649 * @param error location to store any errors
650 * @returns #TRUE if the activation succeeded, #FALSE if not
652 * @todo document what the flags do
655 dbus_bus_activate_service (DBusConnection *connection,
656 const char *service_name,
658 dbus_uint32_t *result,
664 msg = dbus_message_new_method_call (DBUS_SERVICE_ORG_FREEDESKTOP_DBUS,
665 DBUS_PATH_ORG_FREEDESKTOP_DBUS,
666 DBUS_INTERFACE_ORG_FREEDESKTOP_DBUS,
669 if (!dbus_message_append_args (msg, DBUS_TYPE_STRING, service_name,
670 DBUS_TYPE_UINT32, flags, DBUS_TYPE_INVALID))
672 dbus_message_unref (msg);
673 _DBUS_SET_OOM (error);
677 reply = dbus_connection_send_with_reply_and_block (connection, msg,
679 dbus_message_unref (msg);
683 _DBUS_ASSERT_ERROR_IS_SET (error);
687 if (dbus_set_error_from_message (error, reply))
689 _DBUS_ASSERT_ERROR_IS_SET (error);
690 dbus_message_unref (reply);
694 if (result != NULL &&
695 !dbus_message_get_args (reply, error, DBUS_TYPE_UINT32,
696 result, DBUS_TYPE_INVALID))
698 _DBUS_ASSERT_ERROR_IS_SET (error);
699 dbus_message_unref (reply);
703 dbus_message_unref (reply);