X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/8809a9f99783685e43e9d2215961388b20298f8b..fac916bfd7f839a654c839dca609d0d75a77846a:/doc/misc/dbus.texi diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index f4f96d5539..06a52107d7 100644 --- a/doc/misc/dbus.texi +++ b/doc/misc/dbus.texi @@ -9,7 +9,7 @@ @syncodeindex fn cp @copying -Copyright @copyright{} 2007, 2008, 2009, 2010 Free Software Foundation, Inc. +Copyright @copyright{} 2007-2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -25,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 @@ -132,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 @@ -154,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. @@ -322,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 @@ -543,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 @@ -883,14 +893,15 @@ 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}, -@code{:string}, @code{:object-path} and @code{:signature}. +@code{:string}, @code{:object-path}, @code{:signature} and +@code{:unix-fd}. @noindent Example: @@ -1009,6 +1020,7 @@ objects. @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 @@ -1024,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 @@ -1241,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 @@ -1262,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}. @@ -1270,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}. @@ -1292,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 @@ -1366,7 +1450,7 @@ The test runs then @end example @end defun -@defun dbus-register-property bus service path interface property access value &optional emits-signal +@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}. @@ -1376,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}. @@ -1399,6 +1483,13 @@ The interface @samp{org.freedesktop.DBus.Properties} is added to @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 @@ -1473,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. @@ -1737,7 +1816,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. @@ -1770,7 +1849,3 @@ whether a given D-Bus error is related to them. @include doclicense.texi @bye - -@ignore - arch-tag: 2eeec19d-0caf-44e0-a193-329d7f9951d8 -@end ignore