libquentier 0.5.0
The library for rich desktop clients of Evernote service
Loading...
Searching...
No Matches
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 authenticateCurrentAccount ()
 
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, bool somethingDownloaded, bool somethingSent)
 
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 (bool somethingDownloaded)
 
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 (QString host, LocalStorageManagerAsync &localStorageManagerAsync, IAuthenticationManager &authenticationManager, QObject *parent=nullptr, INoteStorePtr pNoteStore={}, IUserStorePtr pUserStore={}, IKeychainServicePtr pKeychainService={}, ISyncStateStoragePtr pSyncStateStorage={})
 
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 ( QString  host,
LocalStorageManagerAsync localStorageManagerAsync,
IAuthenticationManager authenticationManager,
QObject *  parent = nullptr,
INoteStorePtr  pNoteStore = {},
IUserStorePtr  pUserStore = {},
IKeychainServicePtr  pKeychainService = {},
ISyncStateStoragePtr  pSyncStateStorage = {} 
)
Parameters
hostThe host to use for the connection with the Evernote service - typically www.evernote.com but could also be sandbox.evernote.com or some other one
localStorageManagerAsyncLocal storage manager
authenticationManagerReference to an object implementing IAuthenticationManager interface; SynchronizationManager does not store this reference, it only connects to the object via signals and slots during construction
pNoteStorePointer to an object implementing INoteStore interface; if nullptr, SynchronizatrionManager would create and use its own instance; otherwise SynchronizationManager would set itself as the parent of the passed in object
pUserStorePointer to an object implementing IUserStore interface; if nullptr, SynchronizationManager would create and use its own instance
pKeychainServicePointer to an object implementing IKeychainService interface; if nullptr, SynchronizationManager would create and use its own default instance; otherwise SynchronizationManager would set itself as the parent of the passed in object
pSyncStateStoragePointer to an object implementing ISyncStateStorage interface; if nullptr, SynchronizationManager would create and use its own instance; otherwise SynchronizationManager would set itself as the parent of the passed in object

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 invocation of this slot would respond asynchronously with authenticationFinished signal but won't start the synchronization.

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

◆ authenticateCurrentAccount

void quentier::SynchronizationManager::authenticateCurrentAccount ( )
slot

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

If no account was set to SynchronizationManager prior to this slot invocation, it would proceed to OAuth. Otherwise SynchronizationManager would first check whether the persistent authentication data is in place and actual. If yes, no OAuth would be performed.

◆ authenticationFinished

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

This signal is emitted in response to the explicit attempt to authenticate the new user of the client app to the Evernote service. NOTE: this signal is not emitted if the authentication was requested automatically during sync attempt, it is only emitted in response to the explicit invokation of authenticate slot.

Parameters
successTrue if the authentication was successful, false otherwise
errorDescriptionThe textual explanation of the failure to authenticate the new user
accountThe 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
successTrue if the authentication was revoked successfully, false otherwise
errorDescriptionThe textual explanation of the failure to revoke the authentication
userIdThe 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,
bool  somethingDownloaded,
bool  somethingSent 
)
signal

This signal is emitted when the synchronization is finished

Parameters
accountRepresents the latest version of Account structure filled during the synchronization procedure
somethingDownloadedBoolean parameter telling the receiver whether any data items were actually downloaded during remote to local synchronization step; if there was nothing to sync up from the remote storage, this boolean would be false, otherwise it would be true
somethingSentBoolean parameter telling the receiver whether any data items were actually sent during the send local changes synchronization step; if there was nothing to send to the remote storage, this boolean would be false, otherwise it would be true

◆ 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
notesDownloadedThe number of notes downloaded by the moment
totalNotesToDownloadThe 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
resourcesDownloadedThe number of resources downloaded by the moment
totalResourcesToDownloadThe 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
highestDownloadedUsnThe highest update sequence number within data items from linked notebook sync chunks downloaded so far
highestServerUsnThe current highest update sequence number within the linked notebook
lastPreviousUsnThe last update sequence number from previous sync of the given linked notebook; if current sync is the first one, this value is zero
linkedNotebookThe 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 use 's own account.

Parameters
notesDownloadedThe number of notes downloaded by the moment
totalNotesToDownloadThe 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
secondsToWaitThe amount of time (in seconds) necessary to wait before the synchronization will continue

◆ remoteToLocalSyncDone

void quentier::SynchronizationManager::remoteToLocalSyncDone ( bool  somethingDownloaded)
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.

Parameters
somethingDownloadedBoolean parameter telling the receiver whether any data items were actually downloaded during remote to local synchronization step; if there was nothing to sync up from the remote storage, this boolean would be false, otherwise it would be true

◆ 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
resourcesDownloadedThe number of resources downloaded by the moment
totalResourcesToDownloadThe 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 synchronize 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
highestDownloadedUsnThe highest update sequence number within data items from sync chunks downloaded so far
highestServerUsnThe current highest update sequence number within the account
lastPreviousUsnThe 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.