ggzcore_h man page on OpenSuSE

Man page or keyword search:  
man Server   25941 pages
apropos Keyword Search (all sections)
Output format
OpenSuSE logo
[printable version]

ggzcore.h(3)			    GGZCore			  ggzcore.h(3)

NAME
       ggzcore.h - The interface for the ggzcore library used by GGZ clients.

SYNOPSIS
       #include <stdarg.h>
       #include <sys/types.h>
       #include <ggz_common.h>

   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.

Version 0.0.11			  21 May 2005			  ggzcore.h(3)
[top]

List of man pages available for OpenSuSE

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net