X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/7c82f3e23e37cc848a38b1f8be7149fd672a6393..c6046b94e58b33ddcfca8f6361ddaf780ba5cb18:/doc/misc/dbus.texi diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index dcf1b52186..204afe7056 100644 --- a/doc/misc/dbus.texi +++ b/doc/misc/dbus.texi @@ -9,8 +9,7 @@ @syncodeindex fn cp @copying -Copyright @copyright{} 2007, 2008, 2009, 2010, -2011 Free Software Foundation, Inc. +Copyright @copyright{} 2007-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -26,7 +25,7 @@ developing GNU and promoting software freedom.'' @end quotation @end copying -@dircategory Emacs +@dircategory Emacs lisp libraries @direntry * D-Bus: (dbus). Using D-Bus in Emacs. @end direntry @@ -133,14 +132,24 @@ There are several basic functions which inspect the buses for registered names. Internally they use the basic interface @samp{org.freedesktop.DBus}, which is supported by all objects of a bus. -@defun dbus-list-activatable-names -This function returns the D-Bus service names, which can be activated. -An activatable service is described in a service registration file. -Under GNU/Linux, such files are located at -@file{/usr/share/dbus-1/services/}. +@defun dbus-list-activatable-names &optional bus +This function returns the D-Bus service names, which can be activated +for @var{bus}. It must be either the symbol @code{:system} (the +default) or the symbol @code{:session}. An activatable service is +described in a service registration file. Under GNU/Linux, such files +are located at @file{/usr/share/dbus-1/system-services/} (for the +@code{:system} bus) or @file{/usr/share/dbus-1/services/}. An +activatable service is not necessarily registered at @var{bus} at already. The result is a list of strings, which is @code{nil} when there are no -activatable service names at all. +activatable service names at all. Example: + +@lisp +;; Check, whether the document viewer can be accessed via D-Bus. +(member "org.gnome.evince.Daemon" + (dbus-list-activatable-names :session)) +@end lisp + @end defun @defun dbus-list-names bus @@ -155,7 +164,7 @@ strings like @samp{org.freedesktop.DBus}. Names starting with @end defun @defun dbus-list-known-names bus -Retrieves all services which correspond to a known name in @var{bus}. +Retrieves all registered services which correspond to a known name in @var{bus}. A service has a known name if it doesn't start with @samp{:}. The result is a list of strings, which is @code{nil} when there are no known names at all. @@ -323,7 +332,7 @@ Example: @code{method}, @code{signal}, and @code{property} elements. Unlike properties, which can change their values during lifetime of a D-Bus object, annotations are static. Often they are used for code -generators of D-Bus langugae bindings. Example: +generators of D-Bus language bindings. Example: @example @@ -544,7 +553,7 @@ data from a running system: @node Methods and Signal @section Applying the functionality. -Methods and signals are the communicatione means to D-Bus. The +Methods and signals are the communication means to D-Bus. The following functions return their specifications. @defun dbus-introspect-get-method-names bus service path interface @@ -884,10 +893,10 @@ applied, when the corresponding D-Bus message is created: @end example Other Lisp objects, like symbols or hash tables, are not accepted as -input parameter. +input parameters. If it is necessary to use another D-Bus type, a corresponding type -symbol can be preceeded to the corresponding Lisp object. Basic D-Bus +symbol can be prepended to the corresponding Lisp object. Basic D-Bus types are represented by the type symbols @code{:byte}, @code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32}, @code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double}, @@ -1597,9 +1606,10 @@ D-Bus @var{bus}. @var{service} is the D-Bus service name used by the sending D-Bus object. It can be either a known name or the unique name of the D-Bus -object sending the signal. In case of a unique name, signals won't be -received any longer once the object owning this unique name has -disappeared, and a new queued object has replaced it. +object sending the signal. A known name will be mapped onto the +unique name of the object, owning @var{service} at registration time. +When the corresponding D-Bus object disappears, signals won't be +received any longer. When @var{service} is @code{nil}, related signals from all D-Bus objects shall be accepted. @@ -1668,7 +1678,7 @@ Establish the connection to D-Bus @var{bus}. @var{bus} can be either the symbol @code{:system} or the symbol @code{:session}, or it can be a string denoting the address of the -corresponding bus. For the system and session busses, this function +corresponding bus. For the system and session buses, this function is called when loading @file{dbus.el}, there is no need to call it again. @@ -1807,7 +1817,7 @@ handled by a hook function. @defvar dbus-event-error-hooks This hook variable keeps a list of functions, which are called when a D-Bus error happens in the event handler. Every function must accept -two arguments, the event and the error variable catched in +two arguments, the event and the error variable caught in @code{condition-case} by @code{dbus-error}. Such functions can be used the adapt the error signal to be raised.