SyncEvolution D-Bus API 1.5


Table of Contents

org.syncevolution.Server — Server interface
org.syncevolution.Session — Session interface
org.syncevolution.Connection — Connection interface

Name

org.syncevolution.Server — Server interface

Methods

GetCapabilities       (out 'as'        capabilities)
GetVersions           (out 'a{ss}'     info)
Attach                ()
Detach                ()
DisableNotifications  (in  's'         notifications)
EnableNotifications   (in  's'         notifications)
NotificationAction    ()
GetConfigs            (in  'b'         getTemplate,
                       out 'as'        servers)
GetConfig             (in  's'         server,
                       in  'b'         getTemplate,
                       out 'a{sa{ss}}' configuration)
CheckPresence         (in  's'         server,
                       out 's'         status,
                       out 'as'        transports)
GetReports            (in  's'         server,
                       in  'u'         start,
                       in  'u'         count,
                       out 'aa{ss}'    reports)
GetDatabases          (in  's'         server,
                       in  's'         source,
                       out 'a(ssb)'    databases)
CheckSource           (in  's'         server,
                       in  's'         source)
StartSession          (in  's'         config,
                       out 'o'         session)
StartSessionWithFlags (in  's'         config,
                       in  'as'        flags,
                       out 'o'         session)
Connect               (in  'a{ss}'     peer,
                       in  'b'         must_authenticate,
                       in  's'         session,
                       out 'o'         connection)
GetSessions           (out 'ao'        sessions)
InfoResponse          (    's'         id,
                           's'         state,
                           'a{ss}'     response)

Signals

SessionChanged   ('o'     session,
                  'b'     started)
TemplatesChanged ()
ConfigChanged    ()
Presence         ('s'     server,
                  's'     status,
                  's'     transport)
InfoRequest      ('s'     id,
                  'o'     session,
                  's'     state,
                  's'     handler,
                  's'     type,
                  'a{ss}' parameters)
LogOutput        ('o'     path,
                  's'     level,
                  's'     output,
                  's'     procname)

Implemented Interfaces

Objects implementing org.syncevolution.Server also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties

Description

Server is the entry object for SyncEvolution client API. It can be used to query information and to start and monitor sessions.

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).

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.

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".

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.SourceUnusable: CheckSource() may return this if source is not usable (for various possible reasons).

  • org.syncevolution.InvalidCall: a call is (perhaps no longer) allowed or suitable in the current situation, like Detach() when the client is not attached.

Details

GetCapabilities ()

GetCapabilities (out 'as' capabilities)

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:

  • ConfigChanged: Server.ConfigChange signal available; if not, reread config after each session

  • GetConfigName: Session.GetConfigName() implemented

  • SessionAttach: Session.Attach() implemented

  • Notifications: Server.DisableNotifications() and Server.EnableNotifications() implemented

  • Version: Server.GetVersion() implemented; note that this is not meant to be used to determine supported features

  • SessionFlags: Server.StartSessionWithFlags() and Session.GetFlags() are implemented

  • DatabaseProperties: uses "database", "databaseUser", "databasePassword" source properties instead of the older names "evolutionsource", "evolutionuser", "evolutionpassword"; semantic is unchanged

  • NamedConfig: Session.Get/SetNamedConfig() are implemented

capabilities:
set of supported capabilities

GetVersions ()

GetVersions (out 'a{ss}' info)

Returns information about server side implementations.

info:
"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

Attach ()

Attach ()

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.

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.

Detach ()

Detach ()
Detaches an attached client. A client which disconnects from D-Bus is automatically detached from the server.

DisableNotifications ()

DisableNotifications (in  's' notifications)
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.
notifications:
describes the notifications which are to be disabled; currently ignored by server, pass empty string

EnableNotifications ()

EnableNotifications (in  's' notifications)
Allows showing of user visible notifications again.
notifications:
describes the notifications which are to be enabled; currently ignored by server, pass empty string

NotificationAction ()

NotificationAction ()
Launches sync-ui as a reaction of the user activating a notification.

GetConfigs ()

GetConfigs (in  'b'  getTemplate,
            out 'as' servers)

Get an array of all configured servers (or templates)

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.

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_< mac address>_<sequence number>'. Here 'mac address' is the mac address of the Bluetooth device and 'sequence number' enumerates all the matched templates created for the device.

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.

getTemplate:
if TRUE, will return template names, otherwise will return configured servers
servers:
array of configured server (or template) names

