comparison doc/misc/dbus.texi @ 91304:c938ab6810a4

Merge from emacs--devo--0 Revision: [e-mail]/emacs--unicode--0--patch-308

91303:1ae1f4066439

    <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}
at object path @code{/org/freedesktop/Hal/devices/computer} offers the

@noindent
Example:

@lisp
(dbus-call-method ... @var{NUMBER} @var{STRING})
@end lisp

is equivalent to

@lisp
(dbus-call-method ... :uint32 @var{NUMBER} :string @var{STRING})
@end lisp

but different to

@lisp
(dbus-call-method ... :int32 @var{NUMBER} :signature @var{STRING})
@end lisp

A D-Bus compound type is always represented as list.  The car of this
list can be the type symbol @code{:array}, @code{:variant},
@code{:struct} or @code{:dict-entry}, which would result in a
corresponding D-Bus container.  @code{:array} is optional, because

@noindent
Example:

@lisp
(dbus-send-signal ...
  :object-path STRING '(:variant :boolean BOOL)
  '(:array NUMBER NUMBER) '(:array BOOL :boolean BOOL)
  '(:struct BOOL :boolean BOOL BOOL
    (:array NUMBER NUMBER) (:array BOOL BOOL))
  '(:struct NUMBER NUMBER) '((:dict-entry NUMBER (NUMBER)))

The signal @code{PropertyModified}, discussed as example in
@ref{Inspection}, would offer as Lisp data the following object
(@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}) ...))
@end lisp


@node Synchronous Methods
@chapter Calling methods in a blocking way.

      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


@node Signals

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.

@code{dbus-register-signal} returns a Lisp symbol, which can be used
as argument in @code{dbus-unregister-signal} for removing the
registration for @var{signal}.
@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


@node Errors and Events
@chapter Errors and events.

@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


@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi

91304:c938ab6810a4

    <node>
      <interface name=\"org.freedesktop.Hal.Device\">
        <method name=\"GetAllProperties\">
          <arg name=\"properties\" direction=\"out\" type=\"a@{sv@}\"/>
        </method>
        @dots{}
        <signal name=\"PropertyModified\">
          <arg name=\"num_updates\" type=\"i\"/>
          <arg name=\"updates\" type=\"a(sbb)\"/>
        </signal>
      </interface>
      @dots{}
    </node>"
@end example

This example informs us, that the service @code{org.freedesktop.Hal}
at object path @code{/org/freedesktop/Hal/devices/computer} offers the

@noindent
Example:

@lisp
(dbus-call-method @dots{} @var{NUMBER} @var{STRING})
@end lisp

is equivalent to

@lisp
(dbus-call-method @dots{} :uint32 @var{NUMBER} :string @var{STRING})
@end lisp

but different to

@lisp
(dbus-call-method @dots{} :int32 @var{NUMBER} :signature @var{STRING})
@end lisp

The value for a byte type can be any integer in the range 0 through
255.  If a character is used as argument, modifiers represented
outside this range are stripped of.  For example, @code{:byte ?x} is
equal to @code{:byte ?\M-x}, but it is not equal to @code{:byte
?\C-x} or @code{:byte ?\M-\C-x}.

A D-Bus compound type is always represented as list.  The car of this
list can be the type symbol @code{:array}, @code{:variant},
@code{:struct} or @code{:dict-entry}, which would result in a
corresponding D-Bus container.  @code{:array} is optional, because

@noindent
Example:

@lisp
(dbus-send-signal @dots{}
  :object-path STRING '(:variant :boolean BOOL)
  '(:array NUMBER NUMBER) '(:array BOOL :boolean BOOL)
  '(:struct BOOL :boolean BOOL BOOL
    (:array NUMBER NUMBER) (:array BOOL BOOL))
  '(:struct NUMBER NUMBER) '((:dict-entry NUMBER (NUMBER)))

The signal @code{PropertyModified}, discussed as example in
@ref{Inspection}, would offer as Lisp data the following object
(@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{}))
@end lisp


@node Synchronous Methods
@chapter Calling methods in a blocking way.

      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\"
      @dots{}"
@end example
@end defun


@node Signals

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.

@code{dbus-register-signal} returns a Lisp symbol, which can be used
as argument in @code{dbus-unregister-object} for removing the
registration for @var{signal}.
@end defun

@defun dbus-unregister-object object
Unregister @var{object} from the the D-Bus.  @var{object} must be the
result of a preceding @code{dbus-register-signal} or
@code{dbus-register-method} call.  It returns @code{t} if @var{object}
has been unregistered, @code{nil} otherwise.
@end defun


@node Errors and Events
@chapter Errors and events.

@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

D-Bus errors are not propagated during event handling, because it is
usually not desired.  D-Bus errors in events can be made visible by
setting the variable @code{dbus-debug} to @code{t}.


@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi