<?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(), 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">
      <doc:doc>
        <doc:description>
          Get the session flags set with Server.StartSessionWithFlags().
        </doc:description>
      </doc:doc>
      <arg type="as" name="flags" direction="out">
        <doc:doc><doc:summary>session flags</doc:summary></doc:doc>
      </arg>
    </method>

    <method name="GetConfigName">
      <doc:doc>
        <doc:description>
          <doc:para>Get the configuration name of the session.</doc:para>
          <doc:para>Every session is associated with a specific
            configuration, as requested by the creator of the
            session. This call returns the normalized configuration
            name. Note that this may be different from the name used
            when creating the configuration, because that name is not
            required to be normalized. Therefore this method may be
            useful both for the creator of the session and other
            clients which cannot know the configuration name without
            calling this method.</doc:para>
        </doc:description>
      </doc:doc>
      <arg type="s" name="config" direction="out">
        <doc:doc><doc:summary>peer configuration name</doc:summary></doc:doc>
      </arg>
    </method>  

    <method name="GetConfig">
      <doc:doc><doc:description>Get the configuration identified by the name given to StartSession()</doc:description></doc:doc>
      <arg type="b" name="getTemplate" direction="in">
        <doc:doc><doc:summary>if TRUE, will return a matching template configuration, otherwise will return the stored configuration</doc:summary></doc:doc>
      </arg>
      <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>
      <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="QStringMultiMap"/>
    </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.
            "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.

            "Completely empty" means "no entries at all" ({} in Python
            notation). This is different from a config with no properties
            set ({"": {}} = sync properties reset to defaults, no sources;
            {"": {}, "source/addressbook": {}} = same, with address book
            reset to defaults).

            When a specific peer was selected via the configuration
            name, clearing and removing properties is done only
            for the peer-specific properties.

            When no specific peer was selected, setting an empty
            configuration with "update=FALSE" removes all source
            settings and all peers. This allows starting from scratch;
            setting a non-empty configuration with "update=FALSE"
            will replace the peer-independent source properties with
            those that are sent in the new configuration and remove
            the sources which are not listed, also in all peers.
        </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.
            This is useful to run a single sync session with different settings,
            for example with an increased logging level. "update=FALSE" removes
            all previous temporary settings before adding the current ones.
            Temporary config changes modify the result of GetConfig(), but
            are ignored when making permanent changes in SetConfig().
        </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>
      <annotation name="com.trolltech.QtDBus.QtTypeName.In2" value="QStringMultiMap"/>
    </method>

    <method name="GetNamedConfig">
      <doc:doc><doc:description>Get the configuration identified by
      the name given in the first argument; same as
      Server.GetConfig(), provided again in Session for the sake of
      completeness</doc:description></doc:doc>
      <arg type="s" name="name" direction="in">
        <doc:doc><doc:summary>configuration name</doc:summary></doc:doc>
      </arg>
      <arg type="b" name="getTemplate" direction="in"/>
      <arg type="a{sa{ss}}" name="configuration" direction="out"/>
      <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="QStringMultiMap"/>
    </method>

    <method name="SetNamedConfig">
      <doc:doc><doc:description>Same as SetConfig() except that the modified configuration is named explicitly</doc:description></doc:doc>
      <arg type="s" name="name" direction="in">
        <doc:doc><doc:summary>configuration name; if exactly the same as in StartSession() or StartSessionWithFlags(), then SetNamedConfig() behaves exactly like SetConfig() and none of the constraints for SetNamedConfig() apply</doc:summary></doc:doc>
      </arg>
      <arg type="b" name="update" direction="in"/>
      <arg type="b" name="temporary" direction="in">
        <doc:doc><doc:summary>temporary changes of the configuration are currently only supported for the configuration chosen when creating the session</doc:summary></doc:doc>
      </arg>
      <arg type="a{sa{ss}}" name="configuration" direction="in"/>
      <annotation name="com.trolltech.QtDBus.QtTypeName.In3" value="QStringMultiMap"/>
    </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>
      <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="QArrayOfStringMap"/>
    </method>

    
    <method name="GetDatabases">
      <doc:doc>
        <doc:description>
          Get list of available databases that can be synchronized
          by a source backend.
        </doc:description>
      </doc:doc>
      <arg type="s" name="source" direction="in">
        <doc:doc>
          <doc:summary>
            name of the source configuration which defines
            the backend ("type" property); a temporary config
            is allowed here
          </doc:summary>
        </doc:doc>
      </arg>
      <arg type="a(ssb)" name="databases" direction="out">
        <doc:doc><doc:summary>information about all available databases</doc:summary></doc:doc>
        <doc:doc>
          <doc:description>
            each entry contains in this order:
            an optional name that can be shown to the user
            (already localized or chosen by the user, empty if unavailable),
            a unique value for the "database" (previously "evolutionSource") property,
            a boolean which is true at most once for the default source
          </doc:description>
        </doc:doc>
      </arg>
      <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="QArrayOfDatabases"/>
    </method>

    <method name="CheckSource">
      <doc:doc>
        <doc:description>Tests whether the source configuration
          is correct. Raises the SourceUnusable exception if not.
        </doc:description>
      </doc:doc>
      <arg type="s" name="source" direction="in">
        <doc:doc>
          <doc:summary>
            name of the source configuration which is to be tested;
            a temporary config is allowed here
          </doc:summary>
        </doc:doc>
      </arg>
    </method>

    <method name="Sync">
      <doc:doc><doc:description>
        <doc:para>
          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:
          <doc:list type="bullet">
            <doc:item><doc:definition>sync all with mode from config:
              Sync (NULL, ())</doc:definition>
            </doc:item>
            <doc:item><doc:definition>refresh all from server:
              Sync ("refresh-from-server", ())</doc:definition>
            </doc:item>
            <doc:item><doc:definition>force slow sync for calendar, use mode from config for others:
              Sync (NULL, (("calendar", "slow")))</doc:definition>
            </doc:item>
            <doc:item><doc:definition>sync only calendar and addressbook, with mode from config:
              Sync ("none", (("calendar", NULL), ("addressbook", NULL)))</doc:definition>
            </doc:item>
          </doc:list>
        </doc:para>
        <doc:para>
          Syncevolution will by default output a sync "diff" in the end of Sync().
          Producing the diff can be expensive CPU-wise, so setting the 
          configuration value "printChanges" to 0 before a Sync() is advised
          for clients who are not interested in the diff.
        </doc:para>
      </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>
      <annotation name="com.trolltech.QtDBus.QtTypeName.In1" value="QStringMap"/>
    </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="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>
      </doc:doc>
    </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>

    <method name="Restore">
      <doc:doc><doc:description>
        <doc:para>
          Restores the data of the selected sources to the state from before or after the selected synchronization. The synchronization is selected via its session directory. Other directories can also be given as long as they contain database dumps in the format created by SyncEvolution. 
        </doc:para>
        <doc:para>
          When "sources" are empty, it assumes to restore all available backup sources in the session. If a source is not found in the backup database, then an exception is thrown.
        </doc:para>
        <doc:para>
          Once this method is called, the session is not active anymore. Thus, to call other APIs, a new session is needed to create.  
        </doc:para>
      </doc:description></doc:doc>
      <arg type="s" name="dir" direction="in">
        <doc:doc><doc:summary>the session directory</doc:summary></doc:doc>
      </arg>
      <arg type="b" name="before" direction="in">
        <doc:doc><doc:summary>restore to the data before or after the session</doc:summary></doc:doc>
      </arg>
      <arg type="as" name="sources" direction="in">
        <doc:doc><doc:summary>sources list that be needed to restore</doc:summary></doc:doc>
        <doc:doc><doc:description>Valid values are all available sources.</doc:description></doc:doc>
      </arg>
    </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" direction="out">
        <doc:doc>
          <doc:summary>
            See org.syncevolution.Server Presence signal for details.
          </doc:summary>
        </doc:doc>
      </arg>
    </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">
        <doc:doc><doc:summary>Session status</doc:summary></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;waiting", "suspending;waiting". There may be several specifiers: "running;waiting;foo".
                Specifier "waiting" means that the dbus server is waiting for some external events, typically IO events(like network transports, etc). If "waiting" is absent, then we've done the waiting.
        </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. "done" represents a synced source when the whole sync is not done yet.</doc:description></doc:doc>
      </arg>
      <annotation name="com.trolltech.QtDBus.QtTypeName.Out2" value="QSyncStatusMap"/>
    </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>
      <annotation name="com.trolltech.QtDBus.QtTypeName.Out1" value="QSyncProgressMap"/>
    </method>

    <method name="Execute">
      <doc:doc><doc:description>Starts execution of the operation
      defined via the command line arguments. Like Sync(), it returns
      immediately even if the operation still runs. Session
      completion indicates that the operation is done. To determine
      whether that operation was successful, check the session status.
      </doc:description></doc:doc>
      <arg type="as" name="args" direction="in">
        <doc:doc><doc:summary>Command line arguments</doc:summary></doc:doc>
      </arg>
      <arg type="a{ss}" name="vars" direction="in">
        <doc:doc><doc:summary>Environment variables in clients</doc:summary></doc:doc>
        <annotation name="com.trolltech.QtDBus.QtTypeName.In1" value="QStringMap"/>
      </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"/>
      <annotation name="com.trolltech.QtDBus.QtTypeName.In2" value="QSyncStatusMap"/>
    </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"/>
      <annotation name="com.trolltech.QtDBus.QtTypeName.In1" value="QSyncProgressMap"/>
    </signal>

  </interface>
</node>
