comparison doc/misc/dbus.texi @ 109186:29eae48799da

* dbus.texi (Top): Introduce Index. Emphasize "nil" whereever forgotten. (Type Conversion): Precise conversion of natural numbers. (Errors and Events): Add "debugging" to concept index. Add variable `dbus-debug'.

109185:908904655a40

@setfilename ../../info/dbus
@c %**start of header
@settitle Using of D-Bus
@c @setchapternewpage odd
@c %**end of header

@copying
Copyright @copyright{} 2007, 2008, 2009, 2010 Free Software Foundation, Inc.

@quotation

* Synchronous Methods::         Calling methods in a blocking way.
* Asynchronous Methods::        Calling methods non-blocking.
* Receiving Method Calls::      Offering own methods.
* Signals::                     Sending and receiving signals.
* Errors and Events::           Errors and events.
* GNU Free Documentation License:: The license for this documentation.
@end menu


@node Overview

  "name")

@result{} "/org/freedesktop/SystemToolsBackends/UsersConfig"
@end lisp

If @var{object} has no @var{attribute}, the function returns nil.
@end defun


@node Nodes and Interfaces
@section Detecting object paths and interfaces.

@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
@var{property}.  Example:

@lisp
(dbus-get-property
  :session "org.kde.kded" "/modules/networkstatus"

Input parameters for D-Bus methods and signals occur as arguments of a
Lisp function call.  The following mapping to D-Bus types is
applied, when the corresponding D-Bus message is created:

@example
@multitable {@code{t} and @code{nil}} {@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 float                   @tab @expansion{} @tab DBUS_TYPE_DOUBLE
@item string                  @tab @expansion{} @tab DBUS_TYPE_STRING
@item list                    @tab @expansion{} @tab DBUS_TYPE_ARRAY
@end multitable
@end example

@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 D-Bus 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,

Output parameters of D-Bus methods and signals are mapped to Lisp
objects.

@example
@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {@code{t} or @code{nil}}
@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_DOUBLE      @tab @expansion{} @tab float
@item DBUS_TYPE_STRING      @tab @expansion{} @tab string
@item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string
@item DBUS_TYPE_SIGNATURE   @tab @expansion{} @tab string
@item DBUS_TYPE_ARRAY       @tab @expansion{} @tab list

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

@defun dbus-byte-array-to-string byte-array
If a D-Bus method or signal returns an array of bytes, which are known
to represent an UTF8 string, this function converts @var{byte-array}

@code{:readwrite} can be changed by @code{dbus-set-property}.

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.  When
@var{emits-signal} is non-nil, the signal @samp{PropertiesChanged} is
sent when the property is changed by @code{dbus-set-property}.

@noindent Example:

@lisp
(dbus-register-property

@end defun


@node Errors and Events
@chapter Errors and events.
@cindex errors
@cindex events

Input parameters of @code{dbus-call-method},
@code{dbus-call-method-non-blocking},
@code{dbus-call-method-asynchronously}, and
@code{dbus-register-signal} are checked for correct D-Bus types. If

appended to the @code{dbus-error}.

@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}.
@end defspec

Incoming D-Bus messages are handled as Emacs events, see @pxref{Misc
Events, , , elisp}.  They are retrieved only, when Emacs runs in
interactive mode.  The generated event has this form:

The result is either the symbol @code{:system} or the symbol @code{:session}.
@end defun

@defun dbus-event-message-type event
Returns the message type of the corresponding D-Bus message.  The
result is a number.
@end defun

@defun dbus-event-serial-number event
Returns the serial number of the corresponding D-Bus message.
The result is a number.
@end defun

@defun dbus-event-service-name event
Returns the unique name of the D-Bus object @var{event} is coming from.
@end defun

Hook functions shall take into account, that there might be other
D-Bus applications running.  Therefore, they shall check carefully,
whether a given D-Bus error is related to them.


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

@bye

109186:29eae48799da

@setfilename ../../info/dbus
@c %**start of header
@settitle Using of D-Bus
@c @setchapternewpage odd
@c %**end of header

@syncodeindex vr cp
@syncodeindex fn cp

@copying
Copyright @copyright{} 2007, 2008, 2009, 2010 Free Software Foundation, Inc.

@quotation

* Synchronous Methods::         Calling methods in a blocking way.
* Asynchronous Methods::        Calling methods non-blocking.
* Receiving Method Calls::      Offering own methods.
* Signals::                     Sending and receiving signals.
* Errors and Events::           Errors and events.
* Index::                       Index including concepts, functions, variables.

* GNU Free Documentation License:: The license for this documentation.
@end menu


@node Overview

  "name")

@result{} "/org/freedesktop/SystemToolsBackends/UsersConfig"
@end lisp

If @var{object} has no @var{attribute}, the function returns
@code{nil}.
@end defun


@node Nodes and Interfaces
@section Detecting object paths and interfaces.

@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 @code{nil} if there is no
@var{property}.  Example:

@lisp
(dbus-get-property
  :session "org.kde.kded" "/modules/networkstatus"

Input parameters for D-Bus methods and signals occur as arguments of a
Lisp function call.  The following mapping to D-Bus types is
applied, when the corresponding D-Bus message is created:

@example
@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 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
@end multitable
@end example

@noindent
Example:

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

is equivalent to

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

but different to

@lisp
(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
through 255.  If a character is used as argument, modifiers
represented outside this range are stripped of.  For example,

Output parameters of D-Bus methods and signals are mapped to Lisp
objects.

@example
@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 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_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
@item DBUS_TYPE_SIGNATURE   @tab @expansion{} @tab string
@item DBUS_TYPE_ARRAY       @tab @expansion{} @tab list

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{INTEGER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{}))
@end lisp

@defun dbus-byte-array-to-string byte-array
If a D-Bus method or signal returns an array of bytes, which are known
to represent an UTF8 string, this function converts @var{byte-array}

@code{:readwrite} can be changed by @code{dbus-set-property}.

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.  When
@var{emits-signal} is non-@code{nil}, the signal
@samp{PropertiesChanged} is sent when the property is changed by
@code{dbus-set-property}.

@noindent Example:

@lisp
(dbus-register-property

@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
@code{dbus-register-signal} are checked for correct D-Bus types. If

appended to the @code{dbus-error}.

@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 @code{dbus-debug} is set to @code{t}.
@end defspec

Incoming D-Bus messages are handled as Emacs events, see @pxref{Misc
Events, , , elisp}.  They are retrieved only, when Emacs runs in
interactive mode.  The generated event has this form:

The result is either the symbol @code{:system} or the symbol @code{:session}.
@end defun

@defun dbus-event-message-type event
Returns the message type of the corresponding D-Bus message.  The
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 natural number.
@end defun

@defun dbus-event-service-name event
Returns the unique name of the D-Bus object @var{event} is coming from.
@end defun

Hook functions shall take into account, that there might be other
D-Bus applications running.  Therefore, they shall check carefully,
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