RA_Interface.h

#ifndef RA_INTERFACE_H
#define RA_INTERFACE_H

#include <wtypes.h> /* HWND */

#ifdef __cplusplus
extern "C" {
#endif

/******************************
 * Initialization             *
 ******************************/

/**
 * Loads and initializes the DLL.
 *
 * Must be called before using any of the other functions. Will automatically download the DLL
 * if not found, or prompt the user to upgrade if a newer version is available
 *
 * @param hMainHWND       the handle of the main window
 * @param nEmulatorID     the unique idenfier of the emulator
 * @param sClientVersion  the current version of the emulator (will be validated against the minimum version for the specified emulator ID)
 */
extern void RA_Init(HWND hMainHWND, int nEmulatorID, const char* sClientVersion);

/**
 * Loads and initializes the DLL.
 *
 * Must be called before using any of the other functions. Will automatically download the DLL
 * if not found, or prompt the user to upgrade if a newer version is available
 *
 * @param hMainHWND       the handle of the main window
 * @param sClientName     the name of the client, displayed in the title bar and included in the User-Agent for API calls
 * @param sClientVersion  the current version of the client
 */
extern void RA_InitClient(HWND hMainHWND, const char* sClientName, const char* sClientVersion);

/**
 * Defines callbacks that the DLL can use to interact with the client.
 *
 * @param fpUnusedIsActive  [no longer used] returns non-zero if a game is running
 * @param fpCauseUnpause    unpauses the emulator
 * @param fpCausePause      pauses the emulator
 * @param fpRebuildMenu     notifies the client that the popup menu has changed (@see RA_CreatePopupMenu)
 * @param fpEstimateTitle   gets a short description for the game being loaded (parameter is a 256-byte buffer to fill)
 * @param fpResetEmulator   resets the emulator
 * @param fpLoadROM         [currently unused] tells the emulator to load a specific game
 */
extern void RA_InstallSharedFunctions(int (*fpUnusedIsActive)(void),
    void (*fpCauseUnpause)(void), void (*fpCausePause)(void), void (*fpRebuildMenu)(void),
    void (*fpEstimateTitle)(char*), void (*fpResetEmulator)(void), void (*fpLoadROM)(const char*));

/**
 * Tells the DLL to use UpdateWindow instead of InvalidateRect when the UI needs to be repainted. This is primarily
 * necessary when integrating with an emulator using the SDL library as it keeps the message queue flooded so the
 * InvalidateRect messages never get turned into WM_PAINT messages.
 *
 * @param bEnable         non-zero if InvalidateRect calls should be replaced with UpdateWindow
 */
extern void RA_SetForceRepaint(int bEnable);

/**
 * Creates a popup menu that can be appended to the main menu of the emulator.
 *
 * @return                handle to the menu. if not attached to the program menu, caller must destroy it themselves.
 */
extern HMENU RA_CreatePopupMenu(void);

/* Resource values for menu items - needed by MFC ON_COMMAND_RANGE macros or WM_COMMAND WndProc handlers
 * they're not all currently used, allowing additional items without forcing recompilation of the emulators
 */
#define IDM_RA_MENUSTART 1700
#define IDM_RA_MENUEND 1739

typedef struct RA_MenuItem
{
    LPCWSTR sLabel;
    LPARAM nID;
    int bChecked;
} RA_MenuItem;

/**
 * Gets items for building a popup menu.
 *
 * @param pItems          Pre-allocated array to populate [should contain space for at least 32 items]
 * @return                Number of items populated in the items array
 */
extern int RA_GetPopupMenuItems(RA_MenuItem *pItems);

/**
 * Called when a menu item in the popup menu is selected.
 *
 * @param nID             the ID of the menu item (will be between IDM_RA_MENUSTART and IDM_RA_MENUEND)
 */
extern void RA_InvokeDialog(LPARAM nID);

/**
 * Provides additional information to include in the User-Agent string for API calls.
 *
 * This is primarily used to identify dependencies or configurations (such as libretro core versions)
 *
 * @param sDetail         the additional information to include
 */
extern void RA_SetUserAgentDetail(const char* sDetail);

/**
 * Attempts to log in to the retroachievements.org site.
 *
 * Prompts the user for their login credentials and performs the login. If they've previously logged in and have
 * chosen to store their credentials, the login occurs without prompting.
 *
 * @param bBlocking       if zero, control is returned to the calling process while the login request is processed by the server.
 */
extern void RA_AttemptLogin(int bBlocking);

/**
 * Specifies the console associated to the emulator.
 *
 * May be called just before loading a game if the emulator supports multiple consoles.
 *
 * @param nConsoleID      the unique identifier of the console associated to the game being loaded.
 */
extern void RA_SetConsoleID(unsigned int nConsoleID);

/**
 * Resets memory references created by previous calls to RA_InstallMemoryBank.
 */
extern void RA_ClearMemoryBanks(void);

typedef unsigned char (RA_ReadMemoryFunc)(unsigned int nAddress);
typedef void (RA_WriteMemoryFunc)(unsigned int nAddress, unsigned char nValue);
/**
 * Exposes a block of memory to the DLL.
 *
 * The blocks of memory expected by the DLL are unique per console ID. To identify the correct map for a console,
 * view the consoleinfo.c file in the rcheevos repository.
 *
 * @param nBankID         the index of the bank to update. will replace any existing bank at that index.
 * @param pReader         a function to read from the bank. parameter is the offset within the bank to read from.
 * @param pWriter         a function to write to the bank. parameters are the offset within the bank to write to and an 8-bit value to write.
 * @param nBankSize       the size of the bank.
 */
extern void RA_InstallMemoryBank(int nBankID, RA_ReadMemoryFunc pReader, RA_WriteMemoryFunc pWriter, int nBankSize);

typedef unsigned int (RA_ReadMemoryBlockFunc)(unsigned int nAddress, unsigned char* pBuffer, unsigned int nBytes);
extern void RA_InstallMemoryBankBlockReader(int nBankID, RA_ReadMemoryBlockFunc pReader);

/**
 * Deinitializes and unloads the DLL.
 */
extern void RA_Shutdown(void);



/******************************
 * Overlay                    *
 ******************************/

/**
 * Determines if the overlay is fully visible.
 *
 * Precursor check before calling RA_NavigateOverlay
 *
 * @return                non-zero if the overlay is fully visible, zero if it is not.
 */
extern int RA_IsOverlayFullyVisible(void);

/**
 * Called to show or hide the overlay.
 *
 * @param bIsPaused       true to show the overlay, false to hide it.
 */
extern void RA_SetPaused(bool bIsPaused);

struct ControllerInput
{
    int m_bUpPressed;
    int m_bDownPressed;
    int m_bLeftPressed;
    int m_bRightPressed;
    int m_bConfirmPressed; /* Usually C or A */
    int m_bCancelPressed;  /* Usually B */
    int m_bQuitPressed;    /* Usually Start */
};

/**
 * Passes controller input to the overlay.
 *
 * Does nothing if the overlay is not fully visible.
 *
 * @param pInput          pointer to a ControllerInput structure indicating which inputs are active.
 */
extern void RA_NavigateOverlay(struct ControllerInput* pInput);

/**
 * [deprecated] Updates the overlay for a single frame.
 *
 * This function just calls RA_NavigateOverlay. Updating and rendering is now handled internally to the DLL.
 */
extern void RA_UpdateRenderOverlay(HDC, struct ControllerInput* pInput, float, RECT*, bool, bool);

/**
 * Updates the handle to the main window.
 *
 * The main window handle is used to anchor the overlay. If the client recreates the handle as the result of switching
 * from windowed mode to full screen, or for any other reason, it should call this to reattach the overlay.
 *
 * @param hMainHWND       the new handle of the main window
 */
extern void RA_UpdateHWnd(HWND hMainHWND);



/******************************
 * Game Management            *
 ******************************/

/**
 * Identifies the game associated to a block of memory.
 *
 * The block of memory is the fully buffered game file. If more complicated identification is required, the caller
 * needs to link against rcheevos/rhash directly to generate the hash, and call RA_IdentifyHash with the result.
 * Can be called when switching discs to ensure the additional discs are still associated to the loaded game.
 *
 * @param pROMData        the contents of the game file
 * @param nROMSize        the size of the game file
 * @return                the unique identifier of the game, 0 if no association available.
 */
extern unsigned int RA_IdentifyRom(BYTE* pROMData, unsigned int nROMSize);

/**
 * Identifies the game associated to a pre-generated hash.
 *
 * Used when the hash algorithm is something other than full file.
 * Can be called when switching discs to ensure the additional discs are still associated to the loaded game.
 *
 * @param sHash           the hash generated by rcheevos/rhash
 * @return                the unique identifier of the game, 0 if no association available.
 */
extern unsigned int RA_IdentifyHash(const char* sHash);

/**
 * Fetches all retroachievements related data for the specified game.
 *
 * @param nGameId         the unique identifier of the game to activate
 */
extern void RA_ActivateGame(unsigned int nGameId);

/**
 * Identifies and activates the game associated to a block of memory.
 *
 * Functions as a call to RA_IdentifyRom followed by a call to RA_ActivateGame.
 *
 * @param pROMData        the contents of the game file
 * @param nROMSize        the size of the game file
 */
extern void RA_OnLoadNewRom(BYTE* pROMData, unsigned int nROMSize);

/**
 * Called before unloading the game to allow the user to save any changes they might have.
 *
 * @param bIsQuitting     non-zero to change the messaging to indicate the emulator is closing.
 * @return                zero to abort the unload. non-zero to continue.
 */
extern int RA_ConfirmLoadNewRom(int bIsQuitting);



/******************************
 * Runtime Functionality      *
 ******************************/

/**
 * Does all achievement-related processing for a single frame.
 */
extern void RA_DoAchievementsFrame(void);

/**
 * Temporarily disables forced updating of tool windows.
 *
 * Primarily used while fast-forwarding.
 */
extern void RA_SuspendRepaint(void);

/**
 * Resumes forced updating of tool windows.
 */
extern void RA_ResumeRepaint(void);

/**
 * [deprecated] Used to be used to ensure the asynchronous server calls are processed on the UI thread.
 * That's all managed within the DLL now. Calling this function does nothing.
 */
extern void RA_HandleHTTPResults(void);

/**
 * Adds flavor text to the application title bar.
 *
 * Application title bar is managed by the DLL. Value will be "ClientName - Version - Flavor Text - Username"
 *
 * @param sCustomMessage  the flavor text to include in the title bar.
 */
extern void RA_UpdateAppTitle(const char* sCustomMessage);

/**
 * Get the user name of the currently logged in user.
 *
 * @return                user name of the currently logged in user, empty if no user is logged in. 
 */
const char* RA_UserName(void);

/**
 * Determines if the user is currently playing with hardcore enabled.
 *
 * The client should disable any features that would give the player an unfair advantage if this returns non-zero.
 * Things like loading states, using cheats, modifying RAM, disabling rendering layers, viewing decoded tilemaps, etc.
 *
 * @return                non-zero if hardcore mode is currently active.
 */
extern int RA_HardcoreModeIsActive(void);

/**
 * Warns the user they're about to do something that will disable hardcore mode.
 *
 * @param sActivity       what the user is about to do (i.e. "load a state").
 * @return                non-zero if the user disabled hardcore and the activity is allowed.
 *                        zero if the user declined to disable hardcore and the activity should be aborted.
 */
extern int RA_WarnDisableHardcore(const char* sActivity);

/**
 * Disables hardcore mode without prompting or notifying the user.
 *
 * Should only be called if the client does its own prompting/notification.
 * Typically used when an activity cannot be aborted.
 */
extern void RA_DisableHardcore(void);

/**
 * Notifies the DLL that the game has been reset.
 *
 * Disables active leaderboards and resets hit counts on all active achievements.
 */
extern void RA_OnReset(void);

/**
 * Notifies the DLL that a save state has been created.
 *
 * Creates a .rap file next to the state file that contains achievement-related information for the save state.
 *
 * @param sFilename       full path to the save state file.
 */
extern void RA_OnSaveState(const char* sFilename);

/**
 * Notifies the DLL that a save state has been loaded.
 *
 * Loads the .rap file next to the state file that contains achievement-related information for the save state being loaded.
 *
 * @param sFilename       full path to the save state file.
 */
extern void RA_OnLoadState(const char* sFilename);

/**
 * Captures the current state of the achievement runtime for inclusion in a save state.
 *
 * @param pBuffer         buffer to write achievement state information to
 * @param nBufferSize     the size of the buffer
 * @return                the number of bytes needed to capture the achievement state. if less than nBufferSize, pBuffer
 *                        will not be populated. the function should be called again with a larger buffer.
 */
extern int RA_CaptureState(char* pBuffer, int nBufferSize);

/**
 * Restores the state of the achievement runtime from a previously captured state.
 *
 * @param pBuffer         buffer containing previously serialized achievement state information
 */
extern void RA_RestoreState(const char* pBuffer);


#ifdef __cplusplus
} /* extern "C" */
#endif

#endif // !RA_INTERFACE_H