Hello!
I've done a full pass over the docs and merged them with the Connection
API.
Some comments about formatting: I suggest to use () after method names
in comments. Not sure what the convention here is elsewhere, both was
used in our docs.
Without word wrapping and indention the .xml files are hard to read. My
expectation is that extra white space is ignored by formatters, so I'd
prefer to reflow long paragraphs (in Emacs: TAB + ALT-Q). When updating
text, limit the amount of reformatting to keep diffs small.
The Docbook syntax might be wrong in some places. We'll sort this out
later.
About error reporting: we haven't specified any particular error
response when the API is used incorrectly or runs into errors, apart
from the sync status codes. I think that is sufficient, because other
errors are either internal or rare (like permission issues when trying
to write config files). Currently the implementation raises a
std::runtime_error exception with a string that explains the error, then
this is translated into a org.syncevolution.Exception error with that
string as detailed explanation.
On Tue, 2009-09-08 at 23:04 +0200, Patrick Ohly wrote:
Changes to be made:
* rename Session.Close() => Session.Detach(), because the session
might continue to exist. Later we might add a corresponding
Attach().
Was already partly done, with a reference to Close() remaining in a
Server comment.
* add more documentation; we've discussed plenty of stuff
around
these APIs which hasn't been written down yet
See below.
* merge with Connection API
Done.
Do we want to maintain one XML spec file per interface or one spec
file
for all of them? I have no idea what is easier to handle in libdbus-glib
or for merging docs later on.
Jussi?
------------------------------------------------------------------
commit aa15f80d88daadebeb66831652ad5528f792804c
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Wed Sep 9 09:55:21 2009 +0200
D-Bus API: merged Connection and UI API, several editorial changes
The config dictionary didn't mention the "source/" prefix in the keys.
GetReports(): numbering documented
StartSession(): Close()->Detach()
Connect(): added
GetSessions(): explained that "existing" includes active and queueing
sessions
SetConfig(): added more information what "clear" means for
"update=FALSE";
in the most extreme situation it can be used to remove configs.
Gave rationale for "temporary=TRUE".
Sync(): added examples for mode selection
GetStatus(): a session can be "done", which is a read-only state after a
sync.
In queueing and idle the configuration can change, so no
information about sources are provided.
diff --git a/src/dbus/interfaces/syncevo-connection-full.xml
b/src/dbus/interfaces/syncevo-connection-full.xml
new file mode 100644
index 0000000..9b4c541
--- /dev/null
+++ b/src/dbus/interfaces/syncevo-connection-full.xml
[...]
diff --git a/src/dbus/interfaces/syncevo-ng-full.xml
b/src/dbus/interfaces/syncevo-ng-full.xml
deleted file mode 100644
index d54439b..0000000
--- a/src/dbus/interfaces/syncevo-ng-full.xml
+++ /dev/null
[...]
diff --git a/src/dbus/interfaces/syncevo-server-full.xml
b/src/dbus/interfaces/syncevo-server-full.xml
index 0ef236e..f3bcd7a 100644
--- a/src/dbus/interfaces/syncevo-server-full.xml
+++ b/src/dbus/interfaces/syncevo-server-full.xml
@@ -1,7 +1,37 @@
<?xml version="1.0"?>
<node name="/"
xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
<interface name="org.syncevolution.Server">
- <doc:doc><doc:description>Server is the entry object for Syncevolution
client API. It can be used to query information and to start and monitor
sessions.</doc:description></doc:doc>
+ <doc:doc>
+ <doc:para>
+ Server is the entry object for SyncEvolution client API. It
+ can be used to query information and to start and monitor
+ sessions.
+ </doc:para>
+
+ <doc:para>
+ Sessions are required to modify the state of SyncEvolution and
+ to synchronize data. They are implemented by additional
+ objects, which exist as long as they are needed (= have
+ clients) or are executing (for example, running a sync
+ session).
+ </doc:para>
+
+ <doc:para>
+ A session must be active before it can be used. If there are
+ multiple conflicting session requests, they will be queued and
+ started one after the other. At the moment, SyncEvolution
+ will only run one session at a time, although the API would
+ allow concurrent sessions.
+ </doc:para>
+
+ <doc:para>
+ To be notified when a session is ready for use, subscribe to
+ the SessionChanged signal before asking for a session. It
+ may fire before the request to create a session returns. Either
+ handle that or use Session.GetStatus() to check whether the
+ session is still "queueing".
+ </doc:para>
+ </doc:doc>
<method name ="GetConfigs">
<doc:doc><doc:description>Get an array of all configured servers (or
templates)</doc:description></doc:doc>
@@ -23,7 +53,7 @@
</arg>
<arg type="a{sa{ss}}" name="configuration"
direction="out">
<doc:doc><doc:summary>server (or template)
configuration</doc:summary></doc:doc>
- <doc:doc><doc:description>The dictionary keys are source names and
the values are "source configuration dictionaries". An empty source name is used
for the server configuration. The "source configuration dictionary" contains
keys and values matching those in the syncevolution server configuration
files.</doc:description></doc:doc>
+ <doc:doc><doc:description>The dictionary keys are
"source/<source name>" for sources and the empty string for the main
server configuration. More keys might be added in the future. The values are
"configuration dictionaries" which contain keys and values matching those in the
SyncEvolution server configuration files.</doc:description></doc:doc>
</arg>
</method>
@@ -33,7 +63,7 @@
<doc:doc><doc:summary>server
name</doc:summary></doc:doc>
</arg>
<arg type="u" name="start" direction="in">
- <doc:doc><doc:summary>index of the first (newest) report that will be
returned</doc:summary></doc:doc>
+ <doc:doc><doc:summary>index of the first (newest) report that will be
returned; reports are number starting with zero for the
newest</doc:summary></doc:doc>
</arg>
<arg type="u" name="count" direction="in">
<doc:doc><doc:summary>maximum number of returned
reports</doc:summary></doc:doc>
@@ -45,7 +75,7 @@
</method>
<method name="StartSession">
- <doc:doc><doc:description>Start a session. The object is created
instantly but will not be ready for method calls until status changes from
"queueing" to "idle". The Close method can be called before
that.</doc:description></doc:doc>
+ <doc:doc><doc:description>Start a session. The object is created
instantly but will not be ready for method calls until status changes from
"queueing" to "idle". The Detach() method can be called before
that.</doc:description></doc:doc>
<arg type="s" name="server" direction="in">
<doc:doc><doc:summary>server
name</doc:summary></doc:doc>
</arg>
@@ -54,8 +84,130 @@
</arg>
</method>
+ <method name="Connect">
+ <doc:doc>
+ <doc:description>
+ <doc:para>
+ Establishes a connection between SyncEvolution and a peer
+ (SyncML client or server). That peer might contact
+ SyncEvolution via D-Bus directly (local sync) or via a
+ SyncEvolution server stub that acts as gateway between a
+ peer that is connected to the stub via some other
+ transport mechanism (remote sync). For SyncEvolution this
+ difference is almost completely transparent.
+ </doc:para>
+
+ <doc:para>
+ In contrast to connections established by SyncEvolution
+ itself, the peer has to send the first message and
+ SyncEvolution replies. If the first message is a normal
+ SyncML message, then SyncEvolution acts as SyncML server.
+ Alternatively, a Notification message can be sent to
+ request that SyncEvolution initiates a SyncML session as
+ client.
+ </doc:para>
+
+ <doc:para>
+ In the later case, SyncEvolution may or may not use the
+ connection established by Connect(), depending on the
+ content of that first message.
+ </doc:para>
+
+ <doc:para>
+ The result of Connect() is an object that implements the
+ org.syncevolution.Connection interface. It has to be used
+ for sending at least one message to start the sync. If
+ SyncEvolution needs to abort the connection, it will issue
+ the Close-signal and remove the object. A peer needs to
+ subscribe to that signal before starting to wait for a
+ reply. In addition, the client should also watch out for
+ SyncEvolution quitting unexpectedly.
+ </doc:para>
+
+ <doc:para>
+ SyncEvolution supports re-establishing a connection that was
+ interrupted. This only works when the peer is a SyncML
+ client, supports resending messages, and the non-D-Bus
+ message transport supports sending the session number as
+ part of the meta information.
+ </doc:para>
+ </doc:description>
+ </doc:doc>
+ <arg type="a{ss}" name="peer" direction="in">
+ <doc:doc>
+ <doc:summary>
+ Various information about the peer who initiated the
+ connection. All of it is optional unless explicitly
+ specified otherwise. Short, single line strings are
+ preferred.
+
+ "description" - a description of the peer in a format and
+ language that is understood by the user.
+
+ "id" - a unique ID for this particular peer, in a format
+ that is specific to the transport. The ID only has to be
+ unique among peers using that transport at the current
+ point in time.
+
+ "transport" - a string identifying the entity which talks
+ directly to SyncEvolution (peer or transport stub). If
+ available, this should be a D-Bus interface name, like
+ "org.openobex.obexd". The main purpose right now is for
+ informing the user and debugging. Later it might also be
+ used to call methods in that interface or for choosing a
+ local configuration for the peer based on its ID.
+
+ "transport_description" - could be used to describe the
+ version of the transport entity.
+ </doc:summary>
+ </doc:doc>
+ </arg>
+ <arg type="b" name="must_authenticate"
direction="in">
+ <doc:doc>
+ <doc:summary>
+ <doc:para>
+ If false, then the peer is trusted and shall be given
+ access to SyncEvolution without further checks by
+ SyncEvolution itself. This is useful for peers which
+ already run as local user processes with same access
+ rights to the data as SyncEvolution or for transports that
+ authenticate and authorize access via their own
+ mechanisms.
+ </doc:para>
+
+ <doc:para>
+ If true, then a SyncML client peer must provide valid
+ credentials as part of the SyncML session. For a server,
+ a valid configuration must exist. SyncEvolution searches
+ for such a configuration by matching the sync URL in
+ the Notification with sync URLs in the configurations.
+ </doc:para>
+ </doc:summary>
+ </doc:doc>
+ </arg>
+ <arg type="u" name="session" direction="in">
+ <doc:doc>
+ <doc:summary>
+ If this is a reconnect for an older session,
+ then pass the session number here. Otherwise
+ pass 0. New session numbers are created in
+ response to the initial message.
+ </doc:summary>
+ </doc:doc>
+ </arg>
+ <arg type="o" name="connection"
direction="out">
+ <doc:doc>
+ <doc:summary>
+ The connection object created by SyncEvolution in response
+ to this connection request. Implements the
+ org.syncevolution.Connection interface.
+ </doc:summary>
+ </doc:doc>
+ </arg>
+ </method>
+
<method name="GetSessions">
- <doc:doc><doc:description>Get currently existing
sessions</doc:description></doc:doc>
+ <doc:doc><doc:description>Get currently existing sessions. This
includes active and queueing sessions.</doc:description></doc:doc>
<arg type="ao" name="sessions"
direction="out">
<doc:doc><doc:summary>array of session D-Bus object
paths</doc:summary></doc:doc>
</arg>
@@ -67,7 +219,7 @@
<doc:doc><doc:summary>session D-Bus object
path</doc:summary></doc:doc>
</arg>
<arg type="b" name="started">
- <doc:doc><doc:summary>TRUE if session was started, FALSE if it
ended</doc:summary></doc:doc>
+ <doc:doc><doc:summary>TRUE if session was started and is active now
(= ready for use), FALSE if it ended</doc:summary></doc:doc>
</arg>
</signal>
diff --git a/src/dbus/interfaces/syncevo-session-full.xml
b/src/dbus/interfaces/syncevo-session-full.xml
index 522f74e..729bf35 100644
--- a/src/dbus/interfaces/syncevo-session-full.xml
+++ b/src/dbus/interfaces/syncevo-session-full.xml
@@ -3,7 +3,7 @@
<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 a Session with Server.StartSession() and detach from it
with Session.Detach().</doc:para>
- <doc:para>Commands (other than Detach) cannot be used before the status
changes to "idle" (see GetStatus() and StatusChanged).</doc:para>
+ <doc:para>Commands (other than Detach()) cannot be used before the status
changes to "idle" (see GetStatus() and StatusChanged).</doc:para>
</doc:description></doc:doc>
<method name="GetConfig">
@@ -17,10 +17,24 @@
<method name="SetConfig">
<doc:doc><doc:description>Set the configuration of the
server</doc:description></doc:doc>
<arg type="b" name="update" direction="in">
- <doc:doc><doc:summary>TRUE if existing configuration should be
updated. FALSE if existing configuration should be
cleared.</doc:summary></doc:doc>
+ <doc:doc><doc:summary>TRUE if existing configuration should be
updated. FALSE if existing configuration should be cleared.
+ "Cleared" in this context means that all existing
+ properties are removed before setting those passed as
+ argument. Configuration entries (the user-visible part as
+ well as the related meta information, plus the containing
+ directory if it is empty) which are not referenced by a
+ key in the configuration are removed. Setting a completely
+ empty configuration with "update=FALSE" can thus be used
+ to remove the entire
+ configuration.
+ </doc:summary></doc:doc>
</arg>
<arg type="b" name="temporary" direction="in">
- <doc:doc><doc:summary>TRUE if configuration changes should only be
used for the duration of the session.</doc:summary></doc:doc>
+ <doc:doc><doc:summary>TRUE if configuration changes should only be
used for the duration of the session.
+ This is useful to run a single sync session with different settings,
+ for example with an increased logging level. "update=FALSE" and
+ "temporary=TRUE" are mutually exclusive.
+ </doc:summary></doc:doc>
</arg>
<arg type="a{sa{ss}}" name="configuration"
direction="in">
<doc:doc><doc:summary>server
configuration</doc:summary></doc:doc>
@@ -43,7 +57,17 @@
</method>
<method name="Sync">
- <doc:doc><doc:description>Start synchronization. The synchronization
mode selection for sources works like this: Primarily, use mode from "sources"
array. If the source was not found or its mode was empty, use the mode parameter. If mode
parameter is empty, use the mode in
configuration.</doc:description></doc:doc>
+ <doc:doc><doc:description>Start synchronization. The synchronization
mode selection for sources works like this: Primarily, use mode from "sources"
array. If the source was not found or its mode was empty, use the mode parameter. If mode
parameter is empty, use the mode in configuration.
+ Examples:
+ * sync all with mode from config
+ Sync (NULL, ())
+ * refresh all from server
+ Sync ("refresh-from-server", ())
+ * force slow sync for calendar, use mode from config for others
+ Sync (NULL, (("calendar", "slow")))
+ * sync only calendar and addressbook, with mode from config
+ Sync ("none", (("calendar", NULL),
("addressbook", NULL)))
+ </doc:description></doc:doc>
<arg type="s" name="mode" direction="in">
<doc:doc><doc:summary>synchronization
mode</doc:summary></doc:doc>
<doc:doc><doc:description>Valid values are all synchronization modes
used in syncevolution server configuration files and the empty
string.</doc:description></doc:doc>
@@ -67,17 +91,17 @@
</method>
<method name="GetStatus">
- <doc:doc><doc:description>Get session status. Individual source
statuses are relevant only when status is "running", otherwise status covers all
sources.</doc:description></doc:doc>
+ <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">
<doc:doc><doc:summary>Session
status</doc:summary></doc:doc>
- <doc:doc><doc:description>Valid values include strings starting with
"queueing", "idle", "running", "aborting",
"suspending". The strings may contain an additional specifiers separated by a
semicolons: "running;processing", "suspending;waiting". There may be
several specifiers:
"running;waiting;foo"</doc:description></doc:doc>
+ <doc:doc><doc:description>Valid values include strings starting with
"queueing", "idle" (ready to execute commands), "running",
"aborting", "suspending", "done" (a sync was executed,
individual source statuses for that sync are available, session is now inactive and cannot
execute new commands). The strings may contain additional specifiers separated by a
semicolons: "running;processing", "suspending;waiting". There may be
several specifiers:
"running;waiting;foo"</doc:description></doc:doc>
</arg>
<arg type="u" name="error" direction="out">
<doc:doc><doc:summary>Error code for current or last action (zero for
no error).</doc:summary></doc:doc>
</arg>
<arg type="a{s(ssu)}" name="sources"
direction="out">
<doc:doc><doc:summary>Synchronization source status
dictionary</doc:summary></doc:doc>
- <doc:doc><doc:description>Dictionary key is source name. The value
structs contain synchronization mode, source status and error code. Valid values for
status are the same as for status parameter above, plus "done" to represent a
synced source when the whole sync is still
non-idle.</doc:description></doc:doc>
+ <doc:doc><doc:description>Dictionary key is source name. The value
structs contain synchronization mode, source status and error code. Valid values for
status are the same as for status parameter above. "done" represents a synced
source when the whole sync is not done yet.</doc:description></doc:doc>
</arg>
</method>
------------------------------------------------------------------
--
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.