romdev-mcp 0.1.1

package/src/platforms/genesis/lib/sgdk/include/ext/mw/gamejolt.h

@@ -0,0 +1,541 @@
+/************************************************************************//**
+ * \file
+ *
+ * \brief GameJolt Game API implementation for MegaWiFi.
+ *
+ * \defgroup gamejolt gamejolt
+ * \{
+ *
+ * \brief GameJolt Game API implementation for MegaWiFi.
+ *
+ * Implementation of the version 1.2 of the GameJolt Game API, supporting
+ * scoreboards, trophies, friends, etc. For more information, read the original
+ * GameJolt Game API documentation: https://gamejolt.com/game-api/doc
+ *
+ * \author Jesus Alonso (doragasu)
+ * \date 2020
+ *
+ * \note This module requires setting MODULE_MEGAWIFI to 1 in config.h and
+ * rebuilding the library (if you had to change them).
+ * \note The module uses X Macros, making Doxygen documentation of some
+ * elements a bit complicated. Sorry about that.
+ ****************************************************************************/
+
+#ifndef _GAMEJOLT_H_
+#define _GAMEJOLT_H_
+
+#include "types.h"
+
+/// \brief Module error codes.
+///
+/// On success value is 0. On error all values are
+/// negative, with the exception of the HTTP status error. In this case,
+/// the value reported is the HTTP status code obtained (e.g. 500).
+enum gj_error {
+	GJ_ERR_NONE      =  0,	///< No error
+	GJ_ERR_PARAM     = -1,	///< Missing or invalid parameter
+	GJ_ERR_REQUEST   = -2,	///< Request failed (network or server down?)
+	GJ_ERR_RECEPTION = -3,	///< Failed to receive response data
+	GJ_ERR_RESPONSE  = -4,	///< Response has no success:"true" head
+	GJ_ERR_PARSE     = -5	///< Error while parsing response data
+};
+
+/// \brief Difficulty to achieve the trophy
+enum gj_trophy_difficulty {
+	GJ_TROPHY_TYPE_BRONZE = 0,	///< Bronze trophy (easiest)
+	GJ_TROPHY_TYPE_SILVER,		///< Silver trophy (medium)
+	GJ_TROPHY_TYPE_GOLD,		///< Gold trophy (hard)
+	GJ_TROPHY_TYPE_PLATINUM,	///< Platinum trophy (hardest)
+	GJ_TROPHY_TYPE_UNKNOWN		///< Unknown, just for errors
+};
+
+/// \brief Operations supported by gj_data_store_update() function
+enum gj_data_store_update_operation {
+	GJ_OP_ADD = 0,	///< Adds the value to item
+	GJ_OP_SUBTRACT,	///< Subtracs the value from item
+	GJ_OP_MULTIPLY,	///< Multiplies value by item
+	GJ_OP_DIVIDE,	///< Divides the item by value
+	GJ_OP_APPEND,	///< Appends value to the data store
+	GJ_OP_PREPEND,	///< Prepends value to the data store
+	GJ_OP_MAX	///< Maximum enum value, do not use for operation
+};
+
+/// Reply fields to a trophy fetch request.
+#define GJ_TROPHY_RESPONSE_TABLE(X_MACRO) \
+	X_MACRO(id,          string,            char*) \
+	X_MACRO(title,       string,            char*) \
+	X_MACRO(difficulty,  trophy_difficulty, enum gj_trophy_difficulty) \
+	X_MACRO(description, string,            char*) \
+	X_MACRO(image_url,   string,            char*) \
+	X_MACRO(achieved,    string,            char*)
+
+/// Reply fields to a time fetch request.
+#define GJ_TIME_RESPONSE_TABLE(X_MACRO) \
+	X_MACRO(timestamp, string, char*) \
+	X_MACRO(timezone,  string, char*) \
+	X_MACRO(day,       string, char*) \
+	X_MACRO(hour,      string, char*) \
+	X_MACRO(minute,    string, char*) \
+	X_MACRO(second,    string, char*)
+
+/// Reply field to a scores fetch request.
+#define GJ_SCORE_RESPONSE_TABLE(X_MACRO) \
+	X_MACRO(score,            string, char*) \
+	X_MACRO(sort,             string, char*) \
+	X_MACRO(extra_data,       string, char*) \
+	X_MACRO(user,             string, char*) \
+	X_MACRO(user_id,          string, char*) \
+	X_MACRO(guest,            string, char*) \
+	X_MACRO(stored,           string, char*) \
+	X_MACRO(stored_timestamp, string, char*)
+
+/// Reply fields to a scores tables request.
+#define GJ_SCORE_TABLE_RESPONSE_TABLE(X_MACRO) \
+	X_MACRO(id,          string, char*) \
+	X_MACRO(name,        string, char*) \
+	X_MACRO(description, string, char*) \
+	X_MACRO(primary,     bool_num, bool)
+
+/// Reply fields to a scores get-rank request.
+#define GJ_SCORE_GETRANK_RESPONSE_TABLE(X_MACRO) \
+	X_MACRO(message, string, char*) \
+	X_MACRO(rank,    string, char*)
+
+/// Reply fields to a users fetch request
+#define GJ_USER_RESPONSE_TABLE(X_MACRO) \
+	X_MACRO(id,                       string, char*) \
+	X_MACRO(type,                     string, char*) \
+	X_MACRO(username,                 string, char*) \
+	X_MACRO(avatar_url,               string, char*) \
+	X_MACRO(signed_up,                string, char*) \
+	X_MACRO(signed_up_timestamp,      string, char*) \
+	X_MACRO(last_logged_in,           string, char*) \
+	X_MACRO(last_logged_in_timestamp, string, char*) \
+	X_MACRO(status,                   string, char*) \
+	X_MACRO(developer_name,           string, char*) \
+	X_MACRO(developer_website,        string, char*) \
+	X_MACRO(developer_description,    string, char*)
+
+/// Expands a response table as a structure with its fields
+#define X_AS_STRUCT(field, decoder, type) \
+	type field;
+
+/// Holds the data of a single trophy.
+struct gj_trophy {
+	GJ_TROPHY_RESPONSE_TABLE(X_AS_STRUCT);
+	bool secret;	///< If true, trophy is secret
+};
+
+/// Holds the date/time from server
+struct gj_time {
+	GJ_TIME_RESPONSE_TABLE(X_AS_STRUCT);
+};
+
+/// Holds data of a single score.
+struct gj_score {
+	GJ_SCORE_RESPONSE_TABLE(X_AS_STRUCT);
+};
+
+/// Holds data of a single score table.
+struct gj_score_table {
+	GJ_SCORE_TABLE_RESPONSE_TABLE(X_AS_STRUCT);
+};
+
+/// Holds user data
+struct gj_user {
+	GJ_USER_RESPONSE_TABLE(X_AS_STRUCT);
+};
+
+/************************************************************************//**
+ * \brief Initialize the GameJolt API.
+ *
+ * This function sets the API endpoint, game credentials and user credentials.
+ * Call this function before using any other function in the module.
+ *
+ * \param[in] endpoint    Endpoint for the Game API. Most likely you want to
+ *            use "https://api.gamejolt.com/api/game/v1_2/" here.
+ * \param[in] game_id     Game identifier. E.g. "123456"
+ * \param[in] private_key Game private key. Keep it safe!
+ * \param[in] username    Username of the player.
+ * \param[in] user_token  Token corresponding to username.
+ * \param[in] reply_buf   Pre-allocated buffer to use for data reception.
+ * \param[in] buf_len     Length of reply_buf buffer.
+ * \param[in] tout_frames Number of frames to wait for requests before
+ *                        timing out.
+ *
+ * \return false on success, true on error.
+ *
+ * \warning reply_buf length determines the maximum length of the reply to a
+ * command. If buffer length is small, API will not be able to receive
+ * long responses such as trophy lists or long user lists.
+ ****************************************************************************/
+bool gj_init(const char *endpoint, const char *game_id, const char *private_key,
+		const char *username, const char *user_token, char *reply_buf,
+		uint16_t buf_len, uint16_t tout_frames);
+
+/************************************************************************//**
+ * \brief Return the last error code.
+ *
+ * If any other of the functions in the module return with error, call this
+ * function immediately after the error, to get the error code.
+ *
+ * \return The error code. 0 (GJ_ERR_NONE) if no error occurred.
+ ****************************************************************************/
+enum gj_error gj_get_error(void);
+
+/************************************************************************//**
+ * \brief Fetch player trophies.
+ *
+ * \param[in] achieved    If true, only achieved trophies are get.
+ * \param[in] trophy_id   If not NULL, a single trophy with specified id
+ *            is retrieved.
+ *
+ * \return Raw trophy data on success, NULL on failure. Use gj_trophy_get_next()
+ * to decode the raw information.
+ ****************************************************************************/
+char *gj_trophies_fetch(bool achieved, const char *trophy_id);
+
+/************************************************************************//**
+ * \brief Decode the trophy raw data for the next entry.
+ *
+ * On first call, set pos to the value returned by gj_trophies_fetch(). On
+ * successive calls, set pos to the last non-NULL returned value of this
+ * function.
+ *
+ * \param[inout] pos    Position of the trophy to extract. Note that input
+ *               raw data is modified to add null terminations for fields
+ * \param[out]   trophy Decoded trophy data.
+ *
+ * \return Position of the next trophy to decode (to be used on next call
+ * to this function), or NULL if the current trophy could not be decoded.
+ ****************************************************************************/
+char *gj_trophy_get_next(char *pos, struct gj_trophy *trophy);
+
+/************************************************************************//**
+ * \brief Mark a trophy as achieved.
+ *
+ * \param[in] trophy_id   Identifier of the trophy to mark as achieved.
+ *
+ * \return true if error, false on success.
+ ****************************************************************************/
+bool gj_trophy_add_achieved(const char *trophy_id);
+
+/************************************************************************//**
+ * \brief Mark a trophy as not achieved.
+ *
+ * \param[in] trophy_id   Identifier of the trophy to mark as not achieved.
+ *
+ * \return true if error, false on success.
+ ****************************************************************************/
+bool gj_trophy_remove_achieved(const char *trophy_id);
+
+/************************************************************************//**
+ * \brief Get the string corresponding to a trophy difficulty.
+ *
+ * \param[in] difficulty Difficulty value to be translated to a string.
+ *
+ * \return The string corresponding to the specified difficulty. If the input
+ * value of difficulty is out of range, "Unknown" string will be returned.
+ ****************************************************************************/
+const char *gj_trophy_difficulty_str(enum gj_trophy_difficulty difficulty);
+
+/************************************************************************//**
+ * \brief Get the date and time from server.
+ *
+ * \param[out] time        Date and time from the server.
+ *
+ * \return true if error, false on success.
+ ****************************************************************************/
+bool gj_time(struct gj_time *time);
+
+/************************************************************************//**
+ * \brief Fetch scores data.
+ *
+ * \param[in] limit       Number of scores to return (defaults to 10).
+ * \param[in] table_id    Table id, or NULL for the main game table.
+ * \param[in] guest       Set if you want to get score only from guest player.
+ * \param[in] better_than Get only scores better than this sort value.
+ * \param[in] worse_than  Get only scores worse than this sort value.
+ * \param[in] only_user   Set to true if you want to get only the user scores.
+ *
+ * \return Raw scores data on success, or NULL on failure.
+ * Use gj_score_get_next() to decode the raw score data.
+ * \note All parameters are optional, use NULL if you do not want to set
+ * them.
+ ****************************************************************************/
+char *gj_scores_fetch(const char *limit, const char *table_id,
+		const char *guest, const char *better_than,
+		const char *worse_than, bool only_user);
+
+/************************************************************************//**
+ * \brief Decode the score raw data for the next entry.
+ *
+ * On first call, set pos to the value returned by gj_scores_fetch(). On
+ * successive calls, set pos to the last non-NULL returned value of this
+ * function.
+ *
+ * \param[inout] pos   Position of the score to extract. Note that input
+ *               raw data is modified to add null terminations for fields
+ * \param[out]   score Decoded score data.
+ *
+ * \return Position of the next score to decode (to be used on next call
+ * to this function), or NULL if the current score could not be decoded.
+ ****************************************************************************/
+char *gj_score_get_next(char *pos, struct gj_score *score);
+
+/************************************************************************//**
+ * \brief Fetch score tables.
+ *
+ * \return Raw score tables data on success, or NULL on failure.
+ * Use gj_score_table_get_next() to decode the raw score table data.
+ ****************************************************************************/
+char *gj_scores_tables_fetch(void);
+
+/************************************************************************//**
+ * \brief Decode the score tables raw data for the next entry.
+ *
+ * On first call, set pos to the value returned by gj_scores_tables_fetch().
+ * On successive calls, set pos to the last non-NULL returned value by this
+ * function.
+ *
+ * \param[inout] pos         Position of the score table to extract. Note that
+ *               input raw data is modified to add null terminations for fields
+ * \param[out]   score_table Decoded score table data.
+ *
+ * \return Position of the next score to decode (to be used on next call
+ * to this function), or NULL if the current score could not be decoded.
+ ****************************************************************************/
+char *gj_score_table_get_next(char *pos, struct gj_score_table *score_table);
+
+/************************************************************************//**
+ * \brief Get ranking corresponding to a sort parameter.
+ *
+ * \param[in] sort     Score sort value to get ranking position from table.
+ * \param[in] table_id Score table id, or NULL for the main table.
+ *
+ * \return Ranking corresponding to sort parameter, or NULL on error.
+ ****************************************************************************/
+char *gj_scores_get_rank(const char *sort, const char *table_id);
+
+/************************************************************************//**
+ * \brief Add a score to a scoreboard.
+ *
+ * \param[in] score      Score in textual format (e.g. "500 torreznos")
+ * \param[in] sort       Number used to sort the score (e.g. "500")
+ * \param[in] table_id   Table id, or NULL for the main game table.
+ * \param[in] guest      Name of the guest player, or NULL for user player.
+ * \param[in] extra_data Extra data to save with score, NULL for none.
+ *
+ * \return true if error, false on success.
+ ****************************************************************************/
+bool gj_scores_add(const char *score, const char *sort, const char *table_id,
+		const char *guest, const char *extra_data);
+
+/************************************************************************//**
+ * \brief Sets a key/value pair in the data store.
+ *
+ * \param[in] key        Key to set.
+ * \param[in] data       Value to set.
+ * \param[in] user_store When true, data is saved in user storage. Otherwise
+ *                       it will be saved in the game global store.
+ *
+ * \return true if error, false on success.
+ ****************************************************************************/
+bool gj_data_store_set(const char *key, const char *data, bool user_store);
+
+/************************************************************************//**
+ * \brief Fetch data store keys.
+ *
+ * \param[in] pattern    Optional. If set, match returned keys with pattern.
+ * \param[in] user_store When true, data is retrieved from user storage.
+ *                       Otherwise it will be retrieved from the game global
+ *                       store.
+ *
+ * \return Raw keys on success, or NULL on failure. Use
+ * gj_data_store_key_next() to decode the raw key data.
+ ****************************************************************************/
+char *gj_data_store_keys_fetch(const char *pattern, bool user_store);
+
+/************************************************************************//**
+ * \brief Decode the key data from a gj_data_store_keys_fetch() call.
+ *
+ * On first call, set pos to the value returned by gj_data_store_keys_fetch().
+ * On successive calls, set pos to the last non-NULL returned value by this
+ * function.
+ *
+ * \param[inout] pos Position of the key to extract. Note that input raw data
+ *                   is modified to add null terminations.
+ * \param[out]   key Decoded key data.
+ *
+ * \return Position of the next key to decode (to be used on next call
+ * to this function), or NULL if the current key could not be decoded.
+ ****************************************************************************/
+char *gj_data_store_key_next(char *pos, char **key);
+
+/************************************************************************//**
+ * \brief Retrieve data from the data store.
+ *
+ * \param[in] key        Key to use for data retrieval.
+ * \param[in] user_store When true, data is retrieved from user storage.
+ *                       Otherwise it will be retrieved from the game global
+ *                       store.
+ *
+ * \return Data associated with requested key, or NULL on failure.
+ ****************************************************************************/
+char *data_store_fetch(const char *key, bool user_store);
+
+/************************************************************************//**
+ * \brief Update data in the data store.
+ *
+ * \param[in] key        Key to use for the data to be updated.
+ * \param[in] operation  Operation to apply to the data to update.
+ * \param[in] value      Value to use in the update operation.
+ * \param[in] user_store When true, data is updated from user storage.
+ *                       Otherwise it will be updated in the game global store.
+ *
+ * \return The updated data on success, or NULL on error.
+ ****************************************************************************/
+char *gj_data_store_update(const char *key,
+		enum gj_data_store_update_operation operation,
+		const char *value, bool user_store);
+
+/************************************************************************//**
+ * \brief Remove data from the data store.
+ *
+ * \param[in] key        Key to use for data removal.
+ * \param[in] user_store When true, data is removed from user storage.
+ *                       Otherwise it will be removed in the game global store.
+ *
+ * \return false on success, true on error.
+ ****************************************************************************/
+bool gj_data_store_remove(const char *key, bool user_store);
+
+/************************************************************************//**
+ * \brief Open a game session for the player.
+ *
+ * \return false on success, true on error.
+ ****************************************************************************/
+bool gj_sessions_open(void);
+
+/************************************************************************//**
+ * \brief Ping a session, and allow setting it as active or idle.
+ *
+ * \param[in] active If true, session is marked as active. Otherwise, session
+ *                   is marked as idle.
+ *
+ * \return false on success, true on error.
+ ****************************************************************************/
+bool gj_sessions_ping(bool active);
+
+/************************************************************************//**
+ * \brief Checks if a user session is active in the game.
+ *
+ * \param[in] username   (Optional) username to check for open session.
+ * \param[in] user_token (Optional) user token to check for open session.
+ *
+ * \return true if session is active. false is session is not active or other
+ * error has occurred.
+ *
+ * \note If username or user_token is NULL, the session check is performed
+ * against the user configured in gj_init() call.
+ * \note To make sure a session is not active and no error has occurred, when
+ * this function returns false, gj_get_error() must return GJ_ERR_NONE.
+ ****************************************************************************/
+bool gj_sessions_check(const char *username, const char *user_token);
+
+/************************************************************************//**
+ * \brief Close a previously opened session.
+ *
+ * \return false on success, true on error.
+ ****************************************************************************/
+bool gj_sessions_close(void);
+
+/************************************************************************//**
+ * \brief Get user data
+ *
+ * \param[in]  username (Optional) User name to get data from.
+ * \param[in]  user_id  (Optional) user token to check for open session.
+ *
+ * \return Raw user data on success, NULL if error has occurred.
+ *
+ * \note You can pass multiple user ids by separating them with commas (',').
+ * If you do it, be careful not to overflow the receive buffer!
+ * \note Only one of the optional parameters (username, user_id) must be
+ * specified. Set the other to NULL.
+ ****************************************************************************/
+char *gj_users_fetch(const char *username, const char *user_id);
+
+/************************************************************************//**
+ * \brief Decode the user raw data for the next entry.
+ *
+ * On first call, set pos to the value returned by gj_users_fetch(). On
+ * successive calls, set pos to the last non-NULL returned value of this
+ * function.
+ *
+ * \param[inout] pos  Position of the user to extract. Note that input raw
+ *                    data is modified to add null terminations for fields
+ * \param[out]   user Decoded user data
+ *
+ * \return Position of the next user to decode (to be used on next call
+ * to this function), or NULL if the current user could not be decoded.
+ ****************************************************************************/
+char *gj_user_get_next(char *pos, struct gj_user *user);
+
+/************************************************************************//**
+ * \brief Check user credentials.
+ *
+ * \return true if credentials are correct, false if credentials do not match
+ * or error has occurred.
+ *
+ * \note To make sure credentials are not valid and no error has occurred, when
+ * this function returns false, gj_get_error() must return GJ_ERR_NONE.
+ ****************************************************************************/
+bool gj_users_auth(void);
+
+/************************************************************************//**
+ * \brief Get friends list.
+ *
+ * \return Raw user data on success, NULL if error has occurred. Use
+ * gj_friend_get_next() to decode the raw data and get friend user_ids.
+ ****************************************************************************/
+char *gj_friends_fetch(void);
+
+/************************************************************************//**
+ * \brief Decode the friend raw data for the next entry.
+ *
+ * On first call, set pos to the value returned by gj_friends_fetch(). On
+ * successive calls, set pos to the last non-NULL returned value of this
+ * function.
+ *
+ * \param[inout] pos     Position of the friend to extract. Note that input raw
+ *                       data is modified to add null terminations for fields
+ * \param[out]   user_id Decoded friend user_id.
+ *
+ * \return Position of the next friend to decode (to be used on next call
+ * to this function), or NULL if the current friend could not be decoded.
+ ****************************************************************************/
+char *gj_friend_get_next(char *pos, char **user_id);
+
+/************************************************************************//**
+ * \brief Generic GameJolt Game API request.
+ *
+ * Usually you do not need to use this function directly. Use more specific
+ * API calls that do the hard work of filling parameters and decoding the
+ * response.
+ *
+ * \param[in]  path         Array of paths for the request.
+ * \param[in]  num_paths    Number of elements in path array.
+ * \param[in]  key          Array of keys for key/value parameters.
+ * \param[in]  value        Array of values for key/value parameters.
+ * \param[in]  num_kv_pairs Number of elements in key and value arrays.
+ * \param[out] out_len      Length of the received reply to request.
+ *
+ * \return The raw reply data to the request, or NULL on error.
+ ****************************************************************************/
+char *gj_request(const char **path, uint8_t num_paths, const char **key,
+		const char **value, uint8_t num_kv_pairs, uint32_t *out_len);
+
+#endif /* _GAMEJOLT_H_ */
+
+/** \} */
+