comparison doc/misc/dbus.texi @ 112114:2e84d340bbaf

* dbus.texi (Receiving Method Calls): Describe new optional parameter dont-register-service of dbus-register-{method,property}.

112113:f68ebb34e243

@syncodeindex vr cp
@syncodeindex fn cp

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

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no

The object path head "/org/gnu/Emacs" used by Emacs.  All object
paths, used by offered methods or signals, shall start with this
string.
@end deffn

@defun dbus-register-method bus service path interface method handler
With this function, an application registers @var{method} 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 D-Bus object
@var{method} is registered for.  It must be a known name.

@var{path} is the D-Bus object path @var{service} is
registered.

@var{interface} is the interface offered by @var{service}.  It must
provide @var{method}.

@var{handler} is a Lisp function to be called when a @var{method} call

cons cell, @var{handler} can return this object directly, instead of
returning a list containing the object.

In case @var{handler} shall return a reply message with an empty
argument list, @var{handler} must return the symbol @code{:ignore}.

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
absolutely necessary.

@print{} Error org.freedesktop.DBus.Error.Failed:
   Wrong argument list: ("/etc/hosts" "/etc/passwd")
@end example
@end defun

@defun dbus-register-property bus service path interface property access value &optional emits-signal
With this function, an application declares a @var{property} 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 D-Bus.  It must be a
known name.

@var{path} is the D-Bus object path @var{service} is
registered.

@var{interface} is the name of the interface used at @var{path},
@var{property} is the name of the property of @var{interface}.

@var{access} indicates, whether the property can be changed by other

@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

112114:2e84d340bbaf

@syncodeindex vr cp
@syncodeindex fn cp

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

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no

The object path head "/org/gnu/Emacs" used by Emacs.  All object
paths, used by offered methods or signals, shall start with this
string.
@end deffn

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

@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 object
@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 (See
discussion of @var{dont-register-service} below).

@var{interface} is the interface offered by @var{service}.  It must
provide @var{method}.

@var{handler} is a Lisp function to be called when a @var{method} call

cons cell, @var{handler} can return this object directly, instead of
returning a list containing the object.

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 use 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
absolutely necessary.

@print{} Error org.freedesktop.DBus.Error.Failed:
   Wrong argument list: ("/etc/hosts" "/etc/passwd")
@end example
@end defun

@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{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.

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

@var{access} indicates, whether the property can be changed by other

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

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 use to prevent other
clients from discovering the still incomplete interface.

@noindent Example:

@lisp
(dbus-register-property