QEverCloud  4.0.0
Unofficial Evernote Cloud API for Qt
Public Member Functions | List of all members
qevercloud::UserStore Class Reference

#include <services.h>

Inheritance diagram for qevercloud::UserStore:

Public Member Functions

 UserStore (QString host, QString authenticationToken=QString(), QObject *parent=0)
 
void setAuthenticationToken (QString authenticationToken)
 
QString authenticationToken ()
 
bool checkVersion (QString clientName, qint16 edamVersionMajor=EDAM_VERSION_MAJOR, qint16 edamVersionMinor=EDAM_VERSION_MINOR)
 
AsyncResultcheckVersionAsync (QString clientName, qint16 edamVersionMajor=EDAM_VERSION_MAJOR, qint16 edamVersionMinor=EDAM_VERSION_MINOR)
 
BootstrapInfo getBootstrapInfo (QString locale)
 
AsyncResultgetBootstrapInfoAsync (QString locale)
 
AuthenticationResult authenticateLongSession (QString username, QString password, QString consumerKey, QString consumerSecret, QString deviceIdentifier, QString deviceDescription, bool supportsTwoFactor)
 
AsyncResultauthenticateLongSessionAsync (QString username, QString password, QString consumerKey, QString consumerSecret, QString deviceIdentifier, QString deviceDescription, bool supportsTwoFactor)
 
AuthenticationResult completeTwoFactorAuthentication (QString oneTimeCode, QString deviceIdentifier, QString deviceDescription, QString authenticationToken=QString())
 
AsyncResultcompleteTwoFactorAuthenticationAsync (QString oneTimeCode, QString deviceIdentifier, QString deviceDescription, QString authenticationToken=QString())
 
void revokeLongSession (QString authenticationToken=QString())
 
AsyncResultrevokeLongSessionAsync (QString authenticationToken=QString())
 
AuthenticationResult authenticateToBusiness (QString authenticationToken=QString())
 
AsyncResultauthenticateToBusinessAsync (QString authenticationToken=QString())
 
User getUser (QString authenticationToken=QString())
 
AsyncResultgetUserAsync (QString authenticationToken=QString())
 
PublicUserInfo getPublicUserInfo (QString username)
 
AsyncResultgetPublicUserInfoAsync (QString username)
 
UserUrls getUserUrls (QString authenticationToken=QString())
 
AsyncResultgetUserUrlsAsync (QString authenticationToken=QString())
 
void inviteToBusiness (QString emailAddress, QString authenticationToken=QString())
 
AsyncResultinviteToBusinessAsync (QString emailAddress, QString authenticationToken=QString())
 
void removeFromBusiness (QString emailAddress, QString authenticationToken=QString())
 
AsyncResultremoveFromBusinessAsync (QString emailAddress, QString authenticationToken=QString())
 
void updateBusinessUserIdentifier (QString oldEmailAddress, QString newEmailAddress, QString authenticationToken=QString())
 
AsyncResultupdateBusinessUserIdentifierAsync (QString oldEmailAddress, QString newEmailAddress, QString authenticationToken=QString())
 
QList< UserProfilelistBusinessUsers (QString authenticationToken=QString())
 
AsyncResultlistBusinessUsersAsync (QString authenticationToken=QString())
 
QList< BusinessInvitationlistBusinessInvitations (bool includeRequestedInvitations, QString authenticationToken=QString())
 
AsyncResultlistBusinessInvitationsAsync (bool includeRequestedInvitations, QString authenticationToken=QString())
 
AccountLimits getAccountLimits (ServiceLevel::type serviceLevel)
 
AsyncResultgetAccountLimitsAsync (ServiceLevel::type serviceLevel)
 

Detailed Description

Service: UserStore

The UserStore service is primarily used by EDAM clients to establish authentication via username and password over a trusted connection (e.g. SSL). A client's first call to this interface should be checkVersion() to ensure that the client's software is up to date.

All calls which require an authenticationToken may throw an EDAMUserException for the following reasons:

Constructor & Destructor Documentation

◆ UserStore()

