changeset 112179:57d3123a1003

* dbus.texi (Receiving Method Calls): New function dbus-register-service. Rearrange node.

--- a/doc/misc/ChangeLog	Sun Jan 09 16:35:53 2011 -0500
+++ b/doc/misc/ChangeLog	Mon Jan 10 10:35:44 2011 +0100
@@ -1,3 +1,8 @@
[phone]  Jan Moringen  <[e-mail]>
+
+	* dbus.texi (Receiving Method Calls): New function
+	dbus-register-service.  Rearrange node.
+
 2011-01-07  Paul Eggert  <[e-mail]>
 
 	* texinfo.tex: Update to version 2010-12-23.17 from gnulib,

--- a/doc/misc/dbus.texi	Sun Jan 09 16:35:53 2011 -0500
+++ b/doc/misc/dbus.texi	Mon Jan 10 10:35:44 2011 +0100
@@ -1244,9 +1244,73 @@
 @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 @@
 @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 @@
 @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 @@
 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.