307 lines
No EOL
9.7 KiB
C
307 lines
No EOL
9.7 KiB
C
/**
|
|
* @file UplaySaveGame.h
|
|
* @brief The Uplay PC Save Game API
|
|
*/
|
|
#ifndef UPLAY_SAVE_H
|
|
#define UPLAY_SAVE_H
|
|
|
|
#include "Uplay/UplayOverlapped.h"
|
|
#include "Uplay/UplayTypes.h"
|
|
|
|
#if _MSC_VER > 1000
|
|
#pragma once
|
|
#endif
|
|
|
|
#ifndef UPLAY_API
|
|
#ifdef _WIN32
|
|
#if defined EXPORTING_DLL
|
|
#define UPLAY_API __declspec(dllexport)
|
|
#elif defined IMPORTING_DLL
|
|
#define UPLAY_API __declspec(dllimport)
|
|
#else
|
|
#define UPLAY_API
|
|
#endif
|
|
#endif // _Win32
|
|
|
|
#ifdef __APPLE__
|
|
#define UPLAY_API __attribute__((visibility("default")))
|
|
#define __cdecl
|
|
#endif // __APPLE__
|
|
#endif // UPLAY_API
|
|
|
|
|
|
#ifdef __cplusplus
|
|
extern "C"
|
|
{
|
|
#endif // __cplusplus
|
|
|
|
/**
|
|
* @defgroup savegame Save Game
|
|
* @brief Functions for the save game subsystem
|
|
* @note Save game ids starts from 1 (not 0).
|
|
*
|
|
* @{
|
|
*/
|
|
|
|
/** The size of the save game name buffer */
|
|
static const UPLAY_uint32 UPLAY_SAVEGAME_NAME_BUFFER_LEN = 256;
|
|
|
|
/************************************************************************************//**
|
|
* @enum UPLAY_SAVE_Mode
|
|
* @brief Values for open modes used in ::UPLAY_SAVE_Open()
|
|
*/
|
|
typedef enum
|
|
{
|
|
/** Open the save game for reading */
|
|
UPLAY_SAVE_Mode_Read,
|
|
/** Open the save game for writing */
|
|
UPLAY_SAVE_Mode_Write,
|
|
} UPLAY_SAVE_Mode;
|
|
|
|
/** Type definition of a save game handle */
|
|
typedef UPLAY_uint32 UPLAY_SAVE_Handle;
|
|
|
|
#pragma pack(push, 8)
|
|
|
|
/************************************************************************************//**
|
|
* @struct UPLAY_SAVE_Game
|
|
* @brief Struct containing information about a save game
|
|
* @note \a id should be 1 or higher
|
|
*/
|
|
typedef struct UPLAY_SAVE_Game_t
|
|
{
|
|
/** The ID of the save game */
|
|
UPLAY_uint32 id;
|
|
/** Null terminated UTF-8 string containing the name of the save game */
|
|
const char* nameUtf8;
|
|
/** The size of the save game */
|
|
UPLAY_uint32 size;
|
|
} UPLAY_SAVE_Game;
|
|
|
|
/************************************************************************************//**
|
|
* @struct UPLAY_SAVE_GameList
|
|
* @brief Struct representing a list of save games
|
|
*/
|
|
typedef struct UPLAY_SAVE_GameList_t
|
|
{
|
|
/** The number of elements in the list */
|
|
UPLAY_uint32 count;
|
|
/** The list of save games */
|
|
const UPLAY_SAVE_Game** list;
|
|
} UPLAY_SAVE_GameList;
|
|
|
|
#pragma pack(pop)
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_SAVE_GetSavegames(UPLAY_SAVE_GameList**, UPLAY_Overlapped*)
|
|
* @brief Retrieves a list of saved games for the current user and product.
|
|
*
|
|
* The following ::UPLAY_OverlappedResult values can be returned:
|
|
*
|
|
* Result | Description
|
|
* -------------------------------------- | -----------
|
|
* UPLAY_OverlappedResult_Failed | Unknown error
|
|
* UPLAY_OverlappedResult_Ok | Success
|
|
*
|
|
* @note More overlapped results can be added in future versions of the API.
|
|
*
|
|
* @param aOutGameList
|
|
* The resulting list of save games will be stored here
|
|
* @param aOverlapped
|
|
* Overlapped struct
|
|
*
|
|
* @returns Non-zero on success
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_SAVE_GetSavegames(
|
|
UPLAY_SAVE_GameList** aOutGameList,
|
|
UPLAY_Overlapped* aOverlapped);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_SAVE_ReleaseGameList(UPLAY_SAVE_GameList* aGamesList)
|
|
* @brief Release allocated memory from UPLAY_SAVE_GetSavegames
|
|
*
|
|
* @param aImage
|
|
* Pointer to the allocated UPLAY_SAVE_GetSavegames game list
|
|
*
|
|
* @returns Non-zero on success
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_SAVE_ReleaseGameList(
|
|
UPLAY_SAVE_GameList* aGamesList);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_SAVE_Open(UPLAY_uint32, UPLAY_uint32, UPLAY_SAVE_Handle*, UPLAY_Overlapped*)
|
|
* @brief Open a saved game.
|
|
*
|
|
* @note Must call UPLAY_SAVE_Close after use.
|
|
*
|
|
* The following ::UPLAY_OverlappedResult values can be returned:
|
|
*
|
|
* Result | Description
|
|
* ------------------------------------------- | -----------
|
|
* UPLAY_OverlappedResult_InvalidArgument | Not a valid save handle
|
|
* UPLAY_OverlappedResult_SlotLocked | Slot is already opened
|
|
* UPLAY_OverlappedResult_OverwriteNotAllowed | Slot is not writeable
|
|
* UPLAY_OverlappedResult_Failed | Unknown error
|
|
* UPLAY_OverlappedResult_Ok | Success
|
|
*
|
|
* @note More overlapped results can be added in future versions of the API.
|
|
*
|
|
* @param aSlotId
|
|
* Slot to open - must be 1 or higher
|
|
* @param aMode
|
|
* Mode to open the save game. See enum ::UPLAY_SAVE_Mode for valid values.
|
|
* @note The save will be truncated if opened for writing.
|
|
* @param aOutSaveHandle
|
|
* A save handle. Must be available until the overlapped function has been completed
|
|
* @param aOverlapped
|
|
* Overlapped struct
|
|
*
|
|
* @returns Non-zero on success
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_SAVE_Open(
|
|
UPLAY_uint32 aSlotId,
|
|
UPLAY_uint32 aMode,
|
|
UPLAY_SAVE_Handle* aOutSaveHandle,
|
|
UPLAY_Overlapped* aOverlapped);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_SAVE_Close(UPLAY_SAVE_Handle)
|
|
* @brief Close a save game.
|
|
*
|
|
* This function will release memory internally and must be called after a call to ::UPLAY_SAVE_Open()
|
|
*
|
|
* @param aSaveHandle
|
|
* A save handle
|
|
*
|
|
* @returns Non-zero on success
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_SAVE_Close(
|
|
UPLAY_SAVE_Handle aSaveHandle);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_SAVE_Read(UPLAY_SAVE_Handle, UPLAY_uint32, UPLAY_uint32, UPLAY_DataBlob*, UPLAY_uint32*, UPLAY_Overlapped*)
|
|
* @brief Read from a save game.
|
|
*
|
|
* The following ::UPLAY_OverlappedResult values can be returned:
|
|
*
|
|
* Result | Description
|
|
* -------------------------------------- | -----------
|
|
* UPLAY_OverlappedResult_InvalidArgument | Some of the arguments are not valid
|
|
* UPLAY_OverlappedResult_SlotLocked | Slot is already opened for writing
|
|
* UPLAY_OverlappedResult_Failed | Unknown error
|
|
* UPLAY_OverlappedResult_Ok | Success
|
|
*
|
|
* @note More overlapped results can be added in future versions of the API.
|
|
*
|
|
* @param aSaveHandle
|
|
* Save handle to read from
|
|
* @param aNumOfBytesToRead
|
|
* Number of bytes to read. Can't be larger than aOutBuffer's size
|
|
* @param aOffset
|
|
* Offset to start reading from
|
|
* @param aOutBuffer
|
|
* Buffer to store the read data in
|
|
* @param aOutNumOfBytesRead
|
|
* Number of bytes actually read
|
|
* @param aOverlapped
|
|
* Overlapped struct
|
|
*
|
|
* @returns Non-zero on success
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_SAVE_Read(
|
|
UPLAY_SAVE_Handle aSaveHandle,
|
|
UPLAY_uint32 aNumOfBytesToRead,
|
|
UPLAY_uint32 aOffset,
|
|
UPLAY_DataBlob* aOutBuffer,
|
|
UPLAY_uint32* aOutNumOfBytesRead,
|
|
UPLAY_Overlapped* aOverlapped);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_SAVE_Write(UPLAY_SAVE_Handle, UPLAY_uint32, UPLAY_DataBlob*, UPLAY_Overlapped*)
|
|
* @brief Write to a saved game.
|
|
*
|
|
* The following ::UPLAY_OverlappedResult values can be returned:
|
|
*
|
|
* Result | Description
|
|
* -------------------------------------- | -----------
|
|
* UPLAY_OverlappedResult_InvalidArgument | Some of the arguments are not valid
|
|
* UPLAY_OverlappedResult_SlotLocked | Slot is already opened for reading
|
|
* UPLAY_OverlappedResult_Failed | Unknown error
|
|
* UPLAY_OverlappedResult_Ok | Success
|
|
*
|
|
* @note More overlapped results can be added in future versions of the API.
|
|
*
|
|
* @param aSaveHandle
|
|
* Save handle to write
|
|
* @param aNumOfBytesToWrite
|
|
* Number of bytes to write
|
|
* @param aBuffer
|
|
* Buffer containing the data to write
|
|
* @param aOverlapped
|
|
* Overlapped struct
|
|
*
|
|
* @returns Non-zero on success
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_SAVE_Write(
|
|
UPLAY_SAVE_Handle aSaveHandle,
|
|
UPLAY_uint32 aNumOfBytesToWrite,
|
|
UPLAY_DataBlob* aBuffer,
|
|
UPLAY_Overlapped* aOverlapped);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_SAVE_SetName(UPLAY_SAVE_Handle, const char*)
|
|
* @brief Set the name of a save game
|
|
*
|
|
* @param aSaveHandle
|
|
* Save handle to set name of. Must be opened for writing.
|
|
* @param aNameUtf8
|
|
* Null terminated UTF-8 string containing the new name of the save game
|
|
*
|
|
* @returns Non-zero on success
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_SAVE_SetName(
|
|
UPLAY_SAVE_Handle aSaveHandle,
|
|
const char* aNameUtf8);
|
|
|
|
/************************************************************************************//**
|
|
* @fn int UPLAY_SAVE_Remove(UPLAY_uint32, UPLAY_Overlapped*)
|
|
* @brief Remove a save game
|
|
*
|
|
* The following ::UPLAY_OverlappedResult values can be returned:
|
|
*
|
|
* Result | Description
|
|
* -------------------------------------- | -----------
|
|
* UPLAY_OverlappedResult_InvalidArgument | Some of the arguments are not valid
|
|
* UPLAY_OverlappedResult_SlotLocked | Slots can't be removed while open
|
|
* UPLAY_OverlappedResult_NotFound | No save in this slot
|
|
* UPLAY_OverlappedResult_Failed | Unknown error
|
|
* UPLAY_OverlappedResult_Ok | Success
|
|
*
|
|
* @note More overlapped results can be added in future versions of the API.
|
|
*
|
|
* @param aSlotId
|
|
* ID of the save game slot to remove - must be 1 or higher
|
|
* @param aOverlapped
|
|
* Overlapped struct
|
|
*
|
|
* @returns Non-zero on success
|
|
*/
|
|
int
|
|
UPLAY_API UPLAY_SAVE_Remove(
|
|
UPLAY_uint32 aSlotId,
|
|
UPLAY_Overlapped* aOverlapped);
|
|
|
|
/** @} */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif // __cplusplus
|
|
|
|
#endif // UPLAY_SAVE_H
|