qevercloud::UserStore::UserStore ( QString  host,
QString  authenticationToken = QString(),
QObject *  parent = 0 
)
explicit

Member Function Documentation

◆ authenticateLongSession()

AuthenticationResult qevercloud::UserStore::authenticateLongSession ( QString  username,
QString  password,
QString  consumerKey,
QString  consumerSecret,
QString  deviceIdentifier,
QString  deviceDescription,
bool  supportsTwoFactor 
)

This is used to check a username and password in order to create a long-lived authentication token that can be used for further actions.

This function is not available to most third party applications, which typically authenticate using OAuth as described at dev.evernote.com. If you believe that your application requires permission to authenticate using username and password instead of OAuth, please contact Evernote developer support by visiting dev.evernote.com.

Parameters
usernameThe username or registered email address of the account to authenticate against.
passwordThe plaintext password to check against the account. Since this is not protected by the EDAM protocol, this information must be provided over a protected transport (i.e. SSL).
consumerKeyThe "consumer key" portion of the API key issued to the client application by Evernote.
consumerSecretThe "consumer secret" portion of the API key issued to the client application by Evernote.
deviceIdentifierAn optional string that uniquely identifies the device from which the authentication is being performed. This string allows the service to return the same authentication token when a given application requests authentication repeatedly from the same device. This may happen when the user logs out of an application and then logs back in, or when the application is uninstalled and later reinstalled. If no reliable device identifier can be created, this value should be omitted. If set, the device identifier must be between 1 and EDAM_DEVICE_ID_LEN_MAX characters long and must match the regular expression EDAM_DEVICE_ID_REGEX.
deviceDescriptionA description of the device from which the authentication is being performed. This field is displayed to the user in a list of authorized applications to allow them to distinguish between multiple tokens issued to the same client application on different devices. For example, the Evernote iOS client on a user's iPhone and iPad might pass the iOS device names "Bob's iPhone" and "Bob's iPad". The device description must be between 1 and EDAM_DEVICE_DESCRIPTION_LEN_MAX characters long and must match the regular expression EDAM_DEVICE_DESCRIPTION_REGEX.
supportsTwoFactorWhether the calling application supports two-factor authentication. If this parameter is false, this method will fail with the error code INVALID_AUTH and the parameter "password" when called for a user who has enabled two-factor authentication.
Returns

The result of the authentication. The level of detail provided in the returned AuthenticationResult.User structure depends on the access level granted by calling application's API key.

If the user has two-factor authentication enabled, AuthenticationResult.secondFactorRequired will be set and AuthenticationResult.authenticationToken will contain a short-lived token that may only be used to complete the two-factor authentication process by calling UserStore.completeTwoFactorAuthentication.

Exceptions
EDAMUserException
  • DATA_REQUIRED "username" - username is empty
  • DATA_REQUIRED "password" - password is empty
  • DATA_REQUIRED "consumerKey" - consumerKey is empty
  • DATA_REQUIRED "consumerSecret" - consumerSecret is empty
  • DATA_REQUIRED "deviceDescription" - deviceDescription is empty
  • BAD_DATA_FORMAT "deviceDescription" - deviceDescription is not valid.
  • BAD_DATA_FORMAT "deviceIdentifier" - deviceIdentifier is not valid.
  • INVALID_AUTH "username" - username not found
  • INVALID_AUTH "password" - password did not match
  • INVALID_AUTH "consumerKey" - consumerKey is not authorized
  • INVALID_AUTH "consumerSecret" - consumerSecret is incorrect
  • PERMISSION_DENIED "User.active" - user account is closed
  • PERMISSION_DENIED "User.tooManyFailuresTryAgainLater" - user has failed authentication too often
  • AUTH_EXPIRED "password" - user password is expired

◆ authenticateLongSessionAsync()

AsyncResult* qevercloud::UserStore::authenticateLongSessionAsync ( QString  username,
QString  password,
QString  consumerKey,
QString  consumerSecret,
QString  deviceIdentifier,
QString  deviceDescription,
bool  supportsTwoFactor 
)