GetConfig ()

GetConfig (in  's'         server,
           in  'b'         getTemplate,
           out 'a{sa{ss}}' configuration)

Get the configuration of a specific server (or template).

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.

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.

  • configName: 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.

  • description: device template: the description for the template (non-localized string)

  • score: device template: the calculated score based on the device name and template (1-5, 5 is best)

  • deviceName: device template: the device name that the template is for (copied verbatim from that device, typically chosen by the user of the device)

  • templateName: 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

  • hardwareName: 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.

  • fingerPrint: 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

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.

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.

server:
server name
getTemplate:
if TRUE, will return a matching template configuration, otherwise will return a matching server configuration
configuration:
server (or template) configuration

CheckPresence ()

CheckPresence (in  's'  server,
               out 's'  status,
               out 'as' transports)
Checks whether a sync with a particular server can start.
server:
server name
status:
See Presence signal for details.
transports:
All currently available transports. See Presence signal for details.

GetReports ()

GetReports (in  's'      server,
            in  'u'      start,
            in  'u'      count,
            out 'aa{ss}' reports)
Get synchronization reports for a specific server
server:
server name
start:
index of the first (newest) report that will be returned; reports are number starting with zero for the newest
count:
maximum number of returned reports
reports:
synchronization reports

GetDatabases ()

GetDatabases (in  's'      server,
              in  's'      source,
              out 'a(ssb)' databases)
Get list of available databases that can be synchronized by a source backend.
server:
server name
source:
name of the source configuration which defines the backend ("type" property)
databases:
information about all available databases

CheckSource ()

CheckSource (in  's' server,
             in  's' source)
Tests whether the source configuration is correct. Raises the SourceUnusable exception if not.
server:
server name
source:
name of the source configuration which is to be tested

StartSession ()

StartSession (in  's' config,
              out 'o' session)
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.
config:
name of configuration to be created or used in session
session:
session D-Bus object path

StartSessionWithFlags ()

StartSessionWithFlags (in  's'  config,
                       in  'as' flags,
                       out 'o'  session)
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:
  • no-sync: session will not be used for running a synchronization

  • all-configs: session will provide read/write access to all configurations, via Get/SetNamedConfig()

config:
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()
flags:
optional flags
session:
session D-Bus object path

Connect ()

Connect (in  'a{ss}' peer,
         in  'b'     must_authenticate,
         in  's'     session,
         out 'o'     connection)

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.

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.

In the later case, SyncEvolution may or may not use the connection established by Connect(), depending on the content of that first message.

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.

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.

peer:
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.
must_authenticate:

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.

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.

session:
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.
connection:
The connection object created by SyncEvolution in response to this connection request. Implements the org.syncevolution.Connection interface.

GetSessions ()

GetSessions (out 'ao' sessions)
Get currently existing sessions. This includes active and queueing sessions.
sessions:
array of session D-Bus object paths, in the order in which they will run, running ones first

InfoResponse ()

InfoResponse (    's'     id,
                  's'     state,
                  'a{ss}' response)
reply for a specific InfoRequest
id:
unique ID sent by InfoRequest
state:
"working" to indicate that a response will be sent later, "response" for the actual reply
response:
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

Signal Details

The SessionChanged signal

SessionChanged ('o' session,
                'b' started)
Session start or end
session:
session D-Bus object path
started:
TRUE if session was started and is active now (= ready for use), FALSE if it ended

The TemplatesChanged signal

TemplatesChanged ()
Template added or removed, for example because a Bluetooth peer was paired resp. removed. To find out more, request list of templates anew.

The ConfigChanged signal

ConfigChanged ()
Configuration added, updated or removed. To find out more, request list of configurations anew.

The Presence signal

Presence ('s' server,
          's' status,
          's' transport)
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.
server:
name of the server configuration
status:
"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.
transport:
If the server can be reached via multiple transports, this is the one which triggered the signal. Content of the string to be decided...

The InfoRequest signal

InfoRequest ('s'     id,
             'o'     session,
             's'     state,
             's'     handler,
             's'     type,
             'a{ss}' parameters)

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.

Clients react by calling InfoResponse. The flow of events is this:

  1. information needed

  2. InfoRequest("request")

  3. InfoResponse("working") + dialog is opened (if necessary)

  4. InfoRequest("waiting")

  5. information becomes available

  6. InfoResponse("response")

  7. InfoRequest("done")

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.

