ggzmod.h File Reference

Common functions for interfacing a game client and GGZ. More...

#include <ggz.h>
#include <ggz_common.h>

Go to the source code of this file.

Data Structures
struct	GGZSeat
	A seat at a GGZ game table. More...
struct	GGZSpectatorSeat
	A game spectator entry. More...
struct	GGZChat
struct	GGZPlayerInfo
Defines
#define	GGZMOD_VERSION_MAJOR   0
#define	GGZMOD_VERSION_MINOR   0
#define	GGZMOD_VERSION_MICRO   14
#define	GGZMOD_VERSION_IFACE   "5:0:1"
Typedefs
typedef GGZMod	GGZMod
	A GGZmod object, used for tracking a ggz<->table connection.
typedef void(*)	GGZModHandler (GGZMod *mod, GGZModEvent e, const void *data)
	Event handler prototype.
Enumerations
enum	GGZModState {   GGZMOD_STATE_CREATED, GGZMOD_STATE_CONNECTED, GGZMOD_STATE_WAITING, GGZMOD_STATE_PLAYING,   GGZMOD_STATE_DONE }
	Table states. More...
enum	GGZModEvent {   GGZMOD_EVENT_STATE, GGZMOD_EVENT_SERVER, GGZMOD_EVENT_PLAYER, GGZMOD_EVENT_SEAT,   GGZMOD_EVENT_SPECTATOR_SEAT, GGZMOD_EVENT_CHAT, GGZMOD_EVENT_STATS, GGZMOD_EVENT_INFO,   GGZMOD_EVENT_ERROR }
	Callback events. More...
enum	GGZModType { GGZMOD_GGZ, GGZMOD_GAME }
	The "type" of ggzmod. More...
Functions
int	ggzmod_is_ggz_mode (void)
	Is the program running in GGZ mode?
GGZMod *	ggzmod_new (GGZModType type)
	Create a new ggzmod object.
void	ggzmod_free (GGZMod *ggzmod)
	Destroy a finished ggzmod object.
int	ggzmod_get_fd (GGZMod *ggzmod)
	Get the file descriptor for the GGZMod socket.
GGZModType	ggzmod_get_type (GGZMod *ggzmod)
	Get the type of the ggzmod object.
GGZModState	ggzmod_get_state (GGZMod *ggzmod)
	Get the current state of the table.
int	ggzmod_get_server_fd (GGZMod *ggzmod)
	Get the fd of the game server connection.
int	ggzmod_get_num_seats (GGZMod *ggzmod)
	Get the total number of seats at the table.
GGZSeat	ggzmod_get_seat (GGZMod *ggzmod, int seat)
	Get all data for the specified seat.
int	ggzmod_get_num_spectator_seats (GGZMod *ggzmod)
	Get the maximum number of spectators. This function returns the maximum number of spectator seats available. A game can use this to iterate over the spectator seats to look for spectators occupying them. Since spectators may come and go at any point and there is no limit on the number of spectators, you should consider this value to be dynamic and call this function again each time you're looking for spectators.
GGZSpectatorSeat	ggzmod_get_spectator_seat (GGZMod *ggzmod, int seat)
	Get a spectator's data.
const char *	ggzmod_get_player (GGZMod *ggzmod, int *is_spectator, int *seat_num)
	Get data about this player.
void *	ggzmod_get_gamedata (GGZMod *ggzmod)
	Return gamedata pointer.
void	ggzmod_set_gamedata (GGZMod *ggzmod, void *data)
	Set gamedata pointer.
void	ggzmod_set_handler (GGZMod *ggzmod, GGZModEvent e, GGZModHandler func)
	Set a handler for the given event.
int	ggzmod_dispatch (GGZMod *ggzmod)
	Check for and handle input.
int	ggzmod_set_state (GGZMod *ggzmod, GGZModState state)
	Change the table's state.
int	ggzmod_connect (GGZMod *ggzmod)
	Connect to ggz.
int	ggzmod_disconnect (GGZMod *ggzmod)
	Disconnect from ggz.
void	ggzmod_request_stand (GGZMod *ggzmod)
	Stand up (move from your seat into a spectator seat).
void	ggzmod_request_sit (GGZMod *ggzmod, int seat_num)
	Sit down (move from a spectator seat into a player seat).
void	ggzmod_request_boot (GGZMod *ggzmod, const char *name)
	Boot a player. Only the game host may do this.
void	ggzmod_request_bot (GGZMod *ggzmod, int seat_num)
	Change the requested seat from an open seat to a bot.
void	ggzmod_request_open (GGZMod *ggzmod, int seat_num)
	Change the requested seat from a bot to an open seat.
void	ggzmod_request_chat (GGZMod *ggzmod, const char *chat_msg)
	Chat! This initiates a table chat.
int	ggzmod_player_get_record (GGZMod *ggzmod, GGZSeat *seat, int *wins, int *losses, int *ties, int *forfeits)
	Get the player's win-loss record.
int	ggzmod_player_get_rating (GGZMod *ggzmod, GGZSeat *seat, int *rating)
	Get the player's rating.
int	ggzmod_player_get_ranking (GGZMod *ggzmod, GGZSeat *seat, int *ranking)
	Get the player's ranking.
int	ggzmod_player_get_highscore (GGZMod *ggzmod, GGZSeat *seat, int *highscore)
	Get the player's highscore.
int	ggzmod_spectator_get_record (GGZMod *ggzmod, GGZSpectatorSeat *seat, int *wins, int *losses, int *ties, int *forfeits)
	Get the spectator's win-loss record.
int	ggzmod_spectator_get_rating (GGZMod *ggzmod, GGZSpectatorSeat *seat, int *rating)
	Get the spectator's rating.
int	ggzmod_spectator_get_ranking (GGZMod *ggzmod, GGZSpectatorSeat *seat, int *ranking)
	Get the spectator's ranking.
int	ggzmod_spectator_get_highscore (GGZMod *ggzmod, GGZSpectatorSeat *seat, int *highscore)
	Get the spectator's highscore.
int	ggzmod_player_request_info (GGZMod *ggzmod, int seat_num)
	Request extended player information for one or more players.
GGZPlayerInfo *	ggzmod_player_get_info (GGZMod *ggzmod, int seat)
	Get the extended information for the specified seat.

---

Detailed Description

Common functions for interfacing a game client and GGZ.

This file contains all libggzmod functions used by game clients to interface with GGZ. Just include ggzmod.h and make sure your program is linked with libggzmod. Then use the functions below as appropriate.

GGZmod currently provides an event-driven interface. Data from communication sockets is read in by the library, and a handler function (registered as a callback) is invoked to handle any events. The calling program should not read/write data from/to the GGZ socket unless it really knows what it is doing.

This does not apply to the game server sockets: ggzmod provides one file desriptor for communicating (TCP) to the game server. If data is ready to be read this file descriptor, ggzmod may invoke the appropriate handler (see below), but will never actually read any data.

For more information, see the documentation at http://www.ggzgamingzone.org/.

---

Typedef Documentation

typedef struct GGZMod GGZMod

A GGZmod object, used for tracking a ggz<->table connection.

A game client should track a pointer to a GGZMod object; it contains all the state information for communicating with GGZ. The GGZ client will track one such object for every game table that is running.

typedef void(*) GGZModHandler(GGZMod *mod, GGZModEvent e, const void *data)

Event handler prototype.

A function of this type will be called to handle a ggzmod event.

Parameters:

	mod	The ggzmod state object.
	e	The event that has occured.
	data	Pointer to additional data for the event. The additional data will be of the following form: GGZMOD_EVENT_STATE: The old state (GGZModState*) GGZMOD_EVENT_SERVER: The fd of the server connection (int*) GGZMOD_EVENT_PLAYER: The old player data (int[2]) GGZMOD_EVENT_SEAT: The old seat (GGZSeat*) GGZMOD_EVENT_SPECTATOR_SEAT: The old seat (GGZSpectatorSeat*) GGZMOD_EVENT_ERROR: An error string (char*)

---

Enumeration Type Documentation

enum GGZModEvent

Callback events.

Each of these is a possible GGZmod event. For each event, the table may register a handler with GGZmod to handle that event.

See also:

GGZModHandler

ggzmod_set_handler

Enumerator:

GGZMOD_EVENT_STATE	Module status changed This event occurs when the game's status changes. The old state (a GGZModState*) is passed as the event's data. See also: GGZModState
GGZMOD_EVENT_SERVER	A new server connection has been made This event occurs when a new connection to the game server has been made, either by the core client or by the game client itself. The fd is passed as the event's data. See also: ggzmod_connect
GGZMOD_EVENT_PLAYER	The player's seat status has changed. This event occurs when the player's seat status changes; i.e. he changes seats or starts/stops spectating. The event data is a int[2] pair consisting of the old {is_spectator, seat_num}.
GGZMOD_EVENT_SEAT	A seat change. This event occurs when a seat change occurs. The old seat (a GGZSeat*) is passed as the event's data. The seat information will be updated before the event is invoked.
GGZMOD_EVENT_SPECTATOR_SEAT	A spectator seat change. This event occurs when a spectator seat change occurs. The old spectator (a GGZSpectator*) is passed as the event's data. The spectator information will be updated before the event is invoked.
GGZMOD_EVENT_CHAT	A chat message event. This event occurs when we receive a chat. The chat may have originated in another game client or from the GGZ client; in either case it will be routed to us. The chat information (a GGZChat*) is passed as the event's data. Note that the chat may originate with a player or a spectator, and they may have changed seats or left the table by the time it gets to us.
GGZMOD_EVENT_STATS	A players' stats have been updated. See also: ggzmod_player_get_record ggzmod_player_get_rating ggzmod_player_get_ranking ggzmod_player_get_highscore
GGZMOD_EVENT_INFO	Player information has arrived. Information has been requested about one or more players and it has now arrived. The event data is a GGZPlayerInfo* structure or NULL if info about all players was requested.
GGZMOD_EVENT_ERROR	An error has occurred This event occurs when a GGZMod error has occurred. An error message (a char*) will be passed as the event's data. GGZMod may attempt to recover from the error, but it is not guaranteed that the GGZ connection will continue to work after an error has happened.

enum GGZModState

Table states.

Each table has a current "state" that is tracked by ggzmod. First the table is executed and begins running. Then it receives a launch event from GGZ and begins waiting for players. At some point a game will be started and played at the table, after which it may return to waiting. Eventually the table will probably halt and then the program will exit.

More specifically, the game is in the CREATED state when it is first executed. It moves to the CONNECTED state after GGZ first communicates with it, and to WAITING after the connection is established with the game server. After this, the game server may use ggzmod_set_state to change between WAITING, PLAYING, and DONE states. A WAITING game is considered waiting for players (or whatever), while a PLAYING game is actively being played (this information may be, but currently is not, propogated back to GGZ for display purposes). Once the state is changed to DONE, the table is considered dead and will exit shortly thereafter.

Each time the game state changes, a GGZMOD_EVENT_STATE event will be propogated to the game server.

Enumerator:

GGZMOD_STATE_CREATED	Initial state. The game starts out in this state. Once the state is changed it should never be changed back.
GGZMOD_STATE_CONNECTED	Connected state. After the GGZ client and game client get connected, the game changes into this state automatically. Once this happens messages may be sent between these two. Once the game leaves this state it should never be changed back.
GGZMOD_STATE_WAITING	Waiting state. After the game client and game server are connected, the client enters the waiting state. The game client may now call ggzmod_set_state to change between WAITING, PLAYING, and DONE states.
GGZMOD_STATE_PLAYING	Playing state. This state is only entered after the game client changes state to it via ggzmod_set_state. State may be changed back and forth between WAITING and PLAYING as many times as are wanted.
GGZMOD_STATE_DONE	Done state. Once the game client is done running, ggzmod_set_state should be called to set the state to done. At this point nothing "new" can happen. The state cannot be changed again after this. However the game client will not be terminated by the GGZ client; GGZ just waits for it to exit of its own volition.

enum GGZModType

The "type" of ggzmod.

The "flavor" of GGZmod object this is. Affects what operations are allowed.

Enumerator:

GGZMOD_GGZ	Used by the ggz client ("ggz").
GGZMOD_GAME	Used by the game client ("table").

---

Function Documentation

int ggzmod_connect

(

GGZMod *

ggzmod

)

Connect to ggz.

Call this function to make an initial GGZ core client <-> game client connection. Afterwards

Parameters:

ggzmod

The ggzmod object.

Returns:

0 on success, -1 on failure.

int ggzmod_disconnect

(

GGZMod *

ggzmod

)

Disconnect from ggz.

This terminates the link between the game client and the GGZ core client.

Parameters:

ggzmod

The ggzmod object.

Returns:

0 on success, -1 on failure.

int ggzmod_dispatch

(

GGZMod *

ggzmod

)

Check for and handle input.

This function handles input from the communications sockets:

• It will check for input, but will not block.
• It will monitor input from the GGZmod socket.
• It will monitor input from player sockets only if a handler is registered for the PLAYER_DATA event.
• It will call an event handler as necessary.

  Parameters:

  ggzmod

  The ggzmod object.

  Returns:

  -1 on error, the number of events handled (0-1) on success.

void ggzmod_free

(

GGZMod *

ggzmod

)

Destroy a finished ggzmod object.

After the connection is through, the object may be freed.

Parameters:

ggzmod