Asynchronous version of authenticateLongSession

◆ authenticateToBusiness()

AuthenticationResult qevercloud::UserStore::authenticateToBusiness ( QString  authenticationToken = QString())

This is used to take an existing authentication token that grants access to an individual user account (returned from 'authenticate', 'authenticateLongSession' or an OAuth authorization) and obtain an additional authentication token that may be used to access business notebooks if the user is a member of an Evernote Business account.

The resulting authentication token may be used to make NoteStore API calls against the business using the NoteStore URL returned in the result.

Parameters
authenticationTokenThe authentication token for the user. This may not be a shared authentication token (returned by NoteStore.authenticateToSharedNotebook or NoteStore.authenticateToSharedNote) or a business authentication token.
Returns
The result of the authentication, with the token granting access to the business in the result's 'authenticationToken' field. The URL that must be used to access the business account NoteStore will be returned in the result's 'noteStoreUrl' field. The 'User' field will not be set in the result.
Exceptions
EDAMUserException
  • PERMISSION_DENIED "authenticationToken" - the provided authentication token is a shared or business authentication token.
  • PERMISSION_DENIED "Business" - the user identified by the provided authentication token is not currently a member of a business.
  • PERMISSION_DENIED "Business.status" - the business that the user is a member of is not currently in an active status.
  • BUSINESS_SECURITY_LOGIN_REQUIRED "sso" - the user must complete single sign-on before authenticating to the business.

◆ authenticateToBusinessAsync()

AsyncResult* qevercloud::UserStore::authenticateToBusinessAsync ( QString  authenticationToken = QString())

Asynchronous version of authenticateToBusiness

◆ authenticationToken()

QString qevercloud::UserStore::authenticationToken ( )
inline

◆ checkVersion()

bool qevercloud::UserStore::checkVersion ( QString  clientName,
qint16  edamVersionMajor = EDAM_VERSION_MAJOR,
qint16  edamVersionMinor = EDAM_VERSION_MINOR 
)

This should be the first call made by a client to the EDAM service. It tells the service what protocol version is used by the client. The service will then return true if the client is capable of talking to the service, and false if the client's protocol version is incompatible with the service, so the client must upgrade. If a client receives a false value, it should report the incompatibility to the user and not continue with any more EDAM requests (UserStore or NoteStore).

Parameters
clientNameThis string provides some information about the client for tracking/logging on the service. It should provide information about the client's software and platform. The structure should be: application/version; platform/version; [ device/version ] E.g. "Evernote Windows/3.0.1; Windows/XP SP3".
edamVersionMajorThis should be the major protocol version that was compiled by the client. This should be the current value of the EDAM_VERSION_MAJOR constant for the client.
edamVersionMinorThis should be the major protocol version that was compiled by the client. This should be the current value of the EDAM_VERSION_MINOR constant for the client.

◆ checkVersionAsync()

AsyncResult* qevercloud::UserStore::checkVersionAsync ( QString  clientName,
qint16  edamVersionMajor = EDAM_VERSION_MAJOR,
qint16  edamVersionMinor = EDAM_VERSION_MINOR 
)

Asynchronous version of checkVersion

◆ completeTwoFactorAuthentication()

AuthenticationResult qevercloud::UserStore::completeTwoFactorAuthentication ( QString  oneTimeCode,
QString  deviceIdentifier,
QString  deviceDescription,
QString  authenticationToken = QString() 
)

Complete the authentication process when a second factor is required. This call is made after a successful call to authenticate or authenticateLongSession when the authenticating user has enabled two-factor authentication.

Parameters
authenticationTokenAn authentication token returned by a previous call to UserStore.authenticate or UserStore.authenticateLongSession that could not be completed in a single call because a second factor was required.
oneTimeCodeThe one time code entered by the user. This value is delivered out-of-band, typically via SMS or an authenticator application.
deviceIdentifierSee the corresponding parameter in authenticateLongSession.
deviceDescriptionSee the corresponding parameter in authenticateLongSession.
Returns
The result of the authentication. The level of detail provided in the returned AuthenticationResult.User structure depends on the access level granted by the calling application's API key. If the initial authentication call was made to authenticateLongSession, the AuthenticationResult will contain a long-lived authentication token.
Exceptions
EDAMUserException
  • DATA_REQUIRED "authenticationToken" - authenticationToken is empty
  • DATA_REQUIRED "oneTimeCode" - oneTimeCode is empty
  • BAD_DATA_FORMAT "deviceIdentifier" - deviceIdentifier is not valid
  • BAD_DATA_FORMAT "authenticationToken" - authenticationToken is not well formed
  • INVALID_AUTH "oneTimeCode" - oneTimeCode did not match
  • AUTH_EXPIRED "authenticationToken" - authenticationToken has expired
  • PERMISSION_DENIED "authenticationToken" - authenticationToken is not valid
  • PERMISSION_DENIED "User.active" - user account is closed
  • PERMISSION_DENIED "User.tooManyFailuresTryAgainLater" - user has failed authentication too often
  • DATA_CONFLICT "User.twoFactorAuthentication" - The user has not enabled two-factor authentication.

◆ completeTwoFactorAuthenticationAsync()

AsyncResult* qevercloud::UserStore::completeTwoFactorAuthenticationAsync ( QString  oneTimeCode,
QString  deviceIdentifier,
QString  deviceDescription,
QString  authenticationToken = QString() 
)

Asynchronous version of completeTwoFactorAuthentication

◆ getAccountLimits()

AccountLimits qevercloud::UserStore::getAccountLimits ( ServiceLevel::type  serviceLevel)

Retrieve the standard account limits for a given service level. This should only be called when necessary, e.g. to determine if a higher level is available should the user upgrade, and should be cached for long periods (e.g. 30 days) as the values are not expected to fluctuate frequently.

Exceptions
EDAMUserException
  • DATA_REQUIRED "serviceLevel" - serviceLevel is null

◆ getAccountLimitsAsync()

AsyncResult* qevercloud::UserStore::getAccountLimitsAsync ( ServiceLevel::type  serviceLevel)

Asynchronous version of getAccountLimits

◆ getBootstrapInfo()

BootstrapInfo qevercloud::UserStore::getBootstrapInfo ( QString  locale)

This provides bootstrap information to the client. Various bootstrap profiles and settings may be used by the client to configure itself.

Parameters
localeThe client's current locale, expressed in language[_country] format. E.g., "en_US". See ISO-639 and ISO-3166 for valid language and country codes.
Returns
The bootstrap information suitable for this client.

◆ getBootstrapInfoAsync()

AsyncResult* qevercloud::UserStore::getBootstrapInfoAsync ( QString  locale)

Asynchronous version of getBootstrapInfo

◆ getPublicUserInfo()

PublicUserInfo qevercloud::UserStore::getPublicUserInfo ( QString  username)

Asks the UserStore about the publicly available location information for a particular username.

Exceptions
EDAMUserException
  • DATA_REQUIRED "username" - username is empty

◆ getPublicUserInfoAsync()

AsyncResult* qevercloud::UserStore::getPublicUserInfoAsync ( QString  username)

Asynchronous version of getPublicUserInfo

◆ getUser()

User qevercloud::UserStore::getUser ( QString  authenticationToken = QString())

Returns the User corresponding to the provided authentication token, or throws an exception if this token is not valid. The level of detail provided in the returned User structure depends on the access level granted by the token, so a web service client may receive fewer fields than an integrated desktop client.

◆ getUserAsync()

AsyncResult* qevercloud::UserStore::getUserAsync ( QString  authenticationToken = QString())

Asynchronous version of getUser

◆ getUserUrls()

UserUrls qevercloud::UserStore::getUserUrls ( QString  authenticationToken = QString())

Returns the URLs that should be used when sending requests to the service on behalf of the account represented by the provided authenticationToken.

This method isn't needed by most clients, who can retreive the correct set of UserUrls from the AuthenticationResult returned from UserStore::authenticateLongSession(). This method is typically only needed to look up the correct URLs for an existing long-lived authentication token.

◆ getUserUrlsAsync()

AsyncResult* qevercloud::UserStore::getUserUrlsAsync ( QString  authenticationToken = QString())

Asynchronous version of getUserUrls

◆ inviteToBusiness()

void qevercloud::UserStore::inviteToBusiness ( QString  emailAddress,
QString  authenticationToken = QString() 
)

Invite a user to join an Evernote Business account.

Behavior will depend on the auth token.

  1. auth token with privileges to manage Evernote Business membership. "External Provisioning" - The user will receive an email inviting them to join the business. They do not need to have an existing Evernote account. If the user has already been invited, a new invitation email will be sent.
  2. business auth token issued to an admin user. Only for first-party clients: "Approve Invitation" - If there has been a request to invite the email, approve it. Invited user will receive email with a link to join business. "Invite User" - If no invitation for the email exists, create an approved invitation for the email. An email will be sent to the emailAddress with a link to join the caller's business. business auth token: "Request Invitation" - If no invitation exists, create a request to invite the user to the business. These requests do not count towards a business' max active user limit.
Parameters
authenticationTokenthe authentication token with sufficient privileges to manage Evernote Business membership or a business auth token.
emailAddressthe email address of the user to invite to join the Evernote Business account.
Exceptions
EDAMUserException
  • DATA_REQUIRED "email" - if no email address was provided
  • BAD_DATA_FORMAT "email" - if the email address is not well formed
  • DATA_CONFLICT "BusinessUser.email" - if there is already a user in the business whose business email address matches the specified email address.
  • LIMIT_REACHED "Business.maxActiveUsers" - if the business has reached its user limit.

◆ inviteToBusinessAsync()

AsyncResult* qevercloud::UserStore::inviteToBusinessAsync ( QString  emailAddress,
QString  authenticationToken = QString() 
)

Asynchronous version of inviteToBusiness

◆ listBusinessInvitations()

QList< BusinessInvitation > qevercloud::UserStore::listBusinessInvitations ( bool  includeRequestedInvitations,
QString  authenticationToken = QString() 
)

Returns a list of outstanding invitations to join an Evernote Business account.

Only outstanding invitations are returned by this function. Users who have accepted an invitation and joined a business are listed using listBusinessUsers.

Parameters
authenticationTokenAn authentication token with sufficient privileges to manage Evernote Business membership.
includeRequestedInvitationsIf true, invitations with a status of BusinessInvitationStatus.REQUESTED will be included in the returned list. If false, only invitations with a status of BusinessInvitationStatus.APPROVED will be included.

◆ listBusinessInvitationsAsync()

AsyncResult* qevercloud::UserStore::listBusinessInvitationsAsync ( bool  includeRequestedInvitations,
QString  authenticationToken = QString() 
)

Asynchronous version of listBusinessInvitations

◆ listBusinessUsers()

QList< UserProfile > qevercloud::UserStore::listBusinessUsers ( QString  authenticationToken = QString())

Returns a list of active business users in a given business.

Clients are required to cache this information and re-fetch no more than once per day or when they encountered a user ID or username that was not known to them.

To avoid excessive look ups, clients should also track user IDs and usernames that belong to users who are not in the business, since they will not be included in the result.

I.e., when a client encounters a previously unknown user ID as a note's creator, it may query listBusinessUsers to find information about this user. If the user is not in the resulting list, the client should track that fact and not re-query the service the next time that it sees this user on a note.

Parameters
authenticationTokenA business authentication token returned by authenticateToBusiness or with sufficient privileges to manage Evernote Business membership.

◆ listBusinessUsersAsync()

AsyncResult* qevercloud::UserStore::listBusinessUsersAsync ( QString  authenticationToken = QString())

Asynchronous version of listBusinessUsers

◆ removeFromBusiness()

void qevercloud::UserStore::removeFromBusiness ( QString  emailAddress,
QString  authenticationToken = QString() 
)

Remove a user from an Evernote Business account. Once removed, the user will no longer be able to access content within the Evernote Business account.

