libquentier  0.4.0
The library for rich desktop clients of Evernote service
Public Slots | Signals | Public Member Functions | List of all members
quentier::SynchronizationManager Class Reference

The SynchronizationManager class encapsulates methods and signals & slots required to perform the full or partial synchronization of data with remote Evernote servers. The class also deals with authentication with Evernote service through OAuth. More...

#include <SynchronizationManager.h>

Inheritance diagram for quentier::SynchronizationManager:
Inheritance graph
[legend]
Collaboration diagram for quentier::SynchronizationManager:
Collaboration graph
[legend]

Public Slots

void setAccount (Account account)
 
void authenticate ()
 
void synchronize ()
 
void stop ()
 
void revokeAuthentication (const qevercloud::UserID userId)
 
void setDownloadNoteThumbnails (bool flag)
 
void setDownloadInkNoteImages (bool flag)
 
void setInkNoteImagesStoragePath (QString path)
 

Signals

void started ()
 
void stopped ()
 
void failed (ErrorString errorDescription)
 
void finished (Account account)
 
void authenticationRevoked (bool success, ErrorString errorDescription, qevercloud::UserID userId)
 
void authenticationFinished (bool success, ErrorString errorDescription, Account account)
 
void remoteToLocalSyncStopped ()
 
void sendLocalChangesStopped ()
 
void willRepeatRemoteToLocalSyncAfterSendingChanges ()
 
void detectedConflictDuringLocalChangesSending ()
 
void rateLimitExceeded (qint32 secondsToWait)
 
void remoteToLocalSyncDone ()
 
void syncChunksDownloadProgress (qint32 highestDownloadedUsn, qint32 highestServerUsn, qint32 lastPreviousUsn)
 
void syncChunksDownloaded ()
 
void linkedNotebookSyncChunksDownloadProgress (qint32 highestDownloadedUsn, qint32 highestServerUsn, qint32 lastPreviousUsn, LinkedNotebook linkedNotebook)
 
void linkedNotebooksSyncChunksDownloaded ()
 
void notesDownloadProgress (quint32 notesDownloaded, quint32 totalNotesToDownload)
 
void linkedNotebooksNotesDownloadProgress (quint32 notesDownloaded, quint32 totalNotesToDownload)
 
void resourcesDownloadProgress (quint32 resourcesDownloaded, quint32 totalResourcesToDownload)
 
void linkedNotebooksResourcesDownloadProgress (quint32 resourcesDownloaded, quint32 totalResourcesToDownload)
 
void preparedDirtyObjectsForSending ()
 
void preparedLinkedNotebooksDirtyObjectsForSending ()
 
void setAccountDone (Account account)
 
void setDownloadNoteThumbnailsDone (bool flag)
 
void setDownloadInkNoteImagesDone (bool flag)
 
void setInkNoteImagesStoragePathDone (QString path)
 

Public Member Functions

 SynchronizationManager (const QString &consumerKey, const QString &consumerSecret, const QString &host, LocalStorageManagerAsync &localStorageManagerAsync, IAuthenticationManager &authenticationManager)
 
bool active () const
 
bool downloadNoteThumbnailsOption () const
 

Detailed Description

The SynchronizationManager class encapsulates methods and signals & slots required to perform the full or partial synchronization of data with remote Evernote servers. The class also deals with authentication with Evernote service through OAuth.

Constructor & Destructor Documentation

◆ SynchronizationManager()

quentier::SynchronizationManager::SynchronizationManager ( const QString &  consumerKey,
const QString &  consumerSecret,
const QString &  host,
LocalStorageManagerAsync localStorageManagerAsync,
IAuthenticationManager authenticationManager 
)
Parameters
consumerKey- consumer key for your application obtained from the Evernote service
consumerSecret- consumer secret for your application obtained from the Evernote service
host- the host to use for the connection with the Evernote service - typically www.evernote.com but could be sandbox.evernote.com or some other one
localStorageManagerAsync- local storage manager
authenticationManager- authentication manager (particular implementation of IAuthenticationManager abstract class)

Member Function Documentation

◆ active()

bool quentier::SynchronizationManager::active ( ) const
Returns
true if the synchronization is being performed at the moment, false otherwise

◆ authenticate

