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
spec-to-docbook.xsl
Description: XML document
<?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> <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"> <doc:doc><doc:summary>if TRUE, will return template names, otherwise will return configured servers</doc:summary></doc:doc> </arg> <arg type="as" name="servers" direction="out"> <doc:doc><doc:summary>array of configured server (or template) names</doc:summary></doc:doc> </arg> </method> <method name="GetConfig"> <doc:doc><doc:description>Get the configuration of a specific server (or template)</doc:description></doc:doc> <arg type="s" name="server" direction="in"> <doc:doc><doc:summary>server name</doc:summary></doc:doc> </arg> <arg type="b" name="template" direction="in"> <doc:doc><doc:summary>if TRUE, will return a matching template configuration, otherwise will return a matching server configuration</doc:summary></doc:doc> </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> </arg> </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"> <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> </arg> <arg type="u" name="count" direction="in"> <doc:doc><doc:summary>maximum number of returned reports</doc:summary></doc:doc> </arg> <arg type="aa{ss}" name="reports" direction="out"> <doc:doc><doc:summary>synchronization reports</doc:summary></doc:doc> <doc:doc><doc:description>The array contains report dictionaries. TODO: Document the keys used in the dictionaries in the array. This should be done by whoever implements this in the server.</doc:description></doc:doc> </arg> </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> <arg type="s" name="server" direction="in"> <doc:doc><doc:summary>server name</doc:summary></doc:doc> </arg> <arg type="o" name="session" direction="out"> <doc:doc><doc:summary>session D-Bus object path</doc:summary></doc:doc> </arg> </method> <method name="GetSessions"> <doc:doc><doc:description>Get currently existing 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> </method> <signal name="SessionChanged"> <doc:doc><doc:description>Session start or end</doc:description></doc:doc> <arg type="o" name="session"> <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> </arg> </signal> </interface> </node>
<?xml version="1.0"?> <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 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:description></doc:doc> <method name="GetConfig"> <doc:doc><doc:description>Get the configuration of the server</doc:description></doc:doc> <arg type="a{sa{ss}}" name="configuration" direction="out"> <doc:doc><doc:summary>server configuration</doc:summary></doc:doc> <doc:doc><doc:description>See Server.GetConfig() for dictionary description.</doc:description></doc:doc> </arg> </method> <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> </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> </arg> <arg type="a{sa{ss}}" name="configuration" direction="in"> <doc:doc><doc:summary>server configuration</doc:summary></doc:doc> <doc:doc><doc:description>See Server.GetConfig() for dictionary description.</doc:description></doc:doc> </arg> </method> <method name="GetReports"> <doc:doc><doc:description>Get synchronization reports for the server</doc:description></doc:doc> <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> </arg> <arg type="u" name="count" direction="in"> <doc:doc><doc:summary>maximum number of returned reports</doc:summary></doc:doc> </arg> <arg type="aa{ss}" name="reports" direction="out"> <doc:doc><doc:summary>synchronization reports</doc:summary></doc:doc> <doc:doc><doc:description>See Server.GetReports() for array description.</doc:description></doc:doc> </arg> </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> <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> </arg> <arg type="a{ss}" name="sources" direction="in"> <doc:doc><doc:summary>synchronization source modes</doc:summary></doc:doc> <doc:doc><doc:description>Source modes to override the 'mode' variable for specific sources. The dictionary key is source name, value is synchronization mode. Valid synchronization modes are all synchronization modes used in syncevolution server configuration files and the empty string.</doc:description></doc:doc> </arg> </method> <method name="Abort"> <doc:doc><doc:description>Abort synchronization. See Status-signal for results.</doc:description></doc:doc> </method> <method name="Suspend"> <doc:doc><doc:description>Suspend synchronization. See Status-signal for results.</doc:description></doc:doc> </method> <method name="Detach"> <doc:doc><doc:description>Detach from the session.</doc:description></doc:doc> </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> <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> </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> </arg> </method> <method name="GetProgress"> <doc:doc><doc:description>Get synchronization progress</doc:description></doc:doc> <arg type="i" name="progress" direction="out"> <doc:doc><doc:summary>Rough estimate of current progress 0-100.</doc:summary></doc:doc> </arg> <arg type="a{s(siiiiii)}" name="sources" direction="out"> <doc:doc><doc:summary>Synchronization source progress dictionary</doc:summary></doc:doc> <doc:doc><doc:description>Dictionary key is source name. The value structs contain phase (can be one of "", "preparing", "sending", "receiving"), prepare count, prepare total, send count, send total, receive count and receive total. -1 is used for unknown. Normally only the 'counts' increase but there are cases where the total will increase as well.</doc:description></doc:doc> </arg> </method> <signal name="StatusChanged"> <doc:doc><doc:description>Session status change. See GetStatus() for argument descriptions.</doc:description></doc:doc> <arg type="s" name="status"/> <arg type="u" name="error"/> <arg type="a{s(ssu)}" name="sources"/> </signal> <signal name="ProgressChanged"> <doc:doc><doc:description>Synchronization progress change. See GetProgress() for argument descriptions.</doc:description></doc:doc> <arg type="i" name="progress"/> <arg type="a{s(siiiiii)}" name="sources"/> </signal> </interface> </node>
_______________________________________________ SyncEvolution mailing list [email protected] http://lists.syncevolution.org/listinfo/syncevolution