The email address of the user to remove from the business must match the email address used to invite a user to join the business via UserStore.inviteToBusiness. This function will only remove users who were invited by external provisioning

Parameters
authenticationTokenAn authentication token with sufficient privileges to manage Evernote Business membership.
emailAddressThe email address of the user to remove from the Evernote Business account.
Exceptions
EDAMUserException
  • DATA_REQUIRED "email" - if no email address was provided
  • BAD_DATA_FORMAT "email" - The email address is not well formed
EDAMNotFoundException
  • "email" - If there is no user with the specified email address in the business or that user was not invited via external provisioning.

◆ removeFromBusinessAsync()

AsyncResult* qevercloud::UserStore::removeFromBusinessAsync ( QString  emailAddress,
QString  authenticationToken = QString() 
)

Asynchronous version of removeFromBusiness

◆ revokeLongSession()

void qevercloud::UserStore::revokeLongSession ( QString  authenticationToken = QString())

Revoke an existing long lived authentication token. This can be used to revoke OAuth tokens or tokens created by calling authenticateLongSession, and allows a user to effectively log out of Evernote from the perspective of the application that holds the token. The authentication token that is passed is immediately revoked and may not be used to call any authenticated EDAM function.

Parameters
authenticationTokenthe authentication token to revoke.
Exceptions
EDAMUserException
  • DATA_REQUIRED "authenticationToken" - no authentication token provided
  • BAD_DATA_FORMAT "authenticationToken" - the authentication token is not well formed
  • INVALID_AUTH "authenticationToken" - the authentication token is invalid
  • AUTH_EXPIRED "authenticationToken" - the authentication token is expired or is already revoked.

◆ revokeLongSessionAsync()

AsyncResult* qevercloud::UserStore::revokeLongSessionAsync ( QString  authenticationToken = QString())

Asynchronous version of revokeLongSession

◆ setAuthenticationToken()

void qevercloud::UserStore::setAuthenticationToken ( QString  authenticationToken)
inline

◆ updateBusinessUserIdentifier()

void qevercloud::UserStore::updateBusinessUserIdentifier ( QString  oldEmailAddress,
QString  newEmailAddress,
QString  authenticationToken = QString() 
)

Update the email address used to uniquely identify an Evernote Business user.

This will update the identifier for a user who was previously invited using inviteToBusiness, ensuring that caller and the Evernote service maintain an agreed-upon identifier for a specific user.

For example, the following sequence of calls would invite a user to join a business, update their email address, and then remove the user from the business using the updated email address.

inviteToBusiness("foo@bar.com") updateBusinessUserIdentifier("foo@bar.com", "baz@bar.com") removeFromBusiness("baz@bar.com")

Parameters
authenticationTokenAn authentication token with sufficient privileges to manage Evernote Business membership.
oldEmailAddressThe existing email address used to uniquely identify the user.
newEmailAddressThe new email address used to uniquely identify the user.
Exceptions
EDAMUserException
  • DATA_REQUIRED "oldEmailAddress" - No old email address was provided
  • DATA_REQUIRED "newEmailAddress" - No new email address was provided
  • BAD_DATA_FORMAT "oldEmailAddress" - The old email address is not well formed
  • BAD_DATA_FORMAT "newEmailAddress" - The new email address is not well formed
  • DATA_CONFLICT "oldEmailAddress" - The old and new email addresses were the same
  • DATA_CONFLICT "newEmailAddress" - There is already an invitation or registered user with the provided new email address.
  • DATA_CONFLICT "invitation.externallyProvisioned" - The user identified by oldEmailAddress was not added via UserStore.inviteToBusiness and therefore cannot be updated.
EDAMNotFoundException
  • "oldEmailAddress" - If there is no user or invitation with the specified oldEmailAddress in the business.

◆ updateBusinessUserIdentifierAsync()

AsyncResult* qevercloud::UserStore::updateBusinessUserIdentifierAsync ( QString  oldEmailAddress,
QString  newEmailAddress,
QString  authenticationToken = QString() 
)

Asynchronous version of updateBusinessUserIdentifier