1:20 p.m.
Hi all,
I'm mailing the dbus xml files now so Patrick and Yongsheng can continue...
Changes since last version:
* Changed some arrays to dictionaries. Original reasoning was that
every item in an array that contains sources will always be used so
dictionary brings no improvement. Practical tests show otherwise,
dictionaries are still nicer.
In practice it means source array "a(sssu)" turns into "a{s(ssu)}"
with source name being the dictionary key.
* config dictionaries use "" for the main config and
"sources/<source>"
for source configs.
* SetConfig() now has "boolean temporary" parameter
* Server.GetSessions and Server.SessionChanged now have equivalent
content (basically only the object path).
Open issues:
I think the api is in pretty good shape from my point of view, I've
rebuilt most of the client wrapper object with this for testing
purposes. The last item on the list above is still nagging me a bit,
feel free to take a look... I _think_ we don't need the information on
which session(s) are not "queueing" (so, which one is actually syncing
at the moment) in the Server object but I'm not absolutely sure. The
info is available by hooking into Session object anyway.
Handling passwords... Patrick, maybe we can go through this on thursday
so we don't miss any corner cases?
Docs:
The xsl is the counterpart for spec-strip-docs.xsl in the repo, it
creates docbook documentation from the xml files:
%-doc.xml: %-full.xml
$(XSLT) -o $@ $(srcdir)/spec-to-docbook.xsl $<
The docbook can be used by gtkdoc or you can just call docbook2*
converters (which are found in docbook-utils in Debian).
- Jussi
10:04 p.m.
Hello!
I have merged this into a heavily rebased (and squashed) "dbus-api"
branch. I imported all of the libgdbus history into the "gdbus" branch,
similar to how syncclient-sample-config.xml is synchronized with
Synthesis upstream. "dbus-api" is now based on that branch.
The old syncevo-full.xml is still present. Needs to be removed later on
together with adapting the sync-ui, when Jussi is ready. It's safe to
base work on "dbus-api" again, we'll coordinate the next rebasing.
Changes to be made:
* rename Session.Close() => Session.Detach(), because the session
might continue to exist. Later we might add a corresponding
Attach().
* add more documentation; we've discussed plenty of stuff around
these APIs which hasn't been written down yet
* merge with Connection API
I'll get to this tomorrow morning, before leaving for London.
Yongsheng, if you can, please review the branch as it exists right now.
I'd like to merge it as soon as we are done with 0.9.1.
On Tue, 2009-09-08 at 13:20 +0100, Jussi Kukkonen wrote:
[...]
Open issues:
I think the api is in pretty good shape from my point of view, I've
rebuilt most of the client wrapper object with this for testing
purposes. The last item on the list above is still nagging me a bit,
feel free to take a look...
You mean this one?
* Server.GetSessions and Server.SessionChanged now have equivalent
content (basically only the object path)
What exactly nags you about this? That GetSessions() doesn't distinguish
between queued and started sessions?
Handling passwords... Patrick, maybe we can go through this on
thursday
so we don't miss any corner cases?
Yes. Yongsheng's work is relevant for this. I expect that the D-Bus
server will become a proxy for a UI running in a client.
Docs:
The xsl is the counterpart for spec-strip-docs.xsl in the repo, it
creates docbook documentation from the xml files:
%-doc.xml: %-full.xml
$(XSLT) -o $@ $(srcdir)/spec-to-docbook.xsl $<
The docbook can be used by gtkdoc or you can just call docbook2*
converters (which are found in docbook-utils in Debian).
When I invoke "docbook2txt syncevo-server-doc.xml" (to take just one
example) it prints an error and doesn't produce any output:
Using catalogs: /etc/sgml/catalog
Using stylesheet: /usr/share/docbook-utils/docbook-utils.dsl#html
Working on:
/scratch/work/syncevolution/src/dbus/interfaces/syncevo-server-doc.xml
jade:/usr/share/sgml/declaration/xml.dcl:31:27:W: characters in the document
character set with numbers exceeding 65535 not supported
jade:/scratch/work/syncevolution/src/dbus/interfaces/syncevo-server-doc.xml:2:0:E:
no document type declaration; will parse without validation
Done.
According to the man page, XML input files are not supported. I suppose
this will have to wait.
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.
--
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.
1:55 a.m.
Yongsheng, if you can, please review the branch as it exists right
now.
I'd like to merge it as soon as we are done with 0.9.1.
Ok, no problem.
Actually I've been reading it since this Monday. :)
Cheers,
Yongsheng
-----Original Message-----
From: syncevolution-bounces(a)syncevolution.org
[mailto:syncevolution-bounces@syncevolution.org] On Behalf Of Patrick Ohly
Sent: Wednesday, September 09, 2009 5:05 AM
To: Jussi Kukkonen
Cc: SyncEvolution
Subject: Re: [SyncEvolution] dbus api specification
Hello!
I have merged this into a heavily rebased (and squashed) "dbus-api"
branch. I imported all of the libgdbus history into the "gdbus" branch,
similar to how syncclient-sample-config.xml is synchronized with
Synthesis upstream. "dbus-api" is now based on that branch.
The old syncevo-full.xml is still present. Needs to be removed later on
together with adapting the sync-ui, when Jussi is ready. It's safe to
base work on "dbus-api" again, we'll coordinate the next rebasing.
Changes to be made:
* rename Session.Close() => Session.Detach(), because the session
might continue to exist. Later we might add a corresponding
Attach().
* add more documentation; we've discussed plenty of stuff around
these APIs which hasn't been written down yet
* merge with Connection API
I'll get to this tomorrow morning, before leaving for London.
Yongsheng, if you can, please review the branch as it exists right now.
I'd like to merge it as soon as we are done with 0.9.1.
On Tue, 2009-09-08 at 13:20 +0100, Jussi Kukkonen wrote:
[...]
Open issues:
I think the api is in pretty good shape from my point of view, I've
rebuilt most of the client wrapper object with this for testing
purposes. The last item on the list above is still nagging me a bit,
feel free to take a look...
You mean this one?
* Server.GetSessions and Server.SessionChanged now have equivalent
content (basically only the object path)
What exactly nags you about this? That GetSessions() doesn't distinguish
between queued and started sessions?
Handling passwords... Patrick, maybe we can go through this on
thursday
so we don't miss any corner cases?
Yes. Yongsheng's work is relevant for this. I expect that the D-Bus
server will become a proxy for a UI running in a client.
Docs:
The xsl is the counterpart for spec-strip-docs.xsl in the repo, it
creates docbook documentation from the xml files:
%-doc.xml: %-full.xml
$(XSLT) -o $@ $(srcdir)/spec-to-docbook.xsl $<
The docbook can be used by gtkdoc or you can just call docbook2*
converters (which are found in docbook-utils in Debian).
When I invoke "docbook2txt syncevo-server-doc.xml" (to take just one
example) it prints an error and doesn't produce any output:
Using catalogs: /etc/sgml/catalog
Using stylesheet: /usr/share/docbook-utils/docbook-utils.dsl#html
Working on:
/scratch/work/syncevolution/src/dbus/interfaces/syncevo-server-doc.xml
jade:/usr/share/sgml/declaration/xml.dcl:31:27:W: characters in the document
character set with numbers exceeding 65535 not supported
jade:/scratch/work/syncevolution/src/dbus/interfaces/syncevo-server-doc.xml:2:0:E:
no document type declaration; will parse without validation
Done.
According to the man page, XML input files are not supported. I suppose
this will have to wait.
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.
--
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.
_______________________________________________
SyncEvolution mailing list
SyncEvolution(a)syncevolution.org
http://lists.syncevolution.org/listinfo/syncevolution
7:09 a.m.
Hi,
A nice and smart framework to use libgdbus for C++. I am fascinated by the design in
gdbus-cxx-bridge.h.
I see many classes or methods definition like 'xxx0', 'xxx1',
'xxx2', etc. It would be helpful if a tool could be
used to generate them like dbus-binding-tool in glib.
I find 'org.syncevolution.server' interface is defined in
'syncevo-ng-full.xml'.
But 'syncevo-server-full.xml' also defines this interface but with some other
methods.
What is the purpose to split it into 2 places?
Cheers,
Yongsheng
-----Original Message-----
From: syncevolution-bounces(a)syncevolution.org
[mailto:syncevolution-bounces@syncevolution.org] On Behalf Of Zhu, Yongsheng
Sent: Wednesday, September 09, 2009 8:55 AM
To: Ohly, Patrick; Jussi Kukkonen
Cc: SyncEvolution
Subject: Re: [SyncEvolution] dbus api specification
Yongsheng, if you can, please review the branch as it exists right
now.
I'd like to merge it as soon as we are done with 0.9.1.
Ok, no problem.
Actually I've been reading it since this Monday. :)
Cheers,
Yongsheng
-----Original Message-----
From: syncevolution-bounces(a)syncevolution.org
[mailto:syncevolution-bounces@syncevolution.org] On Behalf Of Patrick Ohly
Sent: Wednesday, September 09, 2009 5:05 AM
To: Jussi Kukkonen
Cc: SyncEvolution
Subject: Re: [SyncEvolution] dbus api specification
Hello!
I have merged this into a heavily rebased (and squashed) "dbus-api"
branch. I imported all of the libgdbus history into the "gdbus" branch,
similar to how syncclient-sample-config.xml is synchronized with
Synthesis upstream. "dbus-api" is now based on that branch.
The old syncevo-full.xml is still present. Needs to be removed later on
together with adapting the sync-ui, when Jussi is ready. It's safe to
base work on "dbus-api" again, we'll coordinate the next rebasing.
Changes to be made:
* rename Session.Close() => Session.Detach(), because the session
might continue to exist. Later we might add a corresponding
Attach().
* add more documentation; we've discussed plenty of stuff around
these APIs which hasn't been written down yet
* merge with Connection API
I'll get to this tomorrow morning, before leaving for London.
Yongsheng, if you can, please review the branch as it exists right now.
I'd like to merge it as soon as we are done with 0.9.1.
On Tue, 2009-09-08 at 13:20 +0100, Jussi Kukkonen wrote:
[...]
Open issues:
I think the api is in pretty good shape from my point of view, I've
rebuilt most of the client wrapper object with this for testing
purposes. The last item on the list above is still nagging me a bit,
feel free to take a look...
You mean this one?
* Server.GetSessions and Server.SessionChanged now have equivalent
content (basically only the object path)
What exactly nags you about this? That GetSessions() doesn't distinguish
between queued and started sessions?
Handling passwords... Patrick, maybe we can go through this on
thursday
so we don't miss any corner cases?
Yes. Yongsheng's work is relevant for this. I expect that the D-Bus
server will become a proxy for a UI running in a client.
Docs:
The xsl is the counterpart for spec-strip-docs.xsl in the repo, it
creates docbook documentation from the xml files:
%-doc.xml: %-full.xml
$(XSLT) -o $@ $(srcdir)/spec-to-docbook.xsl $<
The docbook can be used by gtkdoc or you can just call docbook2*
converters (which are found in docbook-utils in Debian).
When I invoke "docbook2txt syncevo-server-doc.xml" (to take just one
example) it prints an error and doesn't produce any output:
Using catalogs: /etc/sgml/catalog
Using stylesheet: /usr/share/docbook-utils/docbook-utils.dsl#html
Working on:
/scratch/work/syncevolution/src/dbus/interfaces/syncevo-server-doc.xml
jade:/usr/share/sgml/declaration/xml.dcl:31:27:W: characters in the document
character set with numbers exceeding 65535 not supported
jade:/scratch/work/syncevolution/src/dbus/interfaces/syncevo-server-doc.xml:2:0:E:
no document type declaration; will parse without validation
Done.
According to the man page, XML input files are not supported. I suppose
this will have to wait.
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.
--
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.
_______________________________________________
SyncEvolution mailing list
SyncEvolution(a)syncevolution.org
http://lists.syncevolution.org/listinfo/syncevolution
_______________________________________________
SyncEvolution mailing list
SyncEvolution(a)syncevolution.org
http://lists.syncevolution.org/listinfo/syncevolution
7:47 a.m.
On Wed, 2009-09-09 at 07:09 +0100, Zhu, Yongsheng wrote:
A nice and smart framework to use libgdbus for C++. I am fascinated
by the design in gdbus-cxx-bridge.h.
I see many classes or methods definition like 'xxx0', 'xxx1',
'xxx2', etc. It would be helpful if a tool could be
used to generate them like dbus-binding-tool in glib.
It would have saved me about half a day of cut-and-paste. Writing a
script might have taken longer, so I went for the low-tech approach. Not
running any kind of tool during the build process was part of the design
goals, so the script would only be used to update the bridge header in
the repo.
I find 'org.syncevolution.server' interface is defined in
'syncevo-ng-full.xml'.
But 'syncevo-server-full.xml' also defines this interface but with some other
methods.
What is the purpose to split it into 2 places?
I haven't merged yet because I ran out of time yesterday evening ;-)
Will do so now.
--
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.
9:10 a.m.
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.
11:20 a.m.
Patrick Ohly wrote:
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.
This is quite possible, I'm not an expert on this.
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.
Previously I used these dbus errors
"org.Moblin.SyncEvolution.GenericError"
"org.Moblin.SyncEvolution.NoSuchServer" -specified config does not exist
"org.Moblin.SyncEvolution.MissingArgs" -should probably be InvalidArgs
"org.Moblin.SyncEvolution.InvalidCall" -e.g. calling Abort when not syncing
Of those I actually check for NoSuchServer and InvalidCall in the client.
> * 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?
It was useful for the server binding/glue generation, but we're not
doing them anymore and client bindings do not actually benefit from the
separation... So one file is fine for me.
- Jussi
2:01 a.m.
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.
This is quite possible, I'm not an expert on this.
Maybe I could help this.
Previous this project, I'm a developer of XSLT compiler.
Could you tell me which file and what errors do you find?
Cheers,
Yongsheng
-----Original Message-----
From: syncevolution-bounces(a)syncevolution.org
[mailto:syncevolution-bounces@syncevolution.org] On Behalf Of Jussi Kukkonen
Sent: Wednesday, September 09, 2009 6:20 PM
To: SyncEvolution
Subject: Re: [SyncEvolution] dbus api specification
Patrick Ohly wrote:
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.
This is quite possible, I'm not an expert on this.
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.
Previously I used these dbus errors
"org.Moblin.SyncEvolution.GenericError"
"org.Moblin.SyncEvolution.NoSuchServer" -specified config does not exist
"org.Moblin.SyncEvolution.MissingArgs" -should probably be InvalidArgs
"org.Moblin.SyncEvolution.InvalidCall" -e.g. calling Abort when not syncing
Of those I actually check for NoSuchServer and InvalidCall in the client.
> * 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?
It was useful for the server binding/glue generation, but we're not
doing them anymore and client bindings do not actually benefit from the
separation... So one file is fine for me.
- Jussi
_______________________________________________
SyncEvolution mailing list
SyncEvolution(a)syncevolution.org
http://lists.syncevolution.org/listinfo/syncevolution
7:14 a.m.
Is it the error when runing ' xsltproc spec-to-docbook.xsl
syncevo-server-full.xml'?
Please use the below patch to remove errors. Thanks
diff --git a/src/dbus/interfaces/syncevo-server-full.xml
b/src/dbus/interfaces/syncevo-server-full.xml
index f3bcd7a..2cd1235 100644
--- a/src/dbus/interfaces/syncevo-server-full.xml
+++ b/src/dbus/interfaces/syncevo-server-full.xml
@@ -53,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/<source name>" for sources and the empty string
+ <doc:doc><doc:description>The dictionary keys are
"source/<source name>" for sources and the empty
</arg>
</method>
Cheers,
Yongsheng
-----Original Message-----
From: syncevolution-bounces(a)syncevolution.org
[mailto:syncevolution-bounces@syncevolution.org] On Behalf Of Zhu, Yongsheng
Sent: Thursday, September 10, 2009 9:02 AM
To: Jussi Kukkonen; SyncEvolution
Subject: Re: [SyncEvolution] dbus api specification
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.
This is quite possible, I'm not an expert on this.
Maybe I could help this.
Prior to this project, I'm a developer of XSLT compiler.
Could you tell me which file and what errors do you find?
Cheers,
Yongsheng
-----Original Message-----
From: syncevolution-bounces(a)syncevolution.org
[mailto:syncevolution-bounces@syncevolution.org] On Behalf Of Jussi Kukkonen
Sent: Wednesday, September 09, 2009 6:20 PM
To: SyncEvolution
Subject: Re: [SyncEvolution] dbus api specification
Patrick Ohly wrote:
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.
This is quite possible, I'm not an expert on this.
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.
Previously I used these dbus errors
"org.Moblin.SyncEvolution.GenericError"
"org.Moblin.SyncEvolution.NoSuchServer" -specified config does not exist
"org.Moblin.SyncEvolution.MissingArgs" -should probably be InvalidArgs
"org.Moblin.SyncEvolution.InvalidCall" -e.g. calling Abort when not syncing
Of those I actually check for NoSuchServer and InvalidCall in the client.
> * 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?
It was useful for the server binding/glue generation, but we're not
doing them anymore and client bindings do not actually benefit from the
separation... So one file is fine for me.
- Jussi
_______________________________________________
SyncEvolution mailing list
SyncEvolution(a)syncevolution.org
http://lists.syncevolution.org/listinfo/syncevolution
_______________________________________________
SyncEvolution mailing list
SyncEvolution(a)syncevolution.org
http://lists.syncevolution.org/listinfo/syncevolution
7:34 a.m.
On Thu, 2009-09-10 at 02:01 +0100, Zhu, Yongsheng wrote:
> > 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.
> This is quite possible, I'm not an expert on this.
I was more concerned about my own lack of experience with the DocBook
syntax than Jussi's ;-)
Maybe I could help this. Previous this project, I'm a developer
of XSLT compiler.
Could you tell me which file and what errors do you find?
I wasn't aware of any specific problem, but I expect that there will be
once we try to convert the docs that we write now. The one you found and
fixed in your other email is just the first step (extracting the pure
DocBook XML). We also have to find a way how we combine these DocBook
fragments into a coherent API documentation which also includes the C++
Doxygen documentation.
Regarding that fix, please apply it to "dbus-api" and push. We can treat
"dbus-api" much like master right now, except that we'll clean it up
once more before merging. Therefore code reviews can be done on
"dbus-api", we don't need further feature branches.
--
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.
9:37 p.m.
Hello!
Another clarification...
commit 439f27574a0b2bc97074141959a0569e943d689c
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Mon Sep 14 22:31:33 2009 +0200
D-Bus API: added clarification for temporary config changes
It's debateable whether temporary config changes should
affect future GetConfig or SetConfig calls. Let's keep it
simple and define that they don't, which is in line with
the original motivation of using them only for syncs.
Once we add status queries, they might also be applied to those.
diff --git a/src/dbus/interfaces/syncevo-session-full.xml
b/src/dbus/interfaces/syncevo-session-full.xml
index 9e8445d..f7ec758 100644
--- a/src/dbus/interfaces/syncevo-session-full.xml
+++ b/src/dbus/interfaces/syncevo-session-full.xml
@@ -33,7 +33,8 @@
<doc:doc><doc:summary>TRUE if configuration changes should only be
used for the duration of the
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.
+ "temporary=TRUE" are mutually exclusive. Temporary config changes
+ do not affect getting or setting permanent configurations.
</doc:summary></doc:doc>
</arg>
<arg type="a{sa{ss}}" name="configuration"
direction="in">
--
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.
8:42 a.m.
New subject: [SyncEvolution] dbus api specification: errors
On Wed, 2009-09-09 at 11:20 +0100, Jussi Kukkonen wrote:
Previously I used these dbus errors
"org.Moblin.SyncEvolution.GenericError"
"org.Moblin.SyncEvolution.NoSuchServer" -specified config does not
exist
"org.Moblin.SyncEvolution.MissingArgs" -should probably be InvalidArgs
"org.Moblin.SyncEvolution.InvalidCall" -e.g. calling Abort when not
syncing
Of those I actually check for NoSuchServer and InvalidCall in the
client.
I've add the following comment to the spec:
<doc:para>
Method calls may fail with the following errors:
"org.syncevolution.Exception" - catch-all error condition.
"org.syncevolution.NoSuchConfig" - server configuration name is invalid
"org.syncevolution.NoSuchSource" - source name is invalid
"org.syncevolution.InvalidCall" - a call is (perhaps no longer) allowed
or suitable in the current situation, like Detach() when the client
is not attached.
</doc:para>
org.syncevolution.Exception is already used in the new
syncevo-dbus-server, in all cases. So we need to turn some of the other
cases into more specific errors.
--
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.
8:47 p.m.
Hello!
Something I stumbled about while working on the server's support for
config property filtering...
commit 752d212f6dc2be3fb69299bb7561653f39dc1f87
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Mon Sep 14 21:44:00 2009 +0200
D-Bus API: property names are case insensitive
We cannot specify it in D-Bus (only has case sensitive
dictionaries), but the config property names are case
insensitive. Added a warning for API users about this.
diff --git a/src/dbus/interfaces/syncevo-server-full.xml
b/src/dbus/interfaces/syncevo-server-full.xml
index 9a3d132..239fee7 100644
--- a/src/dbus/interfaces/syncevo-server-full.xml
+++ b/src/dbus/interfaces/syncevo-server-full.xml
@@ -82,6 +82,11 @@
values will always use the default value, even after that
changed during a software update. Properties that are set
always use the chosen value.
+
+ Note that property keys are case insensitive. The D-Bus
+ interface specification would allow to send two
+ properties whose keys only differ in case to the
+ server. The result is undefined.
</doc:description>
</doc:doc>
</arg>
--
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.
11:31 a.m.
Hello!
FYI, here's a clarification for the config handling in the new D-Bus
API.
commit f549ce9468fd7950845699f7b3db685941a0e325
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Fri Sep 11 12:26:33 2009 +0200
D-Bus API: unset property clarification
Unset properties are not present in the configuration dictionaries
at all. This is semantically different from set to empty string,
which would be the alternative. A "None" or "NULL" string
unfortunately
doesn't exist in D-Bus (AFAIK).
diff --git a/src/dbus/interfaces/syncevo-server-full.xml
b/src/dbus/interfaces/syncevo-server-full.xml
index f3bcd7a..cc8c91f 100644
--- a/src/dbus/interfaces/syncevo-server-full.xml
+++ b/src/dbus/interfaces/syncevo-server-full.xml
@@ -53,7 +53,15 @@
</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/<source name>" for sources and the empty string for the main
+ <doc:doc><doc:description>The dictionary keys are
"source/<source name>" for sources and the empty string for the main
+ Properties which are not set are also not present in the
+ configuration dictionaries. The semantic difference between
+ "not set" and "empty" or "set to default" is
that unset
+ values will always use the default value, even after that
+ changed during a software update. Properties that are set
+ always use the chosen value.
+ </doc:description>
+ </doc:doc>
</arg>
</method>
4712
days inactive
4728
days old
syncevolution@synevolution.org
13 comments
3 participants
participants (3)
-
Jussi Kukkonen -
Patrick Ohly -
Zhu, Yongsheng