Additionally, a client application can register itself to a so called
@dfn{known name}, which is a series of identifiers separated by dots,
-e.g. @samp{org.gnu.Emacs}. If several applications register to the
+as in @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
@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
@end defun
@defun 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
@end defun
@defun 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
@end defun
@defun dbus-list-queued-owners bus service
-
For a given service, registered at D-Bus @var{bus} under the name
@var{service}, all queued unique names are returned. The result is a
list of strings, or @code{nil} when there are no queued names for
@end defun
@defun dbus-get-name-owner bus service
-
For a given service, registered at D-Bus @var{bus} under the name
@var{service}, 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}.
@end defun
@defun dbus-get-unique-name bus
-
The unique name, under which Emacs is registered at D-Bus @var{bus},
is returned as string.
@end defun
@defun 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
@var{path} at bus @var{bus}.
:system "org.freedesktop.Hal"
"/org/freedesktop/Hal/devices/computer")
-@result{} <!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="a@{sv@}"/>
- </method>
- ...
- <signal name="PropertyModified">
- <arg name="num_updates" type="i"/>
- <arg name="updates" type="a(sbb)"/>
- </signal>
- </interface>
- ...
- </node>
+@result{} "<!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=\"a@{sv@}\"/>
+ </method>
+ ...
+ <signal name=\"PropertyModified\">
+ <arg name=\"num_updates\" type=\"i\"/>
+ <arg name=\"updates\" type=\"a(sbb)\"/>
+ </signal>
+ </interface>
+ ...
+ </node>"
@end example
This example informs us, that the service @code{org.freedesktop.Hal}
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
+parameters, i.e., more D-Bus types are supported by the current
implementation.
@example
parameters from the object.
@defun 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}.
(message " %s = %S"
(car properties) (or (caar (cdr properties)) ""))))
-@result{} 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"
- ...
+@print{} "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\"
+ ..."
@end example
@end defun
are received by all objects which have registered for such a signal.
@defun 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.
@end defun
@defun dbus-register-signal bus signal service path interface handler
-
With this function, an application registers for @var{signal} on the
D-Bus @var{bus}.
@var{bus} is either the symbol @code{:system} or the symbol
@code{:session}.
-@var{service} is the D-Bus service name of the object the signal is
-emitted from. @var{path} is the corresponding D-Bus object path,
-@var{service} is registered at. @var{interface} is an interface
-offered by @var{service}. It must provide @var{signal}.
+@var{service} is the D-Bus service name used by the sending D-Bus
+object. It can be either a known name or the unique name of the D-Bus
+object sending the signal. In case of a unique name, signals won't be
+received any longer once the object owning this unique name has
+disappeared, and a new queued object has replaced it.
+
+When @var{service} is @code{nil}, related signals from all D-Bus
+objects shall be accepted.
+
+@var{path} is the corresponding D-Bus object path, @var{service} is
+registered at. It can also be @code{nil} if the path name of incoming
+signals shall not be checked.
+
+@var{interface} is an interface offered by @var{service}. It must
+provide @var{signal}.
@var{handler} is a Lisp function to be called when the @var{signal} is
received. It must accept as arguments the output parameters
(message "Device %s added" device))
(dbus-register-signal
- :system "DeviceAdded" "org.freedesktop.Hal"
+ :system "DeviceAdded"
+ (dbus-get-name-owner :system "org.freedesktop.Hal")
"/org/freedesktop/Hal/Manager" "org.freedesktop.Hal.Manager"
'my-dbus-signal-handler)
-@result{} :system.org.freedesktop.Hal.Manager.DeviceAdded
+@result{} (:system "org.freedesktop.Hal.Manager" "DeviceAdded")
@end example
As we know from the inspection data of interface
@end defun
@defun 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.
@end defun
@code{condition-case} 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
+Incoming D-Bus messages are handled as Emacs events (see @pxref{Misc
Events, , , elisp}). The generated event has this form:
@example
-(dbus-event @var{symbol} @var{service} @var{path} &rest @var{args})
+(dbus-event @var{handler} @var{bus} @var{service} @var{path} @var{interface} @var{member} &rest @var{args})
@end example
-@var{symbol} 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.
+@var{handler} is the callback function which has been registered for
+this signal (see @pxref{Signals}). When a @code{dbus-event} event
+arrives, @var{handler} is called with @var{args} as arguments.
+
+@var{bus} identifies the D-Bus the signal is coming from. It is
+either the symbol @code{:system} or the symbol @code{:session}.
@var{service} and @var{path} are the unique name and the object path
-of the D-Bus object emitting the signal.
+of the D-Bus object emitting the signal. @var{interface} and
+@var{member} denote the signal which has been sent.
In order to inspect the @code{dbus-event} data, you could extend the
definition of the callback function in @ref{Signals}:
callback function in order to retrieve the information from the event.
@defun 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}.
@end defun
@defun dbus-event-service-name event
-
Returns the unique name of the D-Bus object @var{event} is coming from.
@end defun
@defun dbus-event-path-name event
-
Returns the object path of the D-Bus object @var{event} is coming from.
@end defun
@defun dbus-event-interface-name event
-
Returns the interface name of of the D-Bus object @var{event} is coming from.
@end defun
@defun 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.
@end defun
HCoop / bpt / emacs.git / blobdiff