google_apis/gaia/google_service_auth_error.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // A GoogleServiceAuthError is immutable, plain old data representing an
   6 // error from an attempt to authenticate with a Google service.
   7 // It could be from Google Accounts itself, or any service using Google
   8 // Accounts (e.g expired credentials).  It may contain additional data such as
   9 // captcha or OTP challenges.
  10
  11 // A GoogleServiceAuthError without additional data is just a State, defined
  12 // below. A case could be made to have this relation implicit, to allow raising
  13 // error events concisely by doing OnAuthError(GoogleServiceAuthError::NONE),
  14 // for example. But the truth is this class is ever so slightly more than a
  15 // transparent wrapper around 'State' due to additional Captcha data
  16 // (e.g consider operator=), and this would violate the style guide. Thus,
  17 // you must explicitly use the constructor when all you have is a State.
  18 // The good news is the implementation nests the enum inside a class, so you
  19 // may forward declare and typedef GoogleServiceAuthError to something shorter
  20 // in the comfort of your own translation unit.
  21
  22 #ifndef GOOGLE_APIS_GAIA_GOOGLE_SERVICE_AUTH_ERROR_H_
  23 #define GOOGLE_APIS_GAIA_GOOGLE_SERVICE_AUTH_ERROR_H_
  24
  25 #include <string>
  26
  27 #include "url/gurl.h"
  28
  29 namespace base {
  30 class DictionaryValue;
  31 }
  32
  33 class GoogleServiceAuthError {
  34  public:
  35   //
  36   // These enumerations are referenced by integer value in HTML login code and
  37   // in UMA histograms. Do not change the numeric values.
  38   //
  39   enum State {
  40     // The user is authenticated.
  41     NONE = 0,
  42
  43     // The credentials supplied to GAIA were either invalid, or the locally
  44     // cached credentials have expired.
  45     INVALID_GAIA_CREDENTIALS = 1,
  46
  47     // The GAIA user is not authorized to use the service.
  48     USER_NOT_SIGNED_UP = 2,
  49
  50     // Could not connect to server to verify credentials. This could be in
  51     // response to either failure to connect to GAIA or failure to connect to
  52     // the service needing GAIA tokens during authentication.
  53     CONNECTION_FAILED = 3,
  54
  55     // The user needs to satisfy a CAPTCHA challenge to unlock their account.
  56     // If no other information is available, this can be resolved by visiting
  57     // https://accounts.google.com/DisplayUnlockCaptcha. Otherwise, captcha()
  58     // will provide details about the associated challenge.
  59     CAPTCHA_REQUIRED = 4,
  60
  61     // The user account has been deleted.
  62     ACCOUNT_DELETED = 5,
  63
  64     // The user account has been disabled.
  65     ACCOUNT_DISABLED = 6,
  66
  67     // The service is not available; try again later.
  68     SERVICE_UNAVAILABLE = 7,
  69
  70     // The password is valid but we need two factor to get a token.
  71     TWO_FACTOR = 8,
  72
  73     // The requestor of the authentication step cancelled the request
  74     // prior to completion.
  75     REQUEST_CANCELED = 9,
  76
  77     // The user has provided a HOSTED account, when this service requires
  78     // a GOOGLE account.
  79     HOSTED_NOT_ALLOWED = 10,
  80
  81     // Indicates the service responded to a request, but we cannot
  82     // interpret the response.
  83     UNEXPECTED_SERVICE_RESPONSE = 11,
  84
  85     // Indicates the service responded and response carried details of the
  86     // application error.
  87     SERVICE_ERROR = 12,
  88
  89     // The password is valid but web login is required to get a token.
  90     WEB_LOGIN_REQUIRED = 13,
  91
  92     // The number of known error states.
  93     NUM_STATES = 14,
  94   };
  95
  96   // Additional data for CAPTCHA_REQUIRED errors.
  97   struct Captcha {
  98     Captcha();
  99     Captcha(const std::string& token,
 100             const GURL& audio,
 101             const GURL& img,
 102             const GURL& unlock,
 103             int width,
 104             int height);
 105     ~Captcha();
 106     // For test only.
 107     bool operator==(const Captcha &b) const;
 108
 109     std::string token;  // Globally identifies the specific CAPTCHA challenge.
 110     GURL audio_url;     // The CAPTCHA audio to use instead of image.
 111     GURL image_url;     // The CAPTCHA image to show the user.
 112     GURL unlock_url;    // Pretty unlock page containing above captcha.
 113     int image_width;    // Width of captcha image.
 114     int image_height;   // Height of capture image.
 115   };
 116
 117   // Additional data for TWO_FACTOR errors.
 118   struct SecondFactor {
 119     SecondFactor();
 120     SecondFactor(const std::string& token,
 121                  const std::string& prompt,
 122                  const std::string& alternate,
 123                  int length);
 124     ~SecondFactor();
 125     // For test only.
 126     bool operator==(const SecondFactor &b) const;
 127
 128     // Globally identifies the specific second-factor challenge.
 129     std::string token;
 130     // Localised prompt text, eg Enter the verification code sent to your
 131     // phone number ending in XXX.
 132     std::string prompt_text;
 133     // Localized text describing an alternate option, eg Get a verification
 134     // code in a text message.
 135     std::string alternate_text;
 136     // Character length for the challenge field.
 137     int field_length;
 138   };
 139
 140   // For test only.
 141   bool operator==(const GoogleServiceAuthError &b) const;
 142   bool operator!=(const GoogleServiceAuthError &b) const;
 143
 144   // Construct a GoogleServiceAuthError from a State with no additional data.
 145   explicit GoogleServiceAuthError(State s);
 146
 147   // Construct a GoogleServiceAuthError from a network error.
 148   // It will be created with CONNECTION_FAILED set.
 149   static GoogleServiceAuthError FromConnectionError(int error);
 150
 151   // Construct a CAPTCHA_REQUIRED error with CAPTCHA challenge data from the
 152   // the ClientLogin endpoint.
 153   // TODO(rogerta): once ClientLogin is no longer used, may be able to get
 154   // rid of this function.
 155   static GoogleServiceAuthError FromClientLoginCaptchaChallenge(
 156       const std::string& captcha_token,
 157       const GURL& captcha_image_url,
 158       const GURL& captcha_unlock_url);
 159
 160   // Construct a SERVICE_ERROR error, e.g. invalid client ID, with an
 161   // |error_message| which provides more information about the service error.
 162   static GoogleServiceAuthError FromServiceError(
 163       const std::string& error_message);
 164
 165   // Construct an UNEXPECTED_SERVICE_RESPONSE error, with an |error_message|
 166   // detailing the problems with the response.
 167   static GoogleServiceAuthError FromUnexpectedServiceResponse(
 168       const std::string& error_message);
 169
 170   // Provided for convenience for clients needing to reset an instance to NONE.
 171   // (avoids err_ = GoogleServiceAuthError(GoogleServiceAuthError::NONE), due
 172   // to explicit class and State enum relation. Note: shouldn't be inlined!
 173   static GoogleServiceAuthError AuthErrorNone();
 174
 175   // The error information.
 176   State state() const;
 177   const Captcha& captcha() const;
 178   const SecondFactor& second_factor() const;
 179   int network_error() const;
 180   const std::string& token() const;
 181   const std::string& error_message() const;
 182
 183   // Returns info about this object in a dictionary.  Caller takes
 184   // ownership of returned dictionary.
 185   base::DictionaryValue* ToValue() const;
 186
 187   // Returns a message describing the error.
 188   std::string ToString() const;
 189
 190   // Check if this is error may go away simply by trying again.  Except for the
 191   // NONE case, these are mutually exclusive.
 192   bool IsPersistentError() const;
 193   bool IsTransientError() const;
 194
 195  private:
 196   GoogleServiceAuthError(State s, int error);
 197
 198   // Construct a GoogleServiceAuthError from |state| and |error_message|.
 199   GoogleServiceAuthError(State state, const std::string& error_message);
 200
 201   GoogleServiceAuthError(State s, const std::string& captcha_token,
 202                          const GURL& captcha_audio_url,
 203                          const GURL& captcha_image_url,
 204                          const GURL& captcha_unlock_url,
 205                          int image_width,
 206                          int image_height);
 207
 208   State state_;
 209   Captcha captcha_;
 210   SecondFactor second_factor_;
 211   int network_error_;
 212   std::string error_message_;
 213 };
 214
 215 #endif  // GOOGLE_APIS_GAIA_GOOGLE_SERVICE_AUTH_ERROR_H_