[Emacs-diffs] Changes to dbus.texi

[Michael Albinus]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Michael Albinus <albinus>       07/12/02 16:28:13

Index: dbus.texi
===================================================================
RCS file: dbus.texi
diff -N dbus.texi
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ dbus.texi   2 Dec 2007 16:28:13 -0000       1.1
@@ -0,0 +1,562 @@
+\input texinfo   @c -*-texinfo-*-
address@hidden ../../info/dbus
address@hidden %**start of header
address@hidden Using of D-Bus
address@hidden @setchapternewpage odd
address@hidden %**end of header
+
address@hidden
+Copyright @copyright{} 2007 Free Software Foundation, Inc.
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software.  Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License.  If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
address@hidden quotation
address@hidden copying
+
address@hidden Emacs
address@hidden
+* D-Bus: (dbus).                Using D-Bus in Emacs.
address@hidden direntry
+
address@hidden Top, Overview, (dir), (dir)
address@hidden D-Bus integration in Emacs
+
+This manual documents an API for usage of D-Bus in
address@hidden is not enabled by default.  You must run
address@hidden/configure --with-dbus} in Emacs' top level directory,
+before you compile Emacs.}  D-Bus is a message bus system, a simple
+way for applications to talk to one another.  An overview of D-Bus can
+be found at @uref{http://dbus.freedesktop.org/}.
+
address@hidden
+
address@hidden
+* Overview::                    An overview of D-Bus.
+* Inspection::                  Inspection of the bus names.
+* Type Conversion::             Mapping Lisp types and D-Bus types.
+* Synchronous Methods::         Calling methods in a blocking way.
+* Signals::                     Sending and receiving signals.
+* Errors and Events::           Errors and events.
+* GNU Free Documentation License:: The license for this documentation.
address@hidden menu
+
address@hidden Overview
address@hidden An overview of D-Bus
address@hidden overview
+
+D-Bus is an inter-process communication mechanism for applications
+residing on the same host.  The communication is based on
address@hidden  Data in the messages is carried in a structured way,
+it is not just a byte stream.
+
+The communication is connection oriented to two kinds of message
+buses: a so called @dfn{system bus}, and a @dfn{session bus}.  On a
+given machine, there is always one single system bus for miscellaneous
+system-wide communication, like changing of hardware configuration.
+On the other hand, the session bus is always related to a single
+user's session.
+
+Every client application, which is connected to a bus, registers under
+a @dfn{unique name} at the bus.  This name is used for identifying the
+client application.  Such a unique name starts always with a colon,
+and looks like @samp{:1.42}.
+
+Additionally, a client application can register itself to a so called
address@hidden name}, which is a series of identifiers separated by dots,
+e.g. @samp{org.gnu.Emacs}.  If several applications register to the
+same known name, these registrations are queued, and only the first
+application which has registered for the known name is reachable via
+this name.  If this application disconnects from the bus, the next
+queued unique name becomes the owner of this known name.
+
+An application can install one or several objects under its name.
+Such objects are identified by an @dfn{object path}, which looks
+similar to paths in a filesystem.  An example of such an object path
+could be @samp{/org/gnu/Emacs/}.
+
+Applications might send a request to an object, that means sending a
+message with some data as input parameters, and receiving a message
+from that object with the result of this message, the output
+parameters.  Such a request is called @dfn{method} in D-Bus.
+
+The other form of communication are @dfn{signals}.  The underlying
+message is emitted from an object and will be received by all other
+applications which have registered for such a signal.
+
+All methods and signals an object supports are called @dfn{interface}
+of the object.  Interfaces are specified under a hierarchical name in
+D-Bus; an object can support several interfaces.  Such an interface
+name could be @samp{org.gnu.Emacs.TextEditor} or
address@hidden
+
+
address@hidden Inspection
address@hidden Inspection of the bus names.
address@hidden inspection
+
+There are several basic functions which inspect the buses for
+registered names.  Internally they use the basic interface
address@hidden, which is supported by all objects of a bus.
+
address@hidden 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
address@hidden/usr/share/dbus-1/services/}.
+
+The result is a list of strings, which is @code{nil} when there are no
+activatable service names at all.
address@hidden defun
+
address@hidden dbus-list-names bus
+
+All service names, which are registered at D-Bus @var{bus}, are
+returned.  The result is a list of strings, which is @code{nil} when
+there are no registered service names at all.  Well known names are
+strings like @samp{org.freedesktop.DBus}.  Names starting with
address@hidden:} are unique names for services.
+
address@hidden must be either the symbol @code{:system} or the symbol
address@hidden:session}.
address@hidden defun
+
address@hidden dbus-list-known-names bus
+
+Retrieves all 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.
+
address@hidden must be either the symbol @code{:system} or the symbol
address@hidden:session}.
address@hidden defun
+
address@hidden dbus-list-queued-owners bus service
+
+For a given service, registered at D-Bus @var{bus} under the name
address@hidden, all queued unique names are returned.  The result is a
+list of strings, or @code{nil} when there are no queued names for
address@hidden at all.
+
address@hidden must be either the symbol @code{:system} or the symbol
address@hidden:session}.  @var{service} must be a known service name as
+string.
address@hidden defun
+
address@hidden dbus-get-name-owner bus service
+
+For a given service, registered at D-Bus @var{bus} under the name
address@hidden, the unique name of the name owner is returned.  The result is a
+string, or @code{nil} when there exist no name owner of @var{service}.
+
address@hidden must be either the symbol @code{:system} or the symbol
address@hidden:session}.  @var{service} must be a known service name as
+string.
address@hidden defun
+
address@hidden dbus-get-unique-name bus
+
+The unique name, under which Emacs is registered at D-Bus @var{bus},
+is returned as string.
+
address@hidden must be either the symbol @code{:system} or the symbol
address@hidden:session}.
address@hidden defun
+
address@hidden dbus-introspect bus service path
+
+Objects can publish there interfaces to the D-Bus.  This function
+returns all interfaces of @var{service}, registered at object path
address@hidden at bus @var{bus}.
+
address@hidden must be either the symbol @code{:system} or the symbol
address@hidden:session}.  @var{service} must be a known service name, and
address@hidden must be a valid object path.  The last two parameters are
+strings.  The result, the introspection data, is a string in XML
+format. Example:
+
address@hidden
+(dbus-introspect
+  :system "org.freedesktop.Hal"
+  "/org/freedesktop/Hal/devices/computer")
+
address@hidden <!DOCTYPE node PUBLIC
+   "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+   "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd";>
+   <node>
+     <interface name="org.freedesktop.Hal.Device">
+       <method name="GetAllProperties">
+         <arg name="properties" direction="out" type="address@hidden@}"/>
+       </method>
+       ...
+       <signal name="PropertyModified">
+         <arg name="num_updates" type="i"/>
+         <arg name="updates" type="a(sbb)"/>
+       </signal>
+     </interface>
+     ...
+   </node>
address@hidden example
+
+This example informs us, that the service @code{org.freedesktop.Hal}
+at object path @code{/org/freedesktop/Hal/devices/computer} offers the
+interface @code{org.freedesktop.Hal.Device} (and 2 other interfaces
+not documented here).  This interface contains the method
address@hidden, which needs no input parameters, but returns
+as output parameter an array of dictionary entries (key-value pairs).
+Every dictionary entry has a string as key, and a variant as value.
+
+The interface offers also a signal, which returns 2 parameters: an
+integer, and an array consisting of elements which are a struct of a
+string and 2 boolean values.
+
+Such type descriptions are called @dfn{signature} in D-Bus.  For a
+discussion of D-Bus types and their Lisp representation see @ref{Type
address@hidden signatures are explained in the D-Bus
+specification
address@hidden://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures}.
+The interfaces of the service @code{org.freedesktop.Hal} are described
+at
address@hidden://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces}.}
address@hidden defun
+
+
address@hidden Type Conversion
address@hidden Mapping Lisp types and D-Bus types.
address@hidden type conversion
+
+D-Bus method calls and signals accept usually several arguments as
+parameters, either as input parameter, or as output parameter.  Every
+argument belongs to a D-Bus type.
+
+Such arguments must be mapped between the the value encoded as a D-Bus
+type, and the corresponding type of Lisp objects.  The mapping is
+applied Lisp object @expansion{} D-Bus type for input parameters, and
+D-Bus type @expansion{} Lisp object for output parameters.
+
+
address@hidden Input parameters.
+
+Input parameters for D-Bus methods and signals occur as arguments of a
+Lisp function call.  Only some primitive Lisp types are supported in
+the current implementation.  The following mapping to D-Bus types is
+applied, when the corresponding D-Bus message is created:
+
address@hidden
address@hidden address@hidden and @code{nil}} address@hidden {DBUS_TYPE_BOOLEAN}
address@hidden Lisp type               @tab              @tab D-Bus type
address@hidden
address@hidden @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN
address@hidden number                  @tab @expansion{} @tab DBUS_TYPE_UINT32
address@hidden integer                 @tab @expansion{} @tab DBUS_TYPE_INT32
address@hidden float                   @tab @expansion{} @tab DBUS_TYPE_DOUBLE
address@hidden string                  @tab @expansion{} @tab DBUS_TYPE_STRING
address@hidden multitable
address@hidden example
+
address@hidden
+Other Lisp types, especially lists, are not supported (yet).
+
+
address@hidden Output parameters.
+
+Output parameters of D-Bus methods and signals are mapped to Lisp
+objects.  This mapping is more powerful than the one for input
+parameters, i.e. more types are supported by the current
+implementation.
+
address@hidden
address@hidden {DBUS_TYPE_OBJECT_PATH} address@hidden address@hidden or 
@code{nil}}
address@hidden D-Bus type            @tab              @tab Lisp type
address@hidden
address@hidden DBUS_TYPE_BOOLEAN     @tab @expansion{} @tab @code{t} or 
@code{nil}
address@hidden DBUS_TYPE_UINT32      @tab @expansion{} @tab number
address@hidden DBUS_TYPE_INT32       @tab @expansion{} @tab number
address@hidden DBUS_TYPE_DOUBLE      @tab @expansion{} @tab float
address@hidden DBUS_TYPE_STRING      @tab @expansion{} @tab string
address@hidden DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string
address@hidden DBUS_TYPE_ARRAY       @tab @expansion{} @tab list
address@hidden DBUS_TYPE_VARIANT     @tab @expansion{} @tab list
address@hidden DBUS_TYPE_STRUCT      @tab @expansion{} @tab list
address@hidden DBUS_TYPE_DICT_ENTRY  @tab @expansion{} @tab list
address@hidden multitable
address@hidden example
+
+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
+same rules.
+
+The signal @code{PropertyModified}, discussed as example in
address@hidden, would offer as Lisp data the following object
+(@var{BOOL} stands here for either @code{nil} or @code{t}):
+
address@hidden
+(@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} 
@var{BOOL}) ...))
address@hidden lisp
+
+
address@hidden Synchronous Methods
address@hidden Calling methods in a blocking way.
address@hidden method calls, synchronous
address@hidden synchronous method calls
+
+Methods can be called synchronously (@dfn{blocking}) or asynchronously
+(@dfn{non-blocking}).  Currently, just synchronous methods are
+implemented.
+
+At D-Bus level, a method call consist of two messages: one message
+which carries the input parameters to the object owning the method to
+be called, and a reply message returning the resulting output
+parameters from the object.
+
address@hidden dbus-call-method bus method service path interface &rest args
+
+This function calls @var{method} on the D-Bus @var{bus}.  @var{bus} is
+either the symbol @code{:system} or the symbol @code{:session}.
+
address@hidden is the D-Bus service name to be used.  @var{path} is the
+D-Bus object path, @var{service} is registered at.  @var{interface} is
+an interface offered by @var{service}.  It must provide @var{method}.
+
+All other arguments args are passed to @var{method} as arguments.
+They are converted into D-Bus types as described in @ref{Type
+Conversion}.
+
+The function returns the resulting values of @var{method} as a list of
+Lisp objects, according to the type conversion rules described in
address@hidden Conversion}.  Example:
+
address@hidden
+(dbus-call-method
+  :session "GetKeyField" "org.gnome.seahorse"
+  "/org/gnome/seahorse/keys/openpgp" "org.gnome.seahorse.Keys"
+  "openpgp:657984B8C7A966DD" "simple-name")
+
address@hidden (t ("Philip R. Zimmermann"))
address@hidden example
+
+If the result of the method call is just one value, the converted Lisp
+object is returned instead of a list containing this single Lisp
+object.  Example:
+
address@hidden
+(dbus-call-method
+  :system "GetPropertyString" "org.freedesktop.Hal"
+  "/org/freedesktop/Hal/devices/computer" "org.freedesktop.Hal.Device"
+  "system.kernel.machine")
+
address@hidden "i686"
address@hidden example
+
+With the @code{dbus-introspect} function it is possible to explore the
+interfaces of @samp{org.freedesktop.Hal} service. It offers the
+interfaces @samp{org.freedesktop.Hal.Manager} for the object at the
+path @samp{/org/freedesktop/Hal/Manager} as well as the interface
address@hidden for all objects prefixed with the
+path @samp{/org/freedesktop/Hal/devices}.  With the methods
address@hidden and @samp{GetAllProperties}, it is simple to
+emulate the @code{lshal} command on GNU/Linux systems:
+
address@hidden
+(dolist (device
+          (dbus-call-method
+            :system "GetAllDevices" "org.freedesktop.Hal"
+            "/org/freedesktop/Hal/Manager"
+            "org.freedesktop.Hal.Manager"))
+  (message "\nudi = %s" device)
+  (dolist (properties
+            (dbus-call-method
+              :system "GetAllProperties" "org.freedesktop.Hal"
+              device "org.freedesktop.Hal.Device"))
+    (message "  %s = %S"
+             (car properties) (or (caar (cdr properties)) ""))))
+
address@hidden udi = /org/freedesktop/Hal/devices/computer
+     info.addons = ("hald-addon-acpi")
+     info.bus = "unknown"
+     info.product = "Computer"
+     info.subsystem = "unknown"
+     info.udi = "/org/freedesktop/Hal/devices/computer"
+     linux.sysfs_path_device = "(none)"
+     power_management.acpi.linux.version = "20051216"
+     power_management.can_suspend_to_disk = t
+     power_management.can_suspend_to_ram = ""
+     power_management.type = "acpi"
+     smbios.bios.release_date = "11/07/2001"
+     system.chassis.manufacturer = "COMPAL"
+     system.chassis.type = "Notebook"
+     system.firmware.release_date = "03/19/2005"
+     ...
address@hidden example
address@hidden defun
+
+
address@hidden Signals
address@hidden Sending and receiving signals.
address@hidden signals
+
+Signals are broadcast messages.  They carry input parameters, which
+are received by all objects which have registered for such a signal.
+
address@hidden dbus-send-signal bus signal service path interface &rest args
+
+This function is similar to @code{dbus-call-method}.  The difference
+is, that there are no returning output parameters.
+
+The function emits @var{signal} on the D-Bus @var{bus}.  @var{bus} is
+either the symbol @code{:system} or the symbol @code{:session}.  It
+doesn't matter whether another object has registered for @var{signal}.
+
address@hidden is the D-Bus service name of the object the signal is
+emitted from.  @var{path} is the corresponding D-Bus object path,
address@hidden is registered at.  @var{interface} is an interface
+offered by @var{service}.  It must provide @var{signal}.
+
+All other arguments args are passed to @var{signal} as arguments.
+They are converted into D-Bus types as described in @ref{Type
+Conversion}.  Example:
+
address@hidden
+(dbus-send-signal
+  :session "FileModified" "org.gnu.Emacs" "/org/gnu/Emacs"
+  "org.gnu.Emacs.FileManager" "/home/albinus/.emacs")
address@hidden example
address@hidden defun
+
address@hidden dbus-register-signal bus signal service path interface handler
+
+With this function, an application registers for @var{signal} on the
+D-Bus @var{bus}.
+
address@hidden is either the symbol @code{:system} or the symbol
address@hidden:session}.
+
address@hidden is the D-Bus service name of the object the signal is
+emitted from.  @var{path} is the corresponding D-Bus object path,
address@hidden is registered at.  @var{interface} is an interface
+offered by @var{service}.  It must provide @var{signal}.
+
address@hidden is a Lisp function to be called when the @var{signal} is
+received.  It must accept as arguments the output parameters
address@hidden is sending.  Example:
+
address@hidden
+(defun my-dbus-signal-handler (device)
+  (message "Device %s added" device))
+
+(dbus-register-signal
+  :system "DeviceAdded" "org.freedesktop.Hal"
+  "/org/freedesktop/Hal/Manager" "org.freedesktop.Hal.Manager"
+  'my-dbus-signal-handler)
+
address@hidden :system.org.freedesktop.Hal.Manager.DeviceAdded
address@hidden example
+
+As we know from the inspection data of interface
address@hidden, the signal @code{DeviceAdded}
+provides one single parameter, which is mapped into a Lisp string.
+The callback function @code{my-dbus-signal-handler} must define one
+single string argument therefore.  Plugging an USB device to your
+machine, when registered for signal @code{DeviceAdded}, will show you
+which objects the GNU/Linux @code{hal} daemon adds.
+
address@hidden returns a Lisp symbol, which can be used
+as argument in @code{dbus-unregister-signal} for removing the
+registration for @var{signal}.
address@hidden defun
+
address@hidden dbus-unregister-signal object
+
+Unregister @var{object} from the the D-Bus.  @var{object} must be the
+result of a preceding @code{dbus-register-signal} call.
address@hidden defun
+
+
address@hidden Errors and Events
address@hidden Errors and events.
address@hidden errors
address@hidden events
+
+All errors raised by D-Bus are signaled with the error symbol
address@hidden  As usual, such an error can be trapped with a
address@hidden form.  If possible, error messages from D-Bus
+are appended to the @code{dbus-error}.
+
+Incoming D-Bus messages are handled as Emacs event (see @pxref{Misc
+Events, , , elisp}).  The generated event has this form:
+
address@hidden
+(dbus-event @var{symbol} @var{service} @var{path} &rest @var{args})
address@hidden example
+
address@hidden is the interned Lisp symbol which has been generated
+during signal registration (see @pxref{Signals}).  Its function cell
+is the argument @var{handler}, the callback function which was
+provided by @code{dbus-register-signal}.  When a @code{dbus-event}
+event arrives, @var{handler} is called with @var{args} as arguments.
+
address@hidden and @var{path} are the unique name and the object path
+of the D-Bus object emitting the signal.
+
+In order to inspect the @code{dbus-event} data, you could extend the
+definition of the callback function in @ref{Signals}:
+
address@hidden
+(defun my-dbus-signal-handler (&rest args)
+  (message "my-dbus-signal-handler: %S" last-input-event))
address@hidden example
+
+There exist convenience functions which could be called inside a
+callback function in order to retrieve the information from the event.
+
address@hidden dbus-event-bus-name event
+
+Returns the bus name @var{event} is coming from.
+The result is either the symbol @code{:system} or the symbol @code{:session}.
address@hidden defun
+
address@hidden dbus-event-service-name event
+
+Returns the unique name of the D-Bus object @var{event} is coming from.
address@hidden defun
+
address@hidden dbus-event-path-name event
+
+Returns the object path of the D-Bus object @var{event} is coming from.
address@hidden defun
+
address@hidden dbus-event-interface-name event
+
+Returns the interface name of of the D-Bus object @var{event} is coming from.
address@hidden defun
+
address@hidden dbus-event-member-name event
+
+Returns the member name of of the D-Bus object @var{event} is coming
+from.  It is either a signal name or a method name.
address@hidden defun
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
address@hidden doclicense.texi
+
address@hidden
address@hidden End of dbus.texi
address@hidden