#include <ggz.h>
#include <ggz_common.h>
#define GGZMOD_VERSION_MAJOR 0
#define GGZMOD_VERSION_MINOR 0
#define GGZMOD_VERSION_MICRO 11
#define GGZMOD_VERSION_IFACE '3:1:1'
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.
enum GGZModState { GGZMOD_STATE_CREATED, GGZMOD_STATE_CONNECTED, GGZMOD_STATE_WAITING, GGZMOD_STATE_PLAYING, GGZMOD_STATE_DONE }
Table states.
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_ERROR }
Callback events.
enum GGZModType { GGZMOD_GGZ, GGZMOD_GAME }
The 'type' of ggzmod.
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 opean 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.
Common functions for interfacing a game server and GGZ.
This file contains all libggzmod functions used by game servers to interface with GGZ (and vice versa). 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.
That this does not apply to the client sockets: ggzmod provides one file desriptor for communicating (TCP) to each client. If data is ready to be read by one of these file descriptors ggzmod may invoke the appropriate handler (see below), but will never actually read any data.
For more information, see the documentation at http://ggz.sf.net/.
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.
Event handler prototype.
A function of this type will be called to handle a ggzmod event.
Parameters:
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:
ggzmod_set_handler
Enumeration values:
See also:
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}.
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.
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.
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.
See also:
ggzmod_player_get_rating
ggzmod_player_get_ranking
ggzmod_player_get_highscore
Parameters:
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 (ggzmod_loop will stop looping, etc.) (see the kill_on_exit game option).
Each time the game state changes, a GGZMOD_EVENT_STATE event will be propogated to the game server.
Enumeration values:
The 'type' of ggzmod.
The 'flavor' of GGZmod object this is. Affects what operations are allowed.
Enumeration values:
Connect to ggz.
Call this function to make an initial GGZ <-> game connection.
Parameters:
Returns:
Disconnect from ggz.
Parameters:
Returns:
Check for and handle input.
This function handles input from the communications sockets:
Parameters:
Returns:
Destroy a finished ggzmod object.
After the connection is through, the object may be freed.
Parameters:
Get the file descriptor for the GGZMod socket.
Parameters:
Returns:
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:
Returns:
See also:
Get the total number of seats at the table.
Returns:
Note:
While in GGZMOD_STATE_CREATED, we don't know the number of seats.
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:
Get data about this player.
Call this function to find out where at the table this player is sitting.
Parameters:
Returns:
Get all data for the specified seat.
Parameters:
Returns:
Get the fd of the game server connection.
Parameters:
Returns:
Get a spectator's data.
Parameters:
Returns:
Get the current state of the table.
Parameters:
Returns:
Get the type of the ggzmod object.
Parameters:
Returns:
Create a new ggzmod object.
Before connecting through ggzmod, a new ggzmod object is needed.
Parameters:
See also:
Get the player's highscore.
Returns:
Get the player's ranking.
Returns:
Get the player's rating.
Returns:
Get the player's win-loss record.
Returns:
Boot a player. Only the game host may do this.
Parameters:
Change the requested seat from an opean seat to a bot.
Parameters:
Chat! This initiates a table chat.
Parameters:
Note:
Change the requested seat from a bot to an open seat.
Parameters:
Sit down (move from a spectator seat into a player seat).
Parameters:
Stand up (move from your seat into a spectator seat).
Parameters:
Set gamedata pointer.
Parameters:
See also:
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:
See also:
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:
Returns:
Get the spectator's highscore.
Returns:
Get the spectator's ranking.
Returns:
Get the spectator's rating.
Returns:
Get the spectator's win-loss record.
Returns:
Generated automatically by Doxygen for GGZMod from the source code.