rc_client_begin_change_media

Switches the loaded media for the active game.

Syntax

rc_client_async_handle_t* rc_client_begin_change_media(
    rc_client_t* client,
    const char* file_path,
    const uint8_t* data,
    size_t data_size,
    rc_client_callback_t callback,
    void* callback_userdata
);

Parameters

client

The rc_client_t to manage the game.

file_path

Path to the file containing the new media.

For files extracted from a zip file into memory, it is recommended to append the extracted file to generate a virtual path (i.e. C:\games.zip#game.nes), and data must be provided. The zip file itself will not be processed.

data

Pointer to pre-loaded data (file already loaded in memory - either directly or extracted from an archive). If NULL, the data will be read from file_path.

data_size

The number of bytes pointed to by data.

callback

Function to call when the game load process completes.

callback_userdata

Additional information to pass to the callback function.

Returns

Pointer to an rc_client_async_handle_t that can be passed to rc_client_abort_async to cancel the change media request. The rc_client_async_handle_t is invalid after callback has been called.

---

rc_client_callback_t

void (*rc_client_callback_t)(
    int result,
    const char* error_message,
    rc_client_t* client
);

result

RC_OK on success, or an error code indicating the failure.

result	problem
RC_OK	Game was successfully loaded.
RC_NO_GAME_LOADED	An active game is required.
RC_HARDCORE_DISABLED	The new media could not be identified, so hardcore was disabled.
RC_ABORTED	The process was canceled before it finished (rc_client_unload_game was called, or another game started loading).
RC_INVALID_STATE	Generic failure. See error_message for details.
RC_INVALID_JSON	Server response could not be processed.
RC_MISSING_VALUE	Server response was not complete.
RC_API_FAILURE	Error occurred on the server. See error_message for details.

error_message

NULL on success, or a message related to a non-successful result.

client

The rc_client_t that was handling the load game attempt.

Remarks

If a hash cannot be generated for the new media, it is assumed to not be able to affect the loaded game (i.e. an audio CD for a rhythm game). If the hash does resolve to a known hash, it will be allowed as either a valid media for the loaded game, or something that won't affect the loaded game. If the hash does not resolve to a known hash, hardcore will be disabled and RC_HARDCORE_DISABLED will be passed to the callback.

Requires RC_CLIENT_SUPPORTS_HASH to be defined on 11.2+

Minimum version: 11.0.0

See also

rc_client_begin_change_media_from_hash

rc_client_begin_identify_and_load_game

rc_client_begin_load_game

rc_client_unload_game