Thrift module: UserStore

ModuleServicesData typesConstants
UserStoreUserStore
AuthenticationResult
PublicUserInfo
EDAM_VERSION_MAJOR
EDAM_VERSION_MINOR

Constants

ConstantTypeValue
EDAM_VERSION_MAJORi161
The major version number for the current revision of the EDAM protocol. Clients pass this to the service using UserStore.checkVersion at the beginning of a session to confirm that they are not out of date.
EDAM_VERSION_MINORi1615
The minor version number for the current revision of the EDAM protocol. Clients pass this to the service using UserStore.checkVersion at the beginning of a session to confirm that they are not out of date.

Data structures

Struct: PublicUserInfo

FieldTypeRequiredDefault value
userIdTypes.UserIDyes
shardIdstringyes
privilegeTypes.PrivilegeLevelno
usernamestringno

This structure is used to provide publicly-available user information about a particular account.
userId:
The unique numeric user identifier for the user account.
shardId:
The name of the virtual server that manages the state of this user. This value is used internally to determine which system should service requests about this user's data. It is also used to construct the appropriate URL to make requests from the NoteStore.
privilege:
The privilege level of the account, to determine whether this is a Premium or Free account.

Struct: AuthenticationResult

FieldTypeRequiredDefault value
currentTimeTypes.Timestampyes
authenticationTokenstringyes
expirationTypes.Timestampyes
userTypes.Userno
publicUserInfoPublicUserInfono

When an authentication (or re-authentication) is performed, this structure provides the result to the client.
currentTime:
The server-side date and time when this result was generated.
authenticationToken:
Holds an opaque, ASCII-encoded token that can be used by the client to perform actions on a NoteStore.
expiration:
Holds the server-side date and time when the authentication token will expire. This time can be compared to "currentTime" to produce an expiration time that can be reconciled with the client's local clock.
user:
Holds the information about the account which was authenticated if this was a full authentication. May be absent if this particular authentication did not require user information.
publicUserInfo:
If this authentication result was achieved without full permissions to access the full User structure, this field may be set to give back a more limited public set of data.


Services

Service: UserStore

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:

Function: UserStore.checkVersion

bool checkVersion(string clientName,
                  i16 edamVersionMajor = 1,
                  i16 edamVersionMinor = 15)
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).

@param 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" or "Evernote Clipper/1.0.1; JME/2.0; Motorola RAZR/2.0;

@param 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.

@param 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.

Function: UserStore.authenticate

AuthenticationResult authenticate(string username,
                                  string password,
                                  string consumerKey,
                                  string consumerSecret)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
This is used to check a username and password in order to create an authentication session that could be used for further actions.

@param 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.

@param 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).

@param consumerKey A unique identifier for this client application, provided by Evernote to developers who request an API key. This must be provided to identify the client.

@param consumerSecret If the client was given a "consumer secret" when the API key was issued, it must be provided here to authenticate the application itself.

@return The result of the authentication. If the authentication was successful, the AuthenticationResult.user field will be set, but that User's 'attributes' will not be set. To retrieve the full information about the User, including its UserAttributes, make a separate call to UserStore.getUser() with the authentication from this call.

@throws EDAMUserException


Function: UserStore.refreshAuthentication

AuthenticationResult refreshAuthentication(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
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.

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

@return The result of the authentication, with the new token in the result's "authentication" field. The User field will not be set in the reply.

Function: UserStore.getUser

Types.User getUser(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
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.

Function: UserStore.getPublicUserInfo

PublicUserInfo getPublicUserInfo(string username)
    throws Errors.EDAMNotFoundException, Errors.EDAMSystemException, Errors.EDAMUserException
Asks the UserStore about the publicly available location information for a particular username.

@throws EDAMUserException