Table of Contents
org.syncevolution.Server — Server interface
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)
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)
Objects implementing org.syncevolution.Server also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties
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.
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
:GetVersions (out'a{ss}'info)
Returns information about server side implementations.
info
: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 ()Detaches an attached client. A client which disconnects from D-Bus is automatically detached from the server.
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
:EnableNotifications (in's'notifications)Allows showing of user visible notifications again.
notifications
:NotificationAction ()Launches sync-ui as a reaction of the user activating a notification.
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
:servers
: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
:getTemplate
:configuration
:CheckPresence (in's'server, out's'status, out'as'transports)Checks whether a sync with a particular server can start.
server
:status
:transports
:GetReports (in's'server, in'u'start, in'u'count, out'aa{ss}'reports)Get synchronization reports for a specific server
server
:start
:count
:reports
: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
:source
:databases
:CheckSource (in's'server, in's'source)Tests whether the source configuration is correct. Raises the SourceUnusable exception if not.
server
:source
: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
:session
: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
:flags
:session
: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
: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
:connection
:GetSessions (out'ao'sessions)Get currently existing sessions. This includes active and queueing sessions.
sessions
:InfoResponse ('s'id, 's'state, 'a{ss}'response)reply for a specific InfoRequest
id
:state
:response
:SessionChanged ('o'session, 'b'started)Session start or end
session
:started
:TemplatesChanged ()Template added or removed, for example because a Bluetooth peer was paired resp. removed. To find out more, request list of templates anew.
ConfigChanged ()Configuration added, updated or removed. To find out more, request list of configurations anew.
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
:status
:transport
: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:
information needed
InfoRequest("request")
InfoResponse("working") + dialog is opened (if necessary)
InfoRequest("waiting")
information becomes available
InfoResponse("response")
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
:session
:state
:handler
:type
:parameters
:LogOutput ('o'path, 's'level, 's'output, 's'procname)
path
:level
:output
:procname
:org.syncevolution.Session — Session interface
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)
StatusChanged('s'status, 'u'error, 'a{s(ssu)}'sources) ProgressChanged('i'progress, 'a{s(siiiiii)}'sources)
Objects implementing org.syncevolution.Session also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties
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).
GetFlags (out'as'flags)Get the session flags set with Server.StartSessionWithFlags().
flags
: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
:GetConfig (in'b'getTemplate, out'a{sa{ss}}'configuration)Get the configuration identified by the name given to StartSession()
getTemplate
:configuration
:SetConfig (in'b'update, in'b'temporary, in'a{sa{ss}}'configuration)Set the configuration of the server
update
:temporary
:configuration
: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
:getTemplate
:configuration
: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
:update
:temporary
:configuration
:GetReports (in'u'start, in'u'count, out'aa{ss}'reports)Get synchronization reports for the server
start
:count
:reports
:GetDatabases (in's'source, out'a(ssb)'databases)Get list of available databases that can be synchronized by a source backend.
source
:databases
:CheckSource (in's'source)Tests whether the source configuration is correct. Raises the SourceUnusable exception if not.
source
: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
:sources
: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 ()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 (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
:before
:sources
:CheckPresence (out's'status)Checks whether a sync with the current server can start.
status
: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
:error
:sources
:GetProgress (out'i'progress, out'a{s(siiiiii)}'sources)Get synchronization progress
progress
:sources
: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
:vars
:org.syncevolution.Connection — Connection interface
Objects implementing org.syncevolution.Connection also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties
Process (in'ay'message, in's'message_type)
message
:message_type
:Close (in'b'normal, in's'error)
normal
:error
:Reply ('ay'reply, 's'reply_type, 'a{ss}'meta, 'b'final, 's'session)
reply
:reply_type
:meta
:final
:session
: