From 0fadf00e5407105579c551f495a6d2424536184a Mon Sep 17 00:00:00 2001 From: Michael Albinus Date: Tue, 4 Jan 2011 13:38:33 +0100 Subject: [PATCH] * dbus.texi (Receiving Method Calls): Describe new optional parameter dont-register-service of dbus-register-{method,property}. --- doc/misc/ChangeLog | 5 +++++ doc/misc/dbus.texi | 32 ++++++++++++++++++++++++-------- 2 files changed, 29 insertions(+), 8 deletions(-) diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 655262d5301..39ca2b2b382 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,8 @@ +2011-01-04 Jan Moringen + + * dbus.texi (Receiving Method Calls): Describe new optional + parameter dont-register-service of dbus-register-{method,property}. + 2010-12-17 Daiki Ueno * epa.texi (Encrypting/decrypting *.gpg files): Mention diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index 6f6a897e6dc..39f6221e2f2 100644 --- a/doc/misc/dbus.texi +++ b/doc/misc/dbus.texi @@ -9,7 +9,8 @@ @syncodeindex fn cp @copying -Copyright @copyright{} 2007, 2008, 2009, 2010 Free Software Foundation, Inc. +Copyright @copyright{} 2007, 2008, 2009, 2010, +2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1264,7 +1265,7 @@ paths, used by offered methods or signals, shall start with this string. @end deffn -@defun dbus-register-method bus service path interface method handler +@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}. @@ -1272,10 +1273,11 @@ With this function, an application registers @var{method} on the D-Bus @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{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. +@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}. @@ -1294,6 +1296,13 @@ 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 @@ -1368,7 +1377,7 @@ The test runs then @end example @end defun -@defun dbus-register-property bus service path interface property access value &optional emits-signal +@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}. @@ -1378,8 +1387,8 @@ With this function, an application declares a @var{property} on the D-Bus @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{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}. @@ -1401,6 +1410,13 @@ The interface @samp{org.freedesktop.DBus.Properties} is added to @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 -- 2.39.5