rc_api_init_login_request

Constructs an rc_api_request_t for logging a user into the RetroAchievements API.

Syntax

int rc_api_init_login_request(
    rc_api_request_t* request,
    const rc_api_login_request_t* api_params
);

Parameters

request

The rc_api_request_t to construct.

api_params

Pointer to a rc_api_login_request_t object containing the parameters required for the login.

---

struct rc_api_login_request_t
{
  const char* username;
  const char* api_token;
  const char* password;
};

username

The name of the user being logged in.

api_token

The API token generated by a previous log in for the user.

password

The password for the user being logged in.

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_STATE - one or more required parameters was not provided.
• RC_OUT_OF_MEMORY - enough memory could not be allocated to complete the operation.

Remarks

Only password or api_token should be provided. If both are provided, api_token will be ignored.

The rc_api_request_t must be destroyed by rc_api_destroy_request after the HTTP request has been made.

Minimum version: 10.0.0

Example

The following process applies to all of the rc_api_ functions.

1. Zero out the params object and populate the appropriate fields.

    rc_api_login_request_t api_params;
    memset(&api_params, 0, sizeof(api_params));

    api_params.username = "Username";
    api_params.api_token = "AU6EDN4hASd3rAGi";

2. Convert the API parameters to an HTTP request.

    rc_api_request_t api_request;
    rc_api_init_login_request(&api_request, &api_params);

3. Send the request to the server (send_http_request is used for illustrative purposes and is not provided by rcheevos).

    int status_code;
    const char* response_body = send_http_request(api_request.url, api_request.post_data, &status_code);
    rc_api_request_destroy(&api_request);

4. Handle the response (handle_error and handle_success are used for illustrative purposes only and are not provided by rcheevos).

    if (response_body == NULL)
    {
        handle_error(status_code, "empty response");
    }
    else
    {
        rc_api_login_response_t api_response;
        int result = rc_api_process_login_response(&api_response, response_body);
        if (result != RC_OK)
        {
            handle_error(status_code, rc_error_str(result));
        }
        else if (!api_response.response.succeeded)
        {
            handle_error(status_code, api_response.response.error_message);
        }
        else
        {
            handle_success(&api_response);
        }

        rc_api_destroy_login_response(&api_response);
        free(response_body);
    }

See also

rc_api_destroy_request

rc_api_process_login_response

rc_api_destroy_login_response