#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)

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

BootstrapInfo	getBootstrapInfo (QString locale)

AsyncResult *	getBootstrapInfoAsync (QString locale)

AuthenticationResult	authenticate (QString username, QString password, QString consumerKey, QString consumerSecret, bool supportsTwoFactor)

AsyncResult *	authenticateAsync (QString username, QString password, QString consumerKey, QString consumerSecret, bool supportsTwoFactor)

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

AsyncResult *	authenticateLongSessionAsync (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())

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

void	revokeLongSession (QString authenticationToken=QString())

AsyncResult *	revokeLongSessionAsync (QString authenticationToken=QString())

AuthenticationResult	authenticateToBusiness (QString authenticationToken=QString())

AsyncResult *	authenticateToBusinessAsync (QString authenticationToken=QString())

AuthenticationResult	refreshAuthentication (QString authenticationToken=QString())

AsyncResult *	refreshAuthenticationAsync (QString authenticationToken=QString())

User	getUser (QString authenticationToken=QString())

AsyncResult *	getUserAsync (QString authenticationToken=QString())

PublicUserInfo	getPublicUserInfo (QString username)

AsyncResult *	getPublicUserInfoAsync (QString username)

PremiumInfo	getPremiumInfo (QString authenticationToken=QString())

AsyncResult *	getPremiumInfoAsync (QString authenticationToken=QString())

QString	getNoteStoreUrl (QString authenticationToken=QString())

AsyncResult *	getNoteStoreUrlAsync (QString authenticationToken=QString())

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:

AUTH_EXPIRED "authenticationToken" - token has expired
BAD_DATA_FORMAT "authenticationToken" - token is malformed
DATA_REQUIRED "authenticationToken" - token is empty
INVALID_AUTH "authenticationToken" - token signature is invalid

Constructor & Destructor Documentation

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

explicit

Member Function Documentation

AuthenticationResult qevercloud::UserStore::authenticate	(	QString	username,
		QString	password,
		QString	consumerKey,
		QString	consumerSecret,
		bool	supportsTwoFactor
	)

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

This function is only available to Evernote's internal applications. Third party applications must authenticate using OAuth as described at dev.evernote.com.

Parameters

username	The username (not numeric user ID) for the account to authenticate against. This function will also accept the user's registered email address in this parameter.
password	The 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 (e.g. SSL).
consumerKey	The "consumer key" portion of the API key issued to the client application by Evernote.
consumerSecret	The "consumer secret" portion of the API key issued to the client application by Evernote.
supportsTwoFactor	Whether 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. If the authentication was successful, the AuthenticationResult.user field will be set with the full information about the User.

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
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

AsyncResult* qevercloud::UserStore::authenticateAsync	(	QString	username,
		QString	password,
		QString	consumerKey,
		QString	consumerSecret,
		bool	supportsTwoFactor
	)

Asynchronous version of authenticate

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

username	The username or registered email address of the account to authenticate against.
password	The 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).
consumerKey	The "consumer key" portion of the API key issued to the client application by Evernote.
consumerSecret	The "consumer secret" portion of the API key issued to the client application by Evernote.
deviceIdentifier	An optional string, no more than 32 characters in length, 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.
deviceDescription	A 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.
supportsTwoFactor	Whether 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

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

Asynchronous version of authenticateLongSession

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

authenticationToken The 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.

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

Asynchronous version of authenticateToBusiness

QString qevercloud::UserStore::authenticationToken ( )

inline

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

clientName	This 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".
edamVersionMajor	This 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.
edamVersionMinor	This 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.

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

Asynchronous version of checkVersion

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

authenticationToken	An 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.
oneTimeCode	The one time code entered by the user. This value is delivered out-of-band, typically via SMS or an authenticator application.
deviceIdentifier	See the corresponding parameter in authenticateLongSession.
deviceDescription	See 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 "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.

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

Asynchronous version of completeTwoFactorAuthentication

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

locale The 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.

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

Asynchronous version of getBootstrapInfo

QString qevercloud::UserStore::getNoteStoreUrl ( QString authenticationToken = QString() )

Returns the URL that should be used to talk to the NoteStore for the account represented by the provided authenticationToken. This method isn't needed by most clients, who can retrieve the correct NoteStore URL from the AuthenticationResult returned from the authenticate or refreshAuthentication calls. This method is typically only needed to look up the correct URL for a long-lived session token (e.g. for an OAuth web service).

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

Asynchronous version of getNoteStoreUrl

PremiumInfo qevercloud::UserStore::getPremiumInfo ( QString authenticationToken = QString() )

Returns information regarding a user's Premium account corresponding to the provided authentication token, or throws an exception if this token is not valid.

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

Asynchronous version of getPremiumInfo

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

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

Asynchronous version of getPublicUserInfo

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.

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

Asynchronous version of getUser

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

This is used to take an existing authentication token (returned from 'authenticate') and exchange it for a newer token which will not expire as soon. This must be invoked before the previous token expires.

This function is only availabe to Evernote's internal applications.

Parameters

authenticationToken The previous authentication token from the authenticate() result.

Returns: The result of the authentication, with the new token in the result's 'authenticationToken' field. The 'User' field will not be set in the result.

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

Asynchronous version of refreshAuthentication

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

authenticationToken the 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.

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

Asynchronous version of revokeLongSession

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

inline

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation