rcheevos C Library

rcheevos is a C library designed to help emulators process RetroAchievements data, enabling achievement and leaderboard support.

Key Constraints:

• No Networking: The library does not provide HTTP network connections. Clients must fetch data from RetroAchievements and pass the response to rcheevos for processing.
• Branch Selection: For production integration, use the master branch (official releases). The develop branch is the default for PRs and may contain newer, potentially unstable features.

rapi is a utility within rcheevos used to build valid URLs for RetroAchievements web services. It handles URL-encoding parameters so developers don't have to manually construct complex strings.

Important: rapi does not make HTTP requests. It only generates the URLs.

Workflow:

1. Initialize a params object.
2. Call a function to convert the params into a URL.
3. Send the URL to the server via your own HTTP client.
4. Pass the server response to a rapi function to convert it into a response object.
5. Handle the resulting response values.

Headers:

• rc_api_user.h
• rc_api_runtime.h
• rc_api_common.h

To add achievement support to an emulator, use the rc_client_t functions. The rc_client_t manages:

• User information.
• Game identification and loading.
• Building active/inactive achievement lists for the UI.

Implementation Pattern: rc_client_t uses callback functions. You must implement these callbacks to handle dependent functionality, specifically UI rendering and HTTP network calls, as the library does not perform networking itself.

Functions that return a success indicator will return RC_OK or one of the error constants defined in rc_error.h. To convert these integer return codes into human-readable strings for debugging or UI display, use rc_error_str().

const char* rc_error_str(int ret);

The rhash module (defined in rc_hash.h) provides logic for generating RetroAchievements hashes for games. You can use it in two ways:

1. File Path: Pass a filename and let rhash open and process the file.
2. Memory Buffer: Pass a buffered copy of the file if it is already loaded into memory.

API Functions:

void rc_hash_initialize_iterator(rc_hash_iterator_t* iterator, const char* path, const uint8_t* buffer, size_t buffer_size);
int rc_hash_generate(char hash[33], uint32_t console_id, const rc_hash_iterator_t* iterator);
int rc_hash_iterate(char hash[33], rc_hash_iterator_t* iterator);
void rc_hash_destroy_iterator(rc_hash_iterator_t* iterator);