GameJolt Game API implementation for MegaWiFi. More...

Data Structures
struct	gj_trophy
	Holds the data of a single trophy. More...

struct	gj_time
	Holds the date/time from server. More...

struct	gj_score
	Holds data of a single score. More...

struct	gj_score_table
	Holds data of a single score table. More...

struct	gj_user
	Holds user data. More...

Macros
#define	GJ_TROPHY_RESPONSE_TABLE(X_MACRO)
	Reply fields to a trophy fetch request. More...

#define	GJ_TIME_RESPONSE_TABLE(X_MACRO)
	Reply fields to a time fetch request. More...

#define	GJ_SCORE_RESPONSE_TABLE(X_MACRO)
	Reply field to a scores fetch request. More...

#define	GJ_SCORE_TABLE_RESPONSE_TABLE(X_MACRO)
	Reply fields to a scores tables request. More...

#define	GJ_SCORE_GETRANK_RESPONSE_TABLE(X_MACRO)
	Reply fields to a scores get-rank request. More...

#define	GJ_USER_RESPONSE_TABLE(X_MACRO)
	Reply fields to a users fetch request. More...

#define	X_AS_STRUCT(field, decoder, type) type field;
	Expands a response table as a structure with its fields. More...

Enumerations
enum	gj_error
	Module error codes. More...

enum	gj_trophy_difficulty
	Difficulty to achieve the trophy. More...

enum	gj_data_store_update_operation
	Operations supported by gj_data_store_update() function. More...

Functions
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)
	Initialize the GameJolt API. More...

enum gj_error	gj_get_error (void)
	Return the last error code. More...

char *	gj_trophies_fetch (bool achieved, const char *trophy_id)
	Fetch player trophies. More...

char *	gj_trophy_get_next (char pos, struct gj_trophy trophy)
	Decode the trophy raw data for the next entry. More...

bool	gj_trophy_add_achieved (const char *trophy_id)
	Mark a trophy as achieved. More...

bool	gj_trophy_remove_achieved (const char *trophy_id)
	Mark a trophy as not achieved. More...

const char *	gj_trophy_difficulty_str (enum gj_trophy_difficulty difficulty)
	Get the string corresponding to a trophy difficulty. More...

bool	gj_time (struct gj_time *time)
	Get the date and time from server. More...

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)
	Fetch scores data. More...

char *	gj_score_get_next (char pos, struct gj_score score)
	Decode the score raw data for the next entry. More...

char *	gj_scores_tables_fetch (void)
	Fetch score tables. More...

char *	gj_score_table_get_next (char pos, struct gj_score_table score_table)
	Decode the score tables raw data for the next entry. More...

char *	gj_scores_get_rank (const char sort, const char table_id)
	Get ranking corresponding to a sort parameter. More...

bool	gj_scores_add (const char score, const char sort, const char table_id, const char guest, const char *extra_data)
	Add a score to a scoreboard. More...

bool	gj_data_store_set (const char key, const char data, bool user_store)
	Sets a key/value pair in the data store. More...

char *	gj_data_store_keys_fetch (const char *pattern, bool user_store)
	Fetch data store keys. More...

char *	gj_data_store_key_next (char pos, char *key)
	Decode the key data from a gj_data_store_keys_fetch() call. More...

char *	data_store_fetch (const char *key, bool user_store)
	Retrieve data from the data store. More...

char *	gj_data_store_update (const char key, enum gj_data_store_update_operation operation, const char value, bool user_store)
	Update data in the data store. More...

bool	gj_data_store_remove (const char *key, bool user_store)
	Remove data from the data store. More...

bool	gj_sessions_open (void)
	Open a game session for the player. More...

bool	gj_sessions_ping (bool active)
	Ping a session, and allow setting it as active or idle. More...

bool	gj_sessions_check (const char username, const char user_token)
	Checks if a user session is active in the game. More...

bool	gj_sessions_close (void)
	Close a previously opened session. More...

char *	gj_users_fetch (const char username, const char user_id)
	Get user data. More...

char *	gj_user_get_next (char pos, struct gj_user user)
	Decode the user raw data for the next entry. More...

bool	gj_users_auth (void)
	Check user credentials. More...

char *	gj_friends_fetch (void)
	Get friends list. More...

char *	gj_friend_get_next (char pos, char *user_id)
	Decode the friend raw data for the next entry. More...

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)
	Generic GameJolt Game API request. More...

Detailed Description

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: The module uses X Macros, making Doxygen documentation of some elements a bit complicated. Sorry about that.

Macro Definition Documentation

