Thrift module: UserStore
Constants
Constant | Type | Value |
EDAM_VERSION_MAJOR | i16
| 1 |
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_MINOR | i16
| 15 |
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
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
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:
- 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
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
- 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
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.