Buteo framework API usage

# Available Buteo APIs

- Plugin API
- msycnd Dbus API
- libbuteosyncfw API

# Plugin API

Refer to Writing plugins for Synchronization Framework

# Dbus API

The dbus API can be used by application to get the live data from msyncd. Both signals as well as methods are provided. msyncd listens on the bus com.meego.msyncd and at the path /synchronizer. A dbus method can be invoked from cmdline as

dbus-send --session --type=method_call --print-reply --dest=com.meego.msyncd /synchronizer com.meego.msyncd.startSync string:'abc.com'

Following are the signals available in msyncd

- Signal to give status of an ongoing sync session
  <signal name="syncStatus">
  <arg name="aProfileName" type="s" direction="out"/>
  <arg name="aStatus" type="i" direction="out"/>
  <arg name="aMessage" type="s" direction="out"/>
  <arg name="aMoreDetails" type="i" direction="out"/>
  </signal>
- Signal to indicate the transfer progress (of the number of items transfered and the kind of items)
  <signal name="transferProgress">
  <arg name="aProfileName" type="s" direction="out"/>
  <arg name="aTransferDatabase" type="i" direction="out"/>
  <arg name="aTransferType" type="i" direction="out"/>
  <arg name="aMimeType" type="s" direction="out"/>
  <arg name="aCommittedItems" type="i" direction="out"/>
  </signal>
- Signal to indicate if a profile has changed
  <signal name="signalProfileChanged">
  <arg name="aProfileName" type="s" direction="out"/>
  <arg name="aChangeType" type="i" direction="out"/>
  <arg name="aProfileAsXml" type="s" direction="out"/>
  </signal>
- Signal to indicate a backup operation in progress. If a backup service is ongoing then msyncd does not start sync until the backup is complete. This signal can be use to keep track of an ongoing backup operation
  <signal name="backupInProgress">
  </signal>
  -Signal to indicate that a backup operation is done
  <signal name="backupDone">
  </signal>
- Signal to indicate that restore operation is in progress
  <signal name="restoreInProgress">
  </signal>
- Signal to indicate that the restoration process is completed
  <signal name="restoreDone">
  </signal>
- Signal to indicate that the results of the just finished sync operation are available
  <signal name="resultsAvailable">
  <arg name="aProfileName" type="s" direction="out"/>
  <arg name="aResultsAsXml" type="s" direction="out"/>
  </signal>
- Signal to indicate that the status of the sync operation has changed. The status could be that the state has changed from in progress to failed with also the failed reason
  <signal name="statusChanged">
  <arg name="aAccountId" type="u" direction="out"/>
  <arg name="aNewStatus" type="i" direction="out"/>
  <arg name="aFailedReason" type="i" direction="out"/>
  <arg name="aPrevSyncTime" type="x" direction="out"/>
  <arg name="aNextSyncTime" type="x" direction="out"/>
  </signal>

Following are the dbus methods of msyncd

- Method to start sync given a profile name. The profile name is the name of the Sync profile XML file. The startSync operation is valid only for client plugins
  <method name="startSync">
  <arg type="b" direction="out"/>
  <arg name="aProfileId" type="s" direction="in"/>
  </method>
- Method to cancel an ongoing sync. The profile id has to be specific to cancel an ongoing sync operation
  <method name="abortSync">
  <arg name="aProfileId" type="s" direction="in"/>
  <annotation name="org.freedesktop.DBus.Method.NoReply" value="true"/>
  </method>
- Method to remove a profile. A profile can be removed if it is not longer required, like for example, removing a sync account
  <method name="removeProfile">
  <arg type="b" direction="out"/>
  <arg name="aProfileId" type="s" direction="in"/>
  </method>
- Method to update a given sync profile. The profile to be updated should be in the form of an XML and the XML object should be sent so that it can be updated. If the updation fails, then false is returned, else true
  <method name="updateProfile">
  <arg type="b" direction="out"/>
  <arg name="aProfileAsXml" type="s" direction="in"/>
  </method>
- Method to request storages to be loaded. This is useful if a plugin makes use of existing storage plugins (contacts, calendar, notes) to perform the sync operation. If a plugin has its own way to manage the interaction with plugins, then this method need to be used
  <method name="requestStorages">
  <arg type="b" direction="out"/>
  <arg name="aStorageNames" type="as" direction="in"/>
  </method>
- Method to release a storage that has already been requested using "requestStorage" method
  <method name="releaseStorages">
  <arg name="aStorageNames" type="as" direction="in"/>
  <annotation name="org.freedesktop.DBus.Method.NoReply" value="true"/>
  </method>
