@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
* 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
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.
@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
@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
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
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
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
@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
(@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
@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
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}.
@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}.
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
@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}.
@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}.
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
(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"))
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.
@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
@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
@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
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
HCoop / bpt / emacs.git / blobdiff