void quentier::SynchronizationManager::authenticate ( )
slot

Use this slot to authenticate the new user to do the synchronization with the Evernote service via the client app. The invoking of slot would respond asynchronously with authenticationFinished signal but won't start the synchronization.

Note that this slot would always proceed to the actual OAuth.

◆ authenticationFinished

void quentier::SynchronizationManager::authenticationFinished ( bool  success,
ErrorString  errorDescription,
Account  account 
)
signal

This signal is emitted in response to the attempt to authenticate the new user of the client app to synchronize with the Evernote service

Parameters
success- true if the authentication was successful, false otherwise
errorDescription- the textual explanation of the failure to authenticate the new user
account- the account of the authenticated user

◆ authenticationRevoked

void quentier::SynchronizationManager::authenticationRevoked ( bool  success,
ErrorString  errorDescription,
qevercloud::UserID  userId 
)
signal

This signal is emitted in response to the attempt to revoke the authentication for a given user ID

Parameters
success- true if the authentication was revoked successfully, false otherwise
errorDescription- the textual explanation of the failure to revoke the authentication
userId- the ID of the user for which the revoke of the authentication was requested

◆ detectedConflictDuringLocalChangesSending

void quentier::SynchronizationManager::detectedConflictDuringLocalChangesSending ( )
signal

This signal is emitted if during the "send local changes" synchronization step it was found out that new changes from the Evernote service are available AND some of them conflict with the local changes being sent.

Such situation can rarely happen in case of changes introduced concurrently with the running synchronization - perhaps via another client. The algorithm will handle it by repeating the "remote to local" incremental synchronization step, the signal is just for the sake of diagnostic

◆ downloadNoteThumbnailsOption()

bool quentier::SynchronizationManager::downloadNoteThumbnailsOption ( ) const
Returns
true or false depending on the option to download the thumbnails for notes containing resources during sync; by default no thumbnails are downloaded

◆ failed

void quentier::SynchronizationManager::failed ( ErrorString  errorDescription)
signal

This signal is emitted when the synchronization fails; at this moment there is no error code explaining the reason of the failure programmatically so the only explanation available is the textual one for the end user

◆ finished

void quentier::SynchronizationManager::finished ( Account  account)
signal

This signal is emitted when the synchronization is finished

Parameters
account- represents the latest version of Account structure filled during the synchronization procedure

◆ linkedNotebooksNotesDownloadProgress

void quentier::SynchronizationManager::linkedNotebooksNotesDownloadProgress ( quint32  notesDownloaded,
quint32  totalNotesToDownload 
)
signal

This signal is emitted on each successful download of full note data from linked notebooks

Parameters
notesDownloadedis the number of notes downloaded by the moment
totalNotesToDownloadis the total number of notes that need to be downloaded

◆ linkedNotebooksResourcesDownloadProgress

void quentier::SynchronizationManager::linkedNotebooksResourcesDownloadProgress ( quint32  resourcesDownloaded,
quint32  totalResourcesToDownload 
)
signal

This signal is emitted on each successful download of full resource data from linked notebooks during the incremental sync (as individual resources are downloaded along with their notes during full sync)

Parameters
resourcesDownloadedis the number of resources downloaded by the moment
totalResourcesToDownloadis the total number of resources that need to be downloaded

◆ linkedNotebooksSyncChunksDownloaded

void quentier::SynchronizationManager::linkedNotebooksSyncChunksDownloaded ( )
signal

This signal is emitted when the sync chunks for the stuff from linked notebooks are downloaded during "remote to local" synchronization step

◆ linkedNotebookSyncChunksDownloadProgress

void quentier::SynchronizationManager::linkedNotebookSyncChunksDownloadProgress ( qint32  highestDownloadedUsn,
qint32  highestServerUsn,
qint32  lastPreviousUsn,
LinkedNotebook  linkedNotebook 
)
signal

This signal is emitted during linked notebooks sync chunks downloading and denotes the progress of that step, individually for each linked notebook. The percentage of completeness can be computed roughly as (highestDownloadedUsn - lastPreviousUsn) / (highestServerUsn - lastPreviousUsn) * 100%. The sync chunks for each linked notebook are downloaded sequentially so the signals for one linked notebook should not intermix with signals for other linked notebooks, however, it is within hands of Qt's slot schedulers