For "type = password" the following keys are used as part of the "parameters" string hash:

  • "name": name of the password property in the config

  • "description": 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).

  • "user", "server", "domain", "object", "protocol", "authtype", "port" : optional keys as they would be used in the GNOME keyring.

id:
unique ID for the request
session:
the Session which is affected, may be empty
state:
"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
handler:
for state="waiting": the client which first replied with InfoResponse("working")
type:
Determines which information is needed. Currently only "password" for interactive password requests is defined.
parameters:
Auxiliary parameters which depend on the type.

The LogOutput signal

LogOutput ('o' path,
           's' level,
           's' output,
           's' procname)
path:
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.
level:
the output level (DEBUG/INFO/SHOW/ERROR/WARNING/DEVELOPER)
output:
the output string to be broadcast
procname:
A short tag identifying which process produced the output. Should be shown to the user. Empty for main process in a sync.

Name

org.syncevolution.Session — Session interface

Methods

GetFlags       (out 'as'            flags)
GetConfigName  (out 's'             config)
GetConfig      (in  'b'             getTemplate,
                out 'a{sa{ss}}'     configuration)
SetConfig      (in  'b'             update,
                in  'b'             temporary,
                in  'a{sa{ss}}'     configuration)
GetNamedConfig (in  's'             name,
                in  'b'             getTemplate,
                out 'a{sa{ss}}'     configuration)
SetNamedConfig (in  's'             name,
                in  'b'             update,
                in  'b'             temporary,
                in  'a{sa{ss}}'     configuration)
GetReports     (in  'u'             start,
                in  'u'             count,
                out 'aa{ss}'        reports)
GetDatabases   (in  's'             source,
                out 'a(ssb)'        databases)
CheckSource    (in  's'             source)
Sync           (in  's'             mode,
                in  'a{ss}'         sources)
Abort          ()
Suspend        ()
Attach         ()
Detach         ()
Restore        (in  's'             dir,
                in  'b'             before,
                in  'as'            sources)
CheckPresence  (out 's'             status)
GetStatus      (out 's'             status,
                out 'u'             error,
                out 'a{s(ssu)}'     sources)
GetProgress    (out 'i'             progress,
                out 'a{s(siiiiii)}' sources)
Execute        (in  'as'            args,
                in  'a{ss}'         vars)

Signals

StatusChanged   ('s'             status,
                 'u'             error,
                 'a{s(ssu)}'     sources)
ProgressChanged ('i'             progress,
                 'a{s(siiiiii)}' sources)

Implemented Interfaces

Objects implementing org.syncevolution.Session also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties

Description

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().

Commands (other than Attach() and Detach()) cannot be used before the status changes to "idle" (see GetStatus() and StatusChanged).

Details

GetFlags ()

GetFlags (out 'as' flags)
Get the session flags set with Server.StartSessionWithFlags().
flags:
session flags

GetConfigName ()

GetConfigName (out 's' config)

Get the configuration name of the session.

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.

config:
peer configuration name

GetConfig ()

GetConfig (in  'b'         getTemplate,
           out 'a{sa{ss}}' configuration)
Get the configuration identified by the name given to StartSession()
getTemplate:
if TRUE, will return a matching template configuration, otherwise will return the stored configuration
configuration:
server configuration

SetConfig ()

SetConfig (in  'b'         update,
           in  'b'         temporary,
           in  'a{sa{ss}}' configuration)
Set the configuration of the server
update:
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.
temporary:
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().
configuration:
server configuration

GetNamedConfig ()

GetNamedConfig (in  's'         name,
                in  'b'         getTemplate,
                out 'a{sa{ss}}' configuration)
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
name:
configuration name
getTemplate:
configuration:

SetNamedConfig ()

SetNamedConfig (in  's'         name,
                in  'b'         update,
                in  'b'         temporary,
                in  'a{sa{ss}}' configuration)
Same as SetConfig() except that the modified configuration is named explicitly
name:
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
update:
temporary:
temporary changes of the configuration are currently only supported for the configuration chosen when creating the session
configuration:

GetReports ()

GetReports (in  'u'      start,
            in  'u'      count,
            out 'aa{ss}' reports)
Get synchronization reports for the server
start:
index of the first (newest) report that will be returned
count:
maximum number of returned reports
reports:
synchronization reports

GetDatabases ()

GetDatabases (in  's'      source,
              out 'a(ssb)' databases)
Get list of available databases that can be synchronized by a source backend.
source:
name of the source configuration which defines the backend ("type" property); a temporary config is allowed here
databases:
information about all available databases