◆ GJ_SCORE_GETRANK_RESPONSE_TABLE

#define GJ_SCORE_GETRANK_RESPONSE_TABLE ( X_MACRO )

Value:

X_MACRO(message, string, char*) \

X_MACRO(rank, string, char*)

Reply fields to a scores get-rank request.

Definition at line 99 of file gamejolt.h.

◆ GJ_SCORE_RESPONSE_TABLE

#define GJ_SCORE_RESPONSE_TABLE ( X_MACRO )

Value:

    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 field to a scores fetch request.

Definition at line 81 of file gamejolt.h.

◆ GJ_SCORE_TABLE_RESPONSE_TABLE

#define GJ_SCORE_TABLE_RESPONSE_TABLE ( X_MACRO )

Value:

    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 tables request.

Definition at line 92 of file gamejolt.h.

◆ GJ_TIME_RESPONSE_TABLE

#define GJ_TIME_RESPONSE_TABLE ( X_MACRO )

Value:

    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 fields to a time fetch request.

Definition at line 72 of file gamejolt.h.

◆ GJ_TROPHY_RESPONSE_TABLE

#define GJ_TROPHY_RESPONSE_TABLE ( X_MACRO )

Value:

    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 trophy fetch request.

Definition at line 63 of file gamejolt.h.

◆ GJ_USER_RESPONSE_TABLE

#define GJ_USER_RESPONSE_TABLE ( X_MACRO )

Value:

    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*)

Reply fields to a users fetch request.

Definition at line 104 of file gamejolt.h.

◆ X_AS_STRUCT

#define X_AS_STRUCT	(	field,
		decoder,
		type
	)	type field;

Expands a response table as a structure with its fields.

Definition at line 119 of file gamejolt.h.

Enumeration Type Documentation

◆ gj_data_store_update_operation

enum gj_data_store_update_operation

Operations supported by gj_data_store_update() function.

Enumerator
GJ_OP_ADD	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.

Definition at line 52 of file gamejolt.h.

◆ gj_error

enum gj_error

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).

Enumerator
GJ_ERR_NONE	No error.
GJ_ERR_PARAM	Missing or invalid parameter.
GJ_ERR_REQUEST	Request failed (network or server down?)
GJ_ERR_RECEPTION	Failed to receive response data.
GJ_ERR_RESPONSE	Response has no success:"true" head.
GJ_ERR_PARSE	Error while parsing response data.

Definition at line 33 of file gamejolt.h.

◆ gj_trophy_difficulty

enum gj_trophy_difficulty

Difficulty to achieve the trophy.

Enumerator
GJ_TROPHY_TYPE_BRONZE	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.

Definition at line 43 of file gamejolt.h.

Function Documentation

◆ data_store_fetch()

char * data_store_fetch	(	const char *	key,
		bool	user_store
	)

Retrieve data from the data store.

Parameters

[in]	key	Key to use for data retrieval.
[in]	user_store	When true, data is retrieved from user storage. Otherwise it will be retrieved from the game global store.

Returns: Data associated with requested key, or NULL on failure.

◆ gj_data_store_key_next()

char * gj_data_store_key_next	(	char *	pos,
		char **	key
	)

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.

Parameters

[in,out]	pos	Position of the key to extract. Note that input raw data is modified to add null terminations.
[out]	key	Decoded key data.

Returns: 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.

◆ gj_data_store_keys_fetch()

char * gj_data_store_keys_fetch	(	const char *	pattern,
		bool	user_store
	)

Fetch data store keys.

Parameters

[in]	pattern	Optional. If set, match returned keys with pattern.
[in]	user_store	When true, data is retrieved from user storage. Otherwise it will be retrieved from the game global store.

Returns: Raw keys on success, or NULL on failure. Use gj_data_store_key_next() to decode the raw key data.

◆ gj_data_store_remove()

bool gj_data_store_remove	(	const char *	key,
		bool	user_store
	)

Remove data from the data store.

Parameters

[in]	key	Key to use for data removal.
[in]	user_store	When true, data is removed from user storage. Otherwise it will be removed in the game global store.

Returns: false on success, true on error.

◆ gj_data_store_set()

bool gj_data_store_set	(	const char *	key,
		const char *	data,
		bool	user_store
	)

Sets a key/value pair in the data store.

Parameters

[in]	key	Key to set.
[in]	data	Value to set.
[in]	user_store	When true, data is saved in user storage. Otherwise it will be saved in the game global store.

Returns: true if error, false on success.

◆ gj_data_store_update()

