ggzcore.h

Go to the documentation of this file.

/*
 * File: ggzcore.h
 * Author: GGZ Development Team
 * Project: GGZ Core Client Lib
 * Date: 9/15/00
 * $Id: ggzcore.h 9073 2007-04-29 01:09:54Z jdorje $
 *
 * Interface file to be included by client frontends
 *
 * Copyright (C) 2000-2005 GGZ Development Team.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */


#ifndef __GGZCORE_H__
#define __GGZCORE_H__

#define GGZCORE_VERSION_MAJOR 0
#define GGZCORE_VERSION_MINOR 0
#define GGZCORE_VERSION_MICRO 14
#define GGZCORE_VERSION_IFACE "9:0:0"

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

#include <ggz_common.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Definitions and enumerations */
/* ---------------------------- */

#define GGZCORE_DBG_CONF   "GGZCORE:CONF"

#define GGZCORE_DBG_GAME   "GGZCORE:GAME"

#define GGZCORE_DBG_HOOK   "GGZCORE:HOOK"

#define GGZCORE_DBG_MODULE "GGZCORE:MODULE"

#define GGZCORE_DBG_NET    "GGZCORE:NET"

#define GGZCORE_DBG_POLL   "GGZCORE:POLL"

#define GGZCORE_DBG_ROOM   "GGZCORE:ROOM"

#define GGZCORE_DBG_SERVER "GGZCORE:SERVER"

#define GGZCORE_DBG_STATE  "GGZCORE:STATE"

#define GGZCORE_DBG_TABLE  "GGZCORE:TABLE"

#define GGZCORE_DBG_XML    "GGZCORE:XML"

/* GGZCore library features */
typedef enum {
    GGZ_OPT_PARSER      = 0x0001, /* %0000 0000 */ 
    GGZ_OPT_MODULES     = 0x0002, /* %0000 0010 */ 
    GGZ_OPT_THREADED_IO = 0x0004, /* %0000 0100 */ 
    GGZ_OPT_EMBEDDED    = 0x0008, /* %0000 1000 */ 
    GGZ_OPT_RECONNECT   = 0x0010  /* %0001 0000 */ 
} GGZOptionFlags;


typedef struct _GGZOptions {
    
    GGZOptionFlags flags;

} GGZOptions;


int ggzcore_init(GGZOptions options);


void ggzcore_reload(void);

void ggzcore_destroy(void);


/* Definitions for all internal ggzcore structures. */

typedef struct _GGZServer   GGZServer;

typedef struct _GGZRoom     GGZRoom;

typedef struct _GGZPlayer   GGZPlayer;

typedef struct _GGZTable    GGZTable;

typedef struct _GGZGameType GGZGameType;

typedef struct _GGZModule   GGZModule;

typedef struct _GGZGame     GGZGame;

typedef enum {
    GGZ_HOOK_OK, 
    GGZ_HOOK_REMOVE, 
    GGZ_HOOK_ERROR, 
    GGZ_HOOK_CRISIS 
} GGZHookReturn;

typedef GGZHookReturn (*GGZHookFunc)(unsigned int id, 
                     const void* event_data, 
                     const void* user_data);

typedef void (*GGZDestroyFunc)(void* data);


typedef enum {
    GGZ_LOGIN,
    
    GGZ_LOGIN_GUEST,
    
    GGZ_LOGIN_NEW
} GGZLoginType;


typedef struct {
    GGZClientReqError status;

    const char *message;
} GGZErrorEventData;

typedef struct {
    const char *motd; 
    const char *url; 
} GGZMotdEventData;

typedef enum {
    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_SERVER_ROOMS_CHANGED,

    GGZ_NUM_SERVER_EVENTS
} GGZServerEvent;

typedef struct {
    GGZChatType type; 
    const char *sender; 
    const char *message; 
} GGZChatEventData;

typedef struct {
    GGZLeaveType reason;

    const char *player;
} GGZTableLeaveEventData;

typedef struct {
    const char *player_name;

    /* If this value is false (0) then any NULL rooms (below) mean that
       the room is actually not known.  This should only happen when
       connecting to an older server. */
    int rooms_known;

    GGZRoom *to_room;

    GGZRoom *from_room;
} GGZRoomChangeEventData;

