com.evernote.edam.userstore.UserStoreIface Maven / Gradle / Ivy
The newest version!
/**
* Autogenerated by Thrift
*
* DO NOT EDIT UNLESS YOU ARE SURE THAT YOU KNOW WHAT YOU ARE DOING
*/
package com.evernote.edam.userstore;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.util.HashMap;
import java.util.Set;
import java.util.HashSet;
import com.evernote.thrift.*;
import com.evernote.thrift.protocol.*;
/**
* 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
*
*/
public interface UserStoreIface {
/**
* 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".
*
* @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.
*/
public boolean checkVersion(String clientName, short edamVersionMajor, short edamVersionMinor) throws TException;
/**
* This provides bootstrap information to the client. Various bootstrap
* profiles and settings may be used by the client to configure itself.
*
* @param 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.
*
* @return
* The bootstrap information suitable for this client.
*/
public BootstrapInfo getBootstrapInfo(String locale) throws TException;
/**
* 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.
*
* @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
* The "consumer key" portion of the API key issued to the client application
* by Evernote.
*
* @param consumerSecret
* The "consumer secret" portion of the API key issued to the client application
* by Evernote.
*
* @param 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.
*
* @return
* 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.
*
* @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
*
- PERMISSION_DENIED "User.tooManyFailuresTryAgainLater" - user has
* failed authentication too often
*
*/
public AuthenticationResult authenticate(String username, String password, String consumerKey, String consumerSecret, boolean supportsTwoFactor) throws com.evernote.edam.error.EDAMUserException, com.evernote.edam.error.EDAMSystemException, TException;
/**
* 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.
*
* @param username
* The username or registered email address of the account to
* authenticate against.
*
* @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 (i.e. SSL).
*
* @param consumerKey
* The "consumer key" portion of the API key issued to the client application
* by Evernote.
*
* @param consumerSecret
* The "consumer secret" portion of the API key issued to the client application
* by Evernote.
*
* @param 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.
*
* @param 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.
*
* @param 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.
*
* @return
* 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.
*
* @throws 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
*
*/
public AuthenticationResult authenticateLongSession(String username, String password, String consumerKey, String consumerSecret, String deviceIdentifier, String deviceDescription, boolean supportsTwoFactor) throws com.evernote.edam.error.EDAMUserException, com.evernote.edam.error.EDAMSystemException, TException;
/**
* 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.
*
* @param 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.
*
* @param oneTimeCode The one time code entered by the user. This value is delivered
* out-of-band, typically via SMS or an authenticator application.
*
* @param deviceIdentifier See the corresponding parameter in authenticateLongSession.
*
* @param deviceDescription See the corresponding parameter in authenticateLongSession.
*
* @return
* 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.
*
* @throws 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.
*
*/
public AuthenticationResult completeTwoFactorAuthentication(String authenticationToken, String oneTimeCode, String deviceIdentifier, String deviceDescription) throws com.evernote.edam.error.EDAMUserException, com.evernote.edam.error.EDAMSystemException, TException;
/**
* 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.
*
* @param authenticationToken the authentication token to revoke.
*
* @throws 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.
*
*/
public void revokeLongSession(String authenticationToken) throws com.evernote.edam.error.EDAMUserException, com.evernote.edam.error.EDAMSystemException, TException;
/**
* 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.
*
* @param 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.
*
* @return
* 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.
*
* @throws 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.
*
*/
public AuthenticationResult authenticateToBusiness(String authenticationToken) throws com.evernote.edam.error.EDAMUserException, com.evernote.edam.error.EDAMSystemException, TException;
/**
* 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.
*
* @param authenticationToken
* The previous authentication token from the authenticate() result.
*
* @return
* 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.
*/
public AuthenticationResult refreshAuthentication(String authenticationToken) throws com.evernote.edam.error.EDAMUserException, com.evernote.edam.error.EDAMSystemException, TException;
/**
* 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.
*/
public com.evernote.edam.type.User getUser(String authenticationToken) throws com.evernote.edam.error.EDAMUserException, com.evernote.edam.error.EDAMSystemException, TException;
/**
* Asks the UserStore about the publicly available location information for
* a particular username.
*
* @throws EDAMUserException
* - DATA_REQUIRED "username" - username is empty
*
*/
public PublicUserInfo getPublicUserInfo(String username) throws com.evernote.edam.error.EDAMNotFoundException, com.evernote.edam.error.EDAMSystemException, com.evernote.edam.error.EDAMUserException, TException;
/**
* Returns information regarding a user's Premium account corresponding to the
* provided authentication token, or throws an exception if this token is not
* valid.
*/
public com.evernote.edam.type.PremiumInfo getPremiumInfo(String authenticationToken) throws com.evernote.edam.error.EDAMUserException, com.evernote.edam.error.EDAMSystemException, TException;
/**
* 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).
*/
public String getNoteStoreUrl(String authenticationToken) throws com.evernote.edam.error.EDAMUserException, com.evernote.edam.error.EDAMSystemException, TException;
}