char * gj_data_store_update	(	const char *	key,
		enum gj_data_store_update_operation	operation,
		const char *	value,
		bool	user_store
	)

Update data in the data store.

Parameters

[in]	key	Key to use for the data to be updated.
[in]	operation	Operation to apply to the data to update.
[in]	value	Value to use in the update operation.
[in]	user_store	When true, data is updated from user storage. Otherwise it will be updated in the game global store.

Returns: The updated data on success, or NULL on error.

◆ gj_friend_get_next()

char * gj_friend_get_next	(	char *	pos,
		char **	user_id
	)

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.

Parameters

[in,out]	pos	Position of the friend to extract. Note that input raw data is modified to add null terminations for fields
[out]	user_id	Decoded friend user_id.

Returns: 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.

◆ gj_friends_fetch()

char * gj_friends_fetch ( void )

Get friends list.

Returns: 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.

◆ gj_get_error()

enum gj_error gj_get_error ( void )

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.

Returns: The error code. 0 (GJ_ERR_NONE) if no error occurred.

◆ gj_init()

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
	)

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.

Parameters

[in]	endpoint	Endpoint for the Game API. Most likely you want to use "https://api.gamejolt.com/api/game/v1_2/" here.
[in]	game_id	Game identifier. E.g. "123456"
[in]	private_key	Game private key. Keep it safe!
[in]	username	Username of the player.
[in]	user_token	Token corresponding to username.
[in]	reply_buf	Pre-allocated buffer to use for data reception.
[in]	buf_len	Length of reply_buf buffer.
[in]	tout_frames	Number of frames to wait for requests before timing out.

Returns: 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.

◆ gj_request()

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
	)

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.

Parameters

[in]	path	Array of paths for the request.
[in]	num_paths	Number of elements in path array.
[in]	key	Array of keys for key/value parameters.
[in]	value	Array of values for key/value parameters.
[in]	num_kv_pairs	Number of elements in key and value arrays.
[out]	out_len	Length of the received reply to request.

Returns: The raw reply data to the request, or NULL on error.

◆ gj_score_get_next()

char * gj_score_get_next	(	char *	pos,
		struct gj_score *	score
	)

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.

Parameters

[in,out]	pos	Position of the score to extract. Note that input raw data is modified to add null terminations for fields
[out]	score	Decoded score data.

Returns: 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.

◆ gj_score_table_get_next()

char * gj_score_table_get_next	(	char *	pos,
		struct gj_score_table *	score_table
	)

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.

Parameters

[in,out]	pos	Position of the score table to extract. Note that input raw data is modified to add null terminations for fields
[out]	score_table	Decoded score table data.

Returns: 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.

◆ gj_scores_add()

bool gj_scores_add	(	const char *	score,
		const char *	sort,
		const char *	table_id,
		const char *	guest,
		const char *	extra_data
	)

Add a score to a scoreboard.

Parameters

[in]	score	Score in textual format (e.g. "500 torreznos")
[in]	sort	Number used to sort the score (e.g. "500")
[in]	table_id	Table id, or NULL for the main game table.
[in]	guest	Name of the guest player, or NULL for user player.
[in]	extra_data	Extra data to save with score, NULL for none.

Returns: true if error, false on success.

◆ gj_scores_fetch()

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
	)

Fetch scores data.

Parameters

[in]	limit	Number of scores to return (defaults to 10).
[in]	table_id	Table id, or NULL for the main game table.
[in]	guest	Set if you want to get score only from guest player.
[in]	better_than	Get only scores better than this sort value.
[in]	worse_than	Get only scores worse than this sort value.
[in]	only_user	Set to true if you want to get only the user scores.

Returns: 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.

◆ gj_scores_get_rank()

char * gj_scores_get_rank	(	const char *	sort,
		const char *	table_id
	)

Get ranking corresponding to a sort parameter.

Parameters

[in]	sort	Score sort value to get ranking position from table.
[in]	table_id	Score table id, or NULL for the main table.

Returns: Ranking corresponding to sort parameter, or NULL on error.

◆ gj_scores_tables_fetch()

char * gj_scores_tables_fetch ( void )

Fetch score tables.

Returns: Raw score tables data on success, or NULL on failure. Use gj_score_table_get_next() to decode the raw score table data.

◆ gj_sessions_check()

bool gj_sessions_check	(	const char *	username,
		const char *	user_token
	)

Checks if a user session is active in the game.

Parameters

[in]	username	(Optional) username to check for open session.
[in]	user_token	(Optional) user token to check for open session.

Returns: 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.; 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.

◆ gj_sessions_close()

bool gj_sessions_close ( void )

Close a previously opened session.

Returns: false on success, true on error.

◆ gj_sessions_open()

bool gj_sessions_open ( void )

Open a game session for the player.

Returns: false on success, true on error.

◆ gj_sessions_ping()

bool gj_sessions_ping ( bool active )

Ping a session, and allow setting it as active or idle.

Parameters

[in] active If true, session is marked as active. Otherwise, session is marked as idle.

Returns: false on success, true on error.

◆ gj_time()

bool gj_time ( struct gj_time * time )

Get the date and time from server.

Parameters

[out] time Date and time from the server.

Returns: true if error, false on success.

◆ gj_trophies_fetch()

char * gj_trophies_fetch	(	bool	achieved,
		const char *	trophy_id
	)

Fetch player trophies.

Parameters

[in]	achieved	If true, only achieved trophies are get.
[in]	trophy_id	If not NULL, a single trophy with specified id is retrieved.

Returns: Raw trophy data on success, NULL on failure. Use gj_trophy_get_next() to decode the raw information.

◆ gj_trophy_add_achieved()

bool gj_trophy_add_achieved ( const char * trophy_id )

Mark a trophy as achieved.

Parameters

[in] trophy_id Identifier of the trophy to mark as achieved.

Returns: true if error, false on success.

◆ gj_trophy_difficulty_str()

const char * gj_trophy_difficulty_str ( enum gj_trophy_difficulty difficulty )

Get the string corresponding to a trophy difficulty.

Parameters

[in] difficulty Difficulty value to be translated to a string.

Returns: The string corresponding to the specified difficulty. If the input value of difficulty is out of range, "Unknown" string will be returned.

◆ gj_trophy_get_next()

char * gj_trophy_get_next	(	char *	pos,
		struct gj_trophy *	trophy
	)

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.

Parameters

[in,out]	pos	Position of the trophy to extract. Note that input raw data is modified to add null terminations for fields
[out]	trophy	Decoded trophy data.

Returns: 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.

◆ gj_trophy_remove_achieved()

bool gj_trophy_remove_achieved ( const char * trophy_id )

Mark a trophy as not achieved.

Parameters

[in] trophy_id Identifier of the trophy to mark as not achieved.

Returns: true if error, false on success.

◆ gj_user_get_next()

char * gj_user_get_next	(	char *	pos,
		struct gj_user *	user
	)

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.

Parameters

[in,out]	pos	Position of the user to extract. Note that input raw data is modified to add null terminations for fields
[out]	user	Decoded user data

Returns: 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.

◆ gj_users_auth()

bool gj_users_auth ( void )

Check user credentials.

Returns: 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.

◆ gj_users_fetch()

char * gj_users_fetch	(	const char *	username,
		const char *	user_id
	)

Get user data.

Parameters

[in]	username	(Optional) User name to get data from.
[in]	user_id	(Optional) user token to check for open session.

Returns: 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!; Only one of the optional parameters (username, user_id) must be specified. Set the other to NULL.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ GJ_SCORE_GETRANK_RESPONSE_TABLE

◆ GJ_SCORE_RESPONSE_TABLE

◆ GJ_SCORE_TABLE_RESPONSE_TABLE

◆ GJ_TIME_RESPONSE_TABLE

◆ GJ_TROPHY_RESPONSE_TABLE

◆ GJ_USER_RESPONSE_TABLE

◆ X_AS_STRUCT

Enumeration Type Documentation

◆ gj_data_store_update_operation

◆ gj_error

◆ gj_trophy_difficulty

Function Documentation

◆ data_store_fetch()

◆ gj_data_store_key_next()

◆ gj_data_store_keys_fetch()

◆ gj_data_store_remove()

◆ gj_data_store_set()

◆ gj_data_store_update()

◆ gj_friend_get_next()

◆ gj_friends_fetch()

◆ gj_get_error()

◆ gj_init()

◆ gj_request()

◆ gj_score_get_next()

◆ gj_score_table_get_next()

◆ gj_scores_add()

◆ gj_scores_fetch()

◆ gj_scores_get_rank()

◆ gj_scores_tables_fetch()

◆ gj_sessions_check()

◆ gj_sessions_close()

◆ gj_sessions_open()

◆ gj_sessions_ping()

◆ gj_time()

◆ gj_trophies_fetch()

◆ gj_trophy_add_achieved()

◆ gj_trophy_difficulty_str()

◆ gj_trophy_get_next()

◆ gj_trophy_remove_achieved()

◆ gj_user_get_next()

◆ gj_users_auth()

◆ gj_users_fetch()