typedef enum {
    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,

    GGZ_PLAYER_PERMS
} GGZRoomEvent;


typedef enum {
    GGZ_GAME_LAUNCHED,

    GGZ_GAME_LAUNCH_FAIL,

    GGZ_GAME_NEGOTIATED,

    GGZ_GAME_NEGOTIATE_FAIL,

    GGZ_GAME_PLAYING
} GGZGameEvent;


typedef enum {
    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 
} GGZStateID;


typedef enum {
    GGZ_ENVIRONMENT_PASSIVE, 
    GGZ_ENVIRONMENT_CONSOLE, 
    GGZ_ENVIRONMENT_FRAMEBUFFER, 
    GGZ_ENVIRONMENT_XWINDOW, 
    GGZ_ENVIRONMENT_XFULLSCREEN 
} GGZModuleEnvironment;

/* Server object related functions */
/* ------------------------------- */

GGZServer* ggzcore_server_new(void);

int ggzcore_server_reset(GGZServer *server);

/*
 * Functions for attaching hooks to GGZServer events
 */

int ggzcore_server_add_event_hook(GGZServer *server,
                  const GGZServerEvent event, 
                  const GGZHookFunc func);

int ggzcore_server_add_event_hook_full(GGZServer *server,
                       const GGZServerEvent event, 
                       const GGZHookFunc func,
                       const void *data);

int ggzcore_server_remove_event_hook(GGZServer *server,
                     const GGZServerEvent event, 
                     const GGZHookFunc func);

int ggzcore_server_remove_event_hook_id(GGZServer *server,
                    const GGZServerEvent event, 
                    const unsigned int hook_id);

/*
 * Functions for setting GGZServer data
 */

int ggzcore_server_set_hostinfo(GGZServer *server,
                const char *host,
                const unsigned int port,
                const unsigned int use_tls);

int ggzcore_server_set_logininfo(GGZServer *server,
                 const GGZLoginType type,
                 const char *handle,
                 const char *password,
                 const char *email);

int ggzcore_server_log_session(GGZServer *server, const char *filename);


/* Functions for querying a GGZServer object for information */
/* --------------------------------------------------------- */

const char* ggzcore_server_get_host(const GGZServer *server);

int ggzcore_server_get_port(const GGZServer *server);

GGZLoginType ggzcore_server_get_type(const GGZServer *server);

const char* ggzcore_server_get_handle(const GGZServer *server);

const char* ggzcore_server_get_password(const GGZServer *server);

int ggzcore_server_get_fd(const GGZServer *server);

int ggzcore_server_get_channel(GGZServer *server);

GGZStateID ggzcore_server_get_state(const GGZServer *server);

int ggzcore_server_get_tls(const GGZServer *server);

int ggzcore_server_get_num_players(const GGZServer *server);

int ggzcore_server_get_num_rooms(const GGZServer *server);

GGZRoom* ggzcore_server_get_nth_room(const GGZServer *server, 
                     const unsigned int num);

int ggzcore_server_get_room_num(const GGZServer *server,
                const GGZRoom *room);

GGZRoom* ggzcore_server_get_cur_room(const GGZServer *server);

GGZPlayer* ggzcore_server_get_player(GGZServer *server, const char *name);

int ggzcore_server_get_num_gametypes(const GGZServer *server);

GGZGameType* ggzcore_server_get_nth_gametype(const GGZServer *server, 
                         const unsigned int num);

GGZGame* ggzcore_server_get_cur_game(const GGZServer *server);

int ggzcore_server_is_online(const GGZServer *server);

int ggzcore_server_is_logged_in(const GGZServer *server);

int ggzcore_server_is_in_room(const GGZServer *server);

int ggzcore_server_is_at_table(const GGZServer *server);

/* GGZ Server Actions */
/* ------------------ */

int ggzcore_server_connect(GGZServer *server);

int ggzcore_server_create_channel(GGZServer *server);

int ggzcore_server_login(GGZServer *server);

int ggzcore_server_motd(GGZServer *server);

int ggzcore_server_list_rooms(GGZServer *server, const int type, const char verbose);

int ggzcore_server_list_gametypes(GGZServer *server, const char verbose);

int ggzcore_server_join_room(GGZServer *server, GGZRoom *room);

int ggzcore_server_logout(GGZServer *server);

int ggzcore_server_disconnect(GGZServer *server);


