<?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: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:para>
        Method calls may fail with the following errors:
        <doc:list>
          <doc:item><doc:term>org.syncevolution.Exception</doc:term><doc:definition>catch-all error condition.</doc:definition></doc:item>
          <doc:item><doc:term>org.syncevolution.NoSuchConfig</doc:term><doc:definition>server configuration name is invalid</doc:definition></doc:item>
          <doc:item><doc:term>org.syncevolution.NoSuchSource</doc:term><doc:definition>source name is invalid</doc:definition></doc:item>
          <doc:item><doc:term>org.syncevolution.SourceUnusable</doc:term><doc:definition>CheckSource() may return this if source is not usable (for various possible reasons).</doc:definition></doc:item>
          <doc:item><doc:term>org.syncevolution.InvalidCall</doc:term><doc:definition>a call is (perhaps no longer) allowed or suitable in the current situation, like Detach() when the client is not attached.</doc:definition></doc:item>
        </doc:list>
      </doc:para>
    </doc:doc>

    <method name="GetCapabilities">
      <doc:doc>
        <doc:description>
          <doc:para>
            Describes which features are implemented by the server. If the method itself
            is unavailable, then the features correspond to SyncEvolution 1.0. The following
            capabilities are currently defined:
            <doc:list>
              <doc:item><doc:term>ConfigChanged</doc:term>
                <doc:definition>Server.ConfigChange
                  signal available; if not, reread config after each
                  session
                </doc:definition>
              </doc:item>
             
              <doc:item><doc:term>GetConfigName</doc:term>
                <doc:definition>Session.GetConfigName()
                  implemented
                </doc:definition>
              </doc:item>
             
              <doc:item><doc:term>SessionAttach</doc:term>
                <doc:definition>Session.Attach()
                  implemented
                </doc:definition>
              </doc:item>
             
              <doc:item><doc:term>Notifications</doc:term>
                <doc:definition>Server.DisableNotifications()
                  and Server.EnableNotifications() implemented
                </doc:definition>
              </doc:item>
             
              <doc:item><doc:term>Version</doc:term>
                <doc:definition>Server.GetVersion()
                  implemented; note that this is not meant to be used to determine supported
                  features
                </doc:definition>
              </doc:item>
             
              <doc:item><doc:term>SessionFlags</doc:term>
                <doc:definition>Server.StartSessionWithFlags()
                  and Session.GetFlags() are implemented
                </doc:definition>
              </doc:item>

              <doc:item><doc:term>DatabaseProperties</doc:term>
                <doc:definition>uses "database", "databaseUser", "databasePassword"
                  source properties instead of the older names "evolutionsource",
                  "evolutionuser", "evolutionpassword"; semantic is unchanged
                </doc:definition>
              </doc:item>

              <doc:item><doc:term>NamedConfig</doc:term>
                <doc:definition>Session.Get/SetNamedConfig()
                  are implemented
                </doc:definition>
              </doc:item>

            </doc:list>
          </doc:para>
        </doc:description>
      </doc:doc>
      <arg type="as" name="capabilities" direction="out">
        <doc:doc><doc:summary>
          set of supported capabilities
        </doc:summary></doc:doc>
      </arg>
    </method>

    <method name="GetVersions">
      <doc:doc>
        <doc:description>
          <doc:para>
            Returns information about server side implementations.
          </doc:para>
        </doc:description>
      </doc:doc>
      <arg type="a{ss}" name="info" direction="out">
        <doc:doc><doc:summary>
            "version" - main SyncEvolution release name (usually a number,
            sometimes also a beta or alpha suffix),
            "system" - some plain text information about system libraries,
            "backends" - available backend libraries
        </doc:summary></doc:doc>
        <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="QStringMap"/>
      </arg>
    </method>  

    <method name="Attach">
      <doc:doc>
        <doc:description>
          <doc:para>
          With no client attached, the server will shut down after a
          certain period of inactivity. Attaching to the server
          prevents that. Attaching is not necessary to invoke methods.
          The main purpose is to keep the server running while clients
          are around and listen for signals, in particular the
          Presence signal.
          </doc:para>
          <doc:para>
          Each attach has to be matched by one detach, so that one client has
          the capability to attach to the server many times in different
          modules. The behavior of calling Detach() more often than Attach()
          is undefined.
          </doc:para>
        </doc:description>
      </doc:doc>
    </method>

    <method name="Detach">
      <doc:doc>
        <doc:description>
          Detaches an attached client. A client which disconnects
          from D-Bus is automatically detached from the server.
        </doc:description>
      </doc:doc>
    </method>

    <method name="DisableNotifications">
      <doc:doc>
        <doc:description>
          Prevents showing of user visible notifications by the
          syncevo-dbus-server. Must be called while the client is
          attached to the server. Notifications will be disabled
          until the client detaches or calls EnableNotifications().
          The calls cannot be nested, so calling
          DisableNotifications()/DisableNoticiations()/EnableNotifications()
          will enable notifications.
        </doc:description>
      </doc:doc>
      <arg type="s" name="notifications" direction="in">
        <doc:doc><doc:summary>
            describes the notifications which are to be disabled; currently
            ignored by server, pass empty string
        </doc:summary></doc:doc>
      </arg>
    </method>

    <method name="EnableNotifications">
      <doc:doc>
        <doc:description>
          Allows showing of user visible notifications again.
        </doc:description>
      </doc:doc>
      <arg type="s" name="notifications" direction="in">
        <doc:doc><doc:summary>
            describes the notifications which are to be enabled; currently
            ignored by server, pass empty string
        </doc:summary></doc:doc>
      </arg>
    </method>

    <method name="NotificationAction">
      <doc:doc>
        <doc:description>
          Launches sync-ui as a reaction of the user activating a notification.
        </doc:description>
      </doc:doc>
    </method>

    <method name ="GetConfigs">
      <doc:doc><doc:description>
        <doc:para>
        Get an array of all configured servers (or templates)
        </doc:para>
        <doc:para>
        In getting templates mode, the dbus server checks all paired devices
        from bluez daemon and filters them by SyncML capability. Then it
        looks through built-in templates and returns their matched templates.
        Multiple templates might be created for each device, with different
        matching scores(range: 1-5). Scores represent how well the device name
        matches a template. The higher, the better.
        </doc:para>
        
        <doc:para>
        A template might be used to help creation for multiple devices. Thus template
        names must be reset in a naming rule. They are re-named with 'Bluetooth_&lt;
        mac address&gt;_&lt;sequence number&gt;'. Here 'mac address' is the mac
        address of the Bluetooth device and 'sequence number' enumerates all the
        matched templates created for the device.
        </doc:para>

        <doc:para>
        When retrieving the templates with GetConfig(), several additional
        properties will be returned which can be used to pick the right template for
        a device, see GetConfig(). The 'syncURL' is already replaced with the mac address of the device
        and thus can be used to find all templates refering to the same device.
        </doc:para>
      </doc:description></doc:doc>
      <arg type="b" name="getTemplate" 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>
        <doc:para>Get the configuration of a specific server (or template).</doc:para>

        <doc:para>The dictionary keys are "source/&lt;source name&gt;" 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:para>

        <doc:para>In addition, some special keys for read-only values
        are added. These entries may be set when reading a config or
        template and can be sent when writing it, but will not
        actually be stored.
        <doc:list>
          <doc:item>
            <doc:term>configName</doc:term>
            <doc:definition>Normalized configuration. For example,
            if a session is opened for "FooBar" and there is an
            existing configuration "foobar@some-context", then the
            latter is used for the session instead of the "FooBar"
            shorthand. All configuration names sent by
            syncevo-dbus-server are normalized. D-Bus clients should
            compare that against the "configName" value instead of
            the config name chosen by them or the
            user.</doc:definition>
          </doc:item>
          <doc:item>
            <doc:term>description</doc:term>
            <doc:definition>device template: the description for the template
            (non-localized string)</doc:definition>
          </doc:item>
          <doc:item>
            <doc:term>score</doc:term>
            <doc:definition>device template: the calculated score based on the device
            name and template (1-5, 5 is best)</doc:definition>
          </doc:item>
          <doc:item>
            <doc:term>deviceName</doc:term>
            <doc:definition>device template: the device name that the template is for
            (copied verbatim from that device, typically chosen by the user of the device)</doc:definition>
          </doc:item>
          <doc:item>
            <doc:term>templateName</doc:term>
            <doc:definition>device template: string identifying the class of devices
            the templates works for, like "Nokia S40"; meant to be
            shown to users; optional, fall back to first entry in
            fingerPrint if not set</doc:definition>
          </doc:item>
          <doc:item>
            <doc:term>hardwareName</doc:term>
            <doc:definition>device template: "vendor[ model]" string extracted
            from a device database, unset if neither vendor nor model are known. The
            deviceName above is probably a better way to present the device to the user,
            because if a user has multiple identical devices, he hopefully chose
            unique names for them.</doc:definition>
          </doc:item>
          <doc:item>
            <doc:term>fingerPrint</doc:term>
            <doc:definition>device template: comma separated list of devices which
            work with this template, typically in "vendor model"
            format; can be used by D-Bus clients to re-match with
            user provided device information</doc:definition>
          </doc:item>
        </doc:list>
        </doc:para>

        <doc:para>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:para>

        <doc:para>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:para>

      </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="getTemplate" 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>
      </arg>
      <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="QStringMultiMap"/>
    </method>

    <method name="CheckPresence">
      <doc:doc><doc:description>
        Checks whether a sync with a particular server can start.
      </doc:description></doc:doc>
      <arg type="s" name="server" direction="in">
        <doc:doc><doc:summary>server name</doc:summary></doc:doc>
      </arg>
      <arg type="s" name="status" direction="out">
        <doc:doc>
          <doc:summary>
            See Presence signal for details.
          </doc:summary>
        </doc:doc>
      </arg>
      <arg type="as" name="transports" direction="out">
        <doc:doc>
          <doc:summary>
            All currently available transports. See Presence signal for details.
          </doc:summary>
        </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;
          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>
      </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. The dictionary keys can be defined by below BNFs:
                Key ::= 'dir' | 'peer' | 'start' | 'end' | 'status' | 'error' | SourceKey
                SourceKey ::= SourcePrefix SourcePart
                SourcePrefix ::= 'source' Sep SourceName
                SourceName ::= character+ 
                SourcePart ::= Sep ('mode' | 'first' | 'resume' | 'status' | 'backup-before' 
                               | 'backup-after' | StatPart)
                StatPart ::= 'stat' Sep LocName Sep StateName Sep ResultName
                LocName ::= 'local' | 'remote'
                StateName ::= 'added' | 'updated' | 'removed' | 'any'
                ResultName ::= 'total' | 'reject' | 'match' | 'conflict_server_won' | 'conflict_client_won' 
                                | 'conflict_duplicated' | 'sent' | 'received'
                Sep ::= '-'

                If SourceName has characters '_' and '-', they will be
                escaped with '__' and '_+' respectively. This means
                that a key can be split at '-' before replacing these
                escape sequences in the source name.

                For a key which contains StatPart, if its value is 0,
                its pair-value won't be included in the dictionary.
        </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="server" direction="in">
        <doc:doc><doc:summary>server name</doc:summary></doc:doc>
      </arg>
      <arg type="s" name="source" direction="in">
        <doc:doc>
          <doc:summary>
            name of the source configuration which defines
            the backend ("type" property)
          </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="server" direction="in">
        <doc:doc><doc:summary>server name</doc:summary></doc:doc>
      </arg>
      <arg type="s" name="source" direction="in">
        <doc:doc>
          <doc:summary>
            name of the source configuration which is to be tested
          </doc:summary>
        </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 Detach() method can be called before that. Same as StartSessionWithFlags()
        without any flags set.
      </doc:description></doc:doc>
      <arg type="s" name="config" direction="in">
        <doc:doc><doc:summary>name of configuration to be created or used in session</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="StartSessionWithFlags">
      <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. Additional flags,
        identified by strings, can be passed to control the session creation.
        They can be retrieved with Session.GetFlags(). The following flags are
        currently defined:
        <doc:list>
          <doc:item><doc:term>no-sync</doc:term>
            <doc:definition>session will not be used for running a synchronization</doc:definition>
          </doc:item>
          <doc:item><doc:term>all-configs</doc:term>
            <doc:definition>session will provide read/write access to all configurations, via Get/SetNamedConfig()</doc:definition>
          </doc:item>
        </doc:list>
      </doc:description></doc:doc>
      <arg type="s" name="config" direction="in">
        <doc:doc><doc:summary>name of configuration to be created or used in session; typically this will be empty when used in combination with 'all-configs' and Get/SetNamedConfig()</doc:summary></doc:doc>
      </arg>
      <arg type="as" name="flags" direction="in">
        <doc:doc><doc:summary>optional flags</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="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>
        <annotation name="com.trolltech.QtDBus.QtTypeName.In0" value="QStringMap"/>
      </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="s" name="session" direction="in">
        <doc:doc>
          <doc:summary>
            If this is a reconnect for an older session,
            then pass the session ID here. Otherwise
            pass an empty string. New session IDs are created in
            response to the initial message, see Reply signal.
          </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. 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,
            in the order in which they will run, running ones first</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 and is active now (= ready for use),
          FALSE if it ended
        </doc:summary></doc:doc>
      </arg>
    </signal>

    <signal name="TemplatesChanged">
      <doc:doc>
        <doc:description>
          Template added or removed, for example because a Bluetooth
          peer was paired resp. removed. To find out more, request
          list of templates anew.
      </doc:description>
      </doc:doc>
    </signal>

    <signal name="ConfigChanged">
      <doc:doc>
        <doc:description>
          Configuration added, updated or removed. To find out more,
          request list of configurations anew.
      </doc:description>
      </doc:doc>
    </signal>

    <signal name="Presence">
      <doc:doc>
        <doc:description>
          Indicates whether a server can be reached right now.  This
          signal can be used by GUIs to prevent starting a sync when
          it is known to fail, for example because the network is
          currently down.

          At the moment, the SyncEvolution server can only monitor
          network connectivity, which is a cheap local operation and
          thus done unconditionally while the server runs (see
          Attach()). Detecting the presence of non-HTTP-based peers
          might be more costly. Additional APIs might be added to turn
          that on only when needed. The CheckPresence() method will
          always force a check.
        </doc:description>
      </doc:doc>
      <arg type="s" name="server">
        <doc:doc><doc:summary>
          name of the server configuration
        </doc:summary></doc:doc>
      </arg>
      <arg type="s" name="status">
        <doc:doc>
          <doc:summary>
            "no transport" - the transport necessary to reach the server is not working.
            "not present" - the server is known to be down or unreachable.
            "" - the server might be usable. Syncs can still fail.
            Other non-empty strings might be added in the future. They always
            indicate a condition which prevents syncing.
          </doc:summary>
        </doc:doc>
      </arg>
      <arg type="s" name="transport">
        <doc:doc>
          <doc:summary>
            If the server can be reached via multiple transports, this
            is the one which triggered the signal. Content of the
            string to be decided...
          </doc:summary>
        </doc:doc>
      </arg>
    </signal>

    <signal name="InfoRequest">
      <doc:doc>
        <doc:description>
          <doc:para>
            Emitted whenever the server needs information that only a
            client can provide. Because the server does not know whether
            clients are monitoring it (attaching to the server is
            optional) and/or which of the attached clients are able to
            handle the request, it broadcasts the request.
          </doc:para>

          <doc:para>
            Clients react by calling InfoResponse.  The flow of events is this:
            <doc:list type="number">
              <doc:item><doc:definition>information needed</doc:definition></doc:item>
              <doc:item><doc:definition>InfoRequest("request")</doc:definition></doc:item>
              <doc:item><doc:definition>InfoResponse("working") + dialog is opened (if necessary)</doc:definition></doc:item>
              <doc:item><doc:definition>InfoRequest("waiting")</doc:definition></doc:item>
              <doc:item><doc:definition>information becomes available</doc:definition></doc:item>
              <doc:item><doc:definition>InfoResponse("response")</doc:definition></doc:item>
              <doc:item><doc:definition>InfoRequest("done")</doc:definition></doc:item>
            </doc:list>
          </doc:para>

          <doc:para>
            Clients should work on those requests that they support,
            unless another client was faster (InfoRequest("waiting")).
            Because there is a race condition, multiple dialogs might
            be opened. The user only has to enter data in one of them.
            A client can close his dialog upon InfoRequest("done")
            and/or InfoRequest("waiting") with a 'handler' parameter
            which is some other client. If the server does not get a
            InfoResponse("working") soon enough (in the range of
            minutes, not seconds), it has to assume that no client can
            provide the information and fall back to some default or
            abort.
          </doc:para>

          <doc:para>
            For "type = password" the following keys are used as part of the "parameters" string hash:
            <doc:list>
              <doc:item>
                <doc:term>"name"</doc:term>
                <doc:definition>name of the password property in the config</doc:definition>
              </doc:item>
              <doc:item>
                <doc:term>"description"</doc:term>
                <doc:definition>unique English description of the required password.
                  Content is determined by the individual password property, so this
                  may change. Currently used are "SyncML Server", "proxy",
                  "'source name' backend" (with 'source name' replaced by the same
                  names also used for the corresponding config entry).
                </doc:definition>
              </doc:item>
              <doc:item>
                <doc:term>
                  "user", "server", "domain", "object", "protocol", "authtype", "port"
                </doc:term>
                <doc:definition>
                  optional keys as they would be used in the GNOME keyring.
                </doc:definition>
              </doc:item>
            </doc:list>
          </doc:para>
        </doc:description>
      </doc:doc>

      <arg type="s" name="id">
        <doc:doc><doc:summary>unique ID for the request</doc:summary></doc:doc>
      </arg>
      <arg type="o" name="session">
        <doc:doc><doc:summary>the Session which is affected, may be empty</doc:summary></doc:doc>
      </arg>
      <arg type="s" name="state">
        <doc:doc>
          <doc:summary>
            "request" for a new request,
            "waiting" for one which is being serviced by some client,
            "done" for a request which was resolved or timed out
          </doc:summary>
        </doc:doc>
      </arg>
      <arg type="s" name="handler">
        <doc:doc>
          <doc:summary>
            for state="waiting": the client which first replied
            with InfoResponse("working")
          </doc:summary>
        </doc:doc>
      </arg>
      <arg type="s" name="type">
        <doc:doc>
          <doc:summary>
            Determines which information is needed. Currently only
            "password" for interactive password requests is defined.
          </doc:summary>
        </doc:doc>
      </arg>

      <arg type="a{ss}" name="parameters">
        <doc:doc>
          <doc:summary>
            Auxiliary parameters which depend on the type.
          </doc:summary>
        </doc:doc>
      </arg>
      <annotation name="com.trolltech.QtDBus.QtTypeName.In5" value="QStringMap"/>
    </signal>

    <method name="InfoResponse">
      <doc:doc><doc:description>reply for a specific InfoRequest</doc:description></doc:doc>

      <arg type="s" name="id">
        <doc:doc><doc:summary>unique ID sent by InfoRequest</doc:summary></doc:doc>
      </arg>
      <arg type="s" name="state">
        <doc:doc>
          <doc:summary>
            "working" to indicate that a response will be sent later,
            "response" for the actual reply
          </doc:summary>
        </doc:doc>
      </arg>

      <arg type="a{ss}" name="response">
        <doc:doc>
          <doc:summary>
            Response values, valid in state="response", depend on type.

            For "password" the following keys are used:
            "password" - the password text, optional, do not set the key if the
            user cancelled the request
          </doc:summary>
        </doc:doc>
      </arg>
      <annotation name="com.trolltech.QtDBus.QtTypeName.In2" value="QStringMap"/>
    </method>

    <signal name="LogOutput">
      <doc:doc><doc:description></doc:description>Broadcast the console part of the output</doc:doc>
      <arg type="o" name="path">
          <doc:doc>
            <doc:summary>
              D-Bus object path. If the output belongs to a session, then path is set as session's
              object path. Else, it's set as dbus server's object path.
            </doc:summary>
          </doc:doc>
      </arg>
      <arg type="s" name="level">
        <doc:doc><doc:summary>the output level (DEBUG/INFO/SHOW/ERROR/WARNING/DEVELOPER)</doc:summary></doc:doc>
      </arg>
      <arg type="s" name="output">
        <doc:doc><doc:summary>the output string to be broadcast</doc:summary></doc:doc>
      </arg>
      <arg type="s" name="procname">
        <doc:doc><doc:summary>A short tag identifying which process
        produced the output. Should be shown to the user. Empty for
        main process in a sync.</doc:summary></doc:doc>
      </arg>
    </signal>

  </interface>
</node>
