Man Linux: Main Page and Category List

NAME

       ggzmod.h - Common functions for interfacing a game server and GGZ.

SYNOPSIS

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

   Defines
       #define GGZMOD_VERSION_MAJOR   0
       #define GGZMOD_VERSION_MINOR   0
       #define GGZMOD_VERSION_MICRO   11
       #define GGZMOD_VERSION_IFACE   ’3:1: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.
       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.

   Functions
       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 youre looking
           for spectators.
       GGZSpectatorSeat ggzmod_get_spectator_seat (GGZMod *ggzmod, int seat)
           Get a spectators 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 tables 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 players win-loss record.
       int ggzmod_player_get_rating (GGZMod *ggzmod, GGZSeat *seat, int
           *rating)
           Get the players rating.
       int ggzmod_player_get_ranking (GGZMod *ggzmod, GGZSeat *seat, int
           *ranking)
           Get the players ranking.
       int ggzmod_player_get_highscore (GGZMod *ggzmod, GGZSeat *seat, int
           *highscore)
           Get the players highscore.
       int ggzmod_spectator_get_record (GGZMod *ggzmod, GGZSpectatorSeat
           *seat, int *wins, int *losses, int *ties, int *forfeits)
           Get the spectators win-loss record.
       int ggzmod_spectator_get_rating (GGZMod *ggzmod, GGZSpectatorSeat
           *seat, int *rating)
           Get the spectators rating.
       int ggzmod_spectator_get_ranking (GGZMod *ggzmod, GGZSpectatorSeat
           *seat, int *ranking)
           Get the spectators ranking.
       int ggzmod_spectator_get_highscore (GGZMod *ggzmod, GGZSpectatorSeat
           *seat, int *highscore)
           Get the spectators highscore.

Detailed Description

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

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

       Enumeration values:

       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. The fd is
              passed as the event’s data.

       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 player’s stats have been updated.

       See also:
           ggzmod_player_get_record

           ggzmod_player_get_rating

           ggzmod_player_get_ranking

           ggzmod_player_get_highscore

       Parameters:
           data The name of the player whose stats have changed.

       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
       (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:

       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.

       Enumeration values:

       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 <-> game connection.

       · When called by the game server, this function makes the physical
         connection to ggz.

       · When called by ggz, it will launch a table and connect to it.

       Parameters:
           ggzmod The ggzmod object.

       Returns:
           0 on success, -1 on failure.

   int ggzmod_disconnect (GGZMod * ggzmod)
       Disconnect from ggz.

       · When called by the game server, this function stops the connection to
         GGZ. It should only be called when the table is ready to exit.

         · When called by the GGZ server, this function will kill and clean up
           after the table.

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

   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.

   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.

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

Author

       Generated automatically by Doxygen for GGZMod from the source code.