/* Functions for data processing */
int ggzcore_server_data_is_pending(GGZServer *server);

int ggzcore_server_read_data(GGZServer *server, int fd);

void ggzcore_server_free(GGZServer *server);


/* Functions for manipulating GGZRoom objects */
/* ------------------------------------------ */

GGZRoom* ggzcore_room_new(void);

void ggzcore_room_free(GGZRoom *room);


GGZServer *ggzcore_room_get_server(const GGZRoom *room);

const char* ggzcore_room_get_name(const GGZRoom *room);

const char* ggzcore_room_get_desc(const GGZRoom *room);

GGZGameType* ggzcore_room_get_gametype(const GGZRoom *room);

int ggzcore_room_get_num_players(const GGZRoom *room);

GGZPlayer* ggzcore_room_get_nth_player(const GGZRoom *room,
                       const unsigned int num);

int ggzcore_room_get_num_tables(const GGZRoom *room);

GGZTable* ggzcore_room_get_nth_table(const GGZRoom *room,
                     const unsigned int num);

GGZTable* ggzcore_room_get_table_by_id(const GGZRoom *room,
                       const unsigned int id);

int ggzcore_room_get_closed(const GGZRoom *room);


int ggzcore_room_add_event_hook(GGZRoom *room,
                const GGZRoomEvent event, 
                const GGZHookFunc func);

int ggzcore_room_add_event_hook_full(GGZRoom *room,
                     const GGZRoomEvent event, 
                     const GGZHookFunc func,
                     const void *data);

int ggzcore_room_remove_event_hook(GGZRoom *room,
                   const GGZRoomEvent event, 
                   const GGZHookFunc func);

int ggzcore_room_remove_event_hook_id(GGZRoom *room,
                      const GGZRoomEvent event, 
                      const unsigned int hook_id);


int ggzcore_room_list_players(GGZRoom *room);

int ggzcore_room_list_tables(GGZRoom *room,
                 const int type,
                 const char global);

int ggzcore_room_chat(GGZRoom *room,
              const GGZChatType opcode,
              const char *player,
              const char *msg);

int ggzcore_room_admin(GGZRoom *room,
                   GGZAdminType type,
                   const char *player,
                   const char *reason);

int ggzcore_room_launch_table(GGZRoom *room, GGZTable *table);

int ggzcore_room_join_table(GGZRoom *room, const unsigned int table_id, 
                int spectator);

int ggzcore_room_leave_table(GGZRoom *room, int force);


/* Functions for manipulating GGZPlayer objects */
/* -------------------------------------------- */

char *ggzcore_player_get_name(const GGZPlayer *player);

GGZPlayerType ggzcore_player_get_type(const GGZPlayer *player);

GGZRoom *ggzcore_player_get_room(const GGZPlayer *player);

GGZTable* ggzcore_player_get_table(const GGZPlayer *player);

bool ggzcore_player_has_perm(const GGZPlayer *player, GGZPerm perm);

int ggzcore_player_set_perm(GGZPlayer *player, GGZPerm perm, bool set);

int ggzcore_player_get_lag(const GGZPlayer *player);

int ggzcore_player_get_record(const GGZPlayer *player,
                  int *wins, int *losses,
                  int *ties, int *forfeits);

int ggzcore_player_get_rating(const GGZPlayer *player, int *rating);

int ggzcore_player_get_ranking(const GGZPlayer *player, int *ranking);

int ggzcore_player_get_highscore(const GGZPlayer *player, int *highscore);


GGZTable* ggzcore_table_new(void);

int ggzcore_table_init(GGZTable *table,
               const GGZGameType *gametype,
               const char *desc,
               const unsigned int num_seats);

void ggzcore_table_free(GGZTable *table);

int ggzcore_table_set_seat(GGZTable *table,
               const unsigned int seat,
               GGZSeatType type,
               const char *name);

int ggzcore_table_remove_player(GGZTable *table, const char *name);

int ggzcore_table_get_id(const GGZTable *table);

const GGZRoom *ggzcore_table_get_room(const GGZTable *table);

const GGZGameType *ggzcore_table_get_type(const GGZTable *table);

const char *ggzcore_table_get_desc(const GGZTable *table);

GGZTableState ggzcore_table_get_state(const GGZTable *table);

