--- name: "ggzdmod.h" section: "3" platform: "linux" package: "libggzdmod-dev" version: "0.0.14.1-1.4" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/ggzdmod.h" --- # ggzdmod.h(3) Common functions for interfacing a game server and GGZ. ## NAME ggzdmod.h - Common functions for interfacing a game server and GGZ. ## SYNOPSIS `#include `\ `#include `\ ### Defines \#define **GGZDMOD\_VERSION\_MAJOR** 0\ \#define **GGZDMOD\_VERSION\_MINOR** 0\ \#define **GGZDMOD\_VERSION\_MICRO** 11\ \#define **GGZDMOD\_VERSION\_IFACE** '4:0:0'\ ### Typedefs typedef **GGZdMod** **GGZdMod**\ *A GGZdmod object, used for tracking a ggzd\<-\>table connection.* typedef void(\* **GGZdModHandler** )(**GGZdMod** \*mod, **GGZdModEvent** event, const void \*data)\ *Event handler prototype.* ### Enumerations enum **GGZdModState** { **GGZDMOD\_STATE\_CREATED**, **GGZDMOD\_STATE\_WAITING**, **GGZDMOD\_STATE\_PLAYING**, **GGZDMOD\_STATE\_DONE** }\ *Table states.* enum **GGZdModEvent** { **GGZDMOD\_EVENT\_STATE**, **GGZDMOD\_EVENT\_JOIN**, **GGZDMOD\_EVENT\_LEAVE**, **GGZDMOD\_EVENT\_SEAT**, **GGZDMOD\_EVENT\_SPECTATOR\_JOIN**, **GGZDMOD\_EVENT\_SPECTATOR\_LEAVE**, **GGZDMOD\_EVENT\_SPECTATOR\_SEAT**, **GGZDMOD\_EVENT\_LOG**, **GGZDMOD\_EVENT\_PLAYER\_DATA**, **GGZDMOD\_EVENT\_SPECTATOR\_DATA**, **GGZDMOD\_EVENT\_GAMEREPORT**, **GGZDMOD\_EVENT\_SAVEGAMEREPORT**, **GGZDMOD\_EVENT\_REQ\_NUM\_SEATS**, **GGZDMOD\_EVENT\_REQ\_BOOT**, **GGZDMOD\_EVENT\_REQ\_BOT**, **GGZDMOD\_EVENT\_REQ\_OPEN**, **GGZDMOD\_EVENT\_ERROR** }\ *Callback events.* enum **GGZdModType** { **GGZDMOD\_GGZ**, **GGZDMOD\_GAME** }\ *The 'type' of ggzdmod.* enum **GGZGameResult** { **GGZ\_GAME\_WIN**, **GGZ\_GAME\_LOSS**, **GGZ\_GAME\_TIE**, **GGZ\_GAME\_FORFEIT**, **GGZ\_GAME\_NONE** }\ ### Functions **GGZdMod** \* **ggzdmod\_new** (**GGZdModType** type)\ *Create a new ggzdmod object.* void **ggzdmod\_free** (**GGZdMod** \*ggzdmod)\ *Destroy a finished ggzdmod object.* int **ggzdmod\_get\_fd** (**GGZdMod** \*ggzdmod)\ *Get the file descriptor for the GGZdMod socket.* **GGZdModType** **ggzdmod\_get\_type** (**GGZdMod** \*ggzdmod)\ *Get the type of the ggzdmod object.* **GGZdModState** **ggzdmod\_get\_state** (**GGZdMod** \*ggzdmod)\ *Get the current state of the table.* int **ggzdmod\_get\_num\_seats** (**GGZdMod** \*ggzdmod)\ *Get the total number of seats at the table.* **GGZSeat** **ggzdmod\_get\_seat** (**GGZdMod** \*ggzdmod, int seat)\ *Get all data for the specified seat.* void \* **ggzdmod\_get\_gamedata** (**GGZdMod** \*ggzdmod)\ *Return gamedata pointer.* void **ggzdmod\_set\_gamedata** (**GGZdMod** \*ggzdmod, void \*data)\ *Set gamedata pointer.* int **ggzdmod\_get\_max\_num\_spectators** (**GGZdMod** \*ggzdmod)\ *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 theoretical 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.* **GGZSpectator** **ggzdmod\_get\_spectator** (**GGZdMod** \*ggzdmod, int spectator)\ *Get a spectator's data.* int **ggzdmod\_set\_handler** (**GGZdMod** \*ggzdmod, **GGZdModEvent** e, **GGZdModHandler** func)\ *Set a handler for the given event.* int **ggzdmod\_count\_seats** (**GGZdMod** \*ggzdmod, GGZSeatType seat\_type)\ *Count seats of the given type.* int **ggzdmod\_count\_spectators** (**GGZdMod** \*ggzdmod)\ *Count current number of spectators.* int **ggzdmod\_dispatch** (**GGZdMod** \*ggzdmod)\ *Check for and handle input.* int **ggzdmod\_loop** (**GGZdMod** \*ggzdmod)\ *Loop while handling input.* int **ggzdmod\_set\_state** (**GGZdMod** \*ggzdmod, **GGZdModState** state)\ *Change the table's state.* int **ggzdmod\_connect** (**GGZdMod** \*ggzdmod)\ *Connect to ggz.* int **ggzdmod\_disconnect** (**GGZdMod** \*ggzdmod)\ *Disconnect from ggz.* int **ggzdmod\_log** (**GGZdMod** \*ggzdmod, const char \*fmt,...) ggz\_\_attribute((format(printf\ *Log data.* int void **ggzdmod\_check** (**GGZdMod** \*ggzdmod)\ *Log all information about the ggzdmod.* void **ggzdmod\_report\_game** (**GGZdMod** \*ggzdmod, int \*teams, **GGZGameResult** \*results, int \*scores)\ *Report the results of a game to GGZ.* void **ggzdmod\_report\_savegame** (**GGZdMod** \*ggzdmod, const char \*savegame)\ *Report the savegame to GGZ.* void **ggzdmod\_request\_num\_seats** (**GGZdMod** \*ggzdmod, int num\_seats)\ *Tell GGZ to change the number of seats at this table.* void **ggzdmod\_request\_boot** (**GGZdMod** \*ggzdmod, const char \*name)\ *Tell GGZ to boot the given player from this table.* void **ggzdmod\_request\_bot** (**GGZdMod** \*ggzdmod, int seat\_num)\ *Tell GGZ to change the given seat from OPEN to BOT.* void **ggzdmod\_request\_open** (**GGZdMod** \*ggzdmod, int seat\_num)\ *Tell GGZ to change the given seat from BOT/RESERVED to OPEN.* ## Detailed Description Common functions for interfacing a game server and GGZ. This file contains all libggzdmod functions used by game servers to interface with GGZ (and vice versa). Just include **ggzdmod.h** and make sure your program is linked with libggzdmod. Then use the functions below as appropriate. GGZdmod 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: ggzdmod provides one file desriptor for communicating (TCP) to each client. If data is ready to be read by one of these file descriptors ggzdmod may invoke the appropriate handler (see below), but will never actually read any data. Here is a fairly complete example. In this game we register a handler for each of the possible callbacks. This particular game is played only when all seats are full; when any seats are empty it must wait (much like a card or board game). ``` // Game-defined handler functions for GGZ events; see below. void handle_state_change(GGZdMod* ggz, GGZdModEvent event, const void *data); void handle_player_seat(GGZdMod* ggz, GGZdModEvent event, const void *data); void handle_player_data(GGZdMod* ggz, GGZdModEvent event, const void *data); // Other game-defined functions (not ggz-related). void game_init(GGZdMod *ggz); // initialize a game void game_launch(void); // handle a game 'launch' void game_end(void); // called before the table shuts down void resume_playing(void); // we have enough players to play void stop_playing(void); // not enough players to play int main() { GGZdMod *ggz = ggzdmod_new(GGZ_GAME); // First we register functions to handle some events. ggzdmod_set_handler(ggz, GGZDMOD_EVENT_STATE, &handle_state_change); ggzdmod_set_handler(ggz, GGZDMOD_EVENT_JOIN, &handle_player_seat); ggzdmod_set_handler(ggz, GGZDMOD_EVENT_LEAVE, &handle_player_seat); ggzdmod_set_handler(ggz, GGZDMOD_EVENT_SEAT, &handle_player_seat); ggzdmod_set_handler(ggz, GGZDMOD_EVENT_PLAYER_DATA, &handle_player_data); // Do any other game initializations. You'll probably want to // track 'ggz' globally. game_init(mod); // Then we must connect to GGZ if (ggzdmod_connect(ggz) < 0) exit(-1); (void) ggzdmod_log(ggz, 'Starting game.'); // ggzdmod_loop does most of the work, dispatching handlers // above as necessary. (void) ggzdmod_loop(ggz); // At the end, we disconnect and destroy the ggzdmod object. (void) ggzdmod_log(ggz, 'Ending game.'); (void) ggzdmod_disconnect(ggz); ggzdmod_free(ggz); } void handle_state_change(GGZdMod* ggz, GGZdModEvent event, const void *data) { const GGZdModState *old_state = data; GGZdModState new_state = ggzdmod_get_state(ggz); if (*old_state == GGZDMOD_STATE_CREATED) // ggzdmod data isn't initialized until it connects with GGZ // during the game launch, so some initializations should wait // until here. game_launch(); switch (new_state) { case GGZDMOD_STATE_WAITING: // At this point we've entered the 'waiting' state where we // aren't actually playing. This is generally triggered by // the game calling ggzdmod_set_state, which happens when // a player leaves (down below). It may also be triggered // by GGZ automatically. stop_playing(); break; case GGZDMOD_STATE_PLAYING: // At this point we've entered the 'playing' state, so we // should resume play. This is generally triggered by // the game calling ggzdmod_set_state, which happens when // all seats are full (down below). It may also be // triggered by GGZ automatically. resume_playing(); break; case GGZDMOD_STATE_DONE: // at this point ggzdmod_loop will stop looping, so we'd // better close up shop fast. This will only happen // automatically if all players leave, but we can force it // using ggzdmod_set_state. game_end(); break; } } void handle_player_seat(GGZdMod* ggz, GGZdModEvent event, const void *data) { const GGZSeat *old_seat = data; GGZSeat new_seat = ggzdmod_get_seat(ggz, old_seat->num); if (new_seat.type == GGZ_SEAT_PLAYER && old_seat->type != GGZ_SEAT_PLAYER) { // join event ... do player initializations ... if (ggzdmod_count_seats(ggz, GGZ_SEAT_OPEN) == 0) { // this particular game will only play when all seats are full. // calling this function triggers the STATE event, so we'll end // up executing resume_playing() above. ggzdmod_set_state(ggz, GGZDMOD_STATE_PLAYING); } } else if (new_seat.type != GGZ_SEAT_PLAYER && old_seat->type == GGZ_SEAT_PLAYER) { // leave event ... do de-initialization ... if (ggzdmod_count_seats(ggz, GGZ_SEAT_PLAYER) == 0) // the game will exit when all human players are gone ggzdmod_set_state(ggz, GGZDMOD_STATE_DONE); else // this particular game will only play when all seats are full. // calling this function triggers the STATE event, so we'll end // up executing stop_playing() above. ggzdmod_set_state(ggz, GGZDMOD_STATE_WAITING); } } void handle_player_data(GGZdMod* ggz, GGZdModEvent event, const void *data) { const int *player = data; int socket_fd = ggzdmod_get_seat(ggz, *player).fd; // ... read a packet from the socket ... } ``` For more information, see the documentation at http://ggz.sf.net/. ## Typedef Documentation ### typedef struct GGZdMod GGZdMod A GGZdmod object, used for tracking a ggzd\<-\>table connection. A game server should track a pointer to a GGZdMod object; it contains all the state information for communicating with GGZ. The GGZ server will track one such object for every game table that is running. ### typedef void(\* GGZdModHandler)(GGZdMod \*mod, GGZdModEvent event, const void \*data) Event handler prototype. A function of this type will be called to handle a ggzdmod event. **Parameters:** *mod* The ggzdmod state object. \ *event* The event that has occured. \ *data* Pointer to additional data for the event. The additional data will be of the following form: - • GGZDMOD\_EVENT\_STATE: The old state (GGZdModState\*) - • GGZDMOD\_EVENT\_JOIN: The old seat (GGZSeat\*) - • GGZDMOD\_EVENT\_LEAVE: The old seat (GGZSeat\*) - • GGZDMOD\_EVENT\_SEAT: The old seat (GGZSeat\*) - • GGZDMOD\_EVENT\_SPECTATOR\_JOIN: The old spectator's data (GGZSpectator\*) - • GGZDMOD\_EVENT\_SPECTATOR\_LEAVE: The old spectator's data (GGZSpectator\*) - • GGZDMOD\_EVENT\_LOG: The message string (char\*) - • GGZDMOD\_EVENT\_PLAYER\_DATA: The player number (int\*) - • GGZDMOD\_EVENT\_SPECTATOR\_DATA: The spectator number (int\*) - • GGZDMOD\_EVENT\_ERROR: An error string (char\*) ## Enumeration Type Documentation ### enum GGZdModEvent Callback events. Each of these is a possible GGZdmod event. For each event, the table may register a handler with GGZdmod to handle that event. **See also:** **GGZdModHandler** **ggzdmod\_set\_handler** **Enumeration values:** - *GGZDMOD\_EVENT\_STATE* *Module status changed This event occurs when the game's status changes. The old state (a GGZdModState\*) is passed as the event's data.* **See also:** **GGZdModState** - *GGZDMOD\_EVENT\_JOIN* *Player joined This event occurs when a player joins the table. The old seat (a GGZSeat\*) is passed as the event's data. The seat information will be updated before the event is invoked.* **Note:** *This event is deprecated.* **See also:** **GGZDMOD\_EVENT\_SEAT***.* - *GGZDMOD\_EVENT\_LEAVE* *Player left This event occurs when a player leaves the table. The old seat (a GGZSeat\*) is passed as the event's data. The seat information will be updated before the event is invoked.* **Note:** *This event is deprecated.* **See also:** **GGZDMOD\_EVENT\_SEAT***.* - *GGZDMOD\_EVENT\_SEAT* *General seat change This event occurs when a seat change other than a player leave/join happens. 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 will replace the JOIN and LEAVE events. Games are advised to register the same handler for all three and to check the seat event by comparing the new and old seats. Possible operations include open\|reserved-\>player, player-\>open, open-\>bot, bot-\>open, reserved-\>open, open-\>reserved, and bot-\>bot. Name changes are allowed but there is no player-\>player (i.e., player swap) seat event.* - *GGZDMOD\_EVENT\_SPECTATOR\_JOIN* *A spectator joins the game. The data of the old spectator (GGZSpectator\*) is passed as the data for the event. It can be assumed that the spectator seat was previously empty, so the name and socket given will be invalid (NULL/-1).* - *GGZDMOD\_EVENT\_SPECTATOR\_LEAVE* *A spectator left the game The old spectator data can be obtained via the (GGZSpectator\*) which is passed as the event data.* - *GGZDMOD\_EVENT\_SPECTATOR\_SEAT* *A spectator seat changed. The old spectator data can be obtained via the (GGZSpectator\*) which is passed as the event data. This may someday replace both SPECTATOR\_JOIN and SPECTATOR\_LEAVE.* - *GGZDMOD\_EVENT\_LOG* *Module log request This event occurs when a log request happens. This will only be used by the GGZ server; the game server should use ggzdmod\_log to generate the log.* - *GGZDMOD\_EVENT\_PLAYER\_DATA* *Data available from player This event occurs when there is data ready to be read from one of the player sockets. The player number (an int\*) is passed as the event's data.* - *GGZDMOD\_EVENT\_SPECTATOR\_DATA* *Data available from spectator For games which support spectators, this indicates that one of them sent some data to the game server.* - *GGZDMOD\_EVENT\_GAMEREPORT* *For GGZ only. Reports the results of a game.* - *GGZDMOD\_EVENT\_SAVEGAMEREPORT* *For GGZ only. Reports a savegame.* - *GGZDMOD\_EVENT\_ERROR* *An error has occurred This event occurs when a GGZdMod error has occurred. An error message (a char\*) will be passed as the event's data. GGZdMod 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 GGZdModState *Table states.* *Each table has a current 'state' that is tracked by ggzdmod. First the table is executed and begins running. Then it receives a launch event from GGZD 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 WAITING state after GGZ first communicates with it. After this, the game server may use ggzdmod\_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 (ggzdmod\_loop will stop looping, etc.) (see the kill\_on\_exit game option).* *Each time the game state changes, a GGZDMOD\_EVENT\_STATE event will be propogated to the game server.* **Enumeration values:** - *GGZDMOD\_STATE\_CREATED* *Pre-launch; waiting for ggzdmod* - *GGZDMOD\_STATE\_WAITING* *Ready and waiting to play.* - *GGZDMOD\_STATE\_PLAYING* *Currently playing a game.* - *GGZDMOD\_STATE\_DONE* *Table halted, prepping to exit.* ### enum GGZdModType *The 'type' of ggzdmod.* *The 'flavor' of GGZdmod object this is. Affects what operations are allowed.* **Enumeration values:** - *GGZDMOD\_GGZ* *Used by the ggz server ('ggzd').* - *GGZDMOD\_GAME* *Used by the game server ('table').* ### enum GGZGameResult **Enumeration values:** - *GGZ\_GAME\_FORFEIT* *A forfeit is (for instance) an abandoned game. The player will not only be credited with the forfeit but their rating/ranking may drop dramatically.* - *GGZ\_GAME\_NONE* *If the player didn't take part in the game, use this label. For instance if one player abandons the game they might get a forfeit while nobody else is affected.* ## Function Documentation ### int void ggzdmod\_check (GGZdMod \* ggzdmod) *Log all information about the ggzdmod.* *This is a debugging function that will log all available information about the GGZdMod object. It uses ggzdmod\_log for logging.* **Parameters:** *ggzdmod The GGZdMod object.* **Returns:** *void; errors in ggzdmod\_log are ignored.* ### int ggzdmod\_connect (GGZdMod \* ggzdmod) *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 ggzd, it will launch a table and connect to it. Note - if the game fails to exec, this function may not catch it.* **Parameters:** *ggzdmod The ggzdmod object.* **Returns:** *0 on success, -1 on failure.* ### int ggzdmod\_count\_seats (GGZdMod \* ggzdmod, GGZSeatType seat\_type) *Count seats of the given type.* *This is a convenience function that counts how many seats there are that have the given type. For instance, giving seat\_type==GGZ\_SEAT\_OPEN will count the number of open seats.* **Parameters:** *ggzdmod The ggzdmod object.* \ *seat\_type The type of seat to be counted.* **Returns:** *The number of seats that match seat\_type.* **Note:** *This could go into a wrapper library instead.* ### int ggzdmod\_count\_spectators (GGZdMod \* ggzdmod) *Count current number of spectators.* *This function returns the number of spectators watching the game. Note that the spectator numbers may not match up: if there are two spectators they could be numbered 0 and 4. If you're trying to iterate through the existing spectators, you probably want* **ggzdmod\_get\_max\_num\_spectators()** *instead.* **Parameters:** *ggzdmod The ggzdmod object* **Returns:** *The number of spectators watching the game (0 on error)* ### int ggzdmod\_disconnect (GGZdMod \* ggzdmod) *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:** *ggzdmod The ggzdmod object.* **Returns:** *0 on success, -1 on failure.* ### int ggzdmod\_dispatch (GGZdMod \* ggzdmod) *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 GGZdmod 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:** *ggzdmod The ggzdmod object.* **Returns:** *-1 on error, the number of events handled (0 or more) on success.* ### void ggzdmod\_free (GGZdMod \* ggzdmod) *Destroy a finished ggzdmod object.* *After the connection is through, the object may be freed.* **Parameters:** *ggzdmod The GGZdMod object.* ### int ggzdmod\_get\_fd (GGZdMod \* ggzdmod) *Get the file descriptor for the GGZdMod socket.* **Parameters:** *ggzdmod The GGZdMod object.* **Returns:** *GGZdMod's main ggzd \<-\> table socket FD.* **Note:** *Don't use this; use ggzdmod\_loop and friends instead.* ### void\* ggzdmod\_get\_gamedata (GGZdMod \* ggzdmod) *Return gamedata pointer.* *Each GGZdMod object can be given a 'gamedata' pointer that is returned by this function. This is useful for when a single process serves multiple GGZdmod's.* **Parameters:** *ggzdmod The GGZdMod object.* **Returns:** *A pointer to the gamedata block (or NULL if none).* **See also:** **ggzdmod\_set\_gamedata** ### int ggzdmod\_get\_max\_num\_spectators (GGZdMod \* ggzdmod) *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 theoretical 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.* **Note:** *If no connection is present, -1 will be returned.* ### int ggzdmod\_get\_num\_seats (GGZdMod \* ggzdmod) *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 GGZDMOD\_STATE\_CREATED, we don't know the number of seats.* ### GGZSeat ggzdmod\_get\_seat (GGZdMod \* ggzdmod, int seat) *Get all data for the specified seat.* **Parameters:** *ggzdmod The GGZdMod object.* \ *seat The seat number (0..(number of seats - 1)).* **Returns:** *A valid* **GGZSeat** *structure, if seat is a valid seat.* ### GGZSpectator ggzdmod\_get\_spectator (GGZdMod \* ggzdmod, int spectator) *Get a spectator's data.* **Parameters:** *ggzdmod The GGZdMod object.* \ *spectator The number, between 0 and (number of spectators - 1).* **Returns:** *A valid* **GGZSpectator** *structure, if arguments are valid.* ### GGZdModState ggzdmod\_get\_state (GGZdMod \* ggzdmod) *Get the current state of the table.* **Parameters:** *ggzdmod The GGZdMod object.* **Returns:** *The state of the table.* ### GGZdModType ggzdmod\_get\_type (GGZdMod \* ggzdmod) *Get the type of the ggzdmod object.* **Parameters:** *ggzdmod The GGZdMod object.* **Returns:** *The type of the GGZdMod object (GGZ or GAME).* ### int ggzdmod\_log (GGZdMod \* ggzdmod, const char \* fmt, ...) *Log data.* *This function sends the specified string (printf-style) to the GGZ server to be logged.* **Parameters:** *ggzdmod The GGZdmod object.* \ *fmt A printf-style format string.* **Returns:** *0 on success, -1 on failure.* ### int ggzdmod\_loop (GGZdMod \* ggzdmod) *Loop while handling input.* *This function repeatedly handles input from all sockets. It will only stop once the game state has been changed to DONE (or if there has been an error).* **Parameters:** *ggzdmod The ggzdmod object.* **Returns:** *0 on success, -1 on error.* **See also:** **ggzdmod\_dispatch** **ggzdmod\_set\_state** ### GGZdMod\* ggzdmod\_new (GGZdModType type) *Create a new ggzdmod object.* *Before connecting through ggzdmod, a new ggzdmod object is needed.* **Parameters:** *type The type of ggzdmod. Should be GGZDMOD\_GAME for game servers.* **See also:** **GGZdModType** ### void ggzdmod\_report\_game (GGZdMod \* ggzdmod, int \* teams, GGZGameResult \* results, int \* scores) *Report the results of a game to GGZ.* *After a game has completed, the game server should call this function to report the results to GGZ. GGZ can then use the information to track player statistics - including an ELO-style rating, win-loss records, etc.* **Parameters:** *ggzdmod The ggzdmod object.* \ *teams An array listing a team number for each player, or NULL.* \ *results An array listing the result of the game for each player.* \ *scores The scores for all players (may be NULL)* ### void ggzdmod\_report\_savegame (GGZdMod \* ggzdmod, const char \* savegame) *Report the savegame to GGZ.* *If a game saves the game data to disk, the directory name, file name or any other associated token can be reported to GGZ. In the case of a continuous game log, the reporting should happen at the beginning as to allow the continuation of the saved game.* **Parameters:** *ggzdmod The ggzdmod object.* \ *savegame Name of the savegame file within the game's directory.* ### void ggzdmod\_request\_num\_seats (GGZdMod \* ggzdmod, int num\_seats) *Tell GGZ to change the number of seats at this table.* **Note:** *This functionality is incomplete, and should not yet be used.* ### void ggzdmod\_set\_gamedata (GGZdMod \* ggzdmod, void \* data) *Set gamedata pointer.* **Parameters:** *ggzdmod The GGZdMod object.* \ *data The gamedata block (or NULL for none).* **See also:** **ggzdmod\_get\_gamedata** ### int ggzdmod\_set\_handler (GGZdMod \* ggzdmod, GGZdModEvent e, GGZdModHandler func) *Set a handler for the given event.* *As described above, GGZdmod 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:** *ggzdmod The GGZdmod object.* \ *e The GGZdmod event.* \ *func The handler function being registered.* **Returns:** *0 on success, negative on failure (bad parameters)* **See also:** **ggzdmod\_get\_gamedata** ### int ggzdmod\_set\_state (GGZdMod \* ggzdmod, GGZdModState 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:** *ggzdmod The ggzdmod object.* \ *state The new state.* **Returns:** *0 on success, -1 on failure/error.* ## Author *Generated automatically by Doxygen for GGZdMod from the source code.*