4:20 a.m.
Hello!
Is this API okay? It's in the "dbus-api" branch, please comment and/or
suggest further patches.
commit 35f555809d79dec0a6e012a2706a3b72c54bd563
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Fri Sep 11 20:03:44 2009 +0200
D-Bus API: added support for monitoring presence of servers
The D-Bus server contains the transports which exchange messages
with a SyncML server. Therefore it should also implement the
network monitoring. The API is meant to also cover Bluetooth
peers where the transport might be available, but not the
specific device.
Because the D-Bus server cannot determine whether there is
anyone subscribed to the Presence signal, clients need to
attach to the server if they want it to keep sending that
signal instead of shutting down.
diff --git a/src/dbus/interfaces/syncevo-server-full.xml
b/src/dbus/interfaces/syncevo-server-full.xml
index cc8c91f..9a3d132 100644
--- a/src/dbus/interfaces/syncevo-server-full.xml
+++ b/src/dbus/interfaces/syncevo-server-full.xml
@@ -33,6 +33,28 @@
</doc:para>
</doc:doc>
+ <method name="Attach">
+ <doc:doc>
+ <doc:description>
+ With no client attached, the server will shut down after a
+ certain period of inactivity. Attaching to the server
+ prevents that. Attaching is not necessary to invoke methods.
+ The main purpose is to keep the server running while clients
+ are around and listen for signals, in particular the
+ Presence signal.
+ </doc:description>
+ </doc:doc>
+ </method>
+
+ <method name="Detach">
+ <doc:doc>
+ <doc:description>
+ Detaches an attached client. A client which disconnects
+ from D-Bus is automatically detached from the server.
+ </doc:description>
+ </doc:doc>
+ </method>
+
<method name ="GetConfigs">
<doc:doc><doc:description>Get an array of all configured servers (or
templates)</doc:description></doc:doc>
<arg type="b" name="template" direction="in">
@@ -65,6 +87,19 @@
</arg>
</method>
+ <method name="CheckPresence">
+ <doc:doc><doc:description>Checks whether a sync with a particular
server can start.</doc:description></doc:doc>
+ <arg type="s" name="server" direction="in">
+ <doc:doc><doc:summary>server
name</doc:summary></doc:doc>
+ </arg>
+ <arg type="s" name="status">
+ <doc:doc>
+ <doc:summary>
+ See Presence signal for details.
+ </doc:summary>
+ </doc:doc>
+ </method>
+
<method name="GetReports">
<doc:doc><doc:description>Get synchronization reports for a specific
server</doc:description></doc:doc>
<arg type="s" name="server" direction="in">
@@ -231,5 +266,39 @@
</arg>
</signal>
+ <signal name="Presence">
+ <doc:doc>
+ <doc:description>
+ Indicates whether a server can be reached right now. This
+ signal can be used by GUIs to prevent starting a sync when
+ it is known to fail, for example because the network is
+ currently down.
+
+ At the moment, the SyncEvolution server can only monitor
+ network connectivity, which is a cheap local operation and
+ thus done unconditionally while the server runs (see
+ Attach()). Detecting the presence of non-HTTP-based peers
+ might be more costly. Additional APIs might be added to turn
+ that on only when needed. The CheckPresence() method will
+ always force a check.
+ </doc:description>
+ </doc:doc>
+ <arg type="s" name="server">
+ <doc:doc><doc:summary>name of the server
configuration</doc:summary></doc:doc>
+ </arg>
+ <arg type="s" name="status">
+ <doc:doc>
+ <doc:summary>
+ "no transport" - the transport necessary to reach the server is not
working.
+ "not present" - the server is known to be down or unreachable.
+ "" - the server might be usable. Syncs can still fail.
+ Other non-empty strings might be added in the future. They always
+ indicate a condition which prevents syncing.
+ </doc:summary>
+ </doc:doc>
+ </arg>
+
+ </signal>
+
</interface>
</node>
diff --git a/src/dbus/interfaces/syncevo-session-full.xml
b/src/dbus/interfaces/syncevo-session-full.xml
index 729bf35..9e8445d 100644
--- a/src/dbus/interfaces/syncevo-session-full.xml
+++ b/src/dbus/interfaces/syncevo-session-full.xml
@@ -90,6 +90,16 @@
<doc:doc><doc:description>Detach from the
session.</doc:description></doc:doc>
</method>
+ <method name="CheckPresence">
+ <doc:doc><doc:description>Checks whether a sync with the current server
can start.</doc:description></doc:doc>
+ <arg type="s" name="status">
+ <doc:doc>
+ <doc:summary>
+ See org.syncevolution.Server Presence signal for details.
+ </doc:summary>
+ </doc:doc>
+ </method>
+
<method name="GetStatus">
<doc:doc><doc:description>Get session status. Individual source
statuses are relevant and provided only when status is neither "queuing" nor
"idle".</doc:description></doc:doc>
<arg type="s" name="status" direction="out">