.TH "ggzcore.h" 3 "21 May 2005" "Version 0.0.11" "GGZCore" \" -*- nroff -*- .ad l .nh .SH NAME ggzcore.h \- The interface for the ggzcore library used by GGZ clients. .SH SYNOPSIS .br .PP \fC#include \fP .br \fC#include \fP .br \fC#include \fP .br .SS "Defines" .in +1c .ti -1c .RI "#define \fBGGZCORE_VERSION_MAJOR\fP 0" .br .ti -1c .RI "#define \fBGGZCORE_VERSION_MINOR\fP 0" .br .ti -1c .RI "#define \fBGGZCORE_VERSION_MICRO\fP 11" .br .ti -1c .RI "#define \fBGGZCORE_VERSION_IFACE\fP '7:0:0'" .br .ti -1c .RI "#define \fBGGZCORE_DBG_CONF\fP 'GGZCORE:CONF'" .br .RI "\fIggz_debug debugging type for configuration system. \fP" .ti -1c .RI "#define \fBGGZCORE_DBG_GAME\fP 'GGZCORE:GAME'" .br .RI "\fIggz_debug debugging type for game communication. \fP" .ti -1c .RI "#define \fBGGZCORE_DBG_HOOK\fP 'GGZCORE:HOOK'" .br .RI "\fIggz_debug debugging type for hook system. \fP" .ti -1c .RI "#define \fBGGZCORE_DBG_MODULE\fP 'GGZCORE:MODULE'" .br .RI "\fIggz_debug debugging type for accessing modules. \fP" .ti -1c .RI "#define \fBGGZCORE_DBG_NET\fP 'GGZCORE:NET'" .br .RI "\fIggz_debug debugging type for network interaction. \fP" .ti -1c .RI "#define \fBGGZCORE_DBG_POLL\fP 'GGZCORE:POLL'" .br .RI "\fIggz_debug debugging type for debugging while polling. \fP" .ti -1c .RI "#define \fBGGZCORE_DBG_ROOM\fP 'GGZCORE:ROOM'" .br .RI "\fIggz_debug debugging type for room events and data. \fP" .ti -1c .RI "#define \fBGGZCORE_DBG_SERVER\fP 'GGZCORE:SERVER'" .br .RI "\fIggz_debug debugging type for server events and data. \fP" .ti -1c .RI "#define \fBGGZCORE_DBG_STATE\fP 'GGZCORE:STATE'" .br .RI "\fIggz_debug debugging type for state changes. \fP" .ti -1c .RI "#define \fBGGZCORE_DBG_TABLE\fP 'GGZCORE:TABLE'" .br .RI "\fIggz_debug debugging type for table data. \fP" .ti -1c .RI "#define \fBGGZCORE_DBG_XML\fP 'GGZCORE:XML'" .br .RI "\fIggz_debug debugging type for XML processing. \fP" .ti -1c .RI "#define \fBggzcore_server_get_channel\fP(server) (-1)" .br .RI "\fIDeprecated function. Do not use. \fP" .ti -1c .RI "#define \fBggzcore_server_create_channel\fP(server) (void)0" .br .RI "\fIDeprecated function. Do not use. \fP" .ti -1c .RI "#define \fBggzcore_module_launch\fP(m) ((int)(-1))" .br .ti -1c .RI "#define \fBggzcore_game_set_server_fd\fP(game, fd) (void)0" .br .RI "\fIDeprecated function. Do not use. \fP" .in -1c .SS "Typedefs" .in +1c .ti -1c .RI "typedef \fB_GGZOptions\fP \fBGGZOptions\fP" .br .ti -1c .RI "typedef \fBGGZHookReturn\fP(* \fBGGZHookFunc\fP )(unsigned int id, const void *event_data, const void *user_data)" .br .ti -1c .RI "typedef void(* \fBGGZDestroyFunc\fP )(void *data)" .br .RI "\fIGGZ object destroy function type. \fP" .ti -1c .RI "typedef _GGZServer \fBGGZServer\fP" .br .RI "\fIA server object containing all information about a connection. \fP" .ti -1c .RI "typedef _GGZRoom \fBGGZRoom\fP" .br .RI "\fIContains information about a single room on a server. \fP" .ti -1c .RI "typedef _GGZPlayer \fBGGZPlayer\fP" .br .RI "\fIContains information about a single player. \fP" .ti -1c .RI "typedef _GGZTable \fBGGZTable\fP" .br .RI "\fIContains information about a single table. \fP" .ti -1c .RI "typedef _GGZGameType \fBGGZGameType\fP" .br .RI "\fIContains information about a _game type_. \fP" .ti -1c .RI "typedef _GGZModule \fBGGZModule\fP" .br .RI "\fIContains 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. \fP" .ti -1c .RI "typedef _GGZGame \fBGGZGame\fP" .br .RI "\fIContains 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. \fP" .in -1c .SS "Enumerations" .in +1c .ti -1c .RI "enum \fBGGZOptionFlags\fP { \fBGGZ_OPT_PARSER\fP = 0x0001, \fBGGZ_OPT_MODULES\fP = 0x0002, \fBGGZ_OPT_THREADED_IO\fP = 0x0004, \fBGGZ_OPT_EMBEDDED\fP = 0x0008, \fBGGZ_OPT_RECONNECT\fP = 0x0010 }" .br .ti -1c .RI "enum \fBGGZHookReturn\fP { \fBGGZ_HOOK_OK\fP, \fBGGZ_HOOK_REMOVE\fP, \fBGGZ_HOOK_ERROR\fP, \fBGGZ_HOOK_CRISIS\fP }" .br .ti -1c .RI "enum \fBGGZLoginType\fP { \fBGGZ_LOGIN\fP, \fBGGZ_LOGIN_GUEST\fP, \fBGGZ_LOGIN_NEW\fP }" .br .ti -1c .RI "enum \fBGGZServerEvent\fP { \fBGGZ_CONNECTED\fP, \fBGGZ_CONNECT_FAIL\fP, \fBGGZ_NEGOTIATED\fP, \fBGGZ_NEGOTIATE_FAIL\fP, \fBGGZ_LOGGED_IN\fP, \fBGGZ_LOGIN_FAIL\fP, \fBGGZ_MOTD_LOADED\fP, \fBGGZ_ROOM_LIST\fP, \fBGGZ_TYPE_LIST\fP, \fBGGZ_SERVER_PLAYERS_CHANGED\fP, \fBGGZ_ENTERED\fP, \fBGGZ_ENTER_FAIL\fP, \fBGGZ_LOGOUT\fP, \fBGGZ_NET_ERROR\fP, \fBGGZ_PROTOCOL_ERROR\fP, \fBGGZ_CHAT_FAIL\fP, \fBGGZ_STATE_CHANGE\fP, \fBGGZ_CHANNEL_CONNECTED\fP, \fBGGZ_CHANNEL_READY\fP, \fBGGZ_CHANNEL_FAIL\fP, \fBGGZ_NUM_SERVER_EVENTS\fP }" .br .ti -1c .RI "enum \fBGGZRoomEvent\fP { \fBGGZ_PLAYER_LIST\fP, \fBGGZ_TABLE_LIST\fP, \fBGGZ_CHAT_EVENT\fP, \fBGGZ_ROOM_ENTER\fP, \fBGGZ_ROOM_LEAVE\fP, \fBGGZ_TABLE_UPDATE\fP, \fBGGZ_TABLE_LAUNCHED\fP, \fBGGZ_TABLE_LAUNCH_FAIL\fP, \fBGGZ_TABLE_JOINED\fP, \fBGGZ_TABLE_JOIN_FAIL\fP, \fBGGZ_TABLE_LEFT\fP, \fBGGZ_TABLE_LEAVE_FAIL\fP, \fBGGZ_PLAYER_LAG\fP, \fBGGZ_PLAYER_STATS\fP, \fBGGZ_PLAYER_COUNT\fP }" .br .ti -1c .RI "enum \fBGGZGameEvent\fP { \fBGGZ_GAME_LAUNCHED\fP, \fBGGZ_GAME_LAUNCH_FAIL\fP, \fBGGZ_GAME_NEGOTIATED\fP, \fBGGZ_GAME_NEGOTIATE_FAIL\fP, \fBGGZ_GAME_PLAYING\fP }" .br .ti -1c .RI "enum \fBGGZStateID\fP { \fBGGZ_STATE_OFFLINE\fP, \fBGGZ_STATE_CONNECTING\fP, \fBGGZ_STATE_RECONNECTING\fP, \fBGGZ_STATE_ONLINE\fP, \fBGGZ_STATE_LOGGING_IN\fP, \fBGGZ_STATE_LOGGED_IN\fP, \fBGGZ_STATE_ENTERING_ROOM\fP, \fBGGZ_STATE_IN_ROOM\fP, \fBGGZ_STATE_BETWEEN_ROOMS\fP, \fBGGZ_STATE_LAUNCHING_TABLE\fP, \fBGGZ_STATE_JOINING_TABLE\fP, \fBGGZ_STATE_AT_TABLE\fP, \fBGGZ_STATE_LEAVING_TABLE\fP, \fBGGZ_STATE_LOGGING_OUT\fP }" .br .RI "\fIThe states a server connection may be in. \fP" .ti -1c .RI "enum \fBGGZModuleEnvironment\fP { \fBGGZ_ENVIRONMENT_PASSIVE\fP, \fBGGZ_ENVIRONMENT_CONSOLE\fP, \fBGGZ_ENVIRONMENT_FRAMEBUFFER\fP, \fBGGZ_ENVIRONMENT_XWINDOW\fP, \fBGGZ_ENVIRONMENT_XFULLSCREEN\fP }" .br .RI "\fIThe environment a game frontend expects. \fP" .in -1c .SS "Functions" .in +1c .ti -1c .RI "int \fBggzcore_init\fP (\fBGGZOptions\fP options)" .br .ti -1c .RI "void \fBggzcore_reload\fP (void)" .br .ti -1c .RI "void \fBggzcore_destroy\fP (void)" .br .ti -1c .RI "\fBGGZServer\fP * \fBggzcore_server_new\fP (void)" .br .RI "\fICreate a new server object. \fP" .ti -1c .RI "int \fBggzcore_server_reset\fP (\fBGGZServer\fP *server)" .br .RI "\fIReset the server object. \fP" .ti -1c .RI "int \fBggzcore_server_add_event_hook\fP (\fBGGZServer\fP *server, const \fBGGZServerEvent\fP event, const \fBGGZHookFunc\fP func)" .br .RI "\fIRegister a callback handler for a server event. \fP" .ti -1c .RI "int \fBggzcore_server_add_event_hook_full\fP (\fBGGZServer\fP *server, const \fBGGZServerEvent\fP event, const \fBGGZHookFunc\fP func, const void *data)" .br .RI "\fIRegister a callback handler for a server event. \fP" .ti -1c .RI "int \fBggzcore_server_remove_event_hook\fP (\fBGGZServer\fP *server, const \fBGGZServerEvent\fP event, const \fBGGZHookFunc\fP func)" .br .RI "\fIRemove a single hook function from an event's hook list. \fP" .ti -1c .RI "int \fBggzcore_server_remove_event_hook_id\fP (\fBGGZServer\fP *server, const \fBGGZServerEvent\fP event, const unsigned int hook_id)" .br .RI "\fIRemove a hook function with given ID from the event's hook list. \fP" .ti -1c .RI "int \fBggzcore_server_set_hostinfo\fP (\fBGGZServer\fP *server, const char *host, const unsigned int port, const unsigned int use_tls)" .br .RI "\fISet host info for connecting to the server. \fP" .ti -1c .RI "int \fBggzcore_server_set_logininfo\fP (\fBGGZServer\fP *server, const \fBGGZLoginType\fP type, const char *handle, const char *password, const char *email)" .br .RI "\fISet login info for logging in to the server. \fP" .ti -1c .RI "int \fBggzcore_server_log_session\fP (\fBGGZServer\fP *server, const char *filename)" .br .RI "\fIInitiate logging of ggzcore events. \fP" .ti -1c .RI "const char * \fBggzcore_server_get_host\fP (const \fBGGZServer\fP *server)" .br .RI "\fIGet the hostname of the server. \fP" .ti -1c .RI "int \fBggzcore_server_get_port\fP (const \fBGGZServer\fP *server)" .br .RI "\fIGet the port of the server. \fP" .ti -1c .RI "\fBGGZLoginType\fP \fBggzcore_server_get_type\fP (const \fBGGZServer\fP *server)" .br .RI "\fIGet the login type being used for this server. \fP" .ti -1c .RI "const char * \fBggzcore_server_get_handle\fP (const \fBGGZServer\fP *server)" .br .RI "\fIGet the handle being used for this server. \fP" .ti -1c .RI "const char * \fBggzcore_server_get_password\fP (const \fBGGZServer\fP *server)" .br .RI "\fIGet the password being used for this server. \fP" .ti -1c .RI "int \fBggzcore_server_get_fd\fP (const \fBGGZServer\fP *server)" .br .RI "\fIGet the socket used for connection with the server. \fP" .ti -1c .RI "\fBGGZStateID\fP \fBggzcore_server_get_state\fP (const \fBGGZServer\fP *server)" .br .RI "\fIGet the state of the server connection. \fP" .ti -1c .RI "int \fBggzcore_server_get_tls\fP (const \fBGGZServer\fP *server)" .br .RI "\fIGet the current TLS status of this server. \fP" .ti -1c .RI "int \fBggzcore_server_get_num_players\fP (const \fBGGZServer\fP *server)" .br .RI "\fIGet the total number of players on the server. \fP" .ti -1c .RI "int \fBggzcore_server_get_num_rooms\fP (const \fBGGZServer\fP *server)" .br .RI "\fIReturn the number of rooms on the server, or -1 on error. \fP" .ti -1c .RI "\fBGGZRoom\fP * \fBggzcore_server_get_cur_room\fP (const \fBGGZServer\fP *server)" .br .RI "\fIReturn the current room, or NULL if there is none. \fP" .ti -1c .RI "\fBGGZRoom\fP * \fBggzcore_server_get_nth_room\fP (const \fBGGZServer\fP *server, const unsigned int num)" .br .RI "\fIReturn the nth room on the server, or NULL on error. \fP" .ti -1c .RI "int \fBggzcore_server_get_num_gametypes\fP (const \fBGGZServer\fP *server)" .br .RI "\fIReturn the overall number of game types on the server. \fP" .ti -1c .RI "\fBGGZGameType\fP * \fBggzcore_server_get_nth_gametype\fP (const \fBGGZServer\fP *server, const unsigned int num)" .br .RI "\fIGet the nth gametype, or NULL on error. \fP" .ti -1c .RI "\fBGGZGame\fP * \fBggzcore_server_get_cur_game\fP (const \fBGGZServer\fP *server)" .br .RI "\fIReturn the player's current game. \fP" .ti -1c .RI "int \fBggzcore_server_is_online\fP (const \fBGGZServer\fP *server)" .br .RI "\fIReturn TRUE iff the server is online (connected?). \fP" .ti -1c .RI "int \fBggzcore_server_is_logged_in\fP (const \fBGGZServer\fP *server)" .br .RI "\fIReturn TRUE iff we are logged into the server. \fP" .ti -1c .RI "int \fBggzcore_server_is_in_room\fP (const \fBGGZServer\fP *server)" .br .RI "\fIReturn TRUE iff we are in a room on the server. \fP" .ti -1c .RI "int \fBggzcore_server_is_at_table\fP (const \fBGGZServer\fP *server)" .br .RI "\fIReturn TRUE iff we are at a table on the server. \fP" .ti -1c .RI "int \fBggzcore_server_connect\fP (\fBGGZServer\fP *server)" .br .RI "\fIConnect to the server. \fP" .ti -1c .RI "int \fBggzcore_server_login\fP (\fBGGZServer\fP *server)" .br .RI "\fILog in to the server. \fP" .ti -1c .RI "int \fBggzcore_server_motd\fP (\fBGGZServer\fP *server)" .br .RI "\fIRequest the MOTD from the server. \fP" .ti -1c .RI "int \fBggzcore_server_list_rooms\fP (\fBGGZServer\fP *server, const int type, const char verbose)" .br .RI "\fIRequest room list. \fP" .ti -1c .RI "int \fBggzcore_server_list_gametypes\fP (\fBGGZServer\fP *server, const char verbose)" .br .RI "\fIRequest game type list. \fP" .ti -1c .RI "int \fBggzcore_server_join_room\fP (\fBGGZServer\fP *server, const unsigned int room)" .br .RI "\fIJoin a room on the server. \fP" .ti -1c .RI "int \fBggzcore_server_logout\fP (\fBGGZServer\fP *server)" .br .RI "\fILog out of a server. \fP" .ti -1c .RI "int \fBggzcore_server_disconnect\fP (\fBGGZServer\fP *server)" .br .RI "\fIDisconnect from a server after having logged out. \fP" .ti -1c .RI "int \fBggzcore_server_data_is_pending\fP (\fBGGZServer\fP *server)" .br .RI "\fICheck for data pending from the server socket. \fP" .ti -1c .RI "int \fBggzcore_server_read_data\fP (\fBGGZServer\fP *server, int fd)" .br .RI "\fIRead data for the server on the specified FD. \fP" .ti -1c .RI "void \fBggzcore_server_free\fP (\fBGGZServer\fP *server)" .br .RI "\fIFree GGZServer object and accompanying data. \fP" .ti -1c .RI "\fBGGZRoom\fP * \fBggzcore_room_new\fP (void)" .br .RI "\fIAllocate space for a new room object. \fP" .ti -1c .RI "int \fBggzcore_room_init\fP (\fBGGZRoom\fP *room, \fBGGZServer\fP *server, const unsigned int id, const char *name, const unsigned int game, const char *desc)" .br .RI "\fIInitialize room object. \fP" .ti -1c .RI "void \fBggzcore_room_free\fP (\fBGGZRoom\fP *room)" .br .RI "\fIDe-allocate room object and its children. \fP" .ti -1c .RI "\fBGGZServer\fP * \fBggzcore_room_get_server\fP (\fBGGZRoom\fP *room)" .br .RI "\fIReturn the server for this room (or NULL on error). \fP" .ti -1c .RI "int \fBggzcore_room_get_id\fP (const \fBGGZRoom\fP *room)" .br .RI "\fIReturn the ID number of the room (or negative on error). \fP" .ti -1c .RI "char * \fBggzcore_room_get_name\fP (\fBGGZRoom\fP *room)" .br .RI "\fIReturn the name of the room (or NULL on error). \fP" .ti -1c .RI "char * \fBggzcore_room_get_desc\fP (\fBGGZRoom\fP *room)" .br .RI "\fIReturn the description of the room (or NULL on error). \fP" .ti -1c .RI "\fBGGZGameType\fP * \fBggzcore_room_get_gametype\fP (\fBGGZRoom\fP *room)" .br .RI "\fIReturn the type of game played in this room (or NULL on error). \fP" .ti -1c .RI "int \fBggzcore_room_get_num_players\fP (\fBGGZRoom\fP *room)" .br .RI "\fIReturn the number of players in the room (or negative on error). \fP" .ti -1c .RI "\fBGGZPlayer\fP * \fBggzcore_room_get_nth_player\fP (\fBGGZRoom\fP *room, const unsigned int num)" .br .RI "\fIReturn the nth player in the room (or NULL on error). \fP" .ti -1c .RI "int \fBggzcore_room_get_num_tables\fP (\fBGGZRoom\fP *room)" .br .RI "\fIReturn the number of tables in the room (or negative on error). \fP" .ti -1c .RI "\fBGGZTable\fP * \fBggzcore_room_get_nth_table\fP (\fBGGZRoom\fP *room, const unsigned int num)" .br .RI "\fIReturn the nth table in the room (or NULL on error). \fP" .ti -1c .RI "\fBGGZTable\fP * \fBggzcore_room_get_table_by_id\fP (\fBGGZRoom\fP *room, const unsigned int id)" .br .RI "\fIReturn the table in this room with matching ID (NULL on error). \fP" .ti -1c .RI "int \fBggzcore_room_add_event_hook\fP (\fBGGZRoom\fP *room, const \fBGGZRoomEvent\fP event, const \fBGGZHookFunc\fP func)" .br .RI "\fIRegister a handler (hook) for the room event. \fP" .ti -1c .RI "int \fBggzcore_room_add_event_hook_full\fP (\fBGGZRoom\fP *room, const \fBGGZRoomEvent\fP event, const \fBGGZHookFunc\fP func, const void *data)" .br .RI "\fIRegister a handler (hook) for thee room event, with data. \fP" .ti -1c .RI "int \fBggzcore_room_remove_event_hook\fP (\fBGGZRoom\fP *room, const \fBGGZRoomEvent\fP event, const \fBGGZHookFunc\fP func)" .br .RI "\fIRemove a hook from an event. \fP" .ti -1c .RI "int \fBggzcore_room_remove_event_hook_id\fP (\fBGGZRoom\fP *room, const \fBGGZRoomEvent\fP event, const unsigned int hook_id)" .br .RI "\fIRemove a hook from an event, by ID. \fP" .ti -1c .RI "int \fBggzcore_room_list_players\fP (\fBGGZRoom\fP *room)" .br .RI "\fICall to request a list of players in the room. \fP" .ti -1c .RI "int \fBggzcore_room_list_tables\fP (\fBGGZRoom\fP *room, const int type, const char global)" .br .RI "\fICall to request a list of tables in the room. \fP" .ti -1c .RI "int \fBggzcore_room_chat\fP (\fBGGZRoom\fP *room, const GGZChatType opcode, const char *player, const char *msg)" .br .RI "\fIChat! \fP" .ti -1c .RI "int \fBggzcore_room_launch_table\fP (\fBGGZRoom\fP *room, \fBGGZTable\fP *table)" .br .RI "\fILaunch a table in the room. \fP" .ti -1c .RI "int \fBggzcore_room_join_table\fP (\fBGGZRoom\fP *room, const unsigned int table_id, int spectator)" .br .RI "\fIJoin a table in the room, so that you can then play at it. \fP" .ti -1c .RI "int \fBggzcore_room_leave_table\fP (\fBGGZRoom\fP *room, int force)" .br .RI "\fILeave the table you are currently playing at. \fP" .ti -1c .RI "char * \fBggzcore_player_get_name\fP (const \fBGGZPlayer\fP *player)" .br .RI "\fIReturn the name of the player. \fP" .ti -1c .RI "GGZPlayerType \fBggzcore_player_get_type\fP (const \fBGGZPlayer\fP *player)" .br .RI "\fIReturn the type of the player (admin/registered/guest). \fP" .ti -1c .RI "\fBGGZRoom\fP * \fBggzcore_player_get_room\fP (const \fBGGZPlayer\fP *player)" .br .RI "\fIReturn the player's room, or NULL if none. \fP" .ti -1c .RI "\fBGGZTable\fP * \fBggzcore_player_get_table\fP (const \fBGGZPlayer\fP *player)" .br .RI "\fIReturn the player's table, or NULL if none. \fP" .ti -1c .RI "int \fBggzcore_player_get_lag\fP (const \fBGGZPlayer\fP *player)" .br .RI "\fIReturn the player's lag class (1..5). \fP" .ti -1c .RI "int \fBggzcore_player_get_record\fP (const \fBGGZPlayer\fP *player, int *wins, int *losses, int *ties, int *forfeits)" .br .RI "\fIGet the player's win-loss record. \fP" .ti -1c .RI "int \fBggzcore_player_get_rating\fP (const \fBGGZPlayer\fP *player, int *rating)" .br .RI "\fIGet the player's rating. \fP" .ti -1c .RI "int \fBggzcore_player_get_ranking\fP (const \fBGGZPlayer\fP *player, int *ranking)" .br .RI "\fIGet the player's ranking. \fP" .ti -1c .RI "int \fBggzcore_player_get_highscore\fP (const \fBGGZPlayer\fP *player, int *highscore)" .br .RI "\fIGet the player's highscore. \fP" .ti -1c .RI "\fBGGZTable\fP * \fBggzcore_table_new\fP (void)" .br .RI "\fICreate a new table object. \fP" .ti -1c .RI "int \fBggzcore_table_init\fP (\fBGGZTable\fP *table, const \fBGGZGameType\fP *gametype, const char *desc, const unsigned int num_seats)" .br .RI "\fISet data on a table object. \fP" .ti -1c .RI "void \fBggzcore_table_free\fP (\fBGGZTable\fP *table)" .br .RI "\fIFree the table object. \fP" .ti -1c .RI "int \fBggzcore_table_set_seat\fP (\fBGGZTable\fP *table, const unsigned int seat, GGZSeatType type, const char *name)" .br .RI "\fISet a seat type at a table, pre-launch. \fP" .ti -1c .RI "int \fBggzcore_table_remove_player\fP (\fBGGZTable\fP *table, char *name)" .br .RI "\fIFind and remove the player from the table. \fP" .ti -1c .RI "int \fBggzcore_table_get_id\fP (const \fBGGZTable\fP *table)" .br .RI "\fIReturn the ID of the table. \fP" .ti -1c .RI "const \fBGGZRoom\fP * \fBggzcore_table_get_room\fP (const \fBGGZTable\fP *table)" .br .RI "\fIReturn the room this table is in. \fP" .ti -1c .RI "const \fBGGZGameType\fP * \fBggzcore_table_get_type\fP (const \fBGGZTable\fP *table)" .br .RI "\fIReturn the game type of the table. \fP" .ti -1c .RI "const char * \fBggzcore_table_get_desc\fP (const \fBGGZTable\fP *table)" .br .RI "\fIReturn the table's description (or NULL). \fP" .ti -1c .RI "GGZTableState \fBggzcore_table_get_state\fP (const \fBGGZTable\fP *table)" .br .RI "\fIReturn the state of the table. \fP" .ti -1c .RI "int \fBggzcore_table_get_num_seats\fP (const \fBGGZTable\fP *table)" .br .RI "\fIReturn the number of seats at the table. \fP" .ti -1c .RI "int \fBggzcore_table_set_desc\fP (\fBGGZTable\fP *table, const char *desc)" .br .RI "\fISet the table description. \fP" .ti -1c .RI "int \fBggzcore_table_get_seat_count\fP (const \fBGGZTable\fP *table, GGZSeatType type)" .br .RI "\fICount the seats of the given type. \fP" .ti -1c .RI "const char * \fBggzcore_table_get_nth_player_name\fP (const \fBGGZTable\fP *table, const unsigned int num)" .br .RI "\fIReturn the name of a player at the table, or NULL on error. \fP" .ti -1c .RI "int \fBggzcore_table_get_num_spectator_seats\fP (const \fBGGZTable\fP *table)" .br .RI "\fIReturn the number of spectator seats at the table, or -1. \fP" .ti -1c .RI "const char * \fBggzcore_table_get_nth_spectator_name\fP (const \fBGGZTable\fP *table, const unsigned int num)" .br .RI "\fIReturn the name of the nth spectator, or NULL if seat is empty. \fP" .ti -1c .RI "GGZSeatType \fBggzcore_table_get_nth_player_type\fP (const \fBGGZTable\fP *table, const unsigned int num)" .br .RI "\fIReturn the type of a player at the table, or GGZ_PLAYER_NONE on error. \fP" .ti -1c .RI "unsigned int \fBggzcore_gametype_get_id\fP (const \fBGGZGameType\fP *type)" .br .RI "\fIGet the ID of this gametype. \fP" .ti -1c .RI "const char * \fBggzcore_gametype_get_name\fP (const \fBGGZGameType\fP *type)" .br .RI "\fIGet the name of the game type. \fP" .ti -1c .RI "const char * \fBggzcore_gametype_get_prot_engine\fP (const \fBGGZGameType\fP *type)" .br .RI "\fIGet the protocol 'engine' used by the game type. \fP" .ti -1c .RI "const char * \fBggzcore_gametype_get_prot_version\fP (const \fBGGZGameType\fP *type)" .br .RI "\fIGet the version of the protocol the game uses. \fP" .ti -1c .RI "const char * \fBggzcore_gametype_get_version\fP (const \fBGGZGameType\fP *type)" .br .RI "\fIGet the version of the game itself. \fP" .ti -1c .RI "const char * \fBggzcore_gametype_get_author\fP (const \fBGGZGameType\fP *type)" .br .RI "\fIGet the author of the game. \fP" .ti -1c .RI "const char * \fBggzcore_gametype_get_url\fP (const \fBGGZGameType\fP *type)" .br .RI "\fIGet a URL for more info about the game. \fP" .ti -1c .RI "const char * \fBggzcore_gametype_get_desc\fP (const \fBGGZGameType\fP *type)" .br .RI "\fIGet a description of the game. \fP" .ti -1c .RI "int \fBggzcore_gametype_get_max_players\fP (const \fBGGZGameType\fP *type)" .br .RI "\fIGet the maximum number of players the game can support. \fP" .ti -1c .RI "int \fBggzcore_gametype_get_max_bots\fP (const \fBGGZGameType\fP *type)" .br .RI "\fIGet the maximum number of bots the game can support. \fP" .ti -1c .RI "int \fBggzcore_gametype_get_spectators_allowed\fP (const \fBGGZGameType\fP *type)" .br .RI "\fIReturn TRUE iff spectators are allowed for this game type. \fP" .ti -1c .RI "int \fBggzcore_gametype_num_players_is_valid\fP (const \fBGGZGameType\fP *type, unsigned int num)" .br .RI "\fIReturn TRUE iff the given number of players is valid. \fP" .ti -1c .RI "int \fBggzcore_gametype_num_bots_is_valid\fP (const \fBGGZGameType\fP *type, unsigned int num)" .br .RI "\fIReturn TRUE iff the given number of bots is valid. \fP" .ti -1c .RI "int \fBggzcore_conf_initialize\fP (const char *g_path, const char *u_path)" .br .ti -1c .RI "int \fBggzcore_conf_write_string\fP (const char *section, const char *key, const char *value)" .br .ti -1c .RI "int \fBggzcore_conf_write_int\fP (const char *section, const char *key, int value)" .br .ti -1c .RI "int \fBggzcore_conf_write_list\fP (const char *section, const char *key, int argc, char **argv)" .br .ti -1c .RI "char * \fBggzcore_conf_read_string\fP (const char *section, const char *key, const char *def)" .br .ti -1c .RI "int \fBggzcore_conf_read_int\fP (const char *section, const char *key, int def)" .br .ti -1c .RI "int \fBggzcore_conf_read_list\fP (const char *section, const char *key, int *argcp, char ***argvp)" .br .ti -1c .RI "int \fBggzcore_conf_remove_section\fP (const char *section)" .br .ti -1c .RI "int \fBggzcore_conf_remove_key\fP (const char *section, const char *key)" .br .ti -1c .RI "int \fBggzcore_conf_commit\fP (void)" .br .ti -1c .RI "unsigned int \fBggzcore_module_get_num\fP (void)" .br .RI "\fIThis returns the number of registered modules. \fP" .ti -1c .RI "int \fBggzcore_module_add\fP (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, \fBGGZModuleEnvironment\fP environment)" .br .ti -1c .RI "int \fBggzcore_module_get_num_by_type\fP (const char *game, const char *engine, const char *version)" .br .RI "\fIReturns how many modules support this game and protocol. \fP" .ti -1c .RI "\fBGGZModule\fP * \fBggzcore_module_get_nth_by_type\fP (const char *game, const char *engine, const char *version, const unsigned int num)" .br .RI "\fIReturns n-th module that supports this game and protocol. \fP" .ti -1c .RI "const char * \fBggzcore_module_get_name\fP (\fBGGZModule\fP *module)" .br .RI "\fIReturn the name of the module. \fP" .ti -1c .RI "const char * \fBggzcore_module_get_version\fP (\fBGGZModule\fP *module)" .br .RI "\fIReturn the (game?) version of the module. \fP" .ti -1c .RI "const char * \fBggzcore_module_get_prot_engine\fP (\fBGGZModule\fP *module)" .br .RI "\fIReturn the name of the module's protocol engine. \fP" .ti -1c .RI "const char * \fBggzcore_module_get_prot_version\fP (\fBGGZModule\fP *module)" .br .RI "\fIReturn the version of the module's protocol engine. \fP" .ti -1c .RI "const char * \fBggzcore_module_get_author\fP (\fBGGZModule\fP *module)" .br .RI "\fIReturn the author of the module. \fP" .ti -1c .RI "const char * \fBggzcore_module_get_frontend\fP (\fBGGZModule\fP *module)" .br .RI "\fIReturn the module's frontend type. \fP" .ti -1c .RI "const char * \fBggzcore_module_get_url\fP (\fBGGZModule\fP *module)" .br .RI "\fIReturn the URL associated with the module. \fP" .ti -1c .RI "const char * \fBggzcore_module_get_icon_path\fP (\fBGGZModule\fP *module)" .br .ti -1c .RI "const char * \fBggzcore_module_get_help_path\fP (\fBGGZModule\fP *module)" .br .RI "\fIReturn the help path of the module (?). \fP" .ti -1c .RI "char ** \fBggzcore_module_get_argv\fP (\fBGGZModule\fP *module)" .br .RI "\fIReturn the executable arguments for the module. See exec(). \fP" .ti -1c .RI "\fBGGZModuleEnvironment\fP \fBggzcore_module_get_environment\fP (\fBGGZModule\fP *module)" .br .RI "\fIReturn the preferred environment type. \fP" .ti -1c .RI "\fBGGZGame\fP * \fBggzcore_game_new\fP (void)" .br .RI "\fIMake a new game object. \fP" .ti -1c .RI "int \fBggzcore_game_init\fP (\fBGGZGame\fP *game, \fBGGZServer\fP *server, \fBGGZModule\fP *module)" .br .RI "\fIInitialize the game object. \fP" .ti -1c .RI "void \fBggzcore_game_free\fP (\fBGGZGame\fP *game)" .br .RI "\fIFree the game object. \fP" .ti -1c .RI "int \fBggzcore_game_add_event_hook\fP (\fBGGZGame\fP *game, const \fBGGZGameEvent\fP event, const \fBGGZHookFunc\fP func)" .br .RI "\fIRegister a hook for a game event. \fP" .ti -1c .RI "int \fBggzcore_game_add_event_hook_full\fP (\fBGGZGame\fP *game, const \fBGGZGameEvent\fP event, const \fBGGZHookFunc\fP func, const void *data)" .br .RI "\fIRegister a hook for a game event. \fP" .ti -1c .RI "int \fBggzcore_game_remove_event_hook\fP (\fBGGZGame\fP *game, const \fBGGZGameEvent\fP event, const \fBGGZHookFunc\fP func)" .br .RI "\fIRemove a hook from a game event. \fP" .ti -1c .RI "int \fBggzcore_game_remove_event_hook_id\fP (\fBGGZGame\fP *game, const \fBGGZGameEvent\fP event, const unsigned int hook_id)" .br .RI "\fIRemove a specified hook from a game event. \fP" .ti -1c .RI "int \fBggzcore_game_get_control_fd\fP (\fBGGZGame\fP *game)" .br .RI "\fIReturn the control (ggzmod) socket for the game. \fP" .ti -1c .RI "\fBGGZModule\fP * \fBggzcore_game_get_module\fP (\fBGGZGame\fP *game)" .br .RI "\fIReturn the module set for the game. \fP" .ti -1c .RI "int \fBggzcore_game_launch\fP (\fBGGZGame\fP *game)" .br .RI "\fILaunch thee game! \fP" .ti -1c .RI "int \fBggzcore_game_read_data\fP (\fBGGZGame\fP *game)" .br .RI "\fIRead data from the game. When data is pending on the control socket, call this function. \fP" .in -1c .SH "Detailed Description" .PP The interface for the ggzcore library used by GGZ clients. .SH "Define Documentation" .PP .SS "#define ggzcore_module_launch(m) ((int)(-1))" .PP This attempts to launch the specified module and returns 0 if successful or -1 on error. .SH "Typedef Documentation" .PP .SS "typedef void(* \fBGGZDestroyFunc\fP)(void *data)" .PP GGZ object destroy function type. .PP \fBTodo\fP .RS 4 This is not currently used. .RE .PP .SS "typedef struct _GGZGameType \fBGGZGameType\fP" .PP Contains information about a _game type_. .PP \fBNote:\fP .RS 4 Each room has one game type; a game may be used in multiple rooms. .RE .PP .SS "typedef \fBGGZHookReturn\fP(* \fBGGZHookFunc\fP)(unsigned int id, const void *event_data, const void *user_data)" .PP GGZ Event hook function type, used as a vallback for events .SS "typedef struct \fB_GGZOptions\fP \fBGGZOptions\fP" .PP Options structure for ggzcore library .SH "Enumeration Type Documentation" .PP .SS "enum \fBGGZGameEvent\fP" .PP 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. .PP \fBSee also:\fP .RS 4 \fBggzcore_game_add_event_hook\fP .PP \fBggzcore_server_read_data\fP .RE .PP .PP \fBEnumeration values: \fP .in +1c .TP \fB\fIGGZ_GAME_LAUNCHED \fP\fP 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. .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_game_launch\fP .RE .PP .TP \fB\fIGGZ_GAME_LAUNCH_FAIL \fP\fP Your game launch has failed. Triggered instead of GGZ_GAME_LAUNCHED when there's a failure somewhere. .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP \fBSee also:\fP .RS 4 \fBGGZ_GAME_LAUNCHED\fP .RE .PP .TP \fB\fIGGZ_GAME_NEGOTIATED \fP\fP Negotiation with server was successful. This should happen some time after the launch succeeds. The core client need do nothing at this point. .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP .TP \fB\fIGGZ_GAME_NEGOTIATE_FAIL \fP\fP Negotiation was not successful, game launch failed. .PP \fBTodo\fP .RS 4 Currently this can't actually happen... .RE .PP .TP \fB\fIGGZ_GAME_PLAYING \fP\fP 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. .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP .SS "enum \fBGGZHookReturn\fP" .PP GGZ Hook function return types .PP \fBEnumeration values: \fP .in +1c .TP \fB\fIGGZ_HOOK_OK \fP\fP Success! .TP \fB\fIGGZ_HOOK_REMOVE \fP\fP Remove this hook immediately. .TP \fB\fIGGZ_HOOK_ERROR \fP\fP A localized error. .TP \fB\fIGGZ_HOOK_CRISIS \fP\fP A major error; stop processing the event. .SS "enum \fBGGZLoginType\fP" .PP This controls the type of login a user chooses. A different value will require different information to be sent to the server. .PP \fBEnumeration values: \fP .in +1c .TP \fB\fIGGZ_LOGIN \fP\fP Standard login; uname and correct passwd needed. .TP \fB\fIGGZ_LOGIN_GUEST \fP\fP Guest login; only a uname is required. .TP \fB\fIGGZ_LOGIN_NEW \fP\fP New user login; only a uname is required. Password will be assigned by the server (but can be passed along). .SS "enum \fBGGZModuleEnvironment\fP" .PP The environment a game frontend expects. .PP Core clients should offer those game modules which fit their own environment. .PP \fBEnumeration values: \fP .in +1c .TP \fB\fIGGZ_ENVIRONMENT_PASSIVE \fP\fP No GUI, no interaction with user .TP \fB\fIGGZ_ENVIRONMENT_CONSOLE \fP\fP Text console .TP \fB\fIGGZ_ENVIRONMENT_FRAMEBUFFER \fP\fP VESA or framebuffer .TP \fB\fIGGZ_ENVIRONMENT_XWINDOW \fP\fP X11 windowed mode (default) .TP \fB\fIGGZ_ENVIRONMENT_XFULLSCREEN \fP\fP X11 fullscreen mode .SS "enum \fBGGZOptionFlags\fP" .PP \fBEnumeration values: \fP .in +1c .TP \fB\fIGGZ_OPT_MODULES \fP\fP Load the default configuration file (unused). .TP \fB\fIGGZ_OPT_THREADED_IO \fP\fP Load the game module list. .TP \fB\fIGGZ_OPT_EMBEDDED \fP\fP Provide multi-threaded network IO (unused). .TP \fB\fIGGZ_OPT_RECONNECT \fP\fP Reconnect automatically after connection loss. .SS "enum \fBGGZRoomEvent\fP" .PP 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. .PP \fBSee also:\fP .RS 4 \fBggzcore_room_add_event_hook\fP .PP \fBggzcore_server_read_data\fP .RE .PP .PP \fBEnumeration values: \fP .in +1c .TP \fB\fIGGZ_PLAYER_LIST \fP\fP The list of players in a room has arrived. .PP \fBParameters:\fP .RS 4 \fIdata\fP The room id (int *) .RE .PP \fBNote:\fP .RS 4 This will only be issued for the current room. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_room_list_players\fP .RE .PP .TP \fB\fIGGZ_TABLE_LIST \fP\fP Received the list of active tables. .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_room_list_tables\fP .RE .PP .TP \fB\fIGGZ_CHAT_EVENT \fP\fP Received a chat message of any kind. This can happen at any time when you're in a room. .PP \fBParameters:\fP .RS 4 \fIdata\fP The \fBGGZChatEventData\fP associated with the chat. .RE .PP \fBSee also:\fP .RS 4 \fBGGZChatEventData\fP .RE .PP .TP \fB\fIGGZ_ROOM_ENTER \fP\fP A player has entered the room with you. .PP \fBParameters:\fP .RS 4 \fIdata\fP A \fBGGZRoomChangeEventData\fP structure. .RE .PP .TP \fB\fIGGZ_ROOM_LEAVE \fP\fP A player has left your room. .PP \fBParameters:\fP .RS 4 \fIdata\fP A \fBGGZRoomChangeEventData\fP structure. .RE .PP .TP \fB\fIGGZ_TABLE_UPDATE \fP\fP One of the tables in the current room has changed. .PP \fBTodo\fP .RS 4 How are you supposed to know which table has changed? .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP .RE .PP .TP \fB\fIGGZ_TABLE_LAUNCHED \fP\fP The table you tried to launch has launched! .PP \fBSee also:\fP .RS 4 \fBggzcore_room_launch_table\fP .RE .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP .TP \fB\fIGGZ_TABLE_LAUNCH_FAIL \fP\fP The table you tried to launch couldn't be launched .PP \fBSee also:\fP .RS 4 \fBGGZ_TABLE_LAUNCHED\fP .RE .PP \fBParameters:\fP .RS 4 \fIdata\fP A pointer to a \fBGGZErrorEventData\fP .RE .PP .TP \fB\fIGGZ_TABLE_JOINED \fP\fP Your table join attempt has succeeded. .PP \fBSee also:\fP .RS 4 \fBggzcore_room_join_table\fP .RE .PP \fBParameters:\fP .RS 4 \fIdata\fP The table index (int*) of the table we joined. .RE .PP .TP \fB\fIGGZ_TABLE_JOIN_FAIL \fP\fP Joining a table did not succeed. .PP \fBSee also:\fP .RS 4 \fBGGZ_TABLE_JOINED\fP .RE .PP \fBParameters:\fP .RS 4 \fIdata\fP A helpful error string. .RE .PP .TP \fB\fIGGZ_TABLE_LEFT \fP\fP You have successfully left the table you were at. .PP \fBSee also:\fP .RS 4 \fBggzcore_room_leave_table\fP .RE .PP \fBParameters:\fP .RS 4 \fIdata\fP The \fBGGZTableLeaveEventData\fP associated with the leave. .RE .PP \fBSee also:\fP .RS 4 \fBGGZTableLeaveEventData\fP .RE .PP .TP \fB\fIGGZ_TABLE_LEAVE_FAIL \fP\fP Your attempt to leave the table has failed. .PP \fBSee also:\fP .RS 4 \fBGGZ_TABLE_LEFT\fP .RE .PP \fBParameters:\fP .RS 4 \fIdata\fP A helpful error string. .RE .PP .TP \fB\fIGGZ_PLAYER_LAG \fP\fP A player's lag (measure of connection speed) has been updated .PP \fBSee also:\fP .RS 4 \fBggzcore_player_get_lag\fP .RE .PP \fBParameters:\fP .RS 4 \fIdata\fP The name of the player whose lag has changed. .RE .PP .TP \fB\fIGGZ_PLAYER_STATS \fP\fP A player's stats have been updated. .PP \fBSee also:\fP .RS 4 \fBGGZ_PLAYER_LIST\fP .PP \fBggzcore_player_get_record\fP .PP \fBggzcore_player_get_rating\fP .PP \fBggzcore_player_get_ranking\fP .PP \fBggzcore_player_get_highscore\fP .RE .PP \fBParameters:\fP .RS 4 \fIdata\fP The name of the player whose stats have changed. .RE .PP .TP \fB\fIGGZ_PLAYER_COUNT \fP\fP The number of players in a room has arrived. .PP \fBParameters:\fP .RS 4 \fIdata\fP The room id (int *) .RE .PP .SS "enum \fBGGZServerEvent\fP" .PP 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. .PP \fBSee also:\fP .RS 4 \fBggzcore_server_add_event_hook\fP .RE .PP .PP \fBEnumeration values: \fP .in +1c .TP \fB\fIGGZ_CONNECTED \fP\fP 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! .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_connect\fP .RE .PP .TP \fB\fIGGZ_CONNECT_FAIL \fP\fP 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. .PP \fBParameters:\fP .RS 4 \fIdata\fP An error string (created by strerror) .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_connect\fP .RE .PP .TP \fB\fIGGZ_NEGOTIATED \fP\fP We have negotiated a connection to the server. This will happen automatically once a connection has been established, if the server socket is monitored. .PP \fBNote:\fP .RS 4 This just means we've determined ggzd is at the other end. .RE .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_NEGOTIATE_FAIL \fP\fP 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. .PP \fBParameters:\fP .RS 4 \fIdata\fP A useless error string. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_LOGGED_IN \fP\fP We have successfully logged in. We can now start doing stuff. This will not happen until the client sends their login information. .PP \fBSee also:\fP .RS 4 \fBggzcore_server_login\fP .RE .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_LOGIN_FAIL \fP\fP Error: login failure. This will happen in place of GGZ_LOGGED_IN if the login failed. The server object will be otherwise unaffected. .PP \fBParameters:\fP .RS 4 \fIdata\fP A pointer to a \fBGGZErrorEventData\fP. .RE .PP \fBSee also:\fP .RS 4 \fBGGZErrorEventData\fP .PP \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_MOTD_LOADED \fP\fP 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. .PP \fBParameters:\fP .RS 4 \fIdata\fP Pointer to a \fBGGZMotdEventData\fP including the full MOTD text. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_motd\fP .RE .PP \fBTodo\fP .RS 4 The MOTD cannot be accessed outside of this event .PP \fBSee also:\fP .RS 4 ggzcore_server_read_data! .RE .PP .RE .PP .TP \fB\fIGGZ_ROOM_LIST \fP\fP The room list arrived. This will only happen after the list is requested by \fBggzcore_server_list_rooms()\fP. The list may be accessed through \fBggzcore_server_get_num_rooms()\fP and \fBggzcore_server_get_nth_room()\fP. Until this event arrives these functions will be useless! .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_TYPE_LIST \fP\fP 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 \fBggzcore_server_get_num_gametypes()\fP and \fBggzcore_server_get_nth_gametype()\fP. Until this event arrives these functions will be useless! .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_SERVER_PLAYERS_CHANGED \fP\fP The number of players on the server has changed. This event is issued rather frequently every time players enter or leave. .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_get_num_players\fP .PP \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_ENTERED \fP\fP We have successfully entered a room. This will be issued to tell us a room join has succeeded, after it has been requested. .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_join_room\fP .PP \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_ENTER_FAIL \fP\fP Error: we have tried to enter a room and failed. This will be issued to tell us a room join has failed. .PP \fBParameters:\fP .RS 4 \fIdata\fP A pointer to a \fBGGZErrorEventData\fP. .RE .PP \fBSee also:\fP .RS 4 \fBGGZErrorEventData\fP .PP \fBggzcore_server_join_room\fP .PP \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_LOGOUT \fP\fP Logged out of the server. This will happen when the server completes the communication; usually after ggzcore_net_send_logout is called. .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_NET_ERROR \fP\fP Error: a network (transmission) error occurred. The server will automatically disconnect. .PP \fBParameters:\fP .RS 4 \fIdata\fP A generally unhelpful error string. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_PROTOCOL_ERROR \fP\fP 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. .PP \fBParameters:\fP .RS 4 \fIdata\fP A technical error string. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_CHAT_FAIL \fP\fP Error: A chat message could not be sent. This will happen when we try to send a chat and the server rejects it. .PP \fBParameters:\fP .RS 4 \fIdata\fP A pointer to a \fBGGZErrorEventData\fP. .RE .PP \fBSee also:\fP .RS 4 \fBGGZErrorEventData\fP .PP \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_STATE_CHANGE \fP\fP The internal state of ggzcore has changed. This may happen at any time. .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP \fBSee also:\fP .RS 4 \fBGGZStateID\fP .PP \fBggzcore_server_get_state\fP .RE .PP .TP \fB\fIGGZ_CHANNEL_CONNECTED \fP\fP 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. .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP \fBNote:\fP .RS 4 This event is deprecated and should not be used. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_get_channel\fP .PP \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_CHANNEL_READY \fP\fP 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. .PP \fBParameters:\fP .RS 4 \fIdata\fP NULL .RE .PP \fBNote:\fP .RS 4 This event is deprecated and should not be used. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_CHANNEL_FAIL \fP\fP 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). .PP \fBParameters:\fP .RS 4 \fIdata\fP An unhelpful error string .RE .PP \fBNote:\fP .RS 4 This event is deprecated and should not be used. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_read_data\fP .RE .PP .TP \fB\fIGGZ_NUM_SERVER_EVENTS \fP\fP Terminator. Do not use. .SS "enum \fBGGZStateID\fP" .PP The states a server connection may be in. .PP 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. .PP \fBEnumeration values: \fP .in +1c .TP \fB\fIGGZ_STATE_OFFLINE \fP\fP Not connected (at all) .TP \fB\fIGGZ_STATE_CONNECTING \fP\fP In the process of connecting. .TP \fB\fIGGZ_STATE_RECONNECTING \fP\fP Continuous reconnection attempts. .TP \fB\fIGGZ_STATE_ONLINE \fP\fP Connected, but not doing anything. .TP \fB\fIGGZ_STATE_LOGGING_IN \fP\fP In the process of logging in. .TP \fB\fIGGZ_STATE_LOGGED_IN \fP\fP Online and logged in! .TP \fB\fIGGZ_STATE_ENTERING_ROOM \fP\fP Moving into a room. .TP \fB\fIGGZ_STATE_IN_ROOM \fP\fP Online, logged in, and in a room. .TP \fB\fIGGZ_STATE_BETWEEN_ROOMS \fP\fP Moving between rooms. .TP \fB\fIGGZ_STATE_LAUNCHING_TABLE \fP\fP Trying to launch a table. .TP \fB\fIGGZ_STATE_JOINING_TABLE \fP\fP Trying to join a table. .TP \fB\fIGGZ_STATE_AT_TABLE \fP\fP Online, loggied in, in a room, at a table. .TP \fB\fIGGZ_STATE_LEAVING_TABLE \fP\fP Waiting to leave a table. .TP \fB\fIGGZ_STATE_LOGGING_OUT \fP\fP In the process of logging out. .SH "Function Documentation" .PP .SS "int ggzcore_conf_commit (void)" .PP \fBggzcore_conf_commit()\fP - Commits the core user config file to disk .PP \fBReturns:\fP .RS 4 : int : 0 if successful, -1 on error .RE .PP .SS "int ggzcore_conf_initialize (const char * g_path, const char * u_path)" .PP \fBggzcore_conf_initialize()\fP 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. .PP \fBReturns:\fP .RS 4 : 0 on success, negative on failure .RE .PP .SS "int ggzcore_conf_read_int (const char * section, const char * key, int def)" .PP \fBggzcore_conf_read_int()\fP - Read a integer from the configuration file(s) .PP \fBParameters:\fP .RS 4 \fIsection\fP section to get value from .br \fIkey\fP key value was stored under .br \fIdef\fP default value to return if none is found .RE .PP \fBReturns:\fP .RS 4 an integer from the configuration file OR the default value .RE .PP \fBNote:\fP .RS 4 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. .RE .PP .SS "int ggzcore_conf_read_list (const char * section, const char * key, int * argcp, char *** argvp)" .PP \fBggzcore_conf_read_list()\fP - Read a list from the configuration file(s) .PP \fBParameters:\fP .RS 4 \fIsection\fP section to get value from .br \fIkey\fP key value was stored under .br \fIargcp\fP ptr to int which will receive the list entry count .br \fIargvp\fP a pointer to a dynamically allocated array that \fBggzcore_conf_read_list()\fP will build .RE .PP \fBReturns:\fP .RS 4 int : 0 if successful, -1 on error .RE .PP .SS "char* ggzcore_conf_read_string (const char * section, const char * key, const char * def)" .PP \fBggzcore_conf_read_string()\fP - Read a string from the configuration file(s) .PP \fBParameters:\fP .RS 4 \fIsection\fP section to get value from .br \fIkey\fP key value was stored under .br \fIdef\fP default value to return if none is found .RE .PP \fBReturns:\fP .RS 4 a dynamically allocated string from the configuration file OR a dynamically allocated copy of the default string .RE .PP \fBNote:\fP .RS 4 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. .RE .PP .SS "int ggzcore_conf_remove_key (const char * section, const char * key)" .PP \fBggzcore_conf_remove_key()\fP - Removes a key entry from the user config file .PP \fBParameters:\fP .RS 4 \fIsection\fP section to remove .br \fIkey\fP key entry to remove .RE .PP \fBReturns:\fP .RS 4 int : 0 if success, -1 on error, 1 on soft error (section/key didn't exist) .RE .PP .SS "int ggzcore_conf_remove_section (const char * section)" .PP \fBggzcore_conf_remove_section()\fP - Removes a section from the user config file .PP \fBParameters:\fP .RS 4 \fIsection\fP section to remove .RE .PP \fBReturns:\fP .RS 4 int : 0 if successful, -1 on error, 1 on soft error (section did not exist) .RE .PP .SS "int ggzcore_conf_write_int (const char * section, const char * key, int value)" .PP \fBggzcore_conf_write_int()\fP - Write a integer to the user config file .PP \fBParameters:\fP .RS 4 \fIsection\fP section to store value in .br \fIkey\fP key to store value under .br \fIvalue\fP value to store .RE .PP \fBReturns:\fP .RS 4 int : 0 if successful, -1 on error .RE .PP .SS "int ggzcore_conf_write_list (const char * section, const char * key, int argc, char ** argv)" .PP \fBggzcore_conf_write_list()\fP - Write a list to the user config file .PP \fBParameters:\fP .RS 4 \fIsection\fP section to store value in .br \fIkey\fP key to store value under .br \fIargc\fP count of string arguments in list .br \fIargv\fP array of NULL terminated strings .RE .PP \fBReturns:\fP .RS 4 int : 0 if successful, -1 on error .RE .PP .SS "int ggzcore_conf_write_string (const char * section, const char * key, const char * value)" .PP \fBggzcore_conf_write_string()\fP - Write a string to the user config file .PP \fBParameters:\fP .RS 4 \fIsection\fP section to store value in .br \fIkey\fP key to store value under .br \fIvalue\fP value to store .RE .PP \fBReturns:\fP .RS 4 int : 0 if successful, -1 on error .RE .PP .SS "void ggzcore_destroy (void)" .PP \fBggzcore_destroy()\fP - Cleanup function for ggzcore lib. .SS "int ggzcore_game_add_event_hook (\fBGGZGame\fP * game, const \fBGGZGameEvent\fP event, const \fBGGZHookFunc\fP func)" .PP Register a hook for a game event. .PP \fBSee also:\fP .RS 4 \fBggzcore_server_add_event_hook\fP .PP \fBggzcore_room_add_event_hook\fP .RE .PP .SS "int ggzcore_game_add_event_hook_full (\fBGGZGame\fP * game, const \fBGGZGameEvent\fP event, const \fBGGZHookFunc\fP func, const void * data)" .PP Register a hook for a game event. .PP \fBSee also:\fP .RS 4 \fBggzcore_server_add_event_hook_full\fP .PP \fBggzcore_room_add_event_hook_full\fP .RE .PP .SS "int ggzcore_game_read_data (\fBGGZGame\fP * game)" .PP Read data from the game. When data is pending on the control socket, call this function. .PP \fBReturns:\fP .RS 4 negative on error .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_game_get_control_fd\fP .RE .PP .SS "int ggzcore_game_remove_event_hook (\fBGGZGame\fP * game, const \fBGGZGameEvent\fP event, const \fBGGZHookFunc\fP func)" .PP Remove a hook from a game event. .PP \fBSee also:\fP .RS 4 \fBggzcore_server_remove_event_hook\fP .PP \fBggzcore_room_remove_event_hook\fP .RE .PP .SS "int ggzcore_game_remove_event_hook_id (\fBGGZGame\fP * game, const \fBGGZGameEvent\fP event, const unsigned int hook_id)" .PP Remove a specified hook from a game event. .PP \fBSee also:\fP .RS 4 \fBggzcore_server_remove_event_hook_id\fP .PP \fBggzcore_room_remove_event_hook_id\fP .RE .PP .SS "unsigned int ggzcore_gametype_get_id (const \fBGGZGameType\fP * type)" .PP Get the ID of this gametype. .PP \fBNote:\fP .RS 4 This is not normally useful for a GGZ client to know. .RE .PP .SS "int ggzcore_gametype_get_max_bots (const \fBGGZGameType\fP * type)" .PP Get the maximum number of bots the game can support. .PP \fBSee also:\fP .RS 4 ggzcore_gametype_bots_is_valid .RE .PP .SS "int ggzcore_gametype_get_max_players (const \fBGGZGameType\fP * type)" .PP Get the maximum number of players the game can support. .PP \fBSee also:\fP .RS 4 \fBggzcore_gametype_num_players_is_valid\fP .RE .PP .SS "int ggzcore_init (\fBGGZOptions\fP options)" .PP \fBggzcore_init()\fP - Initializtion function for ggzcore lib. .PP \fBParameters:\fP .RS 4 \fIoptions\fP options structure .RE .PP \fBReturns:\fP .RS 4 int : 0 if successful, -1 on failure .RE .PP .SS "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, \fBGGZModuleEnvironment\fP environment)" .PP This adds a local module to the list. It returns 0 if successful or -1 on failure. .SS "const char* ggzcore_module_get_icon_path (\fBGGZModule\fP * module)" .PP This is (intended to be) an optional xpm file that the module can provide to use for representing the game graphically. .SS "int ggzcore_player_get_highscore (const \fBGGZPlayer\fP * player, int * highscore)" .PP Get the player's highscore. .PP \fBReturns:\fP .RS 4 TRUE if there is a highscore; FALSE if not or on error. .RE .PP .SS "int ggzcore_player_get_ranking (const \fBGGZPlayer\fP * player, int * ranking)" .PP Get the player's ranking. .PP \fBReturns:\fP .RS 4 TRUE if there is a ranking; FALSE if not or on error. .RE .PP .SS "int ggzcore_player_get_rating (const \fBGGZPlayer\fP * player, int * rating)" .PP Get the player's rating. .PP \fBReturns:\fP .RS 4 TRUE if there is a rating; FALSE if not or on error. .RE .PP .SS "int ggzcore_player_get_record (const \fBGGZPlayer\fP * player, int * wins, int * losses, int * ties, int * forfeits)" .PP Get the player's win-loss record. .PP \fBReturns:\fP .RS 4 TRUE if there is a record; FALSE if not or on error. .RE .PP .SS "void ggzcore_reload (void)" .PP \fBggzcore_reload()\fP - Reload game module database .SS "int ggzcore_room_add_event_hook (\fBGGZRoom\fP * room, const \fBGGZRoomEvent\fP event, const \fBGGZHookFunc\fP func)" .PP Register a handler (hook) for the room event. .PP 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). .PP \fBParameters:\fP .RS 4 \fIroom\fP The room object to associate the hook with. .br \fIevent\fP The event the handler is going to be 'hooked' onto. .br \fIfunc\fP The event handler itself. This is called during the event. .RE .PP \fBReturns:\fP .RS 4 The hook ID, or negative on error. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_room_add_event_hook_full\fP .PP \fBggzcore_room_remove_event_hook\fP .PP \fBggzcore_room_remove_event_hook_id\fP .RE .PP .SS "int ggzcore_room_add_event_hook_full (\fBGGZRoom\fP * room, const \fBGGZRoomEvent\fP event, const \fBGGZHookFunc\fP func, const void * data)" .PP Register a handler (hook) for thee room event, with data. .PP 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. .PP \fBParameters:\fP .RS 4 \fIroom\fP The room object to associate the hook with. .br \fIevent\fP The event the handler is going to be 'hooked' onto. .br \fIfunc\fP The event handler itself. This is called during the event. .br \fIdata\fP The user data associated with the hook. .RE .PP \fBReturns:\fP .RS 4 The hook ID, or negative on error. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_room_add_event_hook\fP .RE .PP .SS "int ggzcore_room_chat (\fBGGZRoom\fP * room, const GGZChatType opcode, const char * player, const char * msg)" .PP Chat! .PP \fBParameters:\fP .RS 4 \fIroom\fP Your current room. .br \fIopcode\fP The chat type. .br \fIplayer\fP The name of the target player (only for certain chat types) .br \fImsg\fP The text of the chat message (some chat types don't need it) .RE .PP \fBReturns:\fP .RS 4 0 on success, negative on (any) failure .RE .PP \fBNote:\fP .RS 4 The chat message should be in UTF-8. .RE .PP .SS "int ggzcore_room_join_table (\fBGGZRoom\fP * room, const unsigned int table_id, int spectator)" .PP Join a table in the room, so that you can then play at it. .PP \fBParameters:\fP .RS 4 \fIroom\fP Your current room. .br \fItable_id\fP The table to join. .br \fIspectator\fP TRUE if you wish to spectate, FALSE if you want to play .RE .PP \fBReturns:\fP .RS 4 0 on success, negative on (any) failure .RE .PP .SS "int ggzcore_room_launch_table (\fBGGZRoom\fP * room, \fBGGZTable\fP * table)" .PP Launch a table in the room. .PP 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. .PP \fBParameters:\fP .RS 4 \fIroom\fP Your current room. .br \fItable\fP The table to launch. .RE .PP \fBReturns:\fP .RS 4 0 on success, negative on (any) failure .RE .PP .SS "int ggzcore_room_leave_table (\fBGGZRoom\fP * room, int force)" .PP Leave the table you are currently playing at. .PP 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. .PP \fBParameters:\fP .RS 4 \fIroom\fP Your current room. .br \fIforce\fP TRUE to force the leave, FALSE to leave it up to ggzd .RE .PP \fBReturns:\fP .RS 4 0 on success, negative on (any) failure .RE .PP .SS "int ggzcore_room_list_players (\fBGGZRoom\fP * room)" .PP Call to request a list of players in the room. .PP \fBSee also:\fP .RS 4 \fBGGZ_PLAYER_LIST\fP .RE .PP .SS "int ggzcore_room_list_tables (\fBGGZRoom\fP * room, const int type, const char global)" .PP Call to request a list of tables in the room. .PP \fBParameters:\fP .RS 4 \fIroom\fP Your current room .br \fItype\fP currently ignored (???) .br \fIglobal\fP currently ignored (???) .RE .PP \fBSee also:\fP .RS 4 \fBGGZ_TABLE_LIST\fP .RE .PP .SS "int ggzcore_room_remove_event_hook (\fBGGZRoom\fP * room, const \fBGGZRoomEvent\fP event, const \fBGGZHookFunc\fP func)" .PP Remove a hook from an event. .PP 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. .PP \fBParameters:\fP .RS 4 \fIroom\fP The room object to associate the hook with. .br \fIevent\fP The event the handler is to be unhooked from. .br \fIfunc\fP The event handler function to remove. .RE .PP \fBReturns:\fP .RS 4 0 on success, negative on failure. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_room_add_event_hook\fP .RE .PP .SS "int ggzcore_room_remove_event_hook_id (\fBGGZRoom\fP * room, const \fBGGZRoomEvent\fP event, const unsigned int hook_id)" .PP Remove a hook from an event, by ID. .PP 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. .PP \fBParameters:\fP .RS 4 \fIroom\fP The room object to associate the hook with. .br \fIevent\fP The event the handler is to be unhooked from. .br \fIid\fP The ID of the hook to remove, as returned by the add function return 0 on success, negative on failure .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_room_add_event_hook\fP .RE .PP .SS "int ggzcore_server_add_event_hook (\fBGGZServer\fP * server, const \fBGGZServerEvent\fP event, const \fBGGZHookFunc\fP func)" .PP Register a callback handler for a server event. .PP 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. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .br \fIevent\fP The server event to be handled. .br \fIfunc\fP The handler function to be called when the event occurs. .RE .PP \fBReturns:\fP .RS 4 A hook ID value to identify this handler. .RE .PP \fBNote:\fP .RS 4 Equivalent to ggzcore_server_add_event_hook_full with data==NULL. .PP More than one handler can be registered for each event. .RE .PP .SS "int ggzcore_server_add_event_hook_full (\fBGGZServer\fP * server, const \fBGGZServerEvent\fP event, const \fBGGZHookFunc\fP func, const void * data)" .PP Register a callback handler for a server event. .PP \fBSee also:\fP .RS 4 \fBggzcore_server_add_event_hook\fP .RE .PP \fBParameters:\fP .RS 4 \fIdata\fP An arbitrary pointer that will be passed to the hook function. .RE .PP .SS "int ggzcore_server_connect (\fBGGZServer\fP * server)" .PP Connect to the server. .PP Call this function to initially connect to a GGZ server. Connection info is set using the ggzcore_server_set_hostinfo function. .PP 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. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .RE .PP \fBReturns:\fP .RS 4 0 on success, -1 on failure. .RE .PP \fBNote:\fP .RS 4 On success a GGZ_CONNECTED event will be generated. .PP On failure a GGZ_CONNECT_FAIL event may or may not be generated. .RE .PP .SS "int ggzcore_server_get_fd (const \fBGGZServer\fP * server)" .PP Get the socket used for connection with the server. .PP This returns the file descriptor of the primary socket for the TCP connection to the server. All GGZ data goes across this socket. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .RE .PP \fBReturns:\fP .RS 4 The file descriptor of the connection socket. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_connect\fP .RE .PP .SS "const char* ggzcore_server_get_handle (const \fBGGZServer\fP * server)" .PP Get the handle being used for this server. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .RE .PP \fBReturns:\fP .RS 4 A string containing the handle, or NULL on error. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_set_logininfo\fP .RE .PP .SS "const char* ggzcore_server_get_host (const \fBGGZServer\fP * server)" .PP Get the hostname of the server. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .RE .PP \fBReturns:\fP .RS 4 A string containing the host name, or NULL on error. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_set_hostinfo\fP .RE .PP .SS "int ggzcore_server_get_num_gametypes (const \fBGGZServer\fP * server)" .PP Return the overall number of game types on the server. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .RE .PP \fBReturns:\fP .RS 4 The number of game types on this server, or -1 on error. .RE .PP \fBNote:\fP .RS 4 This number is 0 until .RE .PP \fBSee also:\fP .RS 4 \fBGGZ_TYPE_LIST\fP. .RE .PP .SS "int ggzcore_server_get_num_players (const \fBGGZServer\fP * server)" .PP Get the total number of players on the server. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object return An approximate number of players in all rooms of the server. .RE .PP .SS "int ggzcore_server_get_num_rooms (const \fBGGZServer\fP * server)" .PP Return the number of rooms on the server, or -1 on error. .PP \fBNote:\fP .RS 4 Until we retrieve the list of rooms, this will return 0. .RE .PP .SS "const char* ggzcore_server_get_password (const \fBGGZServer\fP * server)" .PP Get the password being used for this server. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .RE .PP \fBReturns:\fP .RS 4 A string containing the password, or NULL on error. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_set_logininfo\fP .RE .PP .SS "int ggzcore_server_get_port (const \fBGGZServer\fP * server)" .PP Get the port of the server. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .RE .PP \fBReturns:\fP .RS 4 The port number of the server, or -1 on error. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_set_hostinfo\fP .RE .PP .SS "\fBGGZStateID\fP ggzcore_server_get_state (const \fBGGZServer\fP * server)" .PP Get the state of the server connection. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .RE .PP \fBReturns:\fP .RS 4 The state of the connection, or -1 on error. .RE .PP .SS "int ggzcore_server_get_tls (const \fBGGZServer\fP * server)" .PP Get the current TLS status of this server. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object .RE .PP \fBReturns:\fP .RS 4 Whether TLS is active or not .RE .PP .SS "\fBGGZLoginType\fP ggzcore_server_get_type (const \fBGGZServer\fP * server)" .PP Get the login type being used for this server. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .RE .PP \fBReturns:\fP .RS 4 The login type set for the server, or -1 on error. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_set_logininfo\fP .RE .PP .SS "int ggzcore_server_join_room (\fBGGZServer\fP * server, const unsigned int room)" .PP Join a room on the server. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .br \fIroom\fP The number of the room to join. .RE .PP \fBReturns:\fP .RS 4 0 on success, -1 on failure (e.g. non-existing room number). .RE .PP .SS "int ggzcore_server_list_gametypes (\fBGGZServer\fP * server, const char verbose)" .PP Request game type list. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .br \fIverbose\fP Receive detailed gametype information or not. .RE .PP \fBReturns:\fP .RS 4 0 on success, -1 on failure. .RE .PP \fBNote:\fP .RS 4 A GGZ_TYPE_LIST event will be the asynchronous response on success. .RE .PP .SS "int ggzcore_server_list_rooms (\fBGGZServer\fP * server, const int type, const char verbose)" .PP Request room list. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .br \fItype\fP Not used yet. .br \fIverbose\fP Receive all information about a room or only the essentials. .RE .PP \fBReturns:\fP .RS 4 0 on success, -1 on failure. .RE .PP \fBNote:\fP .RS 4 A GGZ_ROOM_LIST might be generated thereafter. .RE .PP .SS "int ggzcore_server_log_session (\fBGGZServer\fP * server, const char * filename)" .PP Initiate logging of ggzcore events. .PP 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. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .br \fIfilename\fP The file the messages are written to. .RE .PP \fBReturns:\fP .RS 4 0 on success, -1 on error. .RE .PP .SS "int ggzcore_server_login (\fBGGZServer\fP * server)" .PP Log in to the server. .PP 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. .PP 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. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .RE .PP \fBReturns:\fP .RS 4 0 on success, -1 on failure. .RE .PP \fBNote:\fP .RS 4 On failure no events will be generated. .RE .PP .SS "\fBGGZServer\fP* ggzcore_server_new (void)" .PP Create a new server object. .PP 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. .SS "int ggzcore_server_read_data (\fBGGZServer\fP * server, int fd)" .PP Read data for the server on the specified FD. .PP \fBReturns:\fP .RS 4 negative on error .RE .PP .SS "int ggzcore_server_remove_event_hook (\fBGGZServer\fP * server, const \fBGGZServerEvent\fP event, const \fBGGZHookFunc\fP func)" .PP Remove a single hook function from an event's hook list. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .br \fIevent\fP The server event the hook is associated with. .br \fIfunc\fP The function to be removed from the hook list. .RE .PP \fBReturns:\fP .RS 4 0 on success (hook removed); -1 on failure (no hook removed) .RE .PP \fBNote:\fP .RS 4 At most one copy of the function will be removed. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_remove_event_hook_id\fP .RE .PP .SS "int ggzcore_server_remove_event_hook_id (\fBGGZServer\fP * server, const \fBGGZServerEvent\fP event, const unsigned int hook_id)" .PP Remove a hook function with given ID from the event's hook list. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .br \fIevent\fP The server event the hook is associated with. .br \fIhook_id\fP The ID of the hook event. .RE .PP \fBReturns:\fP .RS 4 0 on success (hook removed); -1 on failure (no hook removed) .RE .PP \fBNote:\fP .RS 4 The hook ID is given by ggzcore_server_add_event_hook .RE .PP .SS "int ggzcore_server_reset (\fBGGZServer\fP * server)" .PP Reset the server object. .PP 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. .PP \fBNote:\fP .RS 4 You should disconnect before resetting. .RE .PP .SS "int ggzcore_server_set_hostinfo (\fBGGZServer\fP * server, const char * host, const unsigned int port, const unsigned int use_tls)" .PP Set host info for connecting to the server. .PP Call this function to set host info for the GGZ server before trying to connect to it. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .br \fIhost\fP A string containing the hostname. .br \fIport\fP The port to connect to. .br \fIuse_tls\fP If set, the connection will be encrypted. .RE .PP \fBReturns:\fP .RS 4 0 on success, -1 on error. .RE .PP \fBNote:\fP .RS 4 Should never fail when given valid input. .RE .PP \fBSee also:\fP .RS 4 \fBggzcore_server_connect\fP .RE .PP .SS "int ggzcore_server_set_logininfo (\fBGGZServer\fP * server, const \fBGGZLoginType\fP type, const char * handle, const char * password, const char * email)" .PP Set login info for logging in to the server. .PP 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. .PP \fBParameters:\fP .RS 4 \fIserver\fP The GGZ server object. .br \fItype\fP The type of login to attempt. .br \fIhandle\fP The username to use with the server. .br \fIpassword\fP The password to use (may be NULL with some login types). .br \fIemail\fP The email address to use (may be NULL with some login types). .RE .PP \fBReturns:\fP .RS 4 0 on success, -1 on error. .RE .PP .SS "int ggzcore_table_get_seat_count (const \fBGGZTable\fP * table, GGZSeatType type)" .PP Count the seats of the given type. .PP Given a table and a seat type, this function returns the number of seats at the table that match the type. .PP \fBParameters:\fP .RS 4 \fItable\fP A GGZ table. .br \fItype\fP A GGZSeatType. .RE .PP \fBReturns:\fP .RS 4 The number of seats matching the type, or -1 on error. .RE .PP .SS "int ggzcore_table_init (\fBGGZTable\fP * table, const \fBGGZGameType\fP * gametype, const char * desc, const unsigned int num_seats)" .PP Set data on a table object. .PP \fBNote:\fP .RS 4 Useful when launching a game. .RE .PP .SS "\fBGGZTable\fP* ggzcore_table_new (void)" .PP Create a new table object. .PP \fBNote:\fP .RS 4 Useful when launching a game. .RE .PP .SS "int ggzcore_table_set_seat (\fBGGZTable\fP * table, const unsigned int seat, GGZSeatType type, const char * name)" .PP Set a seat type at a table, pre-launch. .PP 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. .PP \fBParameters:\fP .RS 4 \fItable\fP The table object to change. .br \fIseat\fP The seat number at the table to change. .br \fItype\fP The type of seat to make it (open, reserved, or bot). .br \fIname\fP The name of the seat (must be valid for reserved seats). .RE .PP \fBReturns:\fP .RS 4 0 on success, -1 on error. .RE .PP \fBTodo\fP .RS 4 How do we stop the GGZ client from fiddling with random tables? .RE .PP .SH "Author" .PP Generated automatically by Doxygen for GGZCore from the source code.