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&gt; 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">