@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
@end quotation
@end copying
-@dircategory Emacs
+@dircategory Emacs lisp libraries
@direntry
* D-Bus: (dbus). Using D-Bus in Emacs.
@end direntry
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
@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.
@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},
@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
@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 use to prevent other
+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
@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 use to prevent other
+at a time, @var{dont-register-service} can be used to prevent other
clients from discovering the still incomplete interface.
@noindent Example:
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.
@include doclicense.texi
@bye
-
-@ignore
- arch-tag: 2eeec19d-0caf-44e0-a193-329d7f9951d8
-@end ignore