X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/d1f61aaf6f0b6a2cf2bbb7eaf5631f8b580568d4..2b0c7330457b8ca42375c92ada7dc7cefb0fa9fb:/doc/misc/dbus.texi diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index b34a25b64f..e6fb00d348 100644 --- a/doc/misc/dbus.texi +++ b/doc/misc/dbus.texi @@ -5,8 +5,11 @@ @c @setchapternewpage odd @c %**end of header +@syncodeindex vr cp +@syncodeindex fn cp + @copying -Copyright @copyright{} 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +Copyright @copyright{} 2007-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -50,7 +53,10 @@ another. An overview of D-Bus can be found at * Asynchronous Methods:: Calling methods non-blocking. * Receiving Method Calls:: Offering own methods. * Signals:: Sending and receiving signals. +* Alternative Buses:: Alternative buses. * Errors and Events:: Errors and events. +* Index:: Index including concepts, functions, variables. + * GNU Free Documentation License:: The license for this documentation. @end menu @@ -126,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 @@ -148,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. @@ -418,7 +434,8 @@ Example: @result{} "/org/freedesktop/SystemToolsBackends/UsersConfig" @end lisp -If @var{object} has no @var{attribute}, the function returns nil. +If @var{object} has no @var{attribute}, the function returns +@code{nil}. @end defun @@ -669,7 +686,7 @@ A @var{property} value can be retrieved by the function @defun dbus-get-property bus service path interface property This function returns the value of @var{property} of @var{interface}. It will be checked at @var{bus}, @var{service}, @var{path}. The -result can be any valid D-Bus value, or nil if there is no +result can be any valid D-Bus value, or @code{nil} if there is no @var{property}. Example: @lisp @@ -863,12 +880,12 @@ Lisp function call. The following mapping to D-Bus types is applied, when the corresponding D-Bus message is created: @example -@multitable {@code{t} and @code{nil}} {@expansion{}} {DBUS_TYPE_BOOLEAN} +@multitable {negative integer} {@expansion{}} {DBUS_TYPE_BOOLEAN} @item Lisp type @tab @tab D-Bus type @item @item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN -@item number @tab @expansion{} @tab DBUS_TYPE_UINT32 -@item integer @tab @expansion{} @tab DBUS_TYPE_INT32 +@item natural number @tab @expansion{} @tab DBUS_TYPE_UINT32 +@item negative integer @tab @expansion{} @tab DBUS_TYPE_INT32 @item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE @item string @tab @expansion{} @tab DBUS_TYPE_STRING @item list @tab @expansion{} @tab DBUS_TYPE_ARRAY @@ -883,25 +900,26 @@ 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}, -@code{:string}, @code{:object-path} and @code{:signature}. +@code{:string}, @code{:object-path}, @code{:signature} and +@code{:unix-fd}. @noindent Example: @lisp -(dbus-call-method @dots{} @var{NUMBER} @var{STRING}) +(dbus-call-method @dots{} @var{NAT-NUMBER} @var{STRING}) @end lisp is equivalent to @lisp -(dbus-call-method @dots{} :uint32 @var{NUMBER} :string @var{STRING}) +(dbus-call-method @dots{} :uint32 @var{NAT-NUMBER} :string @var{STRING}) @end lisp but different to @lisp -(dbus-call-method @dots{} :int32 @var{NUMBER} :signature @var{STRING}) +(dbus-call-method @dots{} :int32 @var{NAT-NUMBER} :signature @var{STRING}) @end lisp The value for a byte D-Bus type can be any integer in the range 0 @@ -994,17 +1012,18 @@ Output parameters of D-Bus methods and signals are mapped to Lisp objects. @example -@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {@code{t} or @code{nil}} +@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {natural number or float} @item D-Bus type @tab @tab Lisp type @item @item DBUS_TYPE_BOOLEAN @tab @expansion{} @tab @code{t} or @code{nil} -@item DBUS_TYPE_BYTE @tab @expansion{} @tab number -@item DBUS_TYPE_UINT16 @tab @expansion{} @tab number -@item DBUS_TYPE_INT16 @tab @expansion{} @tab number -@item DBUS_TYPE_UINT32 @tab @expansion{} @tab number or float -@item DBUS_TYPE_INT32 @tab @expansion{} @tab number or float -@item DBUS_TYPE_UINT64 @tab @expansion{} @tab number or float -@item DBUS_TYPE_INT64 @tab @expansion{} @tab number or float +@item DBUS_TYPE_BYTE @tab @expansion{} @tab natural number +@item DBUS_TYPE_UINT16 @tab @expansion{} @tab natural number +@item DBUS_TYPE_INT16 @tab @expansion{} @tab integer +@item DBUS_TYPE_UINT32 @tab @expansion{} @tab natural number or float +@item DBUS_TYPE_UNIX_FD @tab @expansion{} @tab natural number or float +@item DBUS_TYPE_INT32 @tab @expansion{} @tab integer or float +@item DBUS_TYPE_UINT64 @tab @expansion{} @tab natural number or float +@item DBUS_TYPE_INT64 @tab @expansion{} @tab integer or float @item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float @item DBUS_TYPE_STRING @tab @expansion{} @tab string @item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string @@ -1017,9 +1036,9 @@ objects. @end example A float object in case of @code{DBUS_TYPE_UINT32}, -@code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64} and -@code{DBUS_TYPE_INT6432} is returned, when the C value exceeds the -Emacs number size range. +@code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64}, +@code{DBUS_TYPE_INT64} and @code{DBUS_TYPE_UNIX_FD} is returned, when +the C value exceeds the Emacs number size range. The resulting list of the last 4 D-Bus compound types contains as elements the elements of the D-Bus container, mapped according to the @@ -1030,7 +1049,7 @@ The signal @code{PropertyModified}, discussed as example in (@var{BOOL} stands here for either @code{nil} or @code{t}): @lisp -(@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{})) +(@var{INTEGER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{})) @end lisp @defun dbus-byte-array-to-string byte-array @@ -1234,9 +1253,73 @@ message has been arrived, and @var{handler} is called. Example: @cindex method calls, returning @cindex returning method calls -Emacs can also offer own methods, which can be called by other -applications. These methods could be an implementation of an -interface of a well known service, like @samp{org.freedesktop.TextEditor}. +In order to register methods on the D-Bus, Emacs has to request a well +known name on the D-Bus under which it will be available for other +clients. Names on the D-Bus can be registered and unregistered using +the following functions: + +@defun dbus-register-service bus service &rest flags +Register the known name @var{service} on D-Bus @var{bus}. + +@var{bus} is either the symbol @code{:system} or the symbol +@code{:session}. + +@var{service} is the service name to be registered on the D-Bus. It +must be a known name. + +@var{flags} is a subset of the following keywords: + +@itemize +@item @code{:allow-replacement}: Allow another service to become the primary +owner if requested. + +@item @code{:replace-existing}: Request to replace the current primary owner. + +@item @code{:do-not-queue}: If we can not become the primary owner do not +place us in the queue. +@end itemize + +One of the following keywords is returned: + +@itemize + +@item @code{:primary-owner}: We have become the primary owner of the name +@var{service}. + +@item @code{:in-queue}: We could not become the primary owner and +have been placed in the queue. + +@item @code{:exists}: We already are in the queue. + +@item @code{:already-owner}: We already are the primary +owner. +@end itemize +@end defun + +@defun dbus-unregister-service bus service +Unregister all objects from D-Bus @var{bus}, registered by Emacs for +@var{service}. + +@var{bus} is either the symbol @code{:system} or the symbol +@code{:session}. + +@var{service} is the D-Bus service name of the D-Bus. It must be a +known name. Emacs releases its association to @var{service} from +D-Bus. + +One of the following keywords is returned: + +@itemize +@item @code{:released}: We successfully released the name @var{service}. +@item @code{:non-existent}: The name @var{service} does not exist on the bus. +@item @code{:not-owner}: We are not an owner of the name @var{service}. +@end itemize +@end defun + +When a name has been chosen, Emacs can offer own methods, which can be +called by other applications. These methods could be an +implementation of an interface of a well known service, like +@samp{org.freedesktop.TextEditor}. It could be also an implementation of an own interface. In this case, the service name must be @samp{org.gnu.Emacs}. The object path shall @@ -1255,7 +1338,7 @@ paths, used by offered methods or signals, shall start with this string. @end deffn -@defun dbus-register-method bus service path interface method handler +@defun dbus-register-method bus service path interface method handler dont-register-service With this function, an application registers @var{method} on the D-Bus @var{bus}. @@ -1263,10 +1346,11 @@ With this function, an application registers @var{method} on the D-Bus @code{:session}. @var{service} is the D-Bus service name of the D-Bus object -@var{method} is registered for. It must be a known name. +@var{method} is registered for. It must be a known name (See +discussion of @var{dont-register-service} below). -@var{path} is the D-Bus object path @var{service} is -registered. +@var{path} is the D-Bus object path @var{service} is registered (See +discussion of @var{dont-register-service} below). @var{interface} is the interface offered by @var{service}. It must provide @var{method}. @@ -1285,6 +1369,13 @@ returning a list containing the object. In case @var{handler} shall return a reply message with an empty argument list, @var{handler} must return the symbol @code{:ignore}. +When @var{dont-register-service} is non-@code{nil}, the known name +@var{service} is not registered. This means that other D-Bus clients +have no way of noticing the newly registered method. When interfaces +are constructed incrementally by adding single methods or properties +at a time, @var{dont-register-service} can be used to prevent other +clients from discovering the still incomplete interface. + The default D-Bus timeout when waiting for a message reply is 25 seconds. This value could be even smaller, depending on the calling client. Therefore, @var{handler} shall not last longer than @@ -1359,7 +1450,7 @@ The test runs then @end example @end defun -@defun dbus-register-property bus service path interface property access value +@defun dbus-register-property bus service path interface property access value &optional emits-signal dont-register-service With this function, an application declares a @var{property} on the D-Bus @var{bus}. @@ -1369,8 +1460,8 @@ With this function, an application declares a @var{property} on the D-Bus @var{service} is the D-Bus service name of the D-Bus. It must be a known name. -@var{path} is the D-Bus object path @var{service} is -registered. +@var{path} is the D-Bus object path @var{service} is registered (See +discussion of @var{dont-register-service} below). @var{interface} is the name of the interface used at @var{path}, @var{property} is the name of the property of @var{interface}. @@ -1387,7 +1478,19 @@ only way to change their values. Properties with access type The interface @samp{org.freedesktop.DBus.Properties} is added to @var{path}, including a default handler for the @samp{Get}, -@samp{GetAll} and @samp{Set} methods of this interface. Example: +@samp{GetAll} and @samp{Set} methods of this interface. When +@var{emits-signal} is non-@code{nil}, the signal +@samp{PropertiesChanged} is sent when the property is changed by +@code{dbus-set-property}. + +When @var{dont-register-service} is non-@code{nil}, the known name +@var{service} is not registered. This means that other D-Bus clients +have no way of noticing the newly registered method. When interfaces +are constructed incrementally by adding single methods or properties +at a time, @var{dont-register-service} can be used to prevent other +clients from discovering the still incomplete interface. + +@noindent Example: @lisp (dbus-register-property @@ -1399,7 +1502,7 @@ The interface @samp{org.freedesktop.DBus.Properties} is added to (dbus-register-property :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - "org.freedesktop.TextEditor" "version" :readwrite emacs-version) + "org.freedesktop.TextEditor" "version" :readwrite emacs-version t) @result{} ((:session "org.freedesktop.TextEditor" "version") ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor")) @@ -1461,18 +1564,6 @@ registered for the respective service, Emacs releases its association to the service from D-Bus. @end defun -@defun dbus-unregister-service bus service -Unregister all objects from D-Bus @var{bus}, registered by Emacs for -@var{service}. - -@var{bus} is either the symbol @code{:system} or the symbol -@code{:session}. - -@var{service} is the D-Bus service name of the D-Bus. It must be a -known name. Emacs releases its association to @var{service} from -D-Bus. -@end defun - @node Signals @chapter Sending and receiving signals. @@ -1568,11 +1659,68 @@ which objects the GNU/Linux @code{hal} daemon adds. @end defun +@node Alternative Buses +@chapter Alternative buses. +@cindex bus names +@cindex UNIX domain socket + +Until now, we have spoken about the system and the session buses, +which are the default buses to be connected to. However, it is +possible to connect to any bus, from which the address is known. This +is a UNIX domain socket. Everywhere, where a @var{bus} is mentioned +as argument of a function (the symbol @code{:system} or the symbol +@code{:session}), this address can be used instead. The connection to +this bus must be initialized first. + +@defun dbus-init-bus bus +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 +is called when loading @file{dbus.el}, there is no need to call it +again. + +Example: You open another session bus in a terminal window on your host: + +@example +# eval `dbus-launch --auto-syntax` +# echo $DBUS_SESSION_BUS_ADDRESS + +@print{} unix:abstract=/tmp/dbus-JoFtAVG92w,guid=2f320a1ebe50b7ef58e +@end example + +In Emacs, you can access to this bus via its address: + +@lisp +(setq my-bus + "unix:abstract=/tmp/dbus-JoFtAVG92w,guid=2f320a1ebe50b7ef58e") + +@result{} "unix:abstract=/tmp/dbus-JoFtAVG92w,guid=2f320a1ebe50b7ef58e" + +(dbus-init-bus my-bus) + +@result{} nil + +(dbus-get-unique-name my-bus) + +@result{} ":1.0" +@end lisp +@end defun + + @node Errors and Events @chapter Errors and events. +@cindex debugging @cindex errors @cindex events +The internal actions can be traced by running in a debug mode. + +@defvar dbus-debug +If this variable is non-@code{nil}, D-Bus specific debug messages are raised. +@end defvar + Input parameters of @code{dbus-call-method}, @code{dbus-call-method-non-blocking}, @code{dbus-call-method-asynchronously}, and @@ -1587,8 +1735,7 @@ appended to the @code{dbus-error}. @defspec dbus-ignore-errors forms@dots{} This executes @var{forms} exactly like a @code{progn}, except that @code{dbus-error} errors are ignored during the @var{forms}. These -errors can be made visible when variable @code{dbus-debug} is set to -@code{t}. +errors can be made visible when @code{dbus-debug} is set to @code{t}. @end defspec Incoming D-Bus messages are handled as Emacs events, see @pxref{Misc @@ -1636,12 +1783,12 @@ The result is either the symbol @code{:system} or the symbol @code{:session}. @defun dbus-event-message-type event Returns the message type of the corresponding D-Bus message. The -result is a number. +result is a natural number. @end defun @defun dbus-event-serial-number event Returns the serial number of the corresponding D-Bus message. -The result is a number. +The result is a natural number. @end defun @defun dbus-event-service-name event @@ -1691,12 +1838,14 @@ D-Bus applications running. Therefore, they shall check carefully, whether a given D-Bus error is related to them. +@node Index +@unnumbered Index + +@printindex cp + + @node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi @bye - -@ignore - arch-tag: 2eeec19d-0caf-44e0-a193-329d7f9951d8 -@end ignore