--- name: "ggzcore_h" section: "3" platform: "linux" package: "libggzcore-dev" version: "0.0.14.1-1" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/ggzcore_h" --- # ggzcore\_h(3) The interface for the ggzcore library used by GGZ clients. ## NAME ggzcore.h - The interface for the ggzcore library used by GGZ clients. ## SYNOPSIS `#include `\ `#include `\ `#include `\ ### Defines \#define **GGZCORE\_VERSION\_MAJOR** 0\ \#define **GGZCORE\_VERSION\_MINOR** 0\ \#define **GGZCORE\_VERSION\_MICRO** 11\ \#define **GGZCORE\_VERSION\_IFACE** '7:0:0'\ \#define **GGZCORE\_DBG\_CONF** 'GGZCORE:CONF'\ *ggz\_debug debugging type for configuration system.* #define **GGZCORE\_DBG\_GAME** 'GGZCORE:GAME'\ *ggz\_debug debugging type for game communication.* #define **GGZCORE\_DBG\_HOOK** 'GGZCORE:HOOK'\ *ggz\_debug debugging type for hook system.* #define **GGZCORE\_DBG\_MODULE** 'GGZCORE:MODULE'\ *ggz\_debug debugging type for accessing modules.* #define **GGZCORE\_DBG\_NET** 'GGZCORE:NET'\ *ggz\_debug debugging type for network interaction.* #define **GGZCORE\_DBG\_POLL** 'GGZCORE:POLL'\ *ggz\_debug debugging type for debugging while polling.* #define **GGZCORE\_DBG\_ROOM** 'GGZCORE:ROOM'\ *ggz\_debug debugging type for room events and data.* #define **GGZCORE\_DBG\_SERVER** 'GGZCORE:SERVER'\ *ggz\_debug debugging type for server events and data.* #define **GGZCORE\_DBG\_STATE** 'GGZCORE:STATE'\ *ggz\_debug debugging type for state changes.* #define **GGZCORE\_DBG\_TABLE** 'GGZCORE:TABLE'\ *ggz\_debug debugging type for table data.* #define **GGZCORE\_DBG\_XML** 'GGZCORE:XML'\ *ggz\_debug debugging type for XML processing.* #define **ggzcore\_server\_get\_channel**(server) (-1)\ *Deprecated function. Do not use.* #define **ggzcore\_server\_create\_channel**(server) (void)0\ *Deprecated function. Do not use.* #define **ggzcore\_module\_launch**(m) ((int)(-1))\ \#define **ggzcore\_game\_set\_server\_fd**(game, fd) (void)0\ *Deprecated function. Do not use.* ### Typedefs typedef **\_GGZOptions** **GGZOptions**\ typedef **GGZHookReturn**(\* **GGZHookFunc** )(unsigned int id, const void \*event\_data, const void \*user\_data)\ typedef void(\* **GGZDestroyFunc** )(void \*data)\ *GGZ object destroy function type.* typedef \_GGZServer **GGZServer**\ *A server object containing all information about a connection.* typedef \_GGZRoom **GGZRoom**\ *Contains information about a single room on a server.* typedef \_GGZPlayer **GGZPlayer**\ *Contains information about a single player.* typedef \_GGZTable **GGZTable**\ *Contains information about a single table.* typedef \_GGZGameType **GGZGameType**\ *Contains information about a \_game type\_.* typedef \_GGZModule **GGZModule**\ *Contains information about a single module. A game module, on the client, is an executable designed to play a game. Each game type may have many modules that play it.* typedef \_GGZGame **GGZGame**\ *Contains information about a single game table. This contains information about a table we are present at or are about to launch. It is thus associated with both a GGZTable and a GGZModule.* ### Enumerations enum **GGZOptionFlags** { **GGZ\_OPT\_PARSER** = 0x0001, **GGZ\_OPT\_MODULES** = 0x0002, **GGZ\_OPT\_THREADED\_IO** = 0x0004, **GGZ\_OPT\_EMBEDDED** = 0x0008, **GGZ\_OPT\_RECONNECT** = 0x0010 }\ enum **GGZHookReturn** { **GGZ\_HOOK\_OK**, **GGZ\_HOOK\_REMOVE**, **GGZ\_HOOK\_ERROR**, **GGZ\_HOOK\_CRISIS** }\ enum **GGZLoginType** { **GGZ\_LOGIN**, **GGZ\_LOGIN\_GUEST**, **GGZ\_LOGIN\_NEW** }\ enum **GGZServerEvent** { **GGZ\_CONNECTED**, **GGZ\_CONNECT\_FAIL**, **GGZ\_NEGOTIATED**, **GGZ\_NEGOTIATE\_FAIL**, **GGZ\_LOGGED\_IN**, **GGZ\_LOGIN\_FAIL**, **GGZ\_MOTD\_LOADED**, **GGZ\_ROOM\_LIST**, **GGZ\_TYPE\_LIST**, **GGZ\_SERVER\_PLAYERS\_CHANGED**, **GGZ\_ENTERED**, **GGZ\_ENTER\_FAIL**, **GGZ\_LOGOUT**, **GGZ\_NET\_ERROR**, **GGZ\_PROTOCOL\_ERROR**, **GGZ\_CHAT\_FAIL**, **GGZ\_STATE\_CHANGE**, **GGZ\_CHANNEL\_CONNECTED**, **GGZ\_CHANNEL\_READY**, **GGZ\_CHANNEL\_FAIL**, **GGZ\_NUM\_SERVER\_EVENTS** }\ enum **GGZRoomEvent** { **GGZ\_PLAYER\_LIST**, **GGZ\_TABLE\_LIST**, **GGZ\_CHAT\_EVENT**, **GGZ\_ROOM\_ENTER**, **GGZ\_ROOM\_LEAVE**, **GGZ\_TABLE\_UPDATE**, **GGZ\_TABLE\_LAUNCHED**, **GGZ\_TABLE\_LAUNCH\_FAIL**, **GGZ\_TABLE\_JOINED**, **GGZ\_TABLE\_JOIN\_FAIL**, **GGZ\_TABLE\_LEFT**, **GGZ\_TABLE\_LEAVE\_FAIL**, **GGZ\_PLAYER\_LAG**, **GGZ\_PLAYER\_STATS**, **GGZ\_PLAYER\_COUNT** }\ enum **GGZGameEvent** { **GGZ\_GAME\_LAUNCHED**, **GGZ\_GAME\_LAUNCH\_FAIL**, **GGZ\_GAME\_NEGOTIATED**, **GGZ\_GAME\_NEGOTIATE\_FAIL**, **GGZ\_GAME\_PLAYING** }\ enum **GGZStateID** { **GGZ\_STATE\_OFFLINE**, **GGZ\_STATE\_CONNECTING**, **GGZ\_STATE\_RECONNECTING**, **GGZ\_STATE\_ONLINE**, **GGZ\_STATE\_LOGGING\_IN**, **GGZ\_STATE\_LOGGED\_IN**, **GGZ\_STATE\_ENTERING\_ROOM**, **GGZ\_STATE\_IN\_ROOM**, **GGZ\_STATE\_BETWEEN\_ROOMS**, **GGZ\_STATE\_LAUNCHING\_TABLE**, **GGZ\_STATE\_JOINING\_TABLE**, **GGZ\_STATE\_AT\_TABLE**, **GGZ\_STATE\_LEAVING\_TABLE**, **GGZ\_STATE\_LOGGING\_OUT** }\ *The states a server connection may be in.* enum **GGZModuleEnvironment** { **GGZ\_ENVIRONMENT\_PASSIVE**, **GGZ\_ENVIRONMENT\_CONSOLE**, **GGZ\_ENVIRONMENT\_FRAMEBUFFER**, **GGZ\_ENVIRONMENT\_XWINDOW**, **GGZ\_ENVIRONMENT\_XFULLSCREEN** }\ *The environment a game frontend expects.* ### Functions int **ggzcore\_init** (**GGZOptions** options)\ void **ggzcore\_reload** (void)\ void **ggzcore\_destroy** (void)\ **GGZServer** \* **ggzcore\_server\_new** (void)\ *Create a new server object.* int **ggzcore\_server\_reset** (**GGZServer** \*server)\ *Reset the server object.* int **ggzcore\_server\_add\_event\_hook** (**GGZServer** \*server, const **GGZServerEvent** event, const **GGZHookFunc** func)\ *Register a callback handler for a server event.* int **ggzcore\_server\_add\_event\_hook\_full** (**GGZServer** \*server, const **GGZServerEvent** event, const **GGZHookFunc** func, const void \*data)\ *Register a callback handler for a server event.* int **ggzcore\_server\_remove\_event\_hook** (**GGZServer** \*server, const **GGZServerEvent** event, const **GGZHookFunc** func)\ *Remove a single hook function from an event's hook list.* int **ggzcore\_server\_remove\_event\_hook\_id** (**GGZServer** \*server, const **GGZServerEvent** event, const unsigned int hook\_id)\ *Remove a hook function with given ID from the event's hook list.* int **ggzcore\_server\_set\_hostinfo** (**GGZServer** \*server, const char \*host, const unsigned int port, const unsigned int use\_tls)\ *Set host info for connecting to the server.* int **ggzcore\_server\_set\_logininfo** (**GGZServer** \*server, const **GGZLoginType** type, const char \*handle, const char \*password, const char \*email)\ *Set login info for logging in to the server.* int **ggzcore\_server\_log\_session** (**GGZServer** \*server, const char \*filename)\ *Initiate logging of ggzcore events.* const char \* **ggzcore\_server\_get\_host** (const **GGZServer** \*server)\ *Get the hostname of the server.* int **ggzcore\_server\_get\_port** (const **GGZServer** \*server)\ *Get the port of the server.* **GGZLoginType** **ggzcore\_server\_get\_type** (const **GGZServer** \*server)\ *Get the login type being used for this server.* const char \* **ggzcore\_server\_get\_handle** (const **GGZServer** \*server)\ *Get the handle being used for this server.* const char \* **ggzcore\_server\_get\_password** (const **GGZServer** \*server)\ *Get the password being used for this server.* int **ggzcore\_server\_get\_fd** (const **GGZServer** \*server)\ *Get the socket used for connection with the server.* **GGZStateID** **ggzcore\_server\_get\_state** (const **GGZServer** \*server)\ *Get the state of the server connection.* int **ggzcore\_server\_get\_tls** (const **GGZServer** \*server)\ *Get the current TLS status of this server.* int **ggzcore\_server\_get\_num\_players** (const **GGZServer** \*server)\ *Get the total number of players on the server.* int **ggzcore\_server\_get\_num\_rooms** (const **GGZServer** \*server)\ *Return the number of rooms on the server, or -1 on error.* **GGZRoom** \* **ggzcore\_server\_get\_cur\_room** (const **GGZServer** \*server)\ *Return the current room, or NULL if there is none.* **GGZRoom** \* **ggzcore\_server\_get\_nth\_room** (const **GGZServer** \*server, const unsigned int num)\ *Return the nth room on the server, or NULL on error.* int **ggzcore\_server\_get\_num\_gametypes** (const **GGZServer** \*server)\ *Return the overall number of game types on the server.* **GGZGameType** \* **ggzcore\_server\_get\_nth\_gametype** (const **GGZServer** \*server, const unsigned int num)\ *Get the nth gametype, or NULL on error.* **GGZGame** \* **ggzcore\_server\_get\_cur\_game** (const **GGZServer** \*server)\ *Return the player's current game.* int **ggzcore\_server\_is\_online** (const **GGZServer** \*server)\ *Return TRUE iff the server is online (connected?).* int **ggzcore\_server\_is\_logged\_in** (const **GGZServer** \*server)\ *Return TRUE iff we are logged into the server.* int **ggzcore\_server\_is\_in\_room** (const **GGZServer** \*server)\ *Return TRUE iff we are in a room on the server.* int **ggzcore\_server\_is\_at\_table** (const **GGZServer** \*server)\ *Return TRUE iff we are at a table on the server.* int **ggzcore\_server\_connect** (**GGZServer** \*server)\ *Connect to the server.* int **ggzcore\_server\_login** (**GGZServer** \*server)\ *Log in to the server.* int **ggzcore\_server\_motd** (**GGZServer** \*server)\ *Request the MOTD from the server.* int **ggzcore\_server\_list\_rooms** (**GGZServer** \*server, const int type, const char verbose)\ *Request room list.* int **ggzcore\_server\_list\_gametypes** (**GGZServer** \*server, const char verbose)\ *Request game type list.* int **ggzcore\_server\_join\_room** (**GGZServer** \*server, const unsigned int room)\ *Join a room on the server.* int **ggzcore\_server\_logout** (**GGZServer** \*server)\ *Log out of a server.* int **ggzcore\_server\_disconnect** (**GGZServer** \*server)\ *Disconnect from a server after having logged out.* int **ggzcore\_server\_data\_is\_pending** (**GGZServer** \*server)\ *Check for data pending from the server socket.* int **ggzcore\_server\_read\_data** (**GGZServer** \*server, int fd)\ *Read data for the server on the specified FD.* void **ggzcore\_server\_free** (**GGZServer** \*server)\ *Free GGZServer object and accompanying data.* **GGZRoom** \* **ggzcore\_room\_new** (void)\ *Allocate space for a new room object.* int **ggzcore\_room\_init** (**GGZRoom** \*room, **GGZServer** \*server, const unsigned int id, const char \*name, const unsigned int game, const char \*desc)\ *Initialize room object.* void **ggzcore\_room\_free** (**GGZRoom** \*room)\ *De-allocate room object and its children.* **GGZServer** \* **ggzcore\_room\_get\_server** (**GGZRoom** \*room)\ *Return the server for this room (or NULL on error).* int **ggzcore\_room\_get\_id** (const **GGZRoom** \*room)\ *Return the ID number of the room (or negative on error).* char \* **ggzcore\_room\_get\_name** (**GGZRoom** \*room)\ *Return the name of the room (or NULL on error).* char \* **ggzcore\_room\_get\_desc** (**GGZRoom** \*room)\ *Return the description of the room (or NULL on error).* **GGZGameType** \* **ggzcore\_room\_get\_gametype** (**GGZRoom** \*room)\ *Return the type of game played in this room (or NULL on error).* int **ggzcore\_room\_get\_num\_players** (**GGZRoom** \*room)\ *Return the number of players in the room (or negative on error).* **GGZPlayer** \* **ggzcore\_room\_get\_nth\_player** (**GGZRoom** \*room, const unsigned int num)\ *Return the nth player in the room (or NULL on error).* int **ggzcore\_room\_get\_num\_tables** (**GGZRoom** \*room)\ *Return the number of tables in the room (or negative on error).* **GGZTable** \* **ggzcore\_room\_get\_nth\_table** (**GGZRoom** \*room, const unsigned int num)\ *Return the nth table in the room (or NULL on error).* **GGZTable** \* **ggzcore\_room\_get\_table\_by\_id** (**GGZRoom** \*room, const unsigned int id)\ *Return the table in this room with matching ID (NULL on error).* int **ggzcore\_room\_add\_event\_hook** (**GGZRoom** \*room, const **GGZRoomEvent** event, const **GGZHookFunc** func)\ *Register a handler (hook) for the room event.* int **ggzcore\_room\_add\_event\_hook\_full** (**GGZRoom** \*room, const **GGZRoomEvent** event, const **GGZHookFunc** func, const void \*data)\ *Register a handler (hook) for thee room event, with data.* int **ggzcore\_room\_remove\_event\_hook** (**GGZRoom** \*room, const **GGZRoomEvent** event, const **GGZHookFunc** func)\ *Remove a hook from an event.* int **ggzcore\_room\_remove\_event\_hook\_id** (**GGZRoom** \*room, const **GGZRoomEvent** event, const unsigned int hook\_id)\ *Remove a hook from an event, by ID.* int **ggzcore\_room\_list\_players** (**GGZRoom** \*room)\ *Call to request a list of players in the room.* int **ggzcore\_room\_list\_tables** (**GGZRoom** \*room, const int type, const char global)\ *Call to request a list of tables in the room.* int **ggzcore\_room\_chat** (**GGZRoom** \*room, const GGZChatType opcode, const char \*player, const char \*msg)\ *Chat!* int **ggzcore\_room\_launch\_table** (**GGZRoom** \*room, **GGZTable** \*table)\ *Launch a table in the room.* int **ggzcore\_room\_join\_table** (**GGZRoom** \*room, const unsigned int table\_id, int spectator)\ *Join a table in the room, so that you can then play at it.* int **ggzcore\_room\_leave\_table** (**GGZRoom** \*room, int force)\ *Leave the table you are currently playing at.* char \* **ggzcore\_player\_get\_name** (const **GGZPlayer** \*player)\ *Return the name of the player.* GGZPlayerType **ggzcore\_player\_get\_type** (const **GGZPlayer** \*player)\ *Return the type of the player (admin/registered/guest).* **GGZRoom** \* **ggzcore\_player\_get\_room** (const **GGZPlayer** \*player)\ *Return the player's room, or NULL if none.* **GGZTable** \* **ggzcore\_player\_get\_table** (const **GGZPlayer** \*player)\ *Return the player's table, or NULL if none.* int **ggzcore\_player\_get\_lag** (const **GGZPlayer** \*player)\ *Return the player's lag class (1..5).* int **ggzcore\_player\_get\_record** (const **GGZPlayer** \*player, int \*wins, int \*losses, int \*ties, int \*forfeits)\ *Get the player's win-loss record.* int **ggzcore\_player\_get\_rating** (const **GGZPlayer** \*player, int \*rating)\ *Get the player's rating.* int **ggzcore\_player\_get\_ranking** (const **GGZPlayer** \*player, int \*ranking)\ *Get the player's ranking.* int **ggzcore\_player\_get\_highscore** (const **GGZPlayer** \*player, int \*highscore)\ *Get the player's highscore.* **GGZTable** \* **ggzcore\_table\_new** (void)\ *Create a new table object.* int **ggzcore\_table\_init** (**GGZTable** \*table, const **GGZGameType** \*gametype, const char \*desc, const unsigned int num\_seats)\ *Set data on a table object.* void **ggzcore\_table\_free** (**GGZTable** \*table)\ *Free the table object.* int **ggzcore\_table\_set\_seat** (**GGZTable** \*table, const unsigned int seat, GGZSeatType type, const char \*name)\ *Set a seat type at a table, pre-launch.* int **ggzcore\_table\_remove\_player** (**GGZTable** \*table, char \*name)\ *Find and remove the player from the table.* int **ggzcore\_table\_get\_id** (const **GGZTable** \*table)\ *Return the ID of the table.* const **GGZRoom** \* **ggzcore\_table\_get\_room** (const **GGZTable** \*table)\ *Return the room this table is in.* const **GGZGameType** \* **ggzcore\_table\_get\_type** (const **GGZTable** \*table)\ *Return the game type of the table.* const char \* **ggzcore\_table\_get\_desc** (const **GGZTable** \*table)\ *Return the table's description (or NULL).* GGZTableState **ggzcore\_table\_get\_state** (const **GGZTable** \*table)\ *Return the state of the table.* int **ggzcore\_table\_get\_num\_seats** (const **GGZTable** \*table)\ *Return the number of seats at the table.* int **ggzcore\_table\_set\_desc** (**GGZTable** \*table, const char \*desc)\ *Set the table description.* int **ggzcore\_table\_get\_seat\_count** (const **GGZTable** \*table, GGZSeatType type)\ *Count the seats of the given type.* const char \* **ggzcore\_table\_get\_nth\_player\_name** (const **GGZTable** \*table, const unsigned int num)\ *Return the name of a player at the table, or NULL on error.* int **ggzcore\_table\_get\_num\_spectator\_seats** (const **GGZTable** \*table)\ *Return the number of spectator seats at the table, or -1.* const char \* **ggzcore\_table\_get\_nth\_spectator\_name** (const **GGZTable** \*table, const unsigned int num)\ *Return the name of the nth spectator, or NULL if seat is empty.* GGZSeatType **ggzcore\_table\_get\_nth\_player\_type** (const **GGZTable** \*table, const unsigned int num)\ *Return the type of a player at the table, or GGZ\_PLAYER\_NONE on error.* unsigned int **ggzcore\_gametype\_get\_id** (const **GGZGameType** \*type)\ *Get the ID of this gametype.* const char \* **ggzcore\_gametype\_get\_name** (const **GGZGameType** \*type)\ *Get the name of the game type.* const char \* **ggzcore\_gametype\_get\_prot\_engine** (const **GGZGameType** \*type)\ *Get the protocol 'engine' used by the game type.* const char \* **ggzcore\_gametype\_get\_prot\_version** (const **GGZGameType** \*type)\ *Get the version of the protocol the game uses.* const char \* **ggzcore\_gametype\_get\_version** (const **GGZGameType** \*type)\ *Get the version of the game itself.* const char \* **ggzcore\_gametype\_get\_author** (const **GGZGameType** \*type)\ *Get the author of the game.* const char \* **ggzcore\_gametype\_get\_url** (const **GGZGameType** \*type)\ *Get a URL for more info about the game.* const char \* **ggzcore\_gametype\_get\_desc** (const **GGZGameType** \*type)\ *Get a description of the game.* int **ggzcore\_gametype\_get\_max\_players** (const **GGZGameType** \*type)\ *Get the maximum number of players the game can support.* int **ggzcore\_gametype\_get\_max\_bots** (const **GGZGameType** \*type)\ *Get the maximum number of bots the game can support.* int **ggzcore\_gametype\_get\_spectators\_allowed** (const **GGZGameType** \*type)\ *Return TRUE iff spectators are allowed for this game type.* int **ggzcore\_gametype\_num\_players\_is\_valid** (const **GGZGameType** \*type, unsigned int num)\ *Return TRUE iff the given number of players is valid.* int **ggzcore\_gametype\_num\_bots\_is\_valid** (const **GGZGameType** \*type, unsigned int num)\ *Return TRUE iff the given number of bots is valid.* int **ggzcore\_conf\_initialize** (const char \*g\_path, const char \*u\_path)\ int **ggzcore\_conf\_write\_string** (const char \*section, const char \*key, const char \*value)\ int **ggzcore\_conf\_write\_int** (const char \*section, const char \*key, int value)\ int **ggzcore\_conf\_write\_list** (const char \*section, const char \*key, int argc, char \*\*argv)\ char \* **ggzcore\_conf\_read\_string** (const char \*section, const char \*key, const char \*def)\ int **ggzcore\_conf\_read\_int** (const char \*section, const char \*key, int def)\ int **ggzcore\_conf\_read\_list** (const char \*section, const char \*key, int \*argcp, char \*\*\*argvp)\ int **ggzcore\_conf\_remove\_section** (const char \*section)\ int **ggzcore\_conf\_remove\_key** (const char \*section, const char \*key)\ int **ggzcore\_conf\_commit** (void)\ unsigned int **ggzcore\_module\_get\_num** (void)\ *This returns the number of registered modules.* int **ggzcore\_module\_add** (const char \*name, const char \*version, const char \*prot\_engine, const char \*prot\_version, const char \*author, const char \*frontend, const char \*url, const char \*exe\_path, const char \*icon\_path, const char \*help\_path, **GGZModuleEnvironment** environment)\ int **ggzcore\_module\_get\_num\_by\_type** (const char \*game, const char \*engine, const char \*version)\ *Returns how many modules support this game and protocol.* **GGZModule** \* **ggzcore\_module\_get\_nth\_by\_type** (const char \*game, const char \*engine, const char \*version, const unsigned int num)\ *Returns n-th module that supports this game and protocol.* const char \* **ggzcore\_module\_get\_name** (**GGZModule** \*module)\ *Return the name of the module.* const char \* **ggzcore\_module\_get\_version** (**GGZModule** \*module)\ *Return the (game?) version of the module.* const char \* **ggzcore\_module\_get\_prot\_engine** (**GGZModule** \*module)\ *Return the name of the module's protocol engine.* const char \* **ggzcore\_module\_get\_prot\_version** (**GGZModule** \*module)\ *Return the version of the module's protocol engine.* const char \* **ggzcore\_module\_get\_author** (**GGZModule** \*module)\ *Return the author of the module.* const char \* **ggzcore\_module\_get\_frontend** (**GGZModule** \*module)\ *Return the module's frontend type.* const char \* **ggzcore\_module\_get\_url** (**GGZModule** \*module)\ *Return the URL associated with the module.* const char \* **ggzcore\_module\_get\_icon\_path** (**GGZModule** \*module)\ const char \* **ggzcore\_module\_get\_help\_path** (**GGZModule** \*module)\ *Return the help path of the module (?).* char \*\* **ggzcore\_module\_get\_argv** (**GGZModule** \*module)\ *Return the executable arguments for the module. See exec().* **GGZModuleEnvironment** **ggzcore\_module\_get\_environment** (**GGZModule** \*module)\ *Return the preferred environment type.* **GGZGame** \* **ggzcore\_game\_new** (void)\ *Make a new game object.* int **ggzcore\_game\_init** (**GGZGame** \*game, **GGZServer** \*server, **GGZModule** \*module)\ *Initialize the game object.* void **ggzcore\_game\_free** (**GGZGame** \*game)\ *Free the game object.* int **ggzcore\_game\_add\_event\_hook** (**GGZGame** \*game, const **GGZGameEvent** event, const **GGZHookFunc** func)\ *Register a hook for a game event.* int **ggzcore\_game\_add\_event\_hook\_full** (**GGZGame** \*game, const **GGZGameEvent** event, const **GGZHookFunc** func, const void \*data)\ *Register a hook for a game event.* int **ggzcore\_game\_remove\_event\_hook** (**GGZGame** \*game, const **GGZGameEvent** event, const **GGZHookFunc** func)\ *Remove a hook from a game event.* int **ggzcore\_game\_remove\_event\_hook\_id** (**GGZGame** \*game, const **GGZGameEvent** event, const unsigned int hook\_id)\ *Remove a specified hook from a game event.* int **ggzcore\_game\_get\_control\_fd** (**GGZGame** \*game)\ *Return the control (ggzmod) socket for the game.* **GGZModule** \* **ggzcore\_game\_get\_module** (**GGZGame** \*game)\ *Return the module set for the game.* int **ggzcore\_game\_launch** (**GGZGame** \*game)\ *Launch thee game!* int **ggzcore\_game\_read\_data** (**GGZGame** \*game)\ *Read data from the game. When data is pending on the control socket, call this function.* ## Detailed Description The interface for the ggzcore library used by GGZ clients. ## Define Documentation ### #define ggzcore\_module\_launch(m) ((int)(-1)) This attempts to launch the specified module and returns 0 if successful or -1 on error. ## Typedef Documentation ### typedef void(\* GGZDestroyFunc)(void \*data) GGZ object destroy function type. **Todo** This is not currently used. ### typedef struct \_GGZGameType GGZGameType Contains information about a \_game type\_. **Note:** Each room has one game type; a game may be used in multiple rooms. ### typedef GGZHookReturn(\* GGZHookFunc)(unsigned int id, const void \*event\_data, const void \*user\_data) GGZ Event hook function type, used as a vallback for events ### typedef struct \_GGZOptions GGZOptions Options structure for ggzcore library ## Enumeration Type Documentation ### enum GGZGameEvent A GGZGameEvent is an event associated with the game, that is triggered by a communication from the server or from the game. When a game event occurs, the associated event handle will be called, and will be passed the event data (a void\*) along with the (optional) user data. All game events apply to the current game. Game events are usually triggered by calling ggzcore\_server\_read\_data or ggzcore\_game\_read\_data. **See also:** **ggzcore\_game\_add\_event\_hook** **ggzcore\_server\_read\_data** **Enumeration values:** - *GGZ\_GAME\_LAUNCHED* *A game was launched by the player (you). After this the core client should call ggzcore\_game\_get\_control\_fd, monitor the socket that function returns, and call ggzcore\_game\_read\_data when there is data pending. This event is triggered inside of ggzcore\_game\_launch.* **Parameters:** *data NULL* **See also:** **ggzcore\_game\_launch** - *GGZ\_GAME\_LAUNCH\_FAIL* *Your game launch has failed. Triggered instead of GGZ\_GAME\_LAUNCHED when there's a failure somewhere.* **Parameters:** *data NULL* **See also:** **GGZ\_GAME\_LAUNCHED** - *GGZ\_GAME\_NEGOTIATED* *Negotiation with server was successful. This should happen some time after the launch succeeds. The core client need do nothing at this point.* **Parameters:** *data NULL* - *GGZ\_GAME\_NEGOTIATE\_FAIL* *Negotiation was not successful, game launch failed.* **Todo** *Currently this can't actually happen...* - *GGZ\_GAME\_PLAYING* *Game reached the 'playing' state. When this happens the core client should call ggzcore\_room\_launch\_table or ggzcore\_room\_join\_table to finalize the game join.* **Parameters:** *data NULL* ### enum GGZHookReturn *GGZ Hook function return types* **Enumeration values:** - *GGZ\_HOOK\_OK* *Success!* - *GGZ\_HOOK\_REMOVE* *Remove this hook immediately.* - *GGZ\_HOOK\_ERROR* *A localized error.* - *GGZ\_HOOK\_CRISIS* *A major error; stop processing the event.* ### enum GGZLoginType *This controls the type of login a user chooses. A different value will require different information to be sent to the server.* **Enumeration values:** - *GGZ\_LOGIN* *Standard login; uname and correct passwd needed.* - *GGZ\_LOGIN\_GUEST* *Guest login; only a uname is required.* - *GGZ\_LOGIN\_NEW* *New user login; only a uname is required. Password will be assigned by the server (but can be passed along).* ### enum GGZModuleEnvironment *The environment a game frontend expects.* *Core clients should offer those game modules which fit their own environment.* **Enumeration values:** - *GGZ\_ENVIRONMENT\_PASSIVE* *No GUI, no interaction with user* - *GGZ\_ENVIRONMENT\_CONSOLE* *Text console* - *GGZ\_ENVIRONMENT\_FRAMEBUFFER* *VESA or framebuffer* - *GGZ\_ENVIRONMENT\_XWINDOW* *X11 windowed mode (default)* - *GGZ\_ENVIRONMENT\_XFULLSCREEN* *X11 fullscreen mode* ### enum GGZOptionFlags **Enumeration values:** - *GGZ\_OPT\_MODULES* *Load the default configuration file (unused).* - *GGZ\_OPT\_THREADED\_IO* *Load the game module list.* - *GGZ\_OPT\_EMBEDDED* *Provide multi-threaded network IO (unused).* - *GGZ\_OPT\_RECONNECT* *Reconnect automatically after connection loss.* ### enum GGZRoomEvent *A GGZRoomEvent is an event associated with the room, that is triggered by a communication from the server. When a room event occurs, the associated event handler will be called, and will be passed the event data (a void\*), along with the (optional) user data. All room events apply to the current room unless a room number is given. Room events are almost always triggered by calling ggzcore\_server\_read\_data.* **See also:** **ggzcore\_room\_add\_event\_hook** **ggzcore\_server\_read\_data** **Enumeration values:** - *GGZ\_PLAYER\_LIST* *The list of players in a room has arrived.* **Parameters:** *data The room id (int \*)* **Note:** *This will only be issued for the current room.* **See also:** **ggzcore\_room\_list\_players** - *GGZ\_TABLE\_LIST* *Received the list of active tables.* **Parameters:** *data NULL* **See also:** **ggzcore\_room\_list\_tables** - *GGZ\_CHAT\_EVENT* *Received a chat message of any kind. This can happen at any time when you're in a room.* **Parameters:** *data The* **GGZChatEventData** *associated with the chat.* **See also:** **GGZChatEventData** - *GGZ\_ROOM\_ENTER* *A player has entered the room with you.* **Parameters:** *data A* **GGZRoomChangeEventData** *structure.* - *GGZ\_ROOM\_LEAVE* *A player has left your room.* **Parameters:** *data A* **GGZRoomChangeEventData** *structure.* - *GGZ\_TABLE\_UPDATE* *One of the tables in the current room has changed.* **Todo** *How are you supposed to know which table has changed?* **Parameters:** *data NULL* - *GGZ\_TABLE\_LAUNCHED* *The table you tried to launch has launched!* **See also:** **ggzcore\_room\_launch\_table** **Parameters:** *data NULL* - *GGZ\_TABLE\_LAUNCH\_FAIL* *The table you tried to launch couldn't be launched* **See also:** **GGZ\_TABLE\_LAUNCHED** **Parameters:** *data A pointer to a* **GGZErrorEventData** - *GGZ\_TABLE\_JOINED* *Your table join attempt has succeeded.* **See also:** **ggzcore\_room\_join\_table** **Parameters:** *data The table index (int\*) of the table we joined.* - *GGZ\_TABLE\_JOIN\_FAIL* *Joining a table did not succeed.* **See also:** **GGZ\_TABLE\_JOINED** **Parameters:** *data A helpful error string.* - *GGZ\_TABLE\_LEFT* *You have successfully left the table you were at.* **See also:** **ggzcore\_room\_leave\_table** **Parameters:** *data The* **GGZTableLeaveEventData** *associated with the leave.* **See also:** **GGZTableLeaveEventData** - *GGZ\_TABLE\_LEAVE\_FAIL* *Your attempt to leave the table has failed.* **See also:** **GGZ\_TABLE\_LEFT** **Parameters:** *data A helpful error string.* - *GGZ\_PLAYER\_LAG* *A player's lag (measure of connection speed) has been updated* **See also:** **ggzcore\_player\_get\_lag** **Parameters:** *data The name of the player whose lag has changed.* - *GGZ\_PLAYER\_STATS* *A player's stats have been updated.* **See also:** **GGZ\_PLAYER\_LIST** **ggzcore\_player\_get\_record** **ggzcore\_player\_get\_rating** **ggzcore\_player\_get\_ranking** **ggzcore\_player\_get\_highscore** **Parameters:** *data The name of the player whose stats have changed.* - *GGZ\_PLAYER\_COUNT* *The number of players in a room has arrived.* **Parameters:** *data The room id (int \*)* ### enum GGZServerEvent *A GGZServerEvent is an event triggered by a communication from the server. Each time an event occurs, the associated event handler will be called, and will be passed the event data (a void\*). Most events are generated as a result of ggzcore\_server\_read\_data.* **See also:** **ggzcore\_server\_add\_event\_hook** **Enumeration values:** - *GGZ\_CONNECTED* *We have just made a connection to the server. After this point the server's socket should be accessible and should be monitored for data. It happens in direct response to ggzcore\_server\_connect. Note that most events after this will only happen by calling ggzcore\_server\_read\_data on the server's FD!* **Parameters:** *data NULL* **See also:** **ggzcore\_server\_connect** - *GGZ\_CONNECT\_FAIL* *Error: we have failed to connect to the server. This is generated in place of GGZ\_CONNECTED if the connection could not be made. The server object is otherwise unaffected.* **Parameters:** *data An error string (created by strerror)* **See also:** **ggzcore\_server\_connect** - *GGZ\_NEGOTIATED* *We have negotiated a connection to the server. This will happen automatically once a connection has been established, if the server socket is monitored.* **Note:** *This just means we've determined ggzd is at the other end.* **Parameters:** *data NULL* **See also:** **ggzcore\_server\_read\_data** - *GGZ\_NEGOTIATE\_FAIL* *Error: negotiation failure. Could be the wrong version. This will happen in place of a GGZ\_NEGOTIATED if the server could not be negotiated with.* **Parameters:** *data A useless error string.* **See also:** **ggzcore\_server\_read\_data** - *GGZ\_LOGGED\_IN* *We have successfully logged in. We can now start doing stuff. This will not happen until the client sends their login information.* **See also:** **ggzcore\_server\_login** **Parameters:** *data NULL* **See also:** **ggzcore\_server\_read\_data** - *GGZ\_LOGIN\_FAIL* *Error: login failure. This will happen in place of GGZ\_LOGGED\_IN if the login failed. The server object will be otherwise unaffected.* **Parameters:** *data A pointer to a* **GGZErrorEventData***.* **See also:** **GGZErrorEventData** **ggzcore\_server\_read\_data** - *GGZ\_MOTD\_LOADED* *The MOTD has been read from the server and can be displayed. The server will send us the MOTD automatically after login; it can also be requested by ggzcore\_server\_motd. It is up to the client whether or not to display it. See the online documentation (somewhere?) about the MOTD markup format.* **Parameters:** *data Pointer to a* **GGZMotdEventData** *including the full MOTD text.* **See also:** **ggzcore\_server\_motd** **Todo** *The MOTD cannot be accessed outside of this event* **See also:** *ggzcore\_server\_read\_data!* - *GGZ\_ROOM\_LIST* *The room list arrived. This will only happen after the list is requested by* **ggzcore\_server\_list\_rooms()***. The list may be accessed through* **ggzcore\_server\_get\_num\_rooms()** *and* **ggzcore\_server\_get\_nth\_room()***. Until this event arrives these functions will be useless!* **Parameters:** *data NULL* **See also:** **ggzcore\_server\_read\_data** - *GGZ\_TYPE\_LIST* *The list of game types is available. This will only happen after the list is requested by ggzcore\_server\_list\_types(). The list may be accessed through* **ggzcore\_server\_get\_num\_gametypes()** *and* **ggzcore\_server\_get\_nth\_gametype()***. Until this event arrives these functions will be useless!* **Parameters:** *data NULL* **See also:** **ggzcore\_server\_read\_data** - *GGZ\_SERVER\_PLAYERS\_CHANGED* *The number of players on the server has changed. This event is issued rather frequently every time players enter or leave.* **Parameters:** *data NULL* **See also:** **ggzcore\_server\_get\_num\_players** **ggzcore\_server\_read\_data** - *GGZ\_ENTERED* *We have successfully entered a room. This will be issued to tell us a room join has succeeded, after it has been requested.* **Parameters:** *data NULL* **See also:** **ggzcore\_server\_join\_room** **ggzcore\_server\_read\_data** - *GGZ\_ENTER\_FAIL* *Error: we have tried to enter a room and failed. This will be issued to tell us a room join has failed.* **Parameters:** *data A pointer to a* **GGZErrorEventData***.* **See also:** **GGZErrorEventData** **ggzcore\_server\_join\_room** **ggzcore\_server\_read\_data** - *GGZ\_LOGOUT* *Logged out of the server. This will happen when the server completes the communication; usually after ggzcore\_net\_send\_logout is called.* **Parameters:** *data NULL* **See also:** **ggzcore\_server\_read\_data** - *GGZ\_NET\_ERROR* *Error: a network (transmission) error occurred. The server will automatically disconnect.* **Parameters:** *data A generally unhelpful error string.* **See also:** **ggzcore\_server\_read\_data** - *GGZ\_PROTOCOL\_ERROR* *Error: a communication protocol error occured. This can happen in a variety of situations when the server sends us something we can't handle. The server will be automatically disconnected.* **Parameters:** *data A technical error string.* **See also:** **ggzcore\_server\_read\_data** - *GGZ\_CHAT\_FAIL* *Error: A chat message could not be sent. This will happen when we try to send a chat and the server rejects it.* **Parameters:** *data A pointer to a* **GGZErrorEventData***.* **See also:** **GGZErrorEventData** **ggzcore\_server\_read\_data** - *GGZ\_STATE\_CHANGE* *The internal state of ggzcore has changed. This may happen at any time.* **Parameters:** *data NULL* **See also:** **GGZStateID** **ggzcore\_server\_get\_state** - *GGZ\_CHANNEL\_CONNECTED* *Status event: a requested direct game connection has been established. To start a game (table), a channel must be created. This event will alert that the channel has been established. The channel's FD should then be monitored for input, which should then be passed back to the server object for handling.* **Parameters:** *data NULL* **Note:** *This event is deprecated and should not be used.* **See also:** **ggzcore\_server\_get\_channel** **ggzcore\_server\_read\_data** - *GGZ\_CHANNEL\_READY* *Game channel is ready for read/write operations. After the channel has been connected, if we continue to monitor the socket eventually it will be negotiated and ready to use. At this point it is ready for the game client to use.* **Parameters:** *data NULL* **Note:** *This event is deprecated and should not be used.* **See also:** **ggzcore\_server\_read\_data** - *GGZ\_CHANNEL\_FAIL* *Error: Failure during setup of direct connection to game server. If the channel could not be prepared, this event will happen instead of GGZ\_CHANNEL\_READY or GGZ\_CHANNEL\_CONNECTED event. At this point the channel is no longer useful (I think).* **Parameters:** *data An unhelpful error string* **Note:** *This event is deprecated and should not be used.* **See also:** **ggzcore\_server\_read\_data** - *GGZ\_NUM\_SERVER\_EVENTS* *Terminator. Do not use.* ### enum GGZStateID *The states a server connection may be in.* *On the client side, a simplistic state maching is used to tell what's going on. A game client should usually consult the current state when determining what actions are possible.* **Enumeration values:** - *GGZ\_STATE\_OFFLINE* *Not connected (at all)* - *GGZ\_STATE\_CONNECTING* *In the process of connecting.* - *GGZ\_STATE\_RECONNECTING* *Continuous reconnection attempts.* - *GGZ\_STATE\_ONLINE* *Connected, but not doing anything.* - *GGZ\_STATE\_LOGGING\_IN* *In the process of logging in.* - *GGZ\_STATE\_LOGGED\_IN* *Online and logged in!* - *GGZ\_STATE\_ENTERING\_ROOM* *Moving into a room.* - *GGZ\_STATE\_IN\_ROOM* *Online, logged in, and in a room.* - *GGZ\_STATE\_BETWEEN\_ROOMS* *Moving between rooms.* - *GGZ\_STATE\_LAUNCHING\_TABLE* *Trying to launch a table.* - *GGZ\_STATE\_JOINING\_TABLE* *Trying to join a table.* - *GGZ\_STATE\_AT\_TABLE* *Online, loggied in, in a room, at a table.* - *GGZ\_STATE\_LEAVING\_TABLE* *Waiting to leave a table.* - *GGZ\_STATE\_LOGGING\_OUT* *In the process of logging out.* ## Function Documentation ### int ggzcore\_conf\_commit (void) **ggzcore\_conf\_commit()** *- Commits the core user config file to disk* **Returns:** *: int : 0 if successful, -1 on error* ### int ggzcore\_conf\_initialize (const char \* g\_path, const char \* u\_path) **ggzcore\_conf\_initialize()** *Opens the global and/or user configuration files for the frontend. Either g\_path or u\_path can be NULL if the file is not to be used. The user config file will be created if it does not exist.* **Returns:** *: 0 on success, negative on failure* ### int ggzcore\_conf\_read\_int (const char \* section, const char \* key, int def) **ggzcore\_conf\_read\_int()** *- Read a integer from the configuration file(s)* **Parameters:** *section section to get value from* \ *key key value was stored under* \ *def default value to return if none is found* **Returns:** *an integer from the configuration file OR the default value* **Note:** *There is no guaranteed way to find if the call failed. If you must know, call ggzcore\_conf\_read\_string with a NULL default value and check for the NULL return.* ### int ggzcore\_conf\_read\_list (const char \* section, const char \* key, int \* argcp, char \*\*\* argvp) **ggzcore\_conf\_read\_list()** *- Read a list from the configuration file(s)* **Parameters:** *section section to get value from* \ *key key value was stored under* \ *argcp ptr to int which will receive the list entry count* \ *argvp a pointer to a dynamically allocated array that* **ggzcore\_conf\_read\_list()** *will build* **Returns:** *int : 0 if successful, -1 on error* ### char\* ggzcore\_conf\_read\_string (const char \* section, const char \* key, const char \* def) **ggzcore\_conf\_read\_string()** *- Read a string from the configuration file(s)* **Parameters:** *section section to get value from* \ *key key value was stored under* \ *def default value to return if none is found* **Returns:** *a dynamically allocated string from the configuration file OR a dynamically allocated copy of the default string* **Note:** *The default may be set to NULL, in which case a NULL will be returned if the value could not be found in either configuration file.* ### int ggzcore\_conf\_remove\_key (const char \* section, const char \* key) **ggzcore\_conf\_remove\_key()** *- Removes a key entry from the user config file* **Parameters:** *section section to remove* \ *key key entry to remove* **Returns:** *int : 0 if success, -1 on error, 1 on soft error (section/key didn't exist)* ### int ggzcore\_conf\_remove\_section (const char \* section) **ggzcore\_conf\_remove\_section()** *- Removes a section from the user config file* **Parameters:** *section section to remove* **Returns:** *int : 0 if successful, -1 on error, 1 on soft error (section did not exist)* ### int ggzcore\_conf\_write\_int (const char \* section, const char \* key, int value) **ggzcore\_conf\_write\_int()** *- Write a integer to the user config file* **Parameters:** *section section to store value in* \ *key key to store value under* \ *value value to store* **Returns:** *int : 0 if successful, -1 on error* ### int ggzcore\_conf\_write\_list (const char \* section, const char \* key, int argc, char \*\* argv) **ggzcore\_conf\_write\_list()** *- Write a list to the user config file* **Parameters:** *section section to store value in* \ *key key to store value under* \ *argc count of string arguments in list* \ *argv array of NULL terminated strings* **Returns:** *int : 0 if successful, -1 on error* ### int ggzcore\_conf\_write\_string (const char \* section, const char \* key, const char \* value) **ggzcore\_conf\_write\_string()** *- Write a string to the user config file* **Parameters:** *section section to store value in* \ *key key to store value under* \ *value value to store* **Returns:** *int : 0 if successful, -1 on error* ### void ggzcore\_destroy (void) **ggzcore\_destroy()** *- Cleanup function for ggzcore lib.* ### int ggzcore\_game\_add\_event\_hook (GGZGame \* game, const GGZGameEvent event, const GGZHookFunc func) *Register a hook for a game event.* **See also:** **ggzcore\_server\_add\_event\_hook** **ggzcore\_room\_add\_event\_hook** ### int ggzcore\_game\_add\_event\_hook\_full (GGZGame \* game, const GGZGameEvent event, const GGZHookFunc func, const void \* data) *Register a hook for a game event.* **See also:** **ggzcore\_server\_add\_event\_hook\_full** **ggzcore\_room\_add\_event\_hook\_full** ### int ggzcore\_game\_read\_data (GGZGame \* game) *Read data from the game. When data is pending on the control socket, call this function.* **Returns:** *negative on error* **See also:** **ggzcore\_game\_get\_control\_fd** ### int ggzcore\_game\_remove\_event\_hook (GGZGame \* game, const GGZGameEvent event, const GGZHookFunc func) *Remove a hook from a game event.* **See also:** **ggzcore\_server\_remove\_event\_hook** **ggzcore\_room\_remove\_event\_hook** ### int ggzcore\_game\_remove\_event\_hook\_id (GGZGame \* game, const GGZGameEvent event, const unsigned int hook\_id) *Remove a specified hook from a game event.* **See also:** **ggzcore\_server\_remove\_event\_hook\_id** **ggzcore\_room\_remove\_event\_hook\_id** ### unsigned int ggzcore\_gametype\_get\_id (const GGZGameType \* type) *Get the ID of this gametype.* **Note:** *This is not normally useful for a GGZ client to know.* ### int ggzcore\_gametype\_get\_max\_bots (const GGZGameType \* type) *Get the maximum number of bots the game can support.* **See also:** *ggzcore\_gametype\_bots\_is\_valid* ### int ggzcore\_gametype\_get\_max\_players (const GGZGameType \* type) *Get the maximum number of players the game can support.* **See also:** **ggzcore\_gametype\_num\_players\_is\_valid** ### int ggzcore\_init (GGZOptions options) **ggzcore\_init()** *- Initializtion function for ggzcore lib.* **Parameters:** *options options structure* **Returns:** *int : 0 if successful, -1 on failure* ### int ggzcore\_module\_add (const char \* name, const char \* version, const char \* prot\_engine, const char \* prot\_version, const char \* author, const char \* frontend, const char \* url, const char \* exe\_path, const char \* icon\_path, const char \* help\_path, GGZModuleEnvironment environment) *This adds a local module to the list. It returns 0 if successful or -1 on failure.* ### const char\* ggzcore\_module\_get\_icon\_path (GGZModule \* module) *This is (intended to be) an optional xpm file that the module can provide to use for representing the game graphically.* ### int ggzcore\_player\_get\_highscore (const GGZPlayer \* player, int \* highscore) *Get the player's highscore.* **Returns:** *TRUE if there is a highscore; FALSE if not or on error.* ### int ggzcore\_player\_get\_ranking (const GGZPlayer \* player, int \* ranking) *Get the player's ranking.* **Returns:** *TRUE if there is a ranking; FALSE if not or on error.* ### int ggzcore\_player\_get\_rating (const GGZPlayer \* player, int \* rating) *Get the player's rating.* **Returns:** *TRUE if there is a rating; FALSE if not or on error.* ### int ggzcore\_player\_get\_record (const GGZPlayer \* player, 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 ggzcore\_reload (void) **ggzcore\_reload()** *- Reload game module database* ### int ggzcore\_room\_add\_event\_hook (GGZRoom \* room, const GGZRoomEvent event, const GGZHookFunc func) *Register a handler (hook) for the room event.* *A room event will happen when data is received from the server. To make updates to the frontend, the client will need to register a hook function to handle the event. This hook function will be called each time the room event occurrs. More than one hook function may be specified, in which case they will all be called (in FIFO order).* **Parameters:** *room The room object to associate the hook with.* \ *event The event the handler is going to be 'hooked' onto.* \ *func The event handler itself. This is called during the event.* **Returns:** *The hook ID, or negative on error.* **See also:** **ggzcore\_room\_add\_event\_hook\_full** **ggzcore\_room\_remove\_event\_hook** **ggzcore\_room\_remove\_event\_hook\_id** ### int ggzcore\_room\_add\_event\_hook\_full (GGZRoom \* room, const GGZRoomEvent event, const GGZHookFunc func, const void \* data) *Register a handler (hook) for thee room event, with data.* *This function is similar to ggzcore\_room\_add\_event\_hook, except that user data will be associated with the hook. This data will be passed back to the function each time it is invoked on this event.* **Parameters:** *room The room object to associate the hook with.* \ *event The event the handler is going to be 'hooked' onto.* \ *func The event handler itself. This is called during the event.* \ *data The user data associated with the hook.* **Returns:** *The hook ID, or negative on error.* **See also:** **ggzcore\_room\_add\_event\_hook** ### int ggzcore\_room\_chat (GGZRoom \* room, const GGZChatType opcode, const char \* player, const char \* msg) *Chat!* **Parameters:** *room Your current room.* \ *opcode The chat type.* \ *player The name of the target player (only for certain chat types)* \ *msg The text of the chat message (some chat types don't need it)* **Returns:** *0 on success, negative on (any) failure* **Note:** *The chat message should be in UTF-8.* ### int ggzcore\_room\_join\_table (GGZRoom \* room, const unsigned int table\_id, int spectator) *Join a table in the room, so that you can then play at it.* **Parameters:** *room Your current room.* \ *table\_id The table to join.* \ *spectator TRUE if you wish to spectate, FALSE if you want to play* **Returns:** *0 on success, negative on (any) failure* ### int ggzcore\_room\_launch\_table (GGZRoom \* room, GGZTable \* table) *Launch a table in the room.* *When a player wants to launch a new table, this is the function to do it. You must first create the table and set up the number and type of seats. Then call this function to initiate the launch.* **Parameters:** *room Your current room.* \ *table The table to launch.* **Returns:** *0 on success, negative on (any) failure* ### int ggzcore\_room\_leave\_table (GGZRoom \* room, int force) *Leave the table you are currently playing at.* *This function tries to leave your current table. You should 'force' the leave only if the game client is inoperable, since for some games this will destroy the game server as well.* **Parameters:** *room Your current room.* \ *force TRUE to force the leave, FALSE to leave it up to ggzd* **Returns:** *0 on success, negative on (any) failure* ### int ggzcore\_room\_list\_players (GGZRoom \* room) *Call to request a list of players in the room.* **See also:** **GGZ\_PLAYER\_LIST** ### int ggzcore\_room\_list\_tables (GGZRoom \* room, const int type, const char global) *Call to request a list of tables in the room.* **Parameters:** *room Your current room* \ *type currently ignored (???)* \ *global currently ignored (???)* **See also:** **GGZ\_TABLE\_LIST** ### int ggzcore\_room\_remove\_event\_hook (GGZRoom \* room, const GGZRoomEvent event, const GGZHookFunc func) *Remove a hook from an event.* *Removes a specific hook function from the hook list for the given room event. If more than one copy of the function exists in the list, the oldest one will be removed.* **Parameters:** *room The room object to associate the hook with.* \ *event The event the handler is to be unhooked from.* \ *func The event handler function to remove.* **Returns:** *0 on success, negative on failure.* **See also:** **ggzcore\_room\_add\_event\_hook** ### int ggzcore\_room\_remove\_event\_hook\_id (GGZRoom \* room, const GGZRoomEvent event, const unsigned int hook\_id) *Remove a hook from an event, by ID.* *Removes a specific hook from the hook list for the given room. The 'ID' should be the same as that returned when the hook was added.* **Parameters:** *room The room object to associate the hook with.* \ *event The event the handler is to be unhooked from.* \ *id The ID of the hook to remove, as returned by the add function return 0 on success, negative on failure* **See also:** **ggzcore\_room\_add\_event\_hook** ### int ggzcore\_server\_add\_event\_hook (GGZServer \* server, const GGZServerEvent event, const GGZHookFunc func) *Register a callback handler for a server event.* *Call this function to register the given GGZHookFunc as a handler for the given event. Then any time that event happens the handler function will be called.* **Parameters:** *server The GGZ server object.* \ *event The server event to be handled.* \ *func The handler function to be called when the event occurs.* **Returns:** *A hook ID value to identify this handler.* **Note:** *Equivalent to ggzcore\_server\_add\_event\_hook\_full with data==NULL.* *More than one handler can be registered for each event.* ### int ggzcore\_server\_add\_event\_hook\_full (GGZServer \* server, const GGZServerEvent event, const GGZHookFunc func, const void \* data) *Register a callback handler for a server event.* **See also:** **ggzcore\_server\_add\_event\_hook** **Parameters:** *data An arbitrary pointer that will be passed to the hook function.* ### int ggzcore\_server\_connect (GGZServer \* server) *Connect to the server.* *Call this function to initially connect to a GGZ server. Connection info is set using the ggzcore\_server\_set\_hostinfo function.* *The function is asynchronous and will return very quickly. After the connection is (hopefully) established we will receive either a GGZ\_CONNECTED or GGZ\_CONNECT\_FAIL server event. If the connection succeeds, negotiations with the GGZ server will begin automatically. Once this is complete, we will receive either a GGZ\_NEGOTIATED or GGZ\_NEGOTIATE\_FAIL event.* **Parameters:** *server The GGZ server object.* **Returns:** *0 on success, -1 on failure.* **Note:** *On success a GGZ\_CONNECTED event will be generated.* *On failure a GGZ\_CONNECT\_FAIL event may or may not be generated.* ### int ggzcore\_server\_get\_fd (const GGZServer \* server) *Get the socket used for connection with the server.* *This returns the file descriptor of the primary socket for the TCP connection to the server. All GGZ data goes across this socket.* **Parameters:** *server The GGZ server object.* **Returns:** *The file descriptor of the connection socket.* **See also:** **ggzcore\_server\_connect** ### const char\* ggzcore\_server\_get\_handle (const GGZServer \* server) *Get the handle being used for this server.* **Parameters:** *server The GGZ server object.* **Returns:** *A string containing the handle, or NULL on error.* **See also:** **ggzcore\_server\_set\_logininfo** ### const char\* ggzcore\_server\_get\_host (const GGZServer \* server) *Get the hostname of the server.* **Parameters:** *server The GGZ server object.* **Returns:** *A string containing the host name, or NULL on error.* **See also:** **ggzcore\_server\_set\_hostinfo** ### int ggzcore\_server\_get\_num\_gametypes (const GGZServer \* server) *Return the overall number of game types on the server.* **Parameters:** *server The GGZ server object.* **Returns:** *The number of game types on this server, or -1 on error.* **Note:** *This number is 0 until* **See also:** **GGZ\_TYPE\_LIST***.* ### int ggzcore\_server\_get\_num\_players (const GGZServer \* server) *Get the total number of players on the server.* **Parameters:** *server The GGZ server object return An approximate number of players in all rooms of the server.* ### int ggzcore\_server\_get\_num\_rooms (const GGZServer \* server) *Return the number of rooms on the server, or -1 on error.* **Note:** *Until we retrieve the list of rooms, this will return 0.* ### const char\* ggzcore\_server\_get\_password (const GGZServer \* server) *Get the password being used for this server.* **Parameters:** *server The GGZ server object.* **Returns:** *A string containing the password, or NULL on error.* **See also:** **ggzcore\_server\_set\_logininfo** ### int ggzcore\_server\_get\_port (const GGZServer \* server) *Get the port of the server.* **Parameters:** *server The GGZ server object.* **Returns:** *The port number of the server, or -1 on error.* **See also:** **ggzcore\_server\_set\_hostinfo** ### GGZStateID ggzcore\_server\_get\_state (const GGZServer \* server) *Get the state of the server connection.* **Parameters:** *server The GGZ server object.* **Returns:** *The state of the connection, or -1 on error.* ### int ggzcore\_server\_get\_tls (const GGZServer \* server) *Get the current TLS status of this server.* **Parameters:** *server The GGZ server object* **Returns:** *Whether TLS is active or not* ### GGZLoginType ggzcore\_server\_get\_type (const GGZServer \* server) *Get the login type being used for this server.* **Parameters:** *server The GGZ server object.* **Returns:** *The login type set for the server, or -1 on error.* **See also:** **ggzcore\_server\_set\_logininfo** ### int ggzcore\_server\_join\_room (GGZServer \* server, const unsigned int room) *Join a room on the server.* **Parameters:** *server The GGZ server object.* \ *room The number of the room to join.* **Returns:** *0 on success, -1 on failure (e.g. non-existing room number).* ### int ggzcore\_server\_list\_gametypes (GGZServer \* server, const char verbose) *Request game type list.* **Parameters:** *server The GGZ server object.* \ *verbose Receive detailed gametype information or not.* **Returns:** *0 on success, -1 on failure.* **Note:** *A GGZ\_TYPE\_LIST event will be the asynchronous response on success.* ### int ggzcore\_server\_list\_rooms (GGZServer \* server, const int type, const char verbose) *Request room list.* **Parameters:** *server The GGZ server object.* \ *type Not used yet.* \ *verbose Receive all information about a room or only the essentials.* **Returns:** *0 on success, -1 on failure.* **Note:** *A GGZ\_ROOM\_LIST might be generated thereafter.* ### int ggzcore\_server\_log\_session (GGZServer \* server, const char \* filename) *Initiate logging of ggzcore events.* *Normally, ggzcore traffic is not logged anywhere. With this functions, such output can be directed into a file. It contains all the network messages received from the server.* **Parameters:** *server The GGZ server object.* \ *filename The file the messages are written to.* **Returns:** *0 on success, -1 on error.* ### int ggzcore\_server\_login (GGZServer \* server) *Log in to the server.* *Call this function to log in to the server once a connection has been established. Typically you must first connect to the server, then wait to receive the GGZ\_CONNECTED and GGZ\_NEGOTIATED events before attempting to log in. Login info is set using the ggzcore\_server\_set\_logininfo function.* *The function is asynchronous and will return immediately. After the login request is sent, we will wait to receive either a GGZ\_LOGGED\_IN or GGZ\_LOGIN\_FAIL server event.* **Parameters:** *server The GGZ server object.* **Returns:** *0 on success, -1 on failure.* **Note:** *On failure no events will be generated.* ### GGZServer\* ggzcore\_server\_new (void) *Create a new server object.* *Call this function to create a server object. This object holds all state data for communicating with a ggz server. It is necessary for any kind of connection.* ### int ggzcore\_server\_read\_data (GGZServer \* server, int fd) *Read data for the server on the specified FD.* **Returns:** *negative on error* ### int ggzcore\_server\_remove\_event\_hook (GGZServer \* server, const GGZServerEvent event, const GGZHookFunc func) *Remove a single hook function from an event's hook list.* **Parameters:** *server The GGZ server object.* \ *event The server event the hook is associated with.* \ *func The function to be removed from the hook list.* **Returns:** *0 on success (hook removed); -1 on failure (no hook removed)* **Note:** *At most one copy of the function will be removed.* **See also:** **ggzcore\_server\_remove\_event\_hook\_id** ### int ggzcore\_server\_remove\_event\_hook\_id (GGZServer \* server, const GGZServerEvent event, const unsigned int hook\_id) *Remove a hook function with given ID from the event's hook list.* **Parameters:** *server The GGZ server object.* \ *event The server event the hook is associated with.* \ *hook\_id The ID of the hook event.* **Returns:** *0 on success (hook removed); -1 on failure (no hook removed)* **Note:** *The hook ID is given by ggzcore\_server\_add\_event\_hook* ### int ggzcore\_server\_reset (GGZServer \* server) *Reset the server object.* *After you've disconnected, call this function to discard all state data and reset the state of the server object. You can then connect again.* **Note:** *You should disconnect before resetting.* ### int ggzcore\_server\_set\_hostinfo (GGZServer \* server, const char \* host, const unsigned int port, const unsigned int use\_tls) *Set host info for connecting to the server.* *Call this function to set host info for the GGZ server before trying to connect to it.* **Parameters:** *server The GGZ server object.* \ *host A string containing the hostname.* \ *port The port to connect to.* \ *use\_tls If set, the connection will be encrypted.* **Returns:** *0 on success, -1 on error.* **Note:** *Should never fail when given valid input.* **See also:** **ggzcore\_server\_connect** ### int ggzcore\_server\_set\_logininfo (GGZServer \* server, const GGZLoginType type, const char \* handle, const char \* password, const char \* email) *Set login info for logging in to the server.* *Call this function to set login info for the GGZ server before trying to login. This should only be called when the server is in certain states.* **Parameters:** *server The GGZ server object.* \ *type The type of login to attempt.* \ *handle The username to use with the server.* \ *password The password to use (may be NULL with some login types).* \ *email The email address to use (may be NULL with some login types).* **Returns:** *0 on success, -1 on error.* ### int ggzcore\_table\_get\_seat\_count (const GGZTable \* table, GGZSeatType type) *Count the seats of the given type.* *Given a table and a seat type, this function returns the number of seats at the table that match the type.* **Parameters:** *table A GGZ table.* \ *type A GGZSeatType.* **Returns:** *The number of seats matching the type, or -1 on error.* ### int ggzcore\_table\_init (GGZTable \* table, const GGZGameType \* gametype, const char \* desc, const unsigned int num\_seats) *Set data on a table object.* **Note:** *Useful when launching a game.* ### GGZTable\* ggzcore\_table\_new (void) *Create a new table object.* **Note:** *Useful when launching a game.* ### int ggzcore\_table\_set\_seat (GGZTable \* table, const unsigned int seat, GGZSeatType type, const char \* name) *Set a seat type at a table, pre-launch.* *When launching a table, call this function to set up a particular seat at the table. It can also be used to fiddle with already existing tables, but that would be extremely unwise.* **Parameters:** *table The table object to change.* \ *seat The seat number at the table to change.* \ *type The type of seat to make it (open, reserved, or bot).* \ *name The name of the seat (must be valid for reserved seats).* **Returns:** *0 on success, -1 on error.* **Todo** *How do we stop the GGZ client from fiddling with random tables?* ## Author *Generated automatically by Doxygen for GGZCore from the source code.*