From 8c904d82f5138a9a78065801cc48348a556f5b14 Mon Sep 17 00:00:00 2001 From: Michael Albinus Date: Mon, 10 Jan 2011 10:35:44 +0100 Subject: [PATCH] * dbus.texi (Receiving Method Calls): New function dbus-register-service. Rearrange node. --- doc/misc/ChangeLog | 5 +++ doc/misc/dbus.texi | 86 +++++++++++++++++++++++++++++++++++++--------- 2 files changed, 74 insertions(+), 17 deletions(-) diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 1acf8b0bbd..ca43b7e06d 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,8 @@ +2011-01-10 Jan Moringen + + * dbus.texi (Receiving Method Calls): New function + dbus-register-service. Rearrange node. + 2011-01-07 Paul Eggert * texinfo.tex: Update to version 2010-12-23.17 from gnulib, diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index 39f6221e2f..fe7918038e 100644 --- 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. -- 2.20.1