rc_api_process_login_response

Parses the response for logging a user into the RetroAchievements API.

Syntax

// 11.0+
int rc_api_process_login_server_response(
    rc_api_login_response_t* response,
    const rc_api_server_response_t* server_response
);

// [deprecated]
int rc_api_process_login_response(
    rc_api_login_response_t* response,
    const char* server_response
);

Parameters

response

The rc_api_login_response_t to construct.

server_response

The body of the HTTP response received from the server.

---

struct rc_api_login_response_t 
{
  const char* username;
  const char* api_token;
  unsigned score;
  unsigned num_unread_messages;
  const char* display_name;
  const char* avatar_url;
  time_t avatar_last_updated;
  rc_api_response_t response;
};

username

The case-corrected name of the user being logged in. This should be passed to future API requests for the user.

api_token

The API token to pass to future API requests for the user.

score

The player's current score.

num_unread_messages

The number of unread messages in the player's inbox on the website.

display_name(Minimum version: 10.3.3)

The preferred display name of the user that was logged in. This should be used whenever the user's name is shown by the client.

avatar_url(Minimum version: 12.0.0)

A URL to the user's avatar image.

avatar_last_updated (Minimum version: 12.4.0)

The timestamp when the user last changed their avatar. If newer than the timestamp of a locally cached avatar, the avatar should be refetched from the server.

response

Common server-provided response information. Contains a succeeded flag, and an error_message field.

Return value

If the function succeeds, the return value is RC_OK. Otherwise, the error code can be converted to a string using rc_error_str.

• RC_INVALID_CREDENTIALS - The provided credentials were not recognized.
• RC_EXPIRED_TOKEN - The provided token has expired. The user should re-enter their credentials to generate a new token.
• RC_ACCESS_DENIED - Valid credentials were provided, but the user has not registered their email or has been banned.
• RC_INVALID_JSON - The response was not valid JSON.
• RC_MISSING_VALUE - One or more required fields was not found in the response.

NOTE: It is important to capture the case-corrected username as returned by this API. Some API calls will fail if passed an incorrectly cased username.

The rc_api_login_response_t must be destroyed by rc_api_destroy_login_response when the caller is done with it.

Minimum version: 10.0.0 (11.0.0 for RC_INVALID_CREDENTIALS, RC_EXPIRED_TOKEN, and RC_ACCESS_DENIED)

See also

rc_api_init_login_request

rc_api_destroy_login_response