-D-BUS is licensed to you under your choice of the Academic Free
+D-Bus is licensed to you under your choice of the Academic Free
License version 2.1, or the GNU General Public License version 2.
Both licenses are included here. Some of the standalone binaries are
under the GPL only; in particular, but not limited to,
+2006-08-03 John (J5) Palmieri <johnp@redhat.com>
+
+ * s/D-BUS/D-Bus/g
+
2006-08-03 John (J5) Palmieri <johnp@redhat.com>
* dbus/dbus-object-tree.c: Patch by Benjamin Otte
#---------------------------------------------------------------------------
# General configuration options
#---------------------------------------------------------------------------
-PROJECT_NAME = D-BUS
+PROJECT_NAME = D-Bus
PROJECT_NUMBER = @VERSION@
OUTPUT_DIRECTORY = doc/api
OUTPUT_LANGUAGE = English
Mailing list
===
-The D-BUS mailing list is message-bus-list@freedesktop.org; discussion
+The D-Bus mailing list is message-bus-list@freedesktop.org; discussion
of patches, etc. should go there.
Security
===
-Most of D-BUS is security sensitive. Guidelines related to that:
+Most of D-Bus is security sensitive. Guidelines related to that:
- avoid memcpy(), sprintf(), strlen(), snprintf, strlcat(),
strstr(), strtok(), or any of this stuff. Use DBusString.
Making a release
===
-To make a release of D-BUS, do the following:
+To make a release of D-Bus, do the following:
- check out a fresh copy from CVS
Environment variables
===
-These are the environment variables that are used by the D-BUS client library
+These are the environment variables that are used by the D-Bus client library
DBUS_VERBOSE=1
-Turns on printing verbose messages. This only works if D-BUS has been
+Turns on printing verbose messages. This only works if D-Bus has been
compiled with --enable-verbose-mode
DBUS_MALLOC_FAIL_NTH=n
Can be set to a number, causing every nth call to dbus_alloc or
-dbus_realloc to fail. This only works if D-BUS has been compiled with
+dbus_realloc to fail. This only works if D-Bus has been compiled with
--enable-tests.
DBUS_MALLOC_FAIL_GREATER_THAN=n
Can be set to a number, causing every call to dbus_alloc or
dbus_realloc to fail if the number of bytes to be allocated is greater
-than the specified number. This only works if D-BUS has been compiled with
+than the specified number. This only works if D-Bus has been compiled with
--enable-tests.
DBUS_TEST_MALLOC_FAILURES=n
-Many of the D-BUS tests will run over and over, once for each malloc
+Many of the D-Bus tests will run over and over, once for each malloc
involved in the test. Each run will fail a different malloc, plus some
number of mallocs following that malloc (because a fair number of bugs
only happen if two or more mallocs fail in a row, e.g. error recovery
--enable-tests.
dbus/dbus-test
-This is the main unit test program that tests all aspects of the D-BUS
+This is the main unit test program that tests all aspects of the D-Bus
client library.
dbus/bus-test
.SH DESCRIPTION
-\fIdbus-daemon\fP is the D-BUS message bus daemon. See
+\fIdbus-daemon\fP is the D-Bus message bus daemon. See
http://www.freedesktop.org/software/dbus/ for more information about
-the big picture. D-BUS is first a library that provides one-to-one
+the big picture. D-Bus is first a library that provides one-to-one
communication between any two applications; \fIdbus-daemon\fP is an
application that uses this library to implement a message bus
daemon. Multiple programs connect to the message bus daemon and can
in any way).
.PP
-SIGHUP will cause the D-BUS daemon to PARTIALLY reload its
+SIGHUP will cause the D-Bus daemon to PARTIALLY reload its
configuration file and to flush its user/group information caches. Some
configuration changes would require kicking all apps off the bus; so they will
only take effect if you restart the daemon. Policy changes should take effect
doctype declaration:
.nf
- <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+ <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-Bus Bus Configuration 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
.fi
.PP
The well-known type of the message bus. Currently known values are
"system" and "session"; if other values are set, they should be
-either added to the D-BUS specification, or namespaced. The last
+either added to the D-Bus specification, or namespaced. The last
<type> element "wins" (previous values are ignored).
.PP
.PP
Add an address that the bus should listen on. The
-address is in the standard D-BUS format that contains
+address is in the standard D-Bus format that contains
a transport name plus possible parameters/options.
.PP
that class.
.PP
-D-BUS performs SELinux security checks in two places.
+D-Bus performs SELinux security checks in two places.
.PP
First, any time a message is routed from one connection to another
See http://www.freedesktop.org/software/dbus/doc/AUTHORS
.SH BUGS
-Please send bug reports to the D-BUS mailing list or bug tracker,
+Please send bug reports to the D-Bus mailing list or bug tracker,
see http://www.freedesktop.org/software/dbus/
static void
version (void)
{
- printf ("D-BUS Message Bus Daemon %s\n"
+ printf ("D-Bus Message Bus Daemon %s\n"
"Copyright (C) 2002, 2003 Red Hat, Inc., CodeFactory AB, and others\n"
"This is free software; see the source for copying conditions.\n"
"There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n",
/* -*- mode: C; c-file-style: "gnu" -*-
- * selinux.c SELinux security checks for D-BUS
+ * selinux.c SELinux security checks for D-Bus
*
* Author: Matthew Rickard <mjricka@epoch.ncsc.mil>
*
}
/**
- * Initialize the user space access vector cache (AVC) for D-BUS and set up
+ * Initialize the user space access vector cache (AVC) for D-Bus and set up
* logging callbacks.
*/
dbus_bool_t
}
/**
- * Get the SELinux policy root. This is used to find the D-BUS
+ * Get the SELinux policy root. This is used to find the D-Bus
* specific config file within the policy.
*/
const char *
Add a session-local.conf and edit that rather than changing this
file directly. -->
-<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-Bus Bus Configuration 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
<busconfig>
<!-- Our well-known bus type, don't change this -->
probably don't want to listen on any more addresses, add any more
auth mechanisms, run as a different user, etc. -->
-<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-Bus Bus Configuration 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
<busconfig>
AC_CHECK_LIB(selinux, is_selinux_enabled,
have_selinux=yes, have_selinux=no)
- # see if we have the SELinux header with the new D-BUS stuff in it
+ # see if we have the SELinux header with the new D-Bus stuff in it
if test x$have_selinux = xyes ; then
AC_MSG_CHECKING([for DBUS Flask permissions in selinux/av_permissions.h])
AC_TRY_COMPILE([#include <selinux/av_permissions.h>],
## on an abstract socket (so only root can create the socket)
DBUS_SYSTEM_BUS_DEFAULT_ADDRESS="unix:path=$DBUS_SYSTEM_SOCKET"
AC_SUBST(DBUS_SYSTEM_BUS_DEFAULT_ADDRESS)
-AC_DEFINE_UNQUOTED(DBUS_SYSTEM_BUS_DEFAULT_ADDRESS, "$DBUS_SYSTEM_BUS_DEFAULT_ADDRESS",[The default D-BUS address of the system bus])
+AC_DEFINE_UNQUOTED(DBUS_SYSTEM_BUS_DEFAULT_ADDRESS, "$DBUS_SYSTEM_BUS_DEFAULT_ADDRESS",[The default D-Bus address of the system bus])
#### Set up the pid file
if ! test -z "$with_system_pid_file"; then
dnl ==========================================================================
echo "
- D-BUS $VERSION
+ D-Bus $VERSION
==============
prefix: ${prefix}
echo "NOTE: building with assertions increases library size and decreases performance."
fi
if test x$enable_checks = xno; then
- echo "NOTE: building without checks for arguments passed to public API makes it harder to debug apps using D-BUS, but will slightly decrease D-BUS library size and _very_ slightly improve performance."
+ echo "NOTE: building without checks for arguments passed to public API makes it harder to debug apps using D-Bus, but will slightly decrease D-Bus library size and _very_ slightly improve performance."
fi
### source code that is generic utility functionality used
### by the bus daemon or test apps, but is NOT included
-### in the D-BUS client library (all symbols in here
+### in the D-Bus client library (all symbols in here
### should be underscore-prefixed but don't really need
### to be unless they move to DBUS_SHARED_SOURCES later)
DBUS_UTIL_SOURCES= \
/**
* @defgroup DBusAddressInternals Address parsing
* @ingroup DBusInternals
- * @brief Implementation of parsing addresses of D-BUS servers.
+ * @brief Implementation of parsing addresses of D-Bus servers.
*
* @{
*/
/**
* @defgroup DBusAddress Address parsing
* @ingroup DBus
- * @brief Parsing addresses of D-BUS servers.
+ * @brief Parsing addresses of D-Bus servers.
*
* @{
*/
/**
* Appends an escaped version of one string to another string,
- * using the D-BUS address escaping mechanism
+ * using the D-Bus address escaping mechanism
*
* @param escaped the string to append to
* @param unescaped the string to escape
if ((p + 2) > end)
{
dbus_set_error (error, DBUS_ERROR_BAD_ADDRESS,
- "In D-BUS address, percent character was not followed by two hex digits");
+ "In D-Bus address, percent character was not followed by two hex digits");
goto out;
}
if (hex_end != 2)
{
dbus_set_error (error, DBUS_ERROR_BAD_ADDRESS,
- "In D-BUS address, percent character was followed by characters other than hex digits");
+ "In D-Bus address, percent character was followed by characters other than hex digits");
goto out;
}
}
{
/* Error, should have been escaped */
dbus_set_error (error, DBUS_ERROR_BAD_ADDRESS,
- "In D-BUS address, character '%c' should have been escaped\n",
+ "In D-Bus address, character '%c' should have been escaped\n",
*p);
goto out;
}
*
* method:key=value,key=value;method:key=value
*
- * See the D-BUS specification for complete docs on the format.
+ * See the D-Bus specification for complete docs on the format.
*
* @param address the address.
* @param entry return location to an array of entries.
/**
* Escapes the given string as a value in a key=value pair
- * for a D-BUS address.
+ * for a D-Bus address.
*
* @param value the unescaped value
* @returns newly-allocated escaped value or #NULL if no memory
/**
* Unescapes the given string as a value in a key=value pair
- * for a D-BUS address.
+ * for a D-Bus address.
*
* @param value the escaped value
* @param error error to set if the unescaping fails
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-auth-script.c Test DBusAuth using a special script file (internal to D-BUS implementation)
+/* dbus-auth-script.c Test DBusAuth using a special script file (internal to D-Bus implementation)
*
* Copyright (C) 2003 Red Hat, Inc.
*
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-auth-script.h Test DBusAuth using a special script file (internal to D-BUS implementation)
+/* dbus-auth-script.h Test DBusAuth using a special script file (internal to D-Bus implementation)
*
* Copyright (C) 2003 Red Hat, Inc.
*
/**
* Asks the bus to assign the given name to this connection by invoking
* the RequestName method on the bus. This method is fully documented
- * in the D-BUS specification. For quick reference, the flags and
+ * in the D-Bus specification. For quick reference, the flags and
* result codes are discussed here, but the specification is the
* canonical version of this information.
*
/**
* Asks the bus to unassign the given name to this connection by invoking
* the ReleaseName method on the bus. This method is fully documented
- * in the D-BUS specification.
+ * in the D-Bus specification.
*
* @param connection the connection
* @param name the name to remove
* but that would require blocking always to determine
* the return value.
*
- * The AddMatch method is fully documented in the D-BUS
+ * The AddMatch method is fully documented in the D-Bus
* specification. For quick reference, the format of the
* match rules is discussed here, but the specification
* is the canonical version of this information.
* dbus_connection_set_dispatch_status_function() allows
* you to set a function to be used to monitor the dispatch status.
*
- * If you're using GLib or Qt add-on libraries for D-BUS, there are
+ * If you're using GLib or Qt add-on libraries for D-Bus, there are
* special convenience APIs in those libraries that hide
* all the details of dispatch and watch/timeout monitoring.
* For example, dbus_connection_setup_with_g_main().
* Types and functions related to reporting errors.
*
*
- * In essence D-BUS error reporting works as follows:
+ * In essence D-Bus error reporting works as follows:
*
* @code
* DBusError error;
* }
* @endcode
*
- * There are some rules. An error passed to a D-BUS function must
+ * There are some rules. An error passed to a D-Bus function must
* always be unset; you can't pass in an error that's already set. If
* a function has a return code indicating whether an error occurred,
* and also a #DBusError parameter, then the error will always be set
* Assigns an error name and message to a DBusError. Does nothing if
* error is #NULL. The message may be NULL, which means a default
* message will be deduced from the name. If the error name is unknown
- * to D-BUS the default message will be totally useless, though.
+ * to D-Bus the default message will be totally useless, though.
*
* @param error the error.
* @param name the error name (not copied!!!)
* Does nothing if error is #NULL.
*
* The format may be NULL, which means a default message will be
- * deduced from the name. If the error name is unknown to D-BUS the
+ * deduced from the name. If the error name is unknown to D-Bus the
* default message will be totally useless, though.
*
* If no memory can be allocated for the error message,
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-hash.c Generic hash table utility (internal to D-BUS implementation)
+/* dbus-hash.c Generic hash table utility (internal to D-Bus implementation)
*
* Copyright (C) 2002 Red Hat, Inc.
* Copyright (c) 1991-1993 The Regents of the University of California.
*
* Hash table implementation based on generic/tclHash.c from the Tcl
* source code. The original Tcl license applies to portions of the
- * code from tclHash.c; the Tcl license follows this standad D-BUS
+ * code from tclHash.c; the Tcl license follows this standad D-Bus
* license information.
*
* Licensed under the Academic Free License version 2.1
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-hash.h Generic hash table utility (internal to D-BUS implementation)
+/* dbus-hash.h Generic hash table utility (internal to D-Bus implementation)
*
* Copyright (C) 2002 Red Hat, Inc.
*
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-internals.c random utility stuff (internal to D-BUS implementation)
+/* dbus-internals.c random utility stuff (internal to D-Bus implementation)
*
* Copyright (C) 2002, 2003 Red Hat, Inc.
*
#include <stdlib.h>
/**
- * @defgroup DBusInternals D-BUS internal implementation details
- * @brief Documentation useful when developing or debugging D-BUS itself.
+ * @defgroup DBusInternals D-Bus internal implementation details
+ * @brief Documentation useful when developing or debugging D-Bus itself.
*
*/
/** String used in _dbus_return_if_fail macro */
const char _dbus_return_if_fail_warning_format[] =
"%lu: arguments to %s() were incorrect, assertion \"%s\" failed in file %s line %d.\n"
-"This is normally a bug in some application using the D-BUS library.\n";
+"This is normally a bug in some application using the D-Bus library.\n";
#endif
#ifndef DBUS_DISABLE_ASSERT
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-internals.h random utility stuff (internal to D-BUS implementation)
+/* dbus-internals.h random utility stuff (internal to D-Bus implementation)
*
* Copyright (C) 2002, 2003 Red Hat, Inc.
*
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-list.c Generic linked list utility (internal to D-BUS implementation)
+/* dbus-list.c Generic linked list utility (internal to D-Bus implementation)
*
* Copyright (C) 2002 Red Hat, Inc.
*
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-list.h Generic linked list utility (internal to D-BUS implementation)
+/* dbus-list.h Generic linked list utility (internal to D-Bus implementation)
*
* Copyright (C) 2002, 2003 Red Hat, Inc.
*
/**
* @def DBUS_BEGIN_DECLS
*
- * Macro used prior to declaring functions in the D-BUS header
+ * Macro used prior to declaring functions in the D-Bus header
* files. Expands to "extern "C"" when using a C++ compiler,
* and expands to nothing when using a C compiler.
*/
/**
* @def DBUS_END_DECLS
*
- * Macro used after declaring functions in the D-BUS header
+ * Macro used after declaring functions in the D-Bus header
* files. Expands to "}" when using a C++ compiler,
* and expands to nothing when using a C compiler.
*/
* type and value strings and set_basic would be a method on that
* object... this would also make DBusTypeReader the same thing as
* DBusTypeMark. But since DBusMessage is effectively that object for
- * D-BUS it doesn't seem worth creating some random object.)
+ * D-Bus it doesn't seem worth creating some random object.)
*
* @todo optimize this by only rewriting until the old and new values
* are at the same alignment. Frequently this should result in only
/**
* Initialize a write iterator, which is used to write out values in
- * serialized D-BUS format.
+ * serialized D-Bus format.
*
* The type_pos passed in is expected to be inside an already-valid,
* though potentially empty, type signature. This means that the byte
/**
* Checks that the given range of the string is a valid object path
- * name in the D-BUS protocol. Part of the validation ensures that
+ * name in the D-Bus protocol. Part of the validation ensures that
* the object path contains only ASCII.
*
* @todo this is inconsistent with most of DBusString in that
/**
* Checks that the given range of the string is a valid interface name
- * in the D-BUS protocol. This includes a length restriction and an
+ * in the D-Bus protocol. This includes a length restriction and an
* ASCII subset, see the specification.
*
* @todo this is inconsistent with most of DBusString in that
/**
* Checks that the given range of the string is a valid member name
- * in the D-BUS protocol. This includes a length restriction, etc.,
+ * in the D-Bus protocol. This includes a length restriction, etc.,
* see the specification.
*
* @todo this is inconsistent with most of DBusString in that
/**
* Checks that the given range of the string is a valid error name
- * in the D-BUS protocol. This includes a length restriction, etc.,
+ * in the D-Bus protocol. This includes a length restriction, etc.,
* see the specification.
*
* @todo this is inconsistent with most of DBusString in that
/**
* Checks that the given range of the string is a valid bus name in
- * the D-BUS protocol. This includes a length restriction, etc., see
+ * the D-Bus protocol. This includes a length restriction, etc., see
* the specification.
*
* @todo this is inconsistent with most of DBusString in that
/**
* Checks that the given range of the string is a valid message type
- * signature in the D-BUS protocol.
+ * signature in the D-Bus protocol.
*
* @todo this is inconsistent with most of DBusString in that
* it allows a start,len range that extends past the string end.
* The implementation of MD5 (see http://www.ietf.org/rfc/rfc1321.txt).
* This MD5 implementation was written by L. Peter Deutsch and
* is not derived from the RSA reference implementation in the
- * RFC. The version included in D-BUS comes from the Ghostscript
+ * RFC. The version included in D-Bus comes from the Ghostscript
* 7.05 distribution.
*
* @{
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-memory.c D-BUS memory handling
+/* dbus-memory.c D-Bus memory handling
*
* Copyright (C) 2002, 2003 Red Hat Inc.
*
*/
/**
- * The D-BUS library keeps some internal global variables, for example
+ * The D-Bus library keeps some internal global variables, for example
* to cache the username of the current process. This function is
* used to free these global variables. It is really useful only for
* leak-checking cleanliness and the like. WARNING: this function is
* NOT thread safe, it must be called while NO other threads are using
- * D-BUS. You cannot continue using D-BUS after calling this function,
+ * D-Bus. You cannot continue using D-Bus after calling this function,
* as it does things like free global mutexes created by
- * dbus_threads_init(). To use a D-BUS function after calling
+ * dbus_threads_init(). To use a D-Bus function after calling
* dbus_shutdown(), you have to start over from scratch, e.g. calling
* dbus_threads_init() again.
*/
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-memory.h D-BUS memory handling
+/* dbus-memory.h D-Bus memory handling
*
* Copyright (C) 2002 Red Hat Inc.
*
* Constructs a new message to invoke a method on a remote
* object. Returns #NULL if memory can't be allocated for the
* message. The destination may be #NULL in which case no destination
- * is set; this is appropriate when using D-BUS in a peer-to-peer
+ * is set; this is appropriate when using D-Bus in a peer-to-peer
* context (no message bus). The interface may be #NULL, which means
* that if multiple methods with the given name exist it is undefined
* which one will be invoked.
* interface and member fields. If the message is not
* #DBUS_MESSAGE_TYPE_METHOD_CALL, or has a different interface or
* member field, returns #FALSE. If the interface field is missing,
- * then it will be assumed equal to the provided interface. The D-BUS
+ * then it will be assumed equal to the provided interface. The D-Bus
* protocol allows method callers to leave out the interface name.
*
* @param message the message
/**
* Utility function to convert a machine-readable (not translated)
- * string into a D-BUS message type.
+ * string into a D-Bus message type.
*
* @code
* "method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
}
/**
- * Utility function to convert a D-BUS message type into a
+ * Utility function to convert a D-Bus message type into a
* machine-readable string (not translated).
*
* @code
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-server-protected.h Used by subclasses of DBusServer object (internal to D-BUS implementation)
+/* dbus-server-protected.h Used by subclasses of DBusServer object (internal to D-Bus implementation)
*
* Copyright (C) 2002 Red Hat Inc.
*
/**
* @defgroup DBusSignature Type signature parsing
* @ingroup DBus
- * @brief Parsing D-BUS type signatures
+ * @brief Parsing D-Bus type signatures
* @{
*/
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-signatures.h utility functions for D-BUS types
+/* dbus-signatures.h utility functions for D-Bus types
*
* Copyright (C) 2005 Red Hat Inc.
*
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-string-private.h String utility class (internal to D-BUS implementation)
+/* dbus-string-private.h String utility class (internal to D-Bus implementation)
*
* Copyright (C) 2002, 2003 Red Hat, Inc.
*
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-string.c String utility class (internal to D-BUS implementation)
+/* dbus-string.c String utility class (internal to D-Bus implementation)
*
* Copyright (C) 2002, 2003, 2004, 2005 Red Hat, Inc.
*
_dbus_assert (len >= 0);
/* we are doing _DBUS_UNLIKELY() here which might be
- * dubious in a generic library like GLib, but in D-BUS
+ * dubious in a generic library like GLib, but in D-Bus
* we know we're validating messages and that it would
* only be evil/broken apps that would have invalid
* UTF-8. Also, this function seems to be a performance
break;
/* Special-case ASCII; this makes us go a lot faster in
- * D-BUS profiles where we are typically validating
+ * D-Bus profiles where we are typically validating
* function names and such. We have to know that
* all following checks will pass for ASCII though,
* comments follow ...
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-string.h String utility class (internal to D-BUS implementation)
+/* dbus-string.h String utility class (internal to D-Bus implementation)
*
* Copyright (C) 2002, 2003 Red Hat, Inc.
*
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-sysdeps.c Wrappers around system/libc features (internal to D-BUS implementation)
+/* dbus-sysdeps.c Wrappers around system/libc features (internal to D-Bus implementation)
*
* Copyright (C) 2002, 2003 Red Hat, Inc.
* Copyright (C) 2003 CodeFactory AB
/**
* Sets the file descriptor to be close
* on exec. Should be called for all file
- * descriptors in D-BUS code.
+ * descriptors in D-Bus code.
*
* @param fd the file descriptor
*/
free (syms);
#else
- _dbus_verbose (" D-BUS not compiled with backtrace support\n");
+ _dbus_verbose (" D-Bus not compiled with backtrace support\n");
#endif
}
#endif /* asserts or tests enabled */
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-sysdeps.h Wrappers around system/libc features (internal to D-BUS implementation)
+/* dbus-sysdeps.h Wrappers around system/libc features (internal to D-Bus implementation)
*
* Copyright (C) 2002, 2003 Red Hat, Inc.
* Copyright (C) 2003 CodeFactory AB
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-threads-internal.h D-BUS thread primitives
+/* dbus-threads-internal.h D-Bus thread primitives
*
* Copyright (C) 2002, 2005 Red Hat Inc.
*
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-threads.h D-BUS threads handling
+/* dbus-threads.h D-Bus threads handling
*
* Copyright (C) 2002, 2003 Red Hat Inc.
*
/**
*
* Initializes threads. If this function is not called,
- * the D-BUS library will not lock any data structures.
- * If it is called, D-BUS will do locking, at some cost
+ * the D-Bus library will not lock any data structures.
+ * If it is called, D-Bus will do locking, at some cost
* in efficiency. Note that this function must be called
- * BEFORE using any other D-BUS functions.
+ * BEFORE using any other D-Bus functions.
*
* This function may be called more than once, as long
* as you pass in the same functions each time. If it's
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-threads.h D-BUS threads handling
+/* dbus-threads.h D-Bus threads handling
*
* Copyright (C) 2002 Red Hat Inc.
*
} DBusThreadFunctionsMask;
/**
- * Functions that must be implemented to make the D-BUS
+ * Functions that must be implemented to make the D-Bus
* library thread-aware.
*/
typedef struct
* Changes the timeout's enabled-ness. Note that you should use
* _dbus_connection_toggle_timeout_unlocked() etc. instead, if
* the timeout is passed out to an application main loop.
- * i.e. you can't use this function in the D-BUS library, it's
+ * i.e. you can't use this function in the D-Bus library, it's
* only used in the message bus daemon implementation.
*
* @param timeout the timeout
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-transport-protected.h Used by subclasses of DBusTransport object (internal to D-BUS implementation)
+/* dbus-transport-protected.h Used by subclasses of DBusTransport object (internal to D-Bus implementation)
*
* Copyright (C) 2002, 2004 Red Hat Inc.
*
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-transport.c DBusTransport object (internal to D-BUS implementation)
+/* dbus-transport.c DBusTransport object (internal to D-Bus implementation)
*
* Copyright (C) 2002, 2003 Red Hat Inc.
*
/**
- * Called to notify the D-BUS library when a previously-added watch is
+ * Called to notify the D-Bus library when a previously-added watch is
* ready for reading or writing, or has an exception such as a hangup.
*
* If this function returns #FALSE, then the file descriptor may still
#define DBUS_INSIDE_DBUS_H 1
#ifndef DBUS_API_SUBJECT_TO_CHANGE
-#error "Please define DBUS_API_SUBJECT_TO_CHANGE to acknowledge your understanding that D-BUS hasn't reached 1.0 and is subject to protocol and API churn. See the README for a full explanation."
+#error "Please define DBUS_API_SUBJECT_TO_CHANGE to acknowledge your understanding that D-Bus hasn't reached 1.0 and is subject to protocol and API churn. See the README for a full explanation."
#endif
#include <dbus/dbus-arch-deps.h>
#undef DBUS_INSIDE_DBUS_H
/**
- * @defgroup DBus D-BUS low-level public API
- * @brief The low-level public API of the D-BUS library
+ * @defgroup DBus D-Bus low-level public API
+ * @brief The low-level public API of the D-Bus library
*
* libdbus provides a low-level API intended primarily for use by
- * bindings to specific object systems and languages. D-BUS is most
+ * bindings to specific object systems and languages. D-Bus is most
* convenient when used with the GLib bindings, Python bindings, Qt
* bindings, Mono bindings, and so forth. This low-level API has a
* lot of complexity useful only for bindings.
<article id="index">
<articleinfo>
- <title>D-BUS FAQ</title>
+ <title>D-Bus FAQ</title>
<releaseinfo>Version 0.1</releaseinfo>
<date>22 January 2005</date>
<authorgroup>
<qandaentry>
<question>
<para>
- What is D-BUS?
+ What is D-Bus?
</para>
</question>
<answer>
<para>
- This is probably best answered by reading the D-B
US <ulink url="dbus-tutorial.html">tutorial</ulink>. In
+ This is probably best answered by reading the D-B
us <ulink url="dbus-tutorial.html">tutorial</ulink>. In
short, it is a system consisting of 1) a wire protocol for exposing a
typical object-oriented language/framework to other applications; and
2) a bus daemon that allows applications to find and monitor one another.
<qandaentry>
<question>
<para>
- Is D-BUS stable/finished?
+ Is D-Bus stable/finished?
</para>
</question>
<answer>
<para>
- D-B
US has not yet reached 1.0. The <ulink url="README">README</ulink>
+ D-B
us has not yet reached 1.0. The <ulink url="README">README</ulink>
file has a discussion of the API/ABI stability guarantees before and
after 1.0. In short, there are no guarantees before 1.0, and stability
of both protocol and reference library will be maintained after 1.0.
as well. The AFL is an "X-style" or "BSD-style" license compatible
with proprietary licensing, but it does have some requirements; in
particular it prohibits you from filing a lawsuit alleging that the
- D-BUS software infringes your patents <emphasis>while you continue to
- use D-BUS</emphasis>. If you're going to sue, you have to stop using
+ D-Bus software infringes your patents <emphasis>while you continue to
+ use D-Bus</emphasis>. If you're going to sue, you have to stop using
the software. Read the licenses to determine their meaning, this FAQ
entry is not intended to change the meaning or terms of the licenses.
</para>
<qandaentry id="components">
<question>
<para>
- Is D-BUS a "component system"?
+ Is D-Bus a "component system"?
</para>
</question>
<answer>
<para>
- D-BUS is not a component system. "Component system" was originally
+ D-Bus is not a component system. "Component system" was originally
defined by COM, and was essentially a workaround for the limitations
of the C++ object system (adding introspection, runtime location of
objects, ABI guarantees, and so forth). With the C# language and CLR,
</para>
<para>
A third, orthogonal feature is interprocess communication or IPC.
- D-BUS is an IPC system. Given an object (or "component" if you must),
+ D-Bus is an IPC system. Given an object (or "component" if you must),
you can expose the functionality of that object over an IPC system.
- Examples of IPC systems are DCOM, CORBA, SOAP, XML-RPC, and D-BUS.
+ Examples of IPC systems are DCOM, CORBA, SOAP, XML-RPC, and D-Bus.
You can use any of these IPC systems with any object/component system,
though some of them are "tuned" for specific object systems.
You can think of an IPC system primarily as a wire protocol.
<qandaentry id="speed">
<question>
<para>
- How fast is the D-BUS reference implementation?
+ How fast is the D-Bus reference implementation?
</para>
</question>
<answer>
Of course it depends a bit on what you're doing.
<ulink url="http://lists.freedesktop.org/pipermail/dbus/2004-November/001779.html">
This mail</ulink> contains some benchmarking. At the time of that
- benchmark, D-BUS one-to-one communication was about 2.5x slower than
+ benchmark, D-Bus one-to-one communication was about 2.5x slower than
simply pushing the data raw over a socket. After the recent rewrite of
- the marshaling code, D-BUS is slower than that because a lot of
+ the marshaling code, D-Bus is slower than that because a lot of
optimization work was lost. But it can probably be sped up again.
</para>
<para>
- D-BUS communication with the intermediate bus daemon should be
+ D-Bus communication with the intermediate bus daemon should be
(and as last profiled, was) about twice as slow as one-to-one
mode, because a round trip involves four socket reads/writes rather
than two socket reads/writes.
not a good idea all things considered.
</para>
<para>
- Raw bandwidth isn't the only concern; D-BUS is designed to
+ Raw bandwidth isn't the only concern; D-Bus is designed to
enable asynchronous communication and avoid round trips.
This is frequently a more important performance issue
than throughput.
<qandaentry id="size">
<question>
<para>
- How large is the D-BUS reference implementation?
+ How large is the D-Bus reference implementation?
</para>
</question>
<answer>
<qandaentry id="other-ipc">
<question>
<para>
- How does D-BUS differ from other interprocess communication
+ How does D-Bus differ from other interprocess communication
or networking protocols?
</para>
</question>
<answer>
<para>
- The best place to start is to read the D-B
US <ulink url="dbus-tutorial.html">tutorial</ulink>, so
- you have a concrete idea what D-BUS actually is. If you
+ The best place to start is to read the D-B
us <ulink url="dbus-tutorial.html">tutorial</ulink>, so
+ you have a concrete idea what D-Bus actually is. If you
understand other protocols on a wire format level, you
- may also want to read the D-B
US <ulink url="dbus-specification.html">specification</ulink> to see what
- D-BUS looks like on a low level.
+ may also want to read the D-B
us <ulink url="dbus-specification.html">specification</ulink> to see what
+ D-Bus looks like on a low level.
</para>
<para>
- As the <ulink url="dbus-tutorial.html">tutorial</ulink> and <ulink url="dbus-specification.html">specification</ulink> both explain, D-BUS is tuned
+ As the <ulink url="dbus-tutorial.html">tutorial</ulink> and <ulink url="dbus-specification.html">specification</ulink> both explain, D-Bus is tuned
for some specific use cases. Thus, it probably isn't tuned
for what you want to do, unless you are doing the things
- D-BUS was designed for. Don't make the mistake of thinking
+ D-Bus was designed for. Don't make the mistake of thinking
that any system labeled "IPC" is the same thing.
</para>
<para>
- The D-BUS authors would not recommend using D-BUS
+ The D-Bus authors would not recommend using D-Bus
for applications where it doesn't make sense.
- The following questions compare D-BUS to some other
- protocols primarily to help you understand D-BUS
- and decide whether it's appropriate; D-BUS is neither intended
+ The following questions compare D-Bus to some other
+ protocols primarily to help you understand D-Bus
+ and decide whether it's appropriate; D-Bus is neither intended
nor claimed to be the right choice for every application.
</para>
<para>
- It should be possible to bridge D-BUS to other IPC systems,
- just as D-BUS can be bridged to object systems.
+ It should be possible to bridge D-Bus to other IPC systems,
+ just as D-Bus can be bridged to object systems.
</para>
<para>
- Note: the D-BUS mailing list subscribers are <emphasis>very much not
+ Note: the D-Bus mailing list subscribers are <emphasis>very much not
interested</emphasis> in debating which IPC system is the One True
System. So if you want to discuss that, please use another forum.
</para>
<qandaentry id="corba">
<question>
<para>
- How does D-BUS differ from CORBA?
+ How does D-Bus differ from CORBA?
</para>
</question>
<answer>
SOAP are the latest fad.
</para>
<para>
- Like D-BUS, CORBA uses a fast binary protocol (IIOP). Both systems
+ Like D-Bus, CORBA uses a fast binary protocol (IIOP). Both systems
work in terms of objects and methods, and have concepts such as
- "oneway" calls. Only D-BUS has direct support for "signals" as in
+ "oneway" calls. Only D-Bus has direct support for "signals" as in
GLib/Qt (or Java listeners, or C# delegates).
</para>
<para>
- D-BUS hardcodes and specifies a lot of things that CORBA leaves open-ended,
- because CORBA is more generic and D-BUS has two specific use-cases in mind.
- This makes D-BUS a bit simpler.
+ D-Bus hardcodes and specifies a lot of things that CORBA leaves open-ended,
+ because CORBA is more generic and D-Bus has two specific use-cases in mind.
+ This makes D-Bus a bit simpler.
</para>
<para>
- However, unlike CORBA D-BUS does <emphasis>not</emphasis> specify the
+ However, unlike CORBA D-Bus does <emphasis>not</emphasis> specify the
API for the language bindings. Instead, "native" bindings adapted
specifically to the conventions of a framework such as QObject,
GObject, C#, Java, Python, etc. are encouraged. The libdbus reference
</para>
<para>
Many CORBA implementations such as ORBit are faster than the libdbus
- reference implementation. One reason is that D-BUS considers data
+ reference implementation. One reason is that D-Bus considers data
from the other end of the connection to be untrusted and extensively
validates it. But generally speaking other priorities were placed
- ahead of raw speed in the libdbus implementation. A fast D-BUS
+ ahead of raw speed in the libdbus implementation. A fast D-Bus
implementation along the lines of ORBit should be possible, of course.
</para>
<para>
- On a more trivial note, D-BUS involves substantially fewer acronyms
+ On a more trivial note, D-Bus involves substantially fewer acronyms
than CORBA.
</para>
</answer>
<qandaentry id="xmlrpcsoap">
<question>
<para>
- How does D-BUS differ from XML-RPC and SOAP?
+ How does D-Bus differ from XML-RPC and SOAP?
</para>
</question>
<answer>
constant fine-grained IPC among applications in a desktop session.
</para>
<para>
- D-BUS offers persistent connections and with the bus daemon
+ D-Bus offers persistent connections and with the bus daemon
supports lifecycle tracking of other applications connected
to the bus. With XML-RPC and SOAP, typically each method call
exists in isolation and has its own HTTP connection.
<qandaentry id="dce">
<question>
<para>
- How does D-BUS differ from DCE?
+ How does D-Bus differ from DCE?
</para>
</question>
<answer>
has released an implementation as open source software</ulink>. DCE
is quite capable, and includes a vast amount of functionality such as
a distributed time service. As the name implies, DCE is intended for
- use in a large, multi-computer distributed application. D-BUS would
+ use in a large, multi-computer distributed application. D-Bus would
not be well-suited for this.
</para>
</answer>
<qandaentry id="dcom">
<question>
<para>
- How does D-BUS differ from DCOM and COM?
+ How does D-Bus differ from DCOM and COM?
</para>
</question>
<answer>
Start by reading <xref linkend="other-ipc"/>.
</para>
<para>
- Comparing D-BUS to COM is apples and oranges;
+ Comparing D-Bus to COM is apples and oranges;
see <xref linkend="components"/>.
</para>
<para>
<qandaentry id="internet-communications-engine">
<question>
<para>
- How does D-BUS differ from ZeroC's Internet Communications Engine (Ice)
+ How does D-Bus differ from ZeroC's Internet Communications Engine (Ice)
</para>
</question>
<answer>
<para>
The <ulink url="http://www.zeroc.com/ice.html"> Internet
Communications Engine (Ice)</ulink> is a powerful IPC mechanism more
- on the level of SOAP or CORBA than D-BUS. Ice has a "dual-license"
+ on the level of SOAP or CORBA than D-Bus. Ice has a "dual-license"
business around it; i.e. you can use it under the GPL, or pay for a
proprietary license.
</para>
<qandaentry id="inter-client-exchange">
<question>
<para>
- How does D-BUS differ from Inter-Client Exchange (ICE)?
+ How does D-Bus differ from Inter-Client Exchange (ICE)?
</para>
</question>
<answer>
</para>
<para>
ICE is a binary protocol designed for desktop use, and KDE's DCOP
- builds on ICE. ICE is substantially simpler than D-BUS (in contrast
+ builds on ICE. ICE is substantially simpler than D-Bus (in contrast
to most of the other IPC systems mentioned here, which are more
complex). ICE doesn't really define a mapping to objects and methods
(DCOP adds that layer). The reference implementation of ICE (libICE)
</para>
<para>
DCOP and XSMP are the only two widely-used applications of ICE,
- and both could in principle be replaced by D-BUS. (Though whether
+ and both could in principle be replaced by D-Bus. (Though whether
GNOME and KDE will bother is an open question.)
</para>
</answer>
<qandaentry id="dcop">
<question>
<para>
- How does D-BUS differ from DCOP?
+ How does D-Bus differ from DCOP?
</para>
</question>
<answer>
Start by reading <xref linkend="other-ipc"/>.
</para>
<para>
- D-B
US is intentionally pretty similar to <ulink
+ D-B
us is intentionally pretty similar to <ulink
url="http://developer.kde.org/documentation/library/kdeqt/dcop.html">DCOP</ulink>,
and can be thought of as a "DCOP the next generation" suitable for
sharing between the various open source desktop projects.
</para>
<para>
- D-BUS is a bit more complex than DCOP, though the Qt binding for D-BUS
+ D-Bus is a bit more complex than DCOP, though the Qt binding for D-Bus
should not be more complex for programmers. The additional complexity
- of D-BUS arises from its separation of object references vs. bus names
+ of D-Bus arises from its separation of object references vs. bus names
vs. interfaces as distinct concepts, and its support for one-to-one
connections in addition to connections over the bus. The libdbus
reference implementation has a lot of API to support multiple bindings
in order to support secure applications such as the systemwide bus.
</para>
<para>
- D-BUS is probably somewhat slower than DCOP due to data validation
+ D-Bus is probably somewhat slower than DCOP due to data validation
and more "layers" in the reference implementation. A comparison
hasn't been posted to the list though.
</para>
<para>
- At this time, KDE has not committed to using D-BUS, but there have
- been discussions of KDE bridging D-BUS and DCOP, or even changing
- DCOP's implementation to use D-BUS internally (so that GNOME and KDE
+ At this time, KDE has not committed to using D-Bus, but there have
+ been discussions of KDE bridging D-Bus and DCOP, or even changing
+ DCOP's implementation to use D-Bus internally (so that GNOME and KDE
would end up using exactly the same bus). See the KDE mailing list
archives for some of these discussions.
</para>
<qandaentry id="yet-more-ipc">
<question>
<para>
- How does D-BUS differ from [yet more IPC mechanisms]?
+ How does D-Bus differ from [yet more IPC mechanisms]?
</para>
</question>
<answer>
</para>
<para>
If you're writing a desktop application for UNIX,
- then D-BUS is of course our recommendation for
+ then D-Bus is of course our recommendation for
talking to other parts of the desktop session.
(With the caveat that you should use a stable release
- of D-BUS; until we reach 1.0, there isn't a stable release.)
+ of D-Bus; until we reach 1.0, there isn't a stable release.)
</para>
<para>
If you're doing something complicated such as clustering,
areas and you should ask someone else or try a search engine.
</para>
<para>
- Note: the D-BUS mailing list is probably not the place to
+ Note: the D-Bus mailing list is probably not the place to
discuss which system is appropriate for your application,
though you are welcome to ask specific questions about
- D-BUS <emphasis>after reading this FAQ, the tutorial, and
+ D-Bus <emphasis>after reading this FAQ, the tutorial, and
searching the list archives</emphasis>. The best way
to search the list archives is probably to use
an Internet engine such as Google. On Google,
</question>
<answer>
<para>
- The D-B
US <ulink url="http://dbus.freedesktop.org">web site</ulink>
+ The D-B
us <ulink url="http://dbus.freedesktop.org">web site</ulink>
has a link to the bug tracker, which is the best place to store
patches. You can also post them to the list, especially if you want
to discuss the patch or get feedback.
<article id="index">
<articleinfo>
- <title>D-BUS Specification</title>
+ <title>D-Bus Specification</title>
<releaseinfo>Version 0.11</releaseinfo>
<date>6 February 2005</date>
<authorgroup>
<sect1 id="introduction">
<title>Introduction</title>
<para>
- D-BUS is a system for low-latency, low-overhead, easy to use
+ D-Bus is a system for low-latency, low-overhead, easy to use
interprocess communication (IPC). In more detail:
<itemizedlist>
<listitem>
<para>
- D-BUS is <emphasis>low-latency</emphasis> because it is designed
+ D-Bus is <emphasis>low-latency</emphasis> because it is designed
to avoid round trips and allow asynchronous operation, much like
the X protocol.
</para>
</listitem>
<listitem>
<para>
- D-BUS is <emphasis>low-overhead</emphasis> because it uses a
+ D-Bus is <emphasis>low-overhead</emphasis> because it uses a
binary protocol, and does not have to convert to and from a text
- format such as XML. Because D-BUS is intended for potentially
+ format such as XML. Because D-Bus is intended for potentially
high-resolution same-machine IPC, not primarily for Internet IPC,
this is an interesting optimization.
</para>
</listitem>
<listitem>
<para>
- D-BUS is <emphasis>easy to use</emphasis> because it works in terms
+ D-Bus is <emphasis>easy to use</emphasis> because it works in terms
of <firstterm>messages</firstterm> rather than byte streams, and
- automatically handles a lot of the hard IPC issues. Also, the D-BUS
+ automatically handles a lot of the hard IPC issues. Also, the D-Bus
library is designed to be wrapped in a way that lets developers use
their framework's existing object/type system, rather than learning
a new one specifically for IPC.
</para>
<para>
- The base D-BUS protocol is a one-to-one (peer-to-peer or client-server)
+ The base D-Bus protocol is a one-to-one (peer-to-peer or client-server)
protocol, specified in <xref linkend="message-protocol"/>. That is, it is
a system for one application to talk to a single other
application. However, the primary intended application of the protocol is the
- D-BUS <firstterm>message bus</firstterm>, specified in <xref
+ D-Bus <firstterm>message bus</firstterm>, specified in <xref
linkend="message-bus"/>. The message bus is a special application that
accepts connections from multiple other applications, and forwards
messages among them.
</para>
<para>
- Uses of D-BUS include notification of system changes (notification of when
+ Uses of D-Bus include notification of system changes (notification of when
a camera is plugged in to a computer, or a new version of some software
has been installed), or desktop interoperability, for example a file
monitoring service or a configuration service.
</para>
<para>
- D-BUS is designed for two specific use cases:
+ D-Bus is designed for two specific use cases:
<itemizedlist>
<listitem>
<para>
</para>
</listitem>
</itemizedlist>
- D-BUS is not intended to be a generic IPC system for any possible
+ D-Bus is not intended to be a generic IPC system for any possible
application, and intentionally omits many features found in other
- IPC systems for this reason. D-BUS may turn out to be useful
+ IPC systems for this reason. D-Bus may turn out to be useful
in unanticipated applications, but future versions of this
spec and the reference implementation probably will not
incorporate features that interfere with the core use cases.
<title>Type Signatures</title>
<para>
- The D-BUS protocol does not include type tags in the marshaled data; a
+ The D-Bus protocol does not include type tags in the marshaled data; a
block of marshaled values must have a known <firstterm>type
signature</firstterm>. The type signature is made up of <firstterm>type
codes</firstterm>. A type code is an ASCII character representing the
</para>
<para>
- The <literal>STRUCT</literal> type code 'r' is not currently used in the D-BUS protocol,
+ The <literal>STRUCT</literal> type code 'r' is not currently used in the D-Bus protocol,
but is useful in code that implements the protocol. This type code
is specified to allow such code to interoperate in non-protocol contexts.
</para>
</para>
<para>
- The following table summarizes the D-BUS types.
+ The following table summarizes the D-Bus types.
<informaltable>
<tgroup cols="3">
<thead>
<para>
Given a type signature, a block of bytes can be converted into typed
values. This section describes the format of the block of bytes. Byte
- order and alignment issues are handled uniformly for all D-BUS types.
+ order and alignment issues are handled uniformly for all D-Bus types.
</para>
<para>
A block of bytes has an associated byte order. The byte order
- has to be discovered in some way; for D-BUS messages, the
+ has to be discovered in some way; for D-Bus messages, the
byte order is part of the message header as described in
<xref linkend="message-protocol-messages"/>. For now, assume
that the byte order is known to be either little endian or big
<para>
An object path is a name used to refer to an object instance.
- Conceptually, each participant in a D-BUS message exchange may have
+ Conceptually, each participant in a D-Bus message exchange may have
any number of object instances (think of C++ or Java objects) and each
such instance will have a path. Like a filesystem, the object
instances in an application form a hierarchical tree.
<entry>Major protocol version of the sending application. If
the major protocol version of the receiving application does not
match, the applications will not be able to communicate and the
- D-BUS connection must be disconnected. The major protocol
+ D-Bus connection must be disconnected. The major protocol
version for this version of the specification is 0.
FIXME this field is stupid and pointless to put in
every message.
<sect2 id="message-protocol-names">
<title>Valid Names</title>
<para>
- The various names in D-BUS messages have some restrictions.
+ The various names in D-Bus messages have some restrictions.
</para>
<para>
There is a <firstterm>maximum name length</firstterm>
<sect4 id="message-protocol-types-method-apis">
<title>Mapping method calls to native APIs</title>
<para>
- APIs for D-BUS may map method calls to a method call in a specific
+ APIs for D-Bus may map method calls to a method call in a specific
programming language, such as C++, or may map a method call written
- in an IDL to a D-BUS message.
+ in an IDL to a D-Bus message.
</para>
<para>
In APIs of this nature, arguments to a method are often termed "in"
(which implies sent in the <literal>METHOD_CALL</literal>), or "out" (which implies
returned in the <literal>METHOD_RETURN</literal>). Some APIs such as CORBA also have
"inout" arguments, which are both sent and received, i.e. the caller
- passes in a value which is modified. Mapped to D-BUS, an "inout"
+ passes in a value which is modified. Mapped to D-Bus, an "inout"
argument is equivalent to an "in" argument, followed by an "out"
argument. You can't pass things "by reference" over the wire, so
"inout" is purely an illusion of the in-process API.
exceptions.
</para>
<para>
- In converting from native APIs to D-BUS, it is perhaps nice to
- map D-BUS naming conventions ("FooBar") to native conventions
+ In converting from native APIs to D-Bus, it is perhaps nice to
+ map D-Bus naming conventions ("FooBar") to native conventions
such as "fooBar" or "foo_bar" automatically. This is OK
as long as you can say that the native API is one that
- was specifically written for D-BUS. It makes the most sense
+ was specifically written for D-Bus. It makes the most sense
when writing object implementations that will be exported
- over the bus. Object proxies used to invoke remote D-BUS
- objects probably need the ability to call any D-BUS method,
+ over the bus. Object proxies used to invoke remote D-Bus
+ objects probably need the ability to call any D-Bus method,
and thus a magic name mapping like this could be a problem.
</para>
<para>
<title>Invalid Protocol and Spec Extensions</title>
<para>
- For security reasons, the D-BUS protocol should be strictly parsed and
+ For security reasons, the D-Bus protocol should be strictly parsed and
validated, with the exception of defined extension points. Any invalid
protocol or spec violations should result in immediately dropping the
connection without notice to the other end. Exceptions should be
</para>
<para>
- The following extension points are built in to D-BUS on purpose and must
+ The following extension points are built in to D-Bus on purpose and must
not be treated as invalid protocol. The extension points are intended
for use by future versions of this spec, they are not intended for third
- parties. At the moment, the only way a third party could extend D-BUS
+ parties. At the moment, the only way a third party could extend D-Bus
without breaking interoperability would be to introduce a way to negotiate new
feature support as part of the auth protocol, using EXTENSION_-prefixed
commands. There is not yet a standard way to negotiate features.
<para>
The first octet received by the client after the \r\n of the OK
command must be the first octet of the authenticated/encrypted
- stream of D-BUS messages.
+ stream of D-Bus messages.
</para>
<para>
The first octet received by the server after the \r\n of the BEGIN
command from the client must be the first octet of the
- authenticated/encrypted stream of D-BUS messages.
+ authenticated/encrypted stream of D-Bus messages.
</para>
</sect2>
<sect2 id="auth-command-cancel">
<para>
The first octet received by the server after the \r\n of the BEGIN
command from the client must be the first octet of the
- authenticated/encrypted stream of D-BUS messages.
+ authenticated/encrypted stream of D-Bus messages.
</para>
</sect2>
<sect2 id="auth-command-rejected">
<title>OK Command</title>
<para>
The OK command indicates that the client has been authenticated,
- and that further communication will be a stream of D-BUS messages
+ and that further communication will be a stream of D-Bus messages
(optionally encrypted, as negotiated) rather than this protocol.
</para>
<para>
The first octet received by the client after the \r\n of the OK
command must be the first octet of the authenticated/encrypted
- stream of D-BUS messages.
+ stream of D-Bus messages.
</para>
<para>
The client must respond to the OK command by sending a BEGIN
if only canceling/rejecting the authentication.
</para>
<para>
- If the D-BUS protocol changes incompatibly at some future time,
+ If the D-Bus protocol changes incompatibly at some future time,
applications implementing the new protocol would probably be able to
check for support of the new protocol by sending a new command and
receiving an ERROR from applications that don't understand it. Thus the
ERROR feature of the auth protocol is an escape hatch that lets us
- negotiate extensions or changes to the D-BUS protocol in the future.
+ negotiate extensions or changes to the D-Bus protocol in the future.
</para>
</sect2>
<sect2 id="auth-examples">
<title>Authentication mechanisms</title>
<para>
This section describes some new authentication mechanisms.
- D-BUS also allows any standard SASL mechanism of course.
+ D-Bus also allows any standard SASL mechanism of course.
</para>
<sect3 id="auth-mechanisms-sha">
<title>DBUS_COOKIE_SHA1</title>
<title>Naming Conventions</title>
<para>
- D-BUS namespaces are all lowercase and correspond to reversed domain
+ D-Bus namespaces are all lowercase and correspond to reversed domain
names, as with Java. e.g. "org.freedesktop"
</para>
<para>
<para>
See <xref linkend="message-protocol-types-notation"/> for details on
the notation used in this section. There are some standard interfaces
- that may be useful across various D-BUS applications.
+ that may be useful across various D-Bus applications.
</para>
<sect2 id="standard-interfaces-peer">
<title><literal>org.freedesktop.DBus.Peer</literal></title>
<para>
The following table describes the keys that can be used to create
a match rule:
- The following table summarizes the D-BUS types.
+ The following table summarizes the D-Bus types.
<informaltable>
<tgroup cols="3">
<thead>
<firstterm>service</firstterm>.
</para>
<para>
- With D-BUS, starting a service is normally done by name. That is,
+ With D-Bus, starting a service is normally done by name. That is,
applications ask the message bus to start some program that will own a
well-known name, such as <literal>org.freedesktop.TextEditor</literal>.
This implies a contract documented along with the name
<literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
<footnote>
<para>
- The D-BUS reference implementation actually honors the
+ The D-Bus reference implementation actually honors the
<literal>$(localstatedir)</literal> configure option
for this address, on both client and server side.
</para>
<glossentry id="term-message"><glossterm>Message</glossterm>
<glossdef>
<para>
- A message is the atomic unit of communication via the D-BUS
+ A message is the atomic unit of communication via the D-Bus
protocol. It consists of a <firstterm>header</firstterm> and a
<firstterm>body</firstterm>; the body is made up of
<firstterm>arguments</firstterm>.
<para>
See <xref linkend="term-bus-name"/>. "Name" may
also be used to refer to some of the other names
- in D-BUS, such as interface names.
+ in D-Bus, such as interface names.
</para>
</glossdef>
</glossentry>
<para>
An application talking directly to another application, without going
through a message bus. One-to-one connections may be "peer to peer" or
- "client to server." The D-BUS protocol has no concept of client
+ "client to server." The D-Bus protocol has no concept of client
vs. server after a connection has authenticated; the flow of messages
is symmetrical (full duplex).
</para>
<glossentry id="term-path"><glossterm>Path</glossterm>
<glossdef>
<para>
- Object references (object names) in D-BUS are organized into a
+ Object references (object names) in D-Bus are organized into a
filesystem-style hierarchy, so each object is named by a path. As in
LDAP, there's no difference between "files" and "directories"; a path
can refer to an object, while still having child objects below it.
<article id="index">
<articleinfo>
- <title>D-BUS Test Plan</title>
+ <title>D-Bus Test Plan</title>
<date>14 February 2003</date>
<authorgroup>
<author>
<sect1 id="introduction">
<title>Introduction</title>
<para>
- This document tries to explain the details of the test plan for D-BUS
+ This document tries to explain the details of the test plan for D-Bus
</para>
<sect2 id="importance-of-testing">
<title>The importance of testing</title>
overall.
</para>
<para>
- D-BUS is a large and complex piece of software (about 25,000
+ D-Bus is a large and complex piece of software (about 25,000
lines of code for the client library, and 2,500 lines of code
for the bus daemon) and it's therefore important to try to make sure
that all parts of the software is functioning correctly.
</para>
<para>
- D-BUS can be built with support for testing by passing
+ D-Bus can be built with support for testing by passing
<literal>--enable-tests</literal>. to the configure script. It
is recommended that production systems build without testing
- since that reduces the D-BUS client library size.
+ since that reduces the D-Bus client library size.
</para>
</sect2>
</sect1>
<sect1 id="client-library">
- <title>Testing the D-BUS client library</title>
+ <title>Testing the D-Bus client library</title>
<para>
The tests for the client library consist of the dbus-test
program which is a unit test for all aspects of the client
<sect2 id="data-structures">
<title>Data Structures</title>
<para>
- The D-BUS client library consists of some data structures that
+ The D-Bus client library consists of some data structures that
are used internally; a linked list class, a hashtable class and
a string class. All aspects of those are tested by dbus-test.
</para>
<sect2 id="message-loader">
<title>Message loader</title>
<para>
- The message loader is the part of D-BUS that takes messages in
+ The message loader is the part of D-Bus that takes messages in
raw character form and parses them, turning them into DBusMessages.
</para>
<para>
- This is one of the parts of D-BUS that
+ This is one of the parts of D-Bus that
<emphasis>must</emphasis> be absolutely bug-free and
robust. The message loader should be able to handle invalid
and incomplete messages without crashing. Not doing so is a
- serious issue and can easily result in D-BUS being exploitable
+ serious issue and can easily result in D-Bus being exploitable
to DoS attacks.
</para>
<para>
</figure>
<para>
The file format of messages in string form is documented in
- the D-BUS Reference Manual.
+ the D-Bus Reference Manual.
</para>
<para>
The message test part of dbus-test is using the message
</sect2>
</sect1>
<sect1 id="daemon">
- <title>Testing the D-BUS bus daemon</title>
+ <title>Testing the D-Bus bus daemon</title>
<para>
- Since the D-BUS bus daemon is using the D-BUS client library it
+ Since the D-Bus bus daemon is using the D-Bus client library it
will benefit from all tests done on the client library, but
there is still the issue of testing client-server communication.
This is more complicated since it it may require another process
<sect2 id="debug-transport">
<title>The debug transport</title>
<para>
- In D-BUS, a <emphasis>transport</emphasis> is a class that
+ In D-Bus, a <emphasis>transport</emphasis> is a class that
handles sending and receiving raw data over a certain
- medium. The transport that is used most in D-BUS is the UNIX
+ medium. The transport that is used most in D-Bus is the UNIX
transport with sends and recevies data over a UNIX socket. A
transport that tunnels data through X11 client messages is
also under development.
</para>
<para>
- The D-BUS debug transport is a specialized transport that
+ The D-Bus debug transport is a specialized transport that
works in-process. This means that a client and server that
exists in the same process can talk to eachother without using
a socket.
<title>The bus-test program</title>
<para>
The bus-test program is a program that is used to test various
- parts of the D-BUS bus daemon; robustness and that it conforms
+ parts of the D-Bus bus daemon; robustness and that it conforms
to the specifications.
</para>
<para>
<sect2 id="oom-robustness">
<title>Out-Of-Memory robustness</title>
<para>
- Since D-BUS should be able to be used in embedded devices, and
+ Since D-Bus should be able to be used in embedded devices, and
also as a system service, it should be able to cope with
low-memory situations without exiting or crashing.
</para>
<article id="index">
<articleinfo>
- <title>D-BUS Tutorial</title>
+ <title>D-Bus Tutorial</title>
<releaseinfo>Version 0.4.1</releaseinfo>
<date>15 July 2005</date>
<authorgroup>
</articleinfo>
<sect1 id="whatis">
- <title>What is D-BUS?</title>
+ <title>What is D-Bus?</title>
<para>
- D-BUS is a system for <firstterm>interprocess communication</firstterm>
+ D-Bus is a system for <firstterm>interprocess communication</firstterm>
(IPC). Architecturally, it has several layers:
<itemizedlist>
application frameworks. For example, libdbus-glib and
libdbus-qt. There are also bindings to languages such as
Python. These wrapper libraries are the API most people should use,
- as they simplify the details of D-BUS programming. libdbus is
+ as they simplify the details of D-Bus programming. libdbus is
intended to be a low-level backend for the higher level bindings.
Much of the libdbus API is only useful for binding implementation.
</para>
</para>
<para>
- If you just want to use D-BUS and don't care how it works, jump directly
+ If you just want to use D-Bus and don't care how it works, jump directly
to <xref linkend="concepts"/>.
Otherwise, read on.
</para>
</para>
<sect2 id="uses">
- <title>D-BUS applications</title>
+ <title>D-Bus applications</title>
<para>
There are many, many technologies in the world that have "Inter-process
communication" or "networking" in their stated purpose: <ulink
url="http://www.zeroc.com/ice.html">Internet Communications Engine (ICE)</ulink>,
and probably hundreds more.
Each of these is tailored for particular kinds of application.
- D-BUS is designed for two specific cases:
+ D-Bus is designed for two specific cases:
<itemizedlist>
<listitem>
<para>
<para>
For the within-desktop-session use case, the GNOME and KDE desktops
have significant previous experience with different IPC solutions
- such as CORBA and DCOP. D-BUS is built on that experience and
+ such as CORBA and DCOP. D-Bus is built on that experience and
carefully tailored to meet the needs of these desktop projects
- in particular. D-BUS may or may not be appropriate for other
+ in particular. D-Bus may or may not be appropriate for other
applications; the FAQ has some comparisons to other IPC systems.
</para>
<para>
</blockquote>
</para>
<para>
- D-BUS may happen to be useful for purposes other than the one it was
+ D-Bus may happen to be useful for purposes other than the one it was
designed for. Its general properties that distinguish it from
other forms of IPC are:
<itemizedlist>
<title>Concepts</title>
<para>
Some basic concepts apply no matter what application framework you're
- using to write a D-BUS application. The exact code you write will be
+ using to write a D-Bus application. The exact code you write will be
different for GLib vs. Qt vs. Python applications, however.
</para>
<sect2 id="objects">
<title>Objects and Object Paths</title>
<para>
- Each application using D-BUS contains <firstterm>objects</firstterm>,
+ Each application using D-Bus contains <firstterm>objects</firstterm>,
which generally map to GObject, QObject, C++ objects, or Python objects
(but need not). An object is an <emphasis>instance</emphasis> rather
- than a type. When messages are received over a D-BUS connection, they
+ than a type. When messages are received over a D-Bus connection, they
are sent to a specific object, not to the application as a whole.
</para>
<para>
application, and thus can't be passed from one application to another.
</para>
<para>
- To solve this, D-BUS introduces a name for each object. The name
+ To solve this, D-Bus introduces a name for each object. The name
looks like a filesystem path, for example an object could be
named <literal>/org/kde/kspread/sheets/3/cells/4/5</literal>.
Human-readable paths are nice, but you are free to create an
<sect2 id="messages">
<title>Message Types</title>
<para>
- Messages are not all the same; in particular, D-BUS has
+ Messages are not all the same; in particular, D-Bus has
4 built-in message types:
<itemizedlist>
<listitem>
<para>
Object paths, interfaces, and messages exist on the level of
- libdbus and the D-BUS protocol; they are used even in the
+ libdbus and the D-Bus protocol; they are used even in the
1-to-1 case with no message bus involved.
</para>
<title>Addresses</title>
<para>
- Applications using D-BUS are either servers or clients. A server
+ Applications using D-Bus are either servers or clients. A server
listens for incoming connections; a client connects to a server. Once
the connection is established, it is a symmetric flow of messages; the
client-server distinction only matters when setting up the
</para>
<para>
- A D-BUS <firstterm>address</firstterm> specifies where a server will
+ A D-Bus <firstterm>address</firstterm> specifies where a server will
listen, and where a client will connect. For example, the address
<literal>unix:path=/tmp/abcdef</literal> specifies that the server will
listen on a UNIX domain socket at the path
<literal>/tmp/abcdef</literal> and the client will connect to that
socket. An address can also specify TCP/IP sockets, or any other
- transport defined in future iterations of the D-BUS specification.
+ transport defined in future iterations of the D-Bus specification.
</para>
<para>
- When using D-BUS with a message bus, the bus daemon is a server
+ When using D-Bus with a message bus, the bus daemon is a server
and all other applications are clients of the bus daemon.
libdbus automatically discovers the address of the per-session bus
daemon by reading an environment variable. It discovers the
</para>
<para>
- If you're using D-BUS without a bus daemon, it's up to you to
+ If you're using D-Bus without a bus daemon, it's up to you to
define which application will be the server and which will be
the client, and specify a mechanism for them to agree on
the server's address.
The interface is also optional, primarily for historical
reasons; DCOP does not require specifying the interface,
instead simply forbidding duplicate method names
- on the same object instance. D-BUS will thus let you
+ on the same object instance. D-Bus will thus let you
omit the interface, but if your method name is ambiguous
it is undefined which method will be invoked.
</para>
</para>
<sect2 id="glib-typemappings">
- <title>D-BUS - GLib type mappings</title>
+ <title>D-Bus - GLib type mappings</title>
<para>
- The heart of the GLib bindings for D-BUS is the mapping it
- provides between D-BUS "type signatures" and GLib types
- (<literal>GType</literal>). The D-BUS type system is composed of
+ The heart of the GLib bindings for D-Bus is the mapping it
+ provides between D-Bus "type signatures" and GLib types
+ (<literal>GType</literal>). The D-Bus type system is composed of
a number of "basic" types, along with several "container" types.
</para>
<sect3 id="glib-basic-typemappings">
<tgroup cols="4">
<thead>
<row>
- <entry>D-BUS basic type</entry>
+ <entry>D-Bus basic type</entry>
<entry>GType</entry>
<entry>Free function</entry>
<entry>Notes</entry>
<sect3 id="glib-container-typemappings">
<title>Container type mappings</title>
<para>
- The D-BUS type system also has a number of "container"
+ The D-Bus type system also has a number of "container"
types, such as <literal>DBUS_TYPE_ARRAY</literal> and
- <literal>DBUS_TYPE_STRUCT</literal>. The D-BUS type system
+ <literal>DBUS_TYPE_STRUCT</literal>. The D-Bus type system
is fully recursive, so one can for example have an array of
array of strings (i.e. type signature
<literal>aas</literal>).
"natural".
</para>
<para>
- First, D-BUS type signatures which have an "obvious"
+ First, D-Bus type signatures which have an "obvious"
corresponding built-in GLib type are mapped using that type:
<informaltable>
<tgroup cols="6">
<thead>
<row>
- <entry>D-BUS type signature</entry>
+ <entry>D-Bus type signature</entry>
<entry>Description</entry>
<entry>GType</entry>
<entry>C typedef</entry>
contained type. Why we need this we will see below.
</para>
<para>
- The approach taken is to create these types in the D-BUS GLib
- bindings; however, there is nothing D-BUS specific about them.
+ The approach taken is to create these types in the D-Bus GLib
+ bindings; however, there is nothing D-Bus specific about them.
In the future, we hope to include such "fundamental" types in GLib
itself.
<informaltable>
<tgroup cols="6">
<thead>
<row>
- <entry>D-BUS type signature</entry>
+ <entry>D-Bus type signature</entry>
<entry>Description</entry>
<entry>GType</entry>
<entry>C typedef</entry>
</informaltable>
</para>
<para>
- D-BUS also includes a special type DBUS_TYPE_DICT_ENTRY which
+ D-Bus also includes a special type DBUS_TYPE_DICT_ENTRY which
is only valid in arrays. It's intended to be mapped to a "dictionary"
type by bindings. The obvious GLib mapping here is GHashTable. Again,
however, there is no builtin <literal>GType</literal> for a GHashTable.
<tgroup cols="6">
<thead>
<row>
- <entry>D-BUS type signature</entry>
+ <entry>D-Bus type signature</entry>
<entry>Description</entry>
<entry>GType</entry>
<entry>C typedef</entry>
<sect3 id="glib-generic-typemappings">
<title>Arbitrarily recursive type mappings</title>
<para>
- Finally, it is possible users will want to write or invoke D-BUS
+ Finally, it is possible users will want to write or invoke D-Bus
methods which have arbitrarily complex type signatures not
directly supported by these bindings. For this case, we have a
<literal>DBusGValue</literal> which acts as a kind of special
</sect2>
<sect2 id="sample-program-1">
<title>A sample program</title>
- <para>Here is a D-BUS program using the GLib bindings.
+ <para>Here is a D-Bus program using the GLib bindings.
<programlisting>
int
main (int argc, char **argv)
<itemizedlist>
<listitem>
<para>
- An internal D-BUS error, such as an out-of-memory
+ An internal D-Bus error, such as an out-of-memory
condition, an I/O error, or a network timeout. Errors
- generated by the D-BUS library itself have the domain
+ generated by the D-Bus library itself have the domain
<literal>DBUS_GERROR</literal>, and a corresponding code
such as <literal>DBUS_GERROR_NO_MEMORY</literal>. It will
not be typical for applications to handle these errors
</listitem>
<listitem>
<para>
- A remote D-BUS exception, thrown by the peer, bus, or
- service. D-BUS remote exceptions have both a textual
+ A remote D-Bus exception, thrown by the peer, bus, or
+ service. D-Bus remote exceptions have both a textual
"name" and a "message". The GLib bindings store this
information in the <literal>GError</literal>, but some
special rules apply.
<sect1 id="glib-server">
<title>GLib API: Implementing Objects</title>
<para>
- At the moment, to expose a GObject via D-BUS, you must
+ At the moment, to expose a GObject via D-Bus, you must
write XML by hand which describes the methods exported
by the object. In the future, this manual step will
be obviated by the upcoming GLib introspection support.
</programlisting>
</para>
<para>
- This XML is in the same format as the D-BUS introspection XML
+ This XML is in the same format as the D-Bus introspection XML
format. Except we must include an "annotation" which give the C
symbols corresponding to the object implementation prefix
(<literal>my_object</literal>). In addition, if particular
<sect1 id="python-client">
<title>Python API: Using Remote Objects</title>
<para>
- The Python bindings provide a simple to use interface for talking over D-BUS.
- Where possible much of the inner-workings of D-BUS are hidden behind what looks
+ The Python bindings provide a simple to use interface for talking over D-Bus.
+ Where possible much of the inner-workings of D-Bus are hidden behind what looks
like normal Python objects.
</para>
<sect2 id="python-typemappings">
- <title>D-BUS - Python type mappings</title>
+ <title>D-Bus - Python type mappings</title>
<para>
- While python itself is a largely untyped language D-BUS provides a simple type system
+ While python itself is a largely untyped language D-Bus provides a simple type system
for talking with other languages which may be strongly typed. Python for the most part
tries automatically map python objects to types on the bus. It is none the less good to
know what the type mappings are so one can better utilize services over the bus.
<tgroup cols="3">
<thead>
<row>
- <entry>D-BUS basic type</entry>
+ <entry>D-Bus basic type</entry>
<entry>Python wrapper</entry>
<entry>Notes</entry>
</row>
<sect3 id="python-container-typemappings">
<title>Container type mappings</title>
<para>
- The D-BUS type system also has a number of "container"
+ The D-Bus type system also has a number of "container"
types, such as <literal>DBUS_TYPE_ARRAY</literal> and
- <literal>DBUS_TYPE_STRUCT</literal>. The D-BUS type system
+ <literal>DBUS_TYPE_STRUCT</literal>. The D-Bus type system
is fully recursive, so one can for example have an array of
array of strings (i.e. type signature
<literal>aas</literal>).
</para>
<para>
- D-BUS container types have native corresponding built-in Python types
+ D-Bus container types have native corresponding built-in Python types
so it is easy to use them.
<informaltable>
<tgroup cols="3">
<thead>
<row>
- <entry>D-BUS type</entry>
+ <entry>D-Bus type</entry>
<entry>Python type</entry>
<entry>Python wrapper</entry>
<entry>Notes</entry>
<entry><literal>dbus.Array</literal></entry>
<entry>Python lists, denoted by square brackets [], are converted into arrays and visa versa.
The one restriction is that when sending a Python list each element of the list must be of the same
- type. This is because D-BUS arrays can contain only one element type. Use Python tuples for mixed types.
+ type. This is because D-Bus arrays can contain only one element type. Use Python tuples for mixed types.
When using the wrapper you may also specify a type or signature of the elements contained in the Array.
This is manditory when passing an empty Array to a method on the bus because Python can not guess at the
<entry><literal>DICTIONARY</literal></entry>
<entry><literal>Python dictionary</literal></entry>
<entry><literal>dbus.Dictionary</literal></entry>
- <entry>D-BUS doesn't have an explicit dictionary type. Instead it uses LISTS of DICT_ENTRIES to
+ <entry>D-Bus doesn't have an explicit dictionary type. Instead it uses LISTS of DICT_ENTRIES to
represent a dictionary. A DICT_ENTRY is simply a two element struct containing a key/value pair.
Python dictionaries are automatically converted to a LIST of DICT_ENTRIES and visa versa.
</sect2>
<sect2 id="python-invoking-methods">
<title>Invoking Methods</title>
- <para>Here is a D-BUS program using the Python bindings to get a listing of all names on the session bus.
+ <para>Here is a D-Bus program using the Python bindings to get a listing of all names on the session bus.
<programlisting>
import dbus
This is all fine and good if all you want to do is call methods on the bus and then exit. In order to
do more complex things such as use a GUI or make asynchronous calls you will need a mainloop. You would use
asynchronous calls because in GUI applications it is very bad to block for any long period of time. This cause
- the GUI to seem to freeze. Since replies to D-BUS messages can take an indeterminate amount of time using async
+ the GUI to seem to freeze. Since replies to D-Bus messages can take an indeterminate amount of time using async
calls allows you to return control to the GUI while you wait for the reply. This is exceedingly easy to do in
Python. Here is an example using the GLib/GTK+ mainloop.
<programlisting>
<para>
You will also notice that I check the version of the dbus bindings before importing dbus.glib. In older versions
glib was the only available mainloop. As of version 0.41.0 we split out the glib dependency to allow for other mainloops
- to be implemented. Notice also the python binding version does not match up with the D-BUS version. Once we reach 1.0
- this should change with Python changes simply tracking the D-BUS changes.
+ to be implemented. Notice also the python binding version does not match up with the D-Bus version. Once we reach 1.0
+ this should change with Python changes simply tracking the D-Bus changes.
While the glib mainloop is the only mainloop currently implemented, integrating other mainloops should
be very easy to do. There are plans for creating a a generic mainloop to be the default for non gui programs.
</para>
<sidebar>
<title>Version Alert</title>
<para>
- The Python D-BUS bindings require version 2.4 or greater of Python when creating D-BUS objects.
+ The Python D-Bus bindings require version 2.4 or greater of Python when creating D-Bus objects.
</para>
</sidebar>
Notice the @ symbol on the line before the hello method. This is a new directive introduced in
Python 2.4. It is called a decorator and it "decorates" methods. All you have to know is that
it provides metadata that can then be used to alter the behavior of the method being decorated.
- In this case we are telling the bindings that the hello method should be exported as a D-BUS method
+ In this case we are telling the bindings that the hello method should be exported as a D-Bus method
over the bus.
</para>
</sidebar>
<sect2 id="python-inheriting-and-overriding">
<title>Inheriting from HelloWorldObject</title>
<para>
- One of the cool things you can do in Python is inherit from another D-BUS object. We use this trick in
+ One of the cool things you can do in Python is inherit from another D-Bus object. We use this trick in
the bindings to provide a default implementation for the org.freedesktop.DBus.Introspectable interface.
Let's inherit from the HelloWorldObject example above and overide the hello method to say goodbye.
<programlisting>
<sect2 id="python-conclusion">
<title>Conclusion</title>
<para>
- As you can see, using D-BUS from Python is an extremely easy proposition. Hopefully
+ As you can see, using D-Bus from Python is an extremely easy proposition. Hopefully
the tutorial has been helpful in getting you started. If you need anymore help please
feel free to post on the <ulink url="http://lists.freedesktop.org/mailman/listinfo/dbus/">mailing list</ulink>.
The Python bindings are still in a state of flux and there may be API changes in the future.
-<!-- DTD for D-BUS Introspection data -->
-<!-- (C) 2005-02-02 David A. Wheeler; released under the D-BUS licenses,
+<!-- DTD for D-Bus Introspection data -->
+<!-- (C) 2005-02-02 David A. Wheeler; released under the D-Bus licenses,
GNU GPL version 2 (or greater) and AFL 1.1 (or greater) -->
-<!-- see D-BUS specification for documentation -->
+<!-- see D-Bus specification for documentation -->
<!ELEMENT node (node|interface)*>
<!ATTLIST node name CDATA #IMPLIED>
.SH DESCRIPTION
The \fIdbus-cleanup-sockets\fP command cleans up sockets used for
-D-BUS connections. See http://www.freedesktop.org/software/dbus/ for
+D-Bus connections. See http://www.freedesktop.org/software/dbus/ for
more information about the big picture.
.PP
linc-cleanup-sockets written by Michael Meeks.
.SH BUGS
-Please send bug reports to the D-BUS mailing list or bug tracker,
+Please send bug reports to the D-Bus mailing list or bug tracker,
see http://www.freedesktop.org/software/dbus/
static void
version (void)
{
- printf ("D-BUS Socket Cleanup Utility %s\n"
+ printf ("D-Bus Socket Cleanup Utility %s\n"
"Copyright (C) 2003 Red Hat, Inc.\n"
"Copyright (C) 2002 Michael Meeks\n"
"This is free software; see the source for copying conditions.\n"
.PP
See http://www.freedesktop.org/software/dbus/ for more information
-about D-BUS. See also the man page for \fIdbus-daemon\fP.
+about D-Bus. See also the man page for \fIdbus-daemon\fP.
.PP
Here is an example of how to use \fIdbus-launch\fP with an
if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then
## if not found, launch a new one
eval `dbus-launch --sh-syntax --exit-with-session`
- echo "D-BUS per-session daemon address is: $DBUS_SESSION_BUS_ADDRESS"
+ echo "D-Bus per-session daemon address is: $DBUS_SESSION_BUS_ADDRESS"
fi
.fi
See http://www.freedesktop.org/software/dbus/doc/AUTHORS
.SH BUGS
-Please send bug reports to the D-BUS mailing list or bug tracker,
+Please send bug reports to the D-Bus mailing list or bug tracker,
see http://www.freedesktop.org/software/dbus/
static void
version (void)
{
- printf ("D-BUS Message Bus Launcher %s\n"
+ printf ("D-Bus Message Bus Launcher %s\n"
"Copyright (C) 2003 Red Hat, Inc.\n"
"This is free software; see the source for copying conditions.\n"
"There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n",
.SH DESCRIPTION
The \fIdbus-monitor\fP command is used to monitor messages going
-through a D-BUS message bus. See
+through a D-Bus message bus. See
http://www.freedesktop.org/software/dbus/ for more information about
the big picture.
dbus-monitor was written by Philip Blundell.
.SH BUGS
-Please send bug reports to the D-BUS mailing list or bug tracker,
+Please send bug reports to the D-Bus mailing list or bug tracker,
see http://www.freedesktop.org/software/dbus/
.SH DESCRIPTION
-The \fIdbus-send\fP command is used to send a message to a D-BUS message
+The \fIdbus-send\fP command is used to send a message to a D-Bus message
bus. See http://www.freedesktop.org/software/dbus/ for more
information about the big picture.
specified. Following arguments, if any, are the message contents
(message arguments). These are given as a type name, a colon, and
then the value of the argument. The possible type names are: string,
-int32, uint32, double, byte, boolean. (D-BUS supports more types than
+int32, uint32, double, byte, boolean. (D-Bus supports more types than
these, but \fIdbus-send\fP currently does not.)
.PP
dbus-send was written by Philip Blundell.
.SH BUGS
-Please send bug reports to the D-BUS mailing list or bug tracker,
+Please send bug reports to the D-Bus mailing list or bug tracker,
see http://www.freedesktop.org/software/dbus/
if (message == NULL)
{
- fprintf (stderr, "Couldn't allocate D-BUS message\n");
+ fprintf (stderr, "Couldn't allocate D-Bus message\n");
exit (1);
}
/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-viewer.c Graphical D-BUS frontend utility
+/* dbus-viewer.c Graphical D-Bus frontend utility
*
* Copyright (C) 2003 Red Hat, Inc.
*
w = g_new0 (TreeWindow, 1);
w->window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
- gtk_window_set_title (GTK_WINDOW (w->window), "D-BUS Viewer");
+ gtk_window_set_title (GTK_WINDOW (w->window), "D-Bus Viewer");
gtk_window_set_default_size (GTK_WINDOW (w->window), 400, 500);
g_signal_connect (w->window, "destroy", G_CALLBACK (window_closed_callback),
static void
version (void)
{
- printf ("D-BUS Message Bus Viewer %s\n"
+ printf ("D-Bus Message Bus Viewer %s\n"
"Copyright (C) 2003 Red Hat, Inc.\n"
"This is free software; see the source for copying conditions.\n"
"There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n",
projects / platform / upstream / dbus.git / commitdiff