CheckSource ()

CheckSource (in  's' source)
Tests whether the source configuration is correct. Raises the SourceUnusable exception if not.
source:
name of the source configuration which is to be tested; a temporary config is allowed here

Sync ()

Sync (in  's'     mode,
      in  'a{ss}' sources)

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)))

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.

mode:
synchronization mode
sources:
synchronization source modes

Abort ()

Abort ()
Abort synchronization. See Status-signal for results.

Suspend ()

Suspend ()
Suspend synchronization. See Status-signal for results.

Attach ()

Attach ()
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.

Detach ()

Detach ()
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.

Restore ()

Restore (in  's'  dir,
         in  'b'  before,
         in  'as' sources)

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.

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.

Once this method is called, the session is not active anymore. Thus, to call other APIs, a new session is needed to create.

dir:
the session directory
before:
restore to the data before or after the session
sources:
sources list that be needed to restore

CheckPresence ()

CheckPresence (out 's' status)
Checks whether a sync with the current server can start.
status:
See org.syncevolution.Server Presence signal for details.

GetStatus ()

GetStatus (out 's'         status,
           out 'u'         error,
           out 'a{s(ssu)}' sources)
Get session status. Individual source statuses are relevant and provided only when status is neither "queuing" nor "idle".
status:
Session status
error:
Error code for current or last action (zero for no error).
sources:
Synchronization source status dictionary

GetProgress ()

GetProgress (out 'i'             progress,
             out 'a{s(siiiiii)}' sources)
Get synchronization progress
progress:
Rough estimate of current progress 0-100.
sources:
Synchronization source progress dictionary

Execute ()

Execute (in  'as'    args,
         in  'a{ss}' vars)
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.
args:
Command line arguments
vars:
Environment variables in clients

Signal Details

The StatusChanged signal

StatusChanged ('s'         status,
               'u'         error,
               'a{s(ssu)}' sources)
Session status change. See GetStatus() for argument descriptions.
status:
error:
sources:

The ProgressChanged signal

ProgressChanged ('i'             progress,
                 'a{s(siiiiii)}' sources)
Synchronization progress change. See GetProgress() for argument descriptions.
progress:
sources:

Name

org.syncevolution.Connection — Connection interface

Methods

Process (in  'ay' message,
         in  's'  message_type)
Close   (in  'b'  normal,
         in  's'  error)

Signals

Reply ('ay'    reply,
       's'     reply_type,
       'a{ss}' meta,
       'b'     final,
       's'     session)
Abort ()

Implemented Interfaces

Objects implementing org.syncevolution.Connection also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties

Description

The SyncEvolution connection object can be used to exchange messages.

Details

Process ()

Process (in  'ay' message,
         in  's'  message_type)
message:
The data to be processed. Empty messages are invalid and will trigger an error.
message_type:
The MIME type of the message. "application/vnd.syncml.ds.notification", "application/vnd.syncml+xml" and "application/vnd.syncml+wbxml" are currently supported.

Close ()

Close (in  'b' normal,
       in  's' error)
normal:
TRUE if the connection is being closed after successfully delivering the final response. FALSE if an error is encountered that cannot be handled by the peer or its transport. SyncEvolution cannot rely on getting a close(FALSE) call in all cases. If its caller disappears from the bus it must assume that there was a fatal error and close the connection.
error:
A description which explains the error, may be empty. Used for debugging.

Signal Details

The Reply signal

Reply ('ay'    reply,
       's'     reply_type,
       'a{ss}' meta,
       'b'     final,
       's'     session)
reply:
The data to be returned to the peer. An empty reply is possible as response to the last message; it must not be delivered. Instead, final will be true and the connection needs to be closed. It is possible that a non-empty reply is sent without the final flag, immediately followed by an empty reply which has the flag set. As described above, the empty reply must be ignored and close() must be called once the non-empty reply is delivered.
reply_type:
The MIME type of the reply. The same types as for the message are supported.
meta:
Transport specific meta information. Currently defined: "URL" - the URL for an HTTP POST.
final:
True if this is the last reply. No further messages are expected and the session should be closed once the reply was delivered successfully.
session:
The first message in a new connection triggers the creation of a new, random session ID which is returned together with the response. The caller is responsible for ensuring that only messages belonging to this session are passed to future process() calls. In practice the session ID does not change after the first message, but this is not guaranteed and the caller should always use the most recent value.

The Abort signal

Abort ()