- Method to check if connectivity for a specific type is avialable. Currently supported type: USB=0, Bluetooth=1 and Network=2
  <method name="isConnectivityAvailable">
  <arg type="b" direction="out"/>
  <arg name="connectivityType" type="i" direction="in"/>
  </method>
- Method to get a list of all running sync sessions
  <method name="runningSyncs">
  <arg type="as" direction="out"/>
  </method>
- Method to get the current state of backup/restore. True=backup/restore ongoing, false otherwise
  <method name="getBackUpRestoreState">
  <arg type="b" direction="out"/>
  </method>
- Method to set the sync schedule
  <method name="setSyncSchedule">
  <arg type="b" direction="out"/>
  <arg name="aProfileId" type="s" direction="in"/>
  <arg name="aScheduleAsXml" type="s" direction="in"/>
  </method>
  The format of the sync schedule is:
  "<schedule time="12:34:56" interval="30" days="1,2,3,4,5,6">"
  "<rush enabled="true" interval="15""
  "begin="08:00:00" end="16:00:00" days="1,4,5"/>"
  "</schedule>"

time is the time starting which the sync schedule has to be enabled
interval is in minutes is the frequency of sync
days is the days on which the sync has to run
rush is the sync setting for peak hours of the day. The idea is to run sync at a higher frequency in rush days than in the normal days. The rush begin time and end time and the rush days can be specified

- Method to save the sync results. This method can be used to persist the sync results given a profile id
  <method name="saveSyncResults">
  <arg type="b" direction="out"/>
  <arg name="aProfileId" type="s" direction="in"/>
  <arg name="aSyncResults" type="s" direction="in"/>
  </method>
- Method to get the sync results of the last finished sync session. The sync results are returned as an XML string, which then has to be parsed to retrieve the results. One can use the SyncResults class of libbuteosycnfw to handle any of the XML data received
  <method name="getLastSyncResult">
  <arg type="s" direction="out"/>
  <arg name="aProfileId" type="s" direction="in"/>
  </method>
- A profile can be made a hidden so as not be be displayed in a UI. This method fetches the profiles that have been marked as visible
  <method name="allVisibleSyncProfiles">
  <arg type="as" direction="out"/>
  </method>
- Method to fetch a sync profile object given a profile id. The profile is returned in XML and the SyncProfile class of libbuteosyncfw can be used to parse the sync profile
  <method name="syncProfile">
  <arg type="s" direction="out"/>
  <arg name="aProfileId" type="s" direction="in"/>
  </method>
- Method to fetch a specific sync profile based on a key. The key can be anything like sync direction, the URL of the target service etc. If there are multiple profiles matching the key, then all of them are returned
  <method name="syncProfilesByKey">
  <arg type="as" direction="out"/>
  <arg name="aKey" type="s" direction="in"/>
  <arg name="aValue" type="s" direction="in"/>
  </method>
- Method to fetch a sync profile given a type of sync. The type can be client, server, storage
  <method name="syncProfilesByType">
  <arg type="as" direction="out"/>
  <arg name="aType" type="s" direction="in"/>
  </method>
- Method to start a sync session with an account Id. This is useful if Buteo is integrated with AccountS&SSO. The account id is passed to start the sync
  <method name="start">
  <arg name="aAccountId" type="u" direction="in"/>
  <annotation name="org.freedesktop.DBus.Method.NoReply" value="true"/>
  </method>
- Method to stop a sync given an account id
  <method name="stop">
  <arg name="aAccountId" type="u" direction="in"/>
  <annotation name="org.freedesktop.DBus.Method.NoReply" value="true"/>
  </method>
- Method to return the list of account id of all the ongoing sync sessions. This method is useful when Buteo is integrated with Accounts&SSO
  <method name="syncingAccounts">
  <arg type="au" direction="out"/>
  <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="QList&lt;uint&gt;"/>
  </method>
- Method to return the status of a sync given an account id. This method is useful if Buteo is integrated with Accounts&SSO
  <method name="status">
  <arg type="i" direction="out"/>
  <arg name="aAccountId" type="u" direction="in"/>
  <arg name="aFailedReason" type="i" direction="out"/>
  <arg name="aPrevSyncTime" type="x" direction="out"/>
  <arg name="aNextSyncTime" type="x" direction="out"/>
  </method>

# libbuteosyncfw API

If one needs to use the API of the syncfw, then you can do so by using the library libbuteosyncfw. The main use of this library is to use the plugin API and the profile API. The profile API provides an easy way to manage the sync profiles. Following is the main API available in this library

- Logging
- Profile management
- Plugin management
- A dbus library interface for client apps, like GUIs

## Using Logging API

The library uses the following Qt logging categories:

- buteo.core (for the library)
- buteo.msyncd (for the msyncd process)
- buteo.plugin (for the plugin runner)
- buteo.trace (for function tracing)

By default, logging is disabled. Logging can be enabled as per Qt logging features. For example, to enable msyncd logging, run it with the buteo.msyncd logging enabled:

    QT_LOGGING_RULES="buteo.plugin.msyncd.debug=true" /usr/bin/msyncd

To enable debugging for all categories under buteo.plugin.*:

    QT_LOGGING_RULES="buteo.plugin.*.debug=true" /usr/bin/msyncd

In addition, LogMacros.h has a FUNCTION_CALL_TRACE macro that can be used to trace the entry and exit of functions.

## Profile Management API

Profile management API can be used to manage the profile information. For example, it can be used to retrive profiles, create profiles from a template, update profiles and save them back, fetch the results of the last sync, fetch the logs of the sync results etc. The main class that handle profile management are:

- Buteo::ProfileManager,
- Buteo::Profile,
- Buteo::SyncProfile,
- Buteo::SyncSchedule,
- Buteo::SyncResults,
- Buteo::StorageProfile,
- Buteo::SyncLog

### Update a given profile

Following is a code snippet to update a given profile

using namespace Buteo;
...
...
ProfileManager pm;
SyncProfile *sp = pm.syncProfile(profileName);
if (sp) {
sp->setSyncDirection(SyncProfile::SYNC_DIRECTION_FROM_REMOTE);
if (pm.updateProfile(sp).isEmpty()) {
qDebug() << "Update failed for profile " << profileName;
} else
qDebug() << "Profile successfully updated";
}
...
...
Buteo::ProfileManager
ProfileManager is responsible for storing and retrieving the profiles.
Definition ProfileManager.h:47
Buteo::ProfileManager::updateProfile
QString updateProfile(const Profile &aProfile)
Updates the existing profile with the profile given as parameter and emits profileChanged() Signal wi...
Definition ProfileManager.cpp:665
Buteo::ProfileManager::syncProfile
SyncProfile * syncProfile(const QString &aName)
Gets a sync profile.
Definition ProfileManager.cpp:320
Buteo::SyncProfile
A top level synchronization profile.
Definition SyncProfile.h:49
Buteo::SyncProfile::SYNC_DIRECTION_FROM_REMOTE
@ SYNC_DIRECTION_FROM_REMOTE
Data is copied from remote device only.
Definition SyncProfile.h:79
Buteo::SyncProfile::setSyncDirection
void setSyncDirection(SyncDirection aDirection)
Sets sync direction.
Definition SyncProfile.cpp:550

### Handle sync schedule

ProfileManager can be used to set the schedule of a sync session

using namespace Buteo;
...
...
ProfileManager pm;
SyncProfile *sp = pm.syncProfile(profileName);
if (sp) {
SyncSchedule sched = sp->syncSchedule();
if (!sched.isEmpty()) {
sched.setInterval(45);
sched.setRushEnabled(false);
DaySet days;
days << Qt::Tuesday << Qt::Thursday << Qt::Sunday;
sched.setDays(days);
sched.setScheduleEnabled(true);
sp->setSyncSchedule(sched);
} else {
SyncSchedule newSched;
newSched.setInterval(15);
newSched.setTime(new QDateTime());
newSched.setScheduleEnabled(true);
sp->setSyncSchedule(newSched);
}
pm.updateProfile(sp);
}
Buteo::SyncProfile::syncSchedule
SyncSchedule syncSchedule() const
Gets sync schedule settings.
Definition SyncProfile.cpp:318
Buteo::SyncProfile::setSyncSchedule
void setSyncSchedule(const SyncSchedule &aSchedule)
Sets sync schedule settings.
Definition SyncProfile.cpp:323
Buteo::SyncSchedule
Class for handling sync schedule settings.
Definition SyncSchedule.h:53
Buteo::SyncSchedule::setTime
void setTime(const QTime &aTime)
Sets the exact time for sync.
Definition SyncSchedule.cpp:192
Buteo::SyncSchedule::setScheduleEnabled
void setScheduleEnabled(bool aEnabled)
Sets if normal schedule is to be obeyed.
Definition SyncSchedule.cpp:212
Buteo::SyncSchedule::setInterval
void setInterval(unsigned aInterval)
Sets sync interval in minutes.
Definition SyncSchedule.cpp:202
Buteo::SyncSchedule::setDays
void setDays(Days aDays)
Sets the enabled week days.
Definition SyncSchedule.cpp:172
Buteo::SyncSchedule::setRushEnabled
void setRushEnabled(bool aEnabled)
Sets rush hour schedule is to be obeyed.
Definition SyncSchedule.cpp:222