int ggzcore_table_get_num_seats(const GGZTable *table);

int ggzcore_table_set_desc(GGZTable *table, const char *desc);

int ggzcore_table_get_seat_count(const GGZTable *table, GGZSeatType type);

const char *ggzcore_table_get_nth_player_name(const GGZTable *table,
                          const unsigned int num);

int ggzcore_table_get_num_spectator_seats(const GGZTable *table);

const char *ggzcore_table_get_nth_spectator_name(const GGZTable *table,
                         const unsigned int num);

GGZSeatType ggzcore_table_get_nth_player_type(const GGZTable *table, 
                          const unsigned int num);


unsigned int ggzcore_gametype_get_id(const GGZGameType *type);

const char * ggzcore_gametype_get_name(const GGZGameType *type);

const char* ggzcore_gametype_get_prot_engine(const GGZGameType *type);

const char* ggzcore_gametype_get_prot_version(const GGZGameType *type);

const char* ggzcore_gametype_get_version(const GGZGameType *type);

const char* ggzcore_gametype_get_author(const GGZGameType *type);

const char* ggzcore_gametype_get_url(const GGZGameType *type);

const char* ggzcore_gametype_get_desc(const GGZGameType *type);

int ggzcore_gametype_get_max_players(const GGZGameType *type);

int ggzcore_gametype_get_max_bots(const GGZGameType *type);

int ggzcore_gametype_get_spectators_allowed(const GGZGameType *type);

int ggzcore_gametype_num_players_is_valid(const GGZGameType *type,
                      unsigned int num);

int ggzcore_gametype_num_bots_is_valid(const GGZGameType *type,
                       unsigned int num);

int ggzcore_gametype_get_num_namedbots(const GGZGameType *type);
const char* ggzcore_gametype_get_namedbot_name(const GGZGameType *type, unsigned int num);
const char* ggzcore_gametype_get_namedbot_class(const GGZGameType *type, unsigned int num);

int ggzcore_gametype_get_peers_allowed(const GGZGameType *type);


/* Group of configuration functions */
/* -------------------------------- */

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


/* Game module related functions */
/* ----------------------------- */

unsigned int ggzcore_module_get_num(void);


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

GGZModule* ggzcore_module_get_nth_by_type(const char *game, 
                      const char *engine,
                      const char *version,
                      const unsigned int num);

const char * ggzcore_module_get_name(GGZModule *module);

const char* ggzcore_module_get_version(GGZModule *module);

const char* ggzcore_module_get_prot_engine(GGZModule *module);

const char* ggzcore_module_get_prot_version(GGZModule *module);

const char* ggzcore_module_get_author(GGZModule *module);

const char* ggzcore_module_get_frontend(GGZModule *module);

const char* ggzcore_module_get_url(GGZModule *module);

const char* ggzcore_module_get_icon_path(GGZModule *module);

const char* ggzcore_module_get_help_path(GGZModule *module);

char** ggzcore_module_get_argv(GGZModule *module);

GGZModuleEnvironment ggzcore_module_get_environment(GGZModule *module);

/* Functions related to game clients */
/* --------------------------------- */

GGZGame* ggzcore_game_new(void);

int ggzcore_game_init(GGZGame *game, GGZServer *server, GGZModule *module);

void ggzcore_game_free(GGZGame *game);

int ggzcore_game_add_event_hook(GGZGame *game,
                const GGZGameEvent event, 
                const GGZHookFunc func);

int ggzcore_game_add_event_hook_full(GGZGame *game,
                     const GGZGameEvent event, 
                     const GGZHookFunc func,
                     const void *data);

int ggzcore_game_remove_event_hook(GGZGame *game,
                   const GGZGameEvent event, 
                   const GGZHookFunc func);

int ggzcore_game_remove_event_hook_id(GGZGame *game,
                      const GGZGameEvent event, 
                      const unsigned int hook_id);

int  ggzcore_game_get_control_fd(GGZGame *game);

void ggzcore_game_set_server_fd(GGZGame *game, unsigned int fd);

GGZModule* ggzcore_game_get_module(GGZGame *game);

int ggzcore_game_launch(GGZGame *game);

int ggzcore_game_read_data(GGZGame *game);

#ifdef __cplusplus
}
#endif 

#endif  /* __GGZCORE_H__ */

---