rc_client_set_read_memory_function

Provides a callback for reading memory from the emulator.

Syntax

void rc_client_set_read_memory_function(
    rc_client_t* client,
    rc_client_read_memory_func_t handler
);

Parameters

client

The rc_client_t to associate the handler to.

handler

Function to call to read memory from the emulator

---

rc_client_read_memory_func_t

uint32_t (*rc_client_read_memory_func_t)(
    uint32_t address,
    uint8_t* buffer,
    uint32_t num_bytes,
    rc_client_t* client
);

address

The RetroAchievements address to begin reading from.

Note that RetroAchievements addresses usually do not accurately represent emulator memory addresses. There is usually a direct mapping though.

buffer

A pointer to a buffer that should be filled.

num_bytes

The number of bytes that should be copied into the buffer.

client

The rc_client_t that's requesting the data.

Return Value

The number of bytes copied into buffer.

If less than num_bytes, the address is marked as invalid and any achievements/leaderboards referencing the address will marked as Unsupported.

Remarks

In addition to the normal use case of fetching memory values during rc_client_do_frame, the memory reading function will be called from one of the rc_client_server_callback_t callbacks to ensure the addresses used by the loaded achievements are available in the emulator. This happens before the rc_client_begin_load_game callback is called so the rc_client_get_user_game_summary function can return an accurate number of unsupported achievements.

This validation will likely occur on a background thread if the HTTP request is implemented asynchronously. If the memory reading function cannot be executed from a background thread, a secondary memory reading function can be registered during the load process by calling rc_client_set_read_memory_function. It just needs to returns the number of requested bytes (without populating the buffer) to indicate the address is valid, or 0 to indicate the address is not valid. Then the original memory reading function can be restored after the load process completes.

Minimum version: 11.0.0

See also

rc_client_create

rc_client_do_frame