Parameters
highestDownloadedUsndenotes the highest update sequence number within data items from linked notebook sync chunks downloaded so far
highestServerUsndenotes the current highest update sequence number within the linked notebook
lastPreviousUsndenotes the last update sequence number from previous sync of the given linked notebook; if current sync is the first one, this value is zero
linkedNotebookdenotes the linked notebook which sync chunks download progress is reported

◆ notesDownloadProgress

void quentier::SynchronizationManager::notesDownloadProgress ( quint32  notesDownloaded,
quint32  totalNotesToDownload 
)
signal

This signal is emitted on each successful download of full note data from user's own account

Parameters
notesDownloadedis the number of notes downloaded by the moment
totalNotesToDownloadis the total number of notes that need to be downloaded

◆ preparedDirtyObjectsForSending

void quentier::SynchronizationManager::preparedDirtyObjectsForSending ( )
signal

This signal is emitted during "send local changes" synchronization step when all the relevant data elements from user's own account were prepared for sending to the Evernote service

◆ preparedLinkedNotebooksDirtyObjectsForSending

void quentier::SynchronizationManager::preparedLinkedNotebooksDirtyObjectsForSending ( )
signal

This signal is emitted during "send local changes" synchronization step when all the relevant data elements from linked notebooks were prepared for sending to the Evernote service

◆ rateLimitExceeded

void quentier::SynchronizationManager::rateLimitExceeded ( qint32  secondsToWait)
signal

This signal is emitted when the Evernote API rate limit is breached during the synchronization; the algorithm will handle it by auto-pausing itself until the time necessary to wait passes and then automatically continuing the synchronization.

Parameters
secondsToWait- the amount of time (in seconds) necessary to wait before the synchronization will continue

◆ remoteToLocalSyncDone

void quentier::SynchronizationManager::remoteToLocalSyncDone ( )
signal

This signal is emitted when the "remote to local" synchronization step is finished; once that step is done, the algorithn switches to sending the local changes back to the Evernote service

◆ remoteToLocalSyncStopped

void quentier::SynchronizationManager::remoteToLocalSyncStopped ( )
signal

This signal is emitted when the "remote to local" synchronization step is stopped

◆ resourcesDownloadProgress

void quentier::SynchronizationManager::resourcesDownloadProgress ( quint32  resourcesDownloaded,
quint32  totalResourcesToDownload 
)
signal

This signal is emitted on each successful doenload of full resource data from user's own account during the incremental sync (as individual resources are downloaded along with their notes during full sync)

Parameters
resourcesDownloadedis the number of resources downloaded by the moment
totalResourcesToDownloadis the total number of resources that need to be downloaded

◆ revokeAuthentication

void quentier::SynchronizationManager::revokeAuthentication ( const qevercloud::UserID  userId)
slot

Use this slot to remove any previously cached authentication tokens (and shard ids) for a given user ID. After the call of this method the next attempt to synchronize the data for this user ID would cause the launch of OAuth to get the new authentication token

◆ sendLocalChangesStopped

void quentier::SynchronizationManager::sendLocalChangesStopped ( )
signal

This signal is emitted when the "send local changes" synchronization step is stopped

◆ setAccount

void quentier::SynchronizationManager::setAccount ( Account  account)
slot

Use this slot to set the current account for the synchronization manager. If the slot is called during the synchronization running, it would stop, any internal caches belonging to previously selected account (if any) would be purged (but persistent settings like the authentication token saved in the system keychain would remain). Setting the current account won't automatically start the synchronization for it, use slot for this. The attempt to set the current account of "Local" type would just clean up the synchronization manager as if it was just created After the method finishes its job, setAccountDone signal is emitted

◆ setAccountDone

void quentier::SynchronizationManager::setAccountDone ( Account  account)
signal

This signal is emitted in response to invoking the setAccount slot after all the activities involved in switching the account inside SynchronizationManager are finished

◆ setDownloadInkNoteImages

void quentier::SynchronizationManager::setDownloadInkNoteImages ( bool  flag)
slot

Use this slot to switch the option whether the synchronization of notes would download the plain images corresponding to ink notes or not. By default the downloading of ink note images is disabled.

After the method finishes its job, setDownloadInkNoteImagesDone signal is emitted

◆ setDownloadInkNoteImagesDone

void quentier::SynchronizationManager::setDownloadInkNoteImagesDone ( bool  flag)
signal

This signal is emitted in response to invoking the setDownloadInkNoteImages slot after the setting is accepted

◆ setDownloadNoteThumbnails

void quentier::SynchronizationManager::setDownloadNoteThumbnails ( bool  flag)
slot

Use this slot to switch the option whether the synchronization of notes would download the note thumbnails or not. By default the downloading of thumbnails for notes containing resources is disabled.

NOTE: even if thumbnails downloading is enabled, the thumbnails would be downloaded during sync only for notes containing resources

After the method finishes its job, setDownloadNoteThumbnailsDone signal is emitted

◆ setDownloadNoteThumbnailsDone

void quentier::SynchronizationManager::setDownloadNoteThumbnailsDone ( bool  flag)
signal

This signal is emitted in response to invoking the setDownloadNoteThumbnails slot after the setting is accepted

◆ setInkNoteImagesStoragePath

void quentier::SynchronizationManager::setInkNoteImagesStoragePath ( QString  path)
slot

Use this slot to specify the path to folder at which the downloaded ink note images should be stored. Each ink note image would be stored in a separate PNG file which name would be the same as the guid of the corresponding resource and the file extension would be PNG

The default storage path would be the folder "inkNoteImages" within the folder returned by applicationPersistentStoragePath function found in quentier/StandardPaths.h header

WARNING: if the passed in path cannot be used (either it doesn't exist and cannot be created or exists but is not writable), the default path is silently restored. So make sure you're setting a valid path

After the method finishes its job, setInkNoteImagesStoragePathDone signal is emitted

◆ setInkNoteImagesStoragePathDone

void quentier::SynchronizationManager::setInkNoteImagesStoragePathDone ( QString  path)
signal

This signal is emitted in response to invoking the setInkNoteImagesStoragePath slot after the setting is accepted

◆ started

void quentier::SynchronizationManager::started ( )
signal

This signal is emitted when the synchronization is started (authentication is not considered a part of synchronization so this signal is only emitted when the authentication is completed)

◆ stop

void quentier::SynchronizationManager::stop ( )
slot

Use this slot to stop the running synchronization; if no synchronization is running by the moment of this slot call, it has no effect

◆ stopped

void quentier::SynchronizationManager::stopped ( )
signal

This signal is emitted in response to invoking the stop slot, whether it was invoked manually or from within the SynchronizationManager itself (due to sync failure, for example)

◆ syncChunksDownloaded

void quentier::SynchronizationManager::syncChunksDownloaded ( )
signal

This signal is emitted when the sync chunks for the stuff from user's own account are downloaded during "remote to local" synchronization step

◆ syncChunksDownloadProgress

void quentier::SynchronizationManager::syncChunksDownloadProgress ( qint32  highestDownloadedUsn,
qint32  highestServerUsn,
qint32  lastPreviousUsn 
)
signal

This signal is emitted during user own account's sync chunks downloading and denotes the progress of that step. The percentage of completeness can be computed roughly as (highestDownloadedUsn - lastPreviousUsn) / (highestServerUsn - lastPreviousUsn) * 100%

Parameters
highestDownloadedUsndenotes the highest update sequence number within data items from sync chunks downloaded so far
highestServerUsndenotes the current highest update sequence number within the account
lastPreviousUsndenotes the last update sequence number from previous sync; if current sync is the first one, this value is zero

◆ synchronize

void quentier::SynchronizationManager::synchronize ( )
slot

Use this slot to launch the synchronization of data

◆ willRepeatRemoteToLocalSyncAfterSendingChanges

void quentier::SynchronizationManager::willRepeatRemoteToLocalSyncAfterSendingChanges ( )
signal

This signal is emitted if during the "send local changes" synchronization step it was found out that new changes from the Evernote service are available yet no conflict between remote and local changes was found yet.

Such situation can rarely happen in case of changes introduced concurrently with the running synchronization - perhaps via another client. The algorithm will handle it, the signal is just for the sake of diagnostic