Re: [SyncEvolution] Session dbus api and documentation

On Mo, 2011-12-19 at 11:02 +0100, Chris Kühl wrote: Good catch. The docs are incomplete. In the patch which introduces the implementation, I added some comments to the documentation, but I missed completely that the actual documentation for Attach() and Detach() were missing. What is missing is something like: <method name="Attach"> <doc:doc> <doc:description> Prevents destruction of the session until the client detaches or quits. Implemented with a counter, so each Attach() must be matched by a Detach() to free the session. Meant to be used by clients which want to follow the progress of a session started by the daemon or some other client. StartSession() automatically includes one Attach() call, so typically the client which created a session never calls Attach() and Detach() only once. </doc:description> </method> <method name="Detach"> <doc:doc> <doc:description> Each Attach() or StartSession() must be matched by one Detach() call, otherwise the session will not be destructed. A client that quits without these calls will be detached automatically. </doc:description> </doc:doc> </method> For the record, here's the commit: commit 320e23e31d163e858ab4e03488b288350f336004 Author: Patrick Ohly <patrick.ohly(a)intel.com&gt; Date: Thu Sep 30 10:32:13 2010 +0200 D-Bus API: added missing Session.Attach() (BMC #7761) It was always part of the design that multiple clients can use any session. Somehow we forgot to implement Session.Attach(), the call that allows a client which hasn't started a session to register it's interest in the session. In particular, that session won't go away unless the client exits or detaches. This patch adds that missing call, a corresponding capability ("SessionAttach") and a unit test. The unit test covers recursive attach/detach, it does not actually verify that the session remains around. diff --git a/src/dbus/interfaces/syncevo-server-full.xml b/src/dbus/interfaces/syncevo-server-full.xml index 861357b..82ba84d 100644 --- a/src/dbus/interfaces/syncevo-server-full.xml +++ b/src/dbus/interfaces/syncevo-server-full.xml @@ -65,6 +65,12 @@ </doc:definition> </doc:item> + <doc:item><doc:term>SessionAttach</doc:term> + <doc:definition>Session.Attach() + implemented + </doc:definition> + </doc:item> + <doc:item><doc:term>Notifications</doc:term> <doc:definition>Server.DisableNotifications() and Server.EnableNotifications() implemented diff --git a/src/dbus/interfaces/syncevo-session-full.xml b/src/dbus/interfaces/syncevo-session-full.xml index d81862b..fb77ecb 100644 --- a/src/dbus/interfaces/syncevo-session-full.xml +++ b/src/dbus/interfaces/syncevo-session-full.xml @@ -2,8 +2,18 @@ <node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd"> <interface name="org.syncevolution.Session"> <doc:doc><doc:description> - <doc:para>A Session object is used to do do syncs and to modify the server configurations. Clients can create - <doc:para>Commands (other than Detach()) cannot be used before the status changes to "idle" (see GetStatus() a + <doc:para> + A Session object is used to do do syncs and to modify + the server configurations. Clients can create a Session with + Server.StartSession(), attach to a session started by some other + client with Session.Attach(), and detach from it with + Session.Detach(). + </doc:para> + <doc:para> + Commands (other than Attach() and Detach()) cannot be used + before the status changes to "idle" (see GetStatus() and + StatusChanged). + </doc:para> </doc:description></doc:doc> <method name="GetFlags"> -- Best Regards, Patrick Ohly The content of this message is my personal opinion only and although I am an employee of Intel, the statements I make here in no way represent Intel's position on the issue, nor am I authorized to speak on behalf of Intel on this matter.