* dbus.texi (Receiving Method Calls): New function

dbus-register-service.  Rearrange node.

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 1acf8b0bbdaeb7b2bdfc67580194dab43c340d2d..ca43b7e06dff1e33afb8fbdad154c2656d1768b9 100644 (file)
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,8 @@
+2011-01-10  Jan Moringen  <jan.moringen@uni-bielefeld.de>
+
+       * dbus.texi (Receiving Method Calls): New function
+       dbus-register-service.  Rearrange node.
+
 2011-01-07  Paul Eggert  <eggert@cs.ucla.edu>
 
        * texinfo.tex: Update to version 2010-12-23.17 from gnulib,

diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 39f6221e2f2a2a8b20a40a135c3eb5eee71c150c..fe7918038e2d5c4bf771e737d2358749cd0cf809 100644 (file)
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -1244,9 +1244,73 @@ message has been arrived, and @var{handler} is called.  Example:
 @cindex method calls, returning
 @cindex returning method calls
 
-Emacs can also offer own methods, which can be called by other
-applications.  These methods could be an implementation of an
-interface of a well known service, like @samp{org.freedesktop.TextEditor}.
+In order to register methods on the D-Bus, Emacs has to request a well
+known name on the D-Bus under which it will be available for other
+clients.  Names on the D-Bus can be registered and unregistered using
+the following functions:
+
+@defun dbus-register-service bus service &rest flags
+Register the known name @var{service} on D-Bus @var{bus}.
+
+@var{bus} is either the symbol @code{:system} or the symbol
+@code{:session}.
+
+@var{service} is the service name to be registered on the D-Bus.  It
+must be a known name.
+
+@var{flags} is a subset of the following keywords:
+
+@itemize
+@item @code{:allow-replacement}: Allow another service to become the primary
+owner if requested.
+
+@item @code{:replace-existing}: Request to replace the current primary owner.
+
+@item @code{:do-not-queue}: If we can not become the primary owner do not
+place us in the queue.
+@end itemize
+
+One of the following keywords is returned:
+
+@itemize
+
+@item @code{:primary-owner}: We have become the primary owner of the name
+@var{service}.
+
+@item @code{:in-queue}: We could not become the primary owner and
+have been placed in the queue.
+
+@item @code{:exists}: We already are in the queue.
+
+@item @code{:already-owner}: We already are the primary
+owner.
+@end itemize
+@end defun
+
+@defun dbus-unregister-service bus service
+Unregister all objects from D-Bus @var{bus}, registered by Emacs for
+@var{service}.
+
+@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.  Emacs releases its association to @var{service} from
+D-Bus.
+
+One of the following keywords is returned:
+
+@itemize
+@item @code{:released}: We successfully released the name @var{service}.
+@item @code{:non-existent}: The name @var{service} does not exist on the bus.
+@item @code{:not-owner}: We are not an owner of the name @var{service}.
+@end itemize
+@end defun
+
+When a name has been chosen, Emacs can offer own methods, which can be
+called by other applications.  These methods could be an
+implementation of an interface of a well known service, like
+@samp{org.freedesktop.TextEditor}.
 
 It could be also an implementation of an own interface.  In this case,
 the service name must be @samp{org.gnu.Emacs}.  The object path shall
@@ -1300,7 +1364,7 @@ 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
+at a time, @var{dont-register-service} can be used to prevent other
 clients from discovering the still incomplete interface.
 
 The default D-Bus timeout when waiting for a message reply is 25
@@ -1414,7 +1478,7 @@ 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
+at a time, @var{dont-register-service} can be used to prevent other
 clients from discovering the still incomplete interface.
 
 @noindent Example:
@@ -1491,18 +1555,6 @@ registered for the respective service, Emacs releases its association
 to the service from D-Bus.
 @end defun
 
-@defun dbus-unregister-service bus service
-Unregister all objects from D-Bus @var{bus}, registered by Emacs for
-@var{service}.
-
-@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.  Emacs releases its association to @var{service} from
-D-Bus.
-@end defun
-
 
 @node Signals
 @chapter Sending and receiving signals.