The GGZMod object.

int ggzmod_get_fd

(

GGZMod *

ggzmod

)

Get the file descriptor for the GGZMod socket.

Parameters:

ggzmod

The GGZMod object.

Returns:

GGZMod's main ggz <-> table socket FD.

void* ggzmod_get_gamedata

(

GGZMod *

ggzmod

)

Return gamedata pointer.

Each GGZMod object can be given a "gamedata" pointer that is returned by this function. This is useful for when a single process serves multiple GGZmod's.

Parameters:

ggzmod

The GGZMod object.

Returns:

A pointer to the gamedata block (or NULL if none).

See also:

ggzmod_set_gamedata

int ggzmod_get_num_seats

(

GGZMod *

ggzmod

)

Get the total number of seats at the table.

Returns:

The number of seats, or -1 on error.

Note:

If no connection is present, -1 will be returned.

While in GGZMOD_STATE_CREATED, we don't know the number of seats.

int ggzmod_get_num_spectator_seats

(

GGZMod *

ggzmod

)

Get the maximum number of spectators. This function returns the maximum number of spectator seats available. A game can use this to iterate over the spectator seats to look for spectators occupying them. Since spectators may come and go at any point and there is no limit on the number of spectators, you should consider this value to be dynamic and call this function again each time you're looking for spectators.

Returns:

The number of available spectator seats, or -1 on error.

const char* ggzmod_get_player	(	GGZMod *	ggzmod,
		int *	is_spectator,
		int *	seat_num
	)

Get data about this player.

Call this function to find out where at the table this player is sitting.

Parameters:

	ggzmod	The GGZMod object.
	is_spectator	Will be set to TRUE iff player is spectating.
	seat_num	Will be set to the number of our (spectator) seat.

Returns:

The name of the player (or NULL on error).

GGZSeat ggzmod_get_seat	(	GGZMod *	ggzmod,
		int	seat
	)

Get all data for the specified seat.

Parameters:

	ggzmod	The GGZMod object.
	seat	The seat number (0..(number of seats - 1)).

Returns:

A valid GGZSeat structure, if seat is a valid seat.

int ggzmod_get_server_fd

(

GGZMod *

ggzmod

)

Get the fd of the game server connection.

Parameters:

ggzmod

The GGZMod object.

Returns:

The server connection fd

GGZSpectatorSeat ggzmod_get_spectator_seat	(	GGZMod *	ggzmod,
		int	seat
	)

Get a spectator's data.

Parameters:

	ggzmod	The GGZMod object.
	seat	The number, between 0 and (number of spectators - 1).

Returns:

A valid GGZSpectator structure, if given a valid seat.

GGZModState ggzmod_get_state

(

GGZMod *

ggzmod

)

Get the current state of the table.

Parameters:

ggzmod

The GGZMod object.

Returns:

The state of the table.

GGZModType ggzmod_get_type

(

GGZMod *

ggzmod

)

Get the type of the ggzmod object.

Parameters:

ggzmod

The GGZMod object.

Returns:

The type of the GGZMod object (GGZ or GAME).

int ggzmod_is_ggz_mode

(

void

)

Is the program running in GGZ mode?

Call this function to see if the program was actually launched by GGZ. This can be used to give an error message if the executable is run outside of the GGZ environment, or for games that will run both inside and outside of GGZ.

Returns:

A boolean value indicating whether the program is running in GGZ.

Note:

Should only be called by game clients, not by GGZ itself.

GGZMod* ggzmod_new

(

GGZModType

type

)

Create a new ggzmod object.

Before connecting through ggzmod, a new ggzmod object is needed.

Parameters:

type

The type of ggzmod. Should be GGZMOD_GAME for game servers.

See also:

GGZModType

int ggzmod_player_get_highscore	(	GGZMod *	ggzmod,
		GGZSeat *	seat,
		int *	highscore
	)

Get the player's highscore.

Returns:

TRUE if there is a highscore; FALSE if not or on error.

GGZPlayerInfo* ggzmod_player_get_info	(	GGZMod *	ggzmod,
		int	seat
	)

Get the extended information for the specified seat.

Parameters:

	ggzmod	The GGZMod object.
	seat	The seat number (0..(number of seats - 1)).

Returns:

A valid GGZPlayerInfo structure, if seat is valid and has info.

int ggzmod_player_get_ranking	(	GGZMod *	ggzmod,
		GGZSeat *	seat,
		int *	ranking
	)

Get the player's ranking.

Returns:

TRUE if there is a ranking; FALSE if not or on error.

int ggzmod_player_get_rating	(	GGZMod *	ggzmod,
		GGZSeat *	seat,
		int *	rating
	)

Get the player's rating.

Returns:

TRUE if there is a rating; FALSE if not or on error.

int ggzmod_player_get_record	(	GGZMod *	ggzmod,
		GGZSeat *	seat,
		int *	wins,
		int *	losses,
		int *	ties,
		int *	forfeits
	)

Get the player's win-loss record.

Returns:

TRUE if there is a record; FALSE if not or on error.

int ggzmod_player_request_info	(	GGZMod *	ggzmod,
		int	seat_num
	)

Request extended player information for one or more players.

Depending on the seat parameter (-1 or valid number), this function asynchronously requests information about player(s), which will arrive with a GGZMOD_EVENT_INFO event.

Parameters:

	ggzmod	The ggzmod object.
	seat_num	The seat number to request info for, or -1 to select all.

Returns:

TRUE if seat is -1 or valid number, FALSE for non-player seats.

void ggzmod_request_boot	(	GGZMod *	ggzmod,
		const char *	name
	)

Boot a player. Only the game host may do this.

Parameters:

	ggzmod	The ggzmod object.
	name	The name of the player to boot.

void ggzmod_request_bot	(	GGZMod *	ggzmod,
		int	seat_num
	)

Change the requested seat from an open seat to a bot.

Parameters:

	ggzmod	The ggzmod object.
	seat_num	The number of the seat to toggle.

void ggzmod_request_chat	(	GGZMod *	ggzmod,
		const char *	chat_msg
	)

Chat! This initiates a table chat.

Parameters:

	ggzmod	The ggzmod object.
	chat_msg	The chat message.

Note:

The chat message should be in UTF-8.

void ggzmod_request_open	(	GGZMod *	ggzmod,
		int	seat_num
	)

Change the requested seat from a bot to an open seat.

Parameters:

	ggzmod	The ggzmod object.
	seat_num	The number of the seat to toggle.

void ggzmod_request_sit	(	GGZMod *	ggzmod,
		int	seat_num
	)

Sit down (move from a spectator seat into a player seat).

Parameters:

	ggzmod	The ggzmod object.
	seat_num	The seat to sit in.

void ggzmod_request_stand

(

GGZMod *

ggzmod

)

Stand up (move from your seat into a spectator seat).

Parameters:

ggzmod

The ggzmod object.

void ggzmod_set_gamedata	(	GGZMod *	ggzmod,
		void *	data
	)

Set gamedata pointer.

Parameters:

	ggzmod	The GGZMod object.
	data	The gamedata block (or NULL for none).

See also:

ggzmod_get_gamedata

void ggzmod_set_handler	(	GGZMod *	ggzmod,
		GGZModEvent	e,
		GGZModHandler	func
	)

Set a handler for the given event.

As described above, GGZmod uses an event-driven structure. Each time an event is called, the event handler (there can be only one) for that event will be called. This function registers such an event handler.

Parameters:

	ggzmod	The GGZmod object.
	e	The GGZmod event.
	func	The handler function being registered.

See also:

ggzmod_get_gamedata

int ggzmod_set_state	(	GGZMod *	ggzmod,
		GGZModState	state
	)

Change the table's state.

This function should be called to change the state of a table. A game can use this function to change state between WAITING and PLAYING, or to set it to DONE.

Parameters:

	ggzmod	The ggzmod object.
	state	The new state.

Returns:

0 on success, -1 on failure/error.

int ggzmod_spectator_get_highscore	(	GGZMod *	ggzmod,
		GGZSpectatorSeat *	seat,
		int *	highscore
	)

Get the spectator's highscore.

Returns:

TRUE if there is a highscore; FALSE if not or on error.

int ggzmod_spectator_get_ranking	(	GGZMod *	ggzmod,
		GGZSpectatorSeat *	seat,
		int *	ranking
	)

Get the spectator's ranking.

Returns:

TRUE if there is a ranking; FALSE if not or on error.

int ggzmod_spectator_get_rating	(	GGZMod *	ggzmod,
		GGZSpectatorSeat *	seat,
		int *	rating
	)

Get the spectator's rating.

Returns:

TRUE if there is a rating; FALSE if not or on error.

int ggzmod_spectator_get_record	(	GGZMod *	ggzmod,
		GGZSpectatorSeat *	seat,
		int *	wins,
		int *	losses,
		int *	ties,
		int *	forfeits
	)

Get the spectator's win-loss record.

Returns:

TRUE if there is a record; FALSE if not or on error.

---