# HG changeset patch # User Medo # Date 1345486597 -7200 # Node ID c92596feac0d5a5286df052c15ea8baad09a6467 # Parent d5c880e6d772eb3a3825d60814c8568730f9f681 frontlib: Improved documentation of netconn, unified naming of a callback diff -r d5c880e6d772 -r c92596feac0d project_files/frontlib/extra/jnacontrol.c --- a/project_files/frontlib/extra/jnacontrol.c Mon Aug 20 17:08:52 2012 +0200 +++ b/project_files/frontlib/extra/jnacontrol.c Mon Aug 20 20:16:37 2012 +0200 @@ -65,10 +65,9 @@ typedef flib_team *TeamPtr; typedef flib_gamesetup *GameSetupPtr; typedef bool boolean; -typedef size_t NativeLong; +typedef size_t NativeSizeT; typedef void *Pointer; typedef char *String; -typedef uint8_t *Buffer; /* * Mapping callback types @@ -85,8 +84,8 @@ typedef void (*BoolCallback)(Pointer context, boolean arg1); typedef void (*StrBoolCallback)(Pointer context, String arg1, boolean arg2); typedef void (*TeamCallback)(Pointer context, TeamPtr arg1); -typedef void (*BytesCallback)(Pointer context, const uint8_t *buffer, NativeLong size); -typedef void (*BytesBoolCallback)(Pointer context, const uint8_t *buffer, NativeLong size, boolean arg3); +typedef void (*BytesCallback)(Pointer context, const uint8_t *buffer, NativeSizeT size); +typedef void (*BytesBoolCallback)(Pointer context, const uint8_t *buffer, NativeSizeT size, boolean arg3); typedef void (*SchemeCallback)(Pointer context, SchemePtr arg1); typedef void (*MapIntCallback)(Pointer context, MapRecipePtr arg1, int arg2); typedef void (*WeaponsetCallback)(Pointer context, WeaponsetPtr arg1); @@ -98,140 +97,137 @@ */ // frontlib.h -int flib_init(); -void flib_quit(); + int flib_init(); + void flib_quit(); -// hwconsts.h -int flib_get_teamcolor_count(); -int flib_get_hedgehogs_per_team(); -int flib_get_weapons_count(); + // hwconsts.h + int flib_get_teamcolor_count(); + int flib_get_hedgehogs_per_team(); + int flib_get_weapons_count(); + MetaschemePtr flib_get_metascheme(); -// net/netconn.h -NetconnPtr flib_netconn_create(String playerName, String dataDirPath, String host, int port); -void flib_netconn_destroy(NetconnPtr conn); + // net/netconn.h + NetconnPtr flib_netconn_create(String playerName, String dataDirPath, String host, int port); + void flib_netconn_destroy(NetconnPtr conn); -void flib_netconn_tick(NetconnPtr conn); -boolean flib_netconn_is_chief(NetconnPtr conn); -String flib_netconn_get_playername(NetconnPtr conn); -GameSetupPtr flib_netconn_create_gamesetup(NetconnPtr conn); -int flib_netconn_send_quit(NetconnPtr conn, String quitmsg); -int flib_netconn_send_chat(NetconnPtr conn, String chat); -int flib_netconn_send_teamchat(NetconnPtr conn, String msg); -int flib_netconn_send_password(NetconnPtr conn, String passwd); -int flib_netconn_send_nick(NetconnPtr conn, String nick); -int flib_netconn_send_request_roomlist(NetconnPtr conn); -int flib_netconn_send_joinRoom(NetconnPtr conn, String room); -int flib_netconn_send_createRoom(NetconnPtr conn, String room); -int flib_netconn_send_renameRoom(NetconnPtr conn, String roomName); -int flib_netconn_send_leaveRoom(NetconnPtr conn, String msg); -int flib_netconn_send_toggleReady(NetconnPtr conn); -int flib_netconn_send_addTeam(NetconnPtr conn, TeamPtr team); -int flib_netconn_send_removeTeam(NetconnPtr conn, String teamname); -int flib_netconn_send_teamHogCount(NetconnPtr conn, String teamname, int hogcount); -int flib_netconn_send_teamColor(NetconnPtr conn, String teamname, int colorIndex); -int flib_netconn_send_weaponset(NetconnPtr conn, WeaponsetPtr weaponset); -int flib_netconn_send_map(NetconnPtr conn, MapRecipePtr map); -int flib_netconn_send_mapName(NetconnPtr conn, String mapName); -int flib_netconn_send_mapGen(NetconnPtr conn, int mapGen); -int flib_netconn_send_mapTemplate(NetconnPtr conn, int templateFilter); -int flib_netconn_send_mapMazeSize(NetconnPtr conn, int mazeSize); -int flib_netconn_send_mapSeed(NetconnPtr conn, String seed); -int flib_netconn_send_mapTheme(NetconnPtr conn, String theme); -int flib_netconn_send_script(NetconnPtr conn, String scriptName); -int flib_netconn_send_scheme(NetconnPtr conn, SchemePtr scheme); -int flib_netconn_send_roundfinished(NetconnPtr conn, boolean withoutError); -int flib_netconn_send_ban(NetconnPtr conn, String playerName); -int flib_netconn_send_kick(NetconnPtr conn, String playerName); -int flib_netconn_send_playerInfo(NetconnPtr conn, String playerName); -int flib_netconn_send_playerFollow(NetconnPtr conn, String playerName); -int flib_netconn_send_startGame(NetconnPtr conn); -int flib_netconn_send_toggleRestrictJoins(NetconnPtr conn); -int flib_netconn_send_toggleRestrictTeams(NetconnPtr conn); -int flib_netconn_send_clearAccountsCache(NetconnPtr conn); -int flib_netconn_send_setServerVar(NetconnPtr conn, String name, String value); -int flib_netconn_send_getServerVars(NetconnPtr conn); + void flib_netconn_tick(NetconnPtr conn); + boolean flib_netconn_is_chief(NetconnPtr conn); + String flib_netconn_get_playername(NetconnPtr conn); + GameSetupPtr flib_netconn_create_gamesetup(NetconnPtr conn); + int flib_netconn_send_quit(NetconnPtr conn, String quitmsg); + int flib_netconn_send_chat(NetconnPtr conn, String chat); + int flib_netconn_send_teamchat(NetconnPtr conn, String msg); + int flib_netconn_send_password(NetconnPtr conn, String passwd); + int flib_netconn_send_nick(NetconnPtr conn, String nick); + int flib_netconn_send_request_roomlist(NetconnPtr conn); + int flib_netconn_send_joinRoom(NetconnPtr conn, String room); + int flib_netconn_send_createRoom(NetconnPtr conn, String room); + int flib_netconn_send_renameRoom(NetconnPtr conn, String roomName); + int flib_netconn_send_leaveRoom(NetconnPtr conn, String msg); + int flib_netconn_send_toggleReady(NetconnPtr conn); + int flib_netconn_send_addTeam(NetconnPtr conn, TeamPtr team); + int flib_netconn_send_removeTeam(NetconnPtr conn, String teamname); + int flib_netconn_send_teamHogCount(NetconnPtr conn, String teamname, int hogcount); + int flib_netconn_send_teamColor(NetconnPtr conn, String teamname, int colorIndex); + int flib_netconn_send_weaponset(NetconnPtr conn, WeaponsetPtr weaponset); + int flib_netconn_send_map(NetconnPtr conn, MapRecipePtr map); + int flib_netconn_send_mapName(NetconnPtr conn, String mapName); + int flib_netconn_send_mapGen(NetconnPtr conn, int mapGen); + int flib_netconn_send_mapTemplate(NetconnPtr conn, int templateFilter); + int flib_netconn_send_mapMazeSize(NetconnPtr conn, int mazeSize); + int flib_netconn_send_mapSeed(NetconnPtr conn, String seed); + int flib_netconn_send_mapTheme(NetconnPtr conn, String theme); + int flib_netconn_send_script(NetconnPtr conn, String scriptName); + int flib_netconn_send_scheme(NetconnPtr conn, SchemePtr scheme); + int flib_netconn_send_roundfinished(NetconnPtr conn, boolean withoutError); + int flib_netconn_send_ban(NetconnPtr conn, String playerName); + int flib_netconn_send_kick(NetconnPtr conn, String playerName); + int flib_netconn_send_playerInfo(NetconnPtr conn, String playerName); + int flib_netconn_send_playerFollow(NetconnPtr conn, String playerName); + int flib_netconn_send_startGame(NetconnPtr conn); + int flib_netconn_send_toggleRestrictJoins(NetconnPtr conn); + int flib_netconn_send_toggleRestrictTeams(NetconnPtr conn); + int flib_netconn_send_clearAccountsCache(NetconnPtr conn); + int flib_netconn_send_setServerVar(NetconnPtr conn, String name, String value); + int flib_netconn_send_getServerVars(NetconnPtr conn); -void flib_netconn_onMessage(NetconnPtr conn, IntStrCallback callback, Pointer context); -void flib_netconn_onChat(NetconnPtr conn, StrStrCallback callback, Pointer context); -void flib_netconn_onConnected(NetconnPtr conn, VoidCallback callback, Pointer context); -void flib_netconn_onDisconnected(NetconnPtr conn, IntStrCallback callback, Pointer context); -void flib_netconn_onRoomlist(NetconnPtr conn, RoomListCallback callback, Pointer context); -void flib_netconn_onRoomAdd(NetconnPtr conn, RoomCallback callback, Pointer context); -void flib_netconn_onRoomDelete(NetconnPtr conn, StrCallback callback, Pointer context); -void flib_netconn_onRoomUpdate(NetconnPtr conn, StrRoomCallback callback, Pointer context); -void flib_netconn_onLobbyJoin(NetconnPtr conn, StrCallback callback, Pointer context); -void flib_netconn_onLobbyLeave(NetconnPtr conn, StrStrCallback callback, Pointer context); -void flib_netconn_onNickTaken(NetconnPtr conn, StrCallback callback, Pointer context); -void flib_netconn_onPasswordRequest(NetconnPtr conn, StrCallback callback, Pointer context); -void flib_netconn_onEnterRoom(NetconnPtr conn, BoolCallback callback, Pointer context); -void flib_netconn_onRoomChiefStatus(NetconnPtr conn, BoolCallback callback, Pointer context); -void flib_netconn_onReadyState(NetconnPtr conn, StrBoolCallback callback, Pointer context); -void flib_netconn_onLeaveRoom(NetconnPtr conn, IntStrCallback callback, Pointer context); -void flib_netconn_onTeamAdd(NetconnPtr conn, TeamCallback callback, Pointer context); -void flib_netconn_onTeamDelete(NetconnPtr conn, StrCallback callback, Pointer context); -void flib_netconn_onRoomJoin(NetconnPtr conn, StrCallback callback, Pointer context); -void flib_netconn_onRoomLeave(NetconnPtr conn, StrStrCallback callback, Pointer context); -void flib_netconn_onRunGame(NetconnPtr conn, VoidCallback callback, Pointer context); -void flib_netconn_onTeamAccepted(NetconnPtr conn, StrCallback callback, Pointer context); -void flib_netconn_onHogCountChanged(NetconnPtr conn, StrIntCallback callback, Pointer context); -void flib_netconn_onTeamColorChanged(NetconnPtr conn, StrIntCallback callback, Pointer context); -void flib_netconn_onEngineMessage(NetconnPtr conn, BytesCallback callback, Pointer context); -void flib_netconn_onCfgScheme(NetconnPtr conn, SchemeCallback callback, Pointer context); -void flib_netconn_onMapChanged(NetconnPtr conn, MapIntCallback callback, Pointer context); -void flib_netconn_onScriptChanged(NetconnPtr conn, StrCallback callback, Pointer context); -void flib_netconn_onWeaponsetChanged(NetconnPtr conn, WeaponsetCallback callback, Pointer context); -void flib_netconn_onAdminAccess(NetconnPtr conn, VoidCallback callback, Pointer context); -void flib_netconn_onServerVar(NetconnPtr conn, StrStrCallback callback, Pointer context); + void flib_netconn_onMessage(NetconnPtr conn, IntStrCallback callback, Pointer context); + void flib_netconn_onChat(NetconnPtr conn, StrStrCallback callback, Pointer context); + void flib_netconn_onConnected(NetconnPtr conn, VoidCallback callback, Pointer context); + void flib_netconn_onDisconnected(NetconnPtr conn, IntStrCallback callback, Pointer context); + void flib_netconn_onRoomlist(NetconnPtr conn, RoomListCallback callback, Pointer context); + void flib_netconn_onRoomAdd(NetconnPtr conn, RoomCallback callback, Pointer context); + void flib_netconn_onRoomDelete(NetconnPtr conn, StrCallback callback, Pointer context); + void flib_netconn_onRoomUpdate(NetconnPtr conn, StrRoomCallback callback, Pointer context); + void flib_netconn_onLobbyJoin(NetconnPtr conn, StrCallback callback, Pointer context); + void flib_netconn_onLobbyLeave(NetconnPtr conn, StrStrCallback callback, Pointer context); + void flib_netconn_onNickTaken(NetconnPtr conn, StrCallback callback, Pointer context); + void flib_netconn_onPasswordRequest(NetconnPtr conn, StrCallback callback, Pointer context); + void flib_netconn_onEnterRoom(NetconnPtr conn, BoolCallback callback, Pointer context); + void flib_netconn_onRoomChiefStatus(NetconnPtr conn, BoolCallback callback, Pointer context); + void flib_netconn_onReadyState(NetconnPtr conn, StrBoolCallback callback, Pointer context); + void flib_netconn_onLeaveRoom(NetconnPtr conn, IntStrCallback callback, Pointer context); + void flib_netconn_onTeamAdd(NetconnPtr conn, TeamCallback callback, Pointer context); + void flib_netconn_onTeamDelete(NetconnPtr conn, StrCallback callback, Pointer context); + void flib_netconn_onRoomJoin(NetconnPtr conn, StrCallback callback, Pointer context); + void flib_netconn_onRoomLeave(NetconnPtr conn, StrStrCallback callback, Pointer context); + void flib_netconn_onRunGame(NetconnPtr conn, VoidCallback callback, Pointer context); + void flib_netconn_onTeamAccepted(NetconnPtr conn, StrCallback callback, Pointer context); + void flib_netconn_onHogCountChanged(NetconnPtr conn, StrIntCallback callback, Pointer context); + void flib_netconn_onTeamColorChanged(NetconnPtr conn, StrIntCallback callback, Pointer context); + void flib_netconn_onEngineMessage(NetconnPtr conn, BytesCallback callback, Pointer context); + void flib_netconn_onSchemeChanged(NetconnPtr conn, SchemeCallback callback, Pointer context); + void flib_netconn_onMapChanged(NetconnPtr conn, MapIntCallback callback, Pointer context); + void flib_netconn_onScriptChanged(NetconnPtr conn, StrCallback callback, Pointer context); + void flib_netconn_onWeaponsetChanged(NetconnPtr conn, WeaponsetCallback callback, Pointer context); + void flib_netconn_onAdminAccess(NetconnPtr conn, VoidCallback callback, Pointer context); + void flib_netconn_onServerVar(NetconnPtr conn, StrStrCallback callback, Pointer context); -// ipc/gameconn.h -GameconnPtr flib_gameconn_create(String playerName, GameSetupPtr setup, boolean netgame); -GameconnPtr flib_gameconn_create_playdemo(Buffer demo, NativeLong size); -GameconnPtr flib_gameconn_create_loadgame(String playerName, Buffer save, NativeLong size); -GameconnPtr flib_gameconn_create_campaign(String playerName, String seed, String script); + // ipc/gameconn.h + GameconnPtr flib_gameconn_create(String playerName, GameSetupPtr setup, boolean netgame); + GameconnPtr flib_gameconn_create_campaign(String playerName, String seed, String script); -void flib_gameconn_destroy(GameconnPtr conn); -int flib_gameconn_getport(GameconnPtr conn); -void flib_gameconn_tick(GameconnPtr conn); + void flib_gameconn_destroy(GameconnPtr conn); + int flib_gameconn_getport(GameconnPtr conn); + void flib_gameconn_tick(GameconnPtr conn); -int flib_gameconn_send_textmsg(GameconnPtr conn, int msgtype, String msg); -int flib_gameconn_send_chatmsg(GameconnPtr conn, String playername, String msg); -int flib_gameconn_send_quit(GameconnPtr conn); + int flib_gameconn_send_textmsg(GameconnPtr conn, int msgtype, String msg); + int flib_gameconn_send_chatmsg(GameconnPtr conn, String playername, String msg); + int flib_gameconn_send_quit(GameconnPtr conn); + int flib_gameconn_send_cmd(GameconnPtr conn, String cmdString); -void flib_gameconn_onConnect(GameconnPtr conn, VoidCallback callback, Pointer context); -void flib_gameconn_onDisconnect(GameconnPtr conn, IntCallback callback, Pointer context); -void flib_gameconn_onErrorMessage(GameconnPtr conn, StrCallback callback, Pointer context); -void flib_gameconn_onChat(GameconnPtr conn, StrBoolCallback callback, Pointer context); -void flib_gameconn_onGameRecorded(GameconnPtr conn, BytesBoolCallback callback, Pointer context); -void flib_gameconn_onEngineMessage(GameconnPtr conn, BytesCallback callback, Pointer context); + void flib_gameconn_onConnect(GameconnPtr conn, VoidCallback callback, Pointer context); + void flib_gameconn_onDisconnect(GameconnPtr conn, IntCallback callback, Pointer context); + void flib_gameconn_onErrorMessage(GameconnPtr conn, StrCallback callback, Pointer context); + void flib_gameconn_onChat(GameconnPtr conn, StrBoolCallback callback, Pointer context); + void flib_gameconn_onGameRecorded(GameconnPtr conn, BytesBoolCallback callback, Pointer context); + void flib_gameconn_onEngineMessage(GameconnPtr conn, BytesCallback callback, Pointer context); -// ipc/mapconn.h -MapconnPtr flib_mapconn_create(MapRecipePtr mapdesc); -void flib_mapconn_destroy(MapconnPtr conn); -int flib_mapconn_getport(MapconnPtr conn); -void flib_mapconn_onSuccess(MapconnPtr conn, MapimageCallback callback, Pointer context); -void flib_mapconn_onFailure(MapconnPtr conn, StrCallback callback, Pointer context); -void flib_mapconn_tick(MapconnPtr conn); - -MetaschemePtr flib_get_metascheme(); + // ipc/mapconn.h + MapconnPtr flib_mapconn_create(MapRecipePtr mapdesc); + void flib_mapconn_destroy(MapconnPtr conn); + int flib_mapconn_getport(MapconnPtr conn); + void flib_mapconn_onSuccess(MapconnPtr conn, MapimageCallback callback, Pointer context); + void flib_mapconn_onFailure(MapconnPtr conn, StrCallback callback, Pointer context); + void flib_mapconn_tick(MapconnPtr conn); -// model/schemelist.h -SchemelistPtr flib_schemelist_from_ini(String filename); -int flib_schemelist_to_ini(String filename, SchemelistPtr list); -void flib_schemelist_destroy(SchemelistPtr list); + // model/schemelist.h + SchemelistPtr flib_schemelist_from_ini(String filename); + int flib_schemelist_to_ini(String filename, SchemelistPtr list); + void flib_schemelist_destroy(SchemelistPtr list); -// model/team.h -TeamPtr flib_team_from_ini(String filename); -int flib_team_to_ini(String filename, TeamPtr team); -void flib_team_destroy(TeamPtr team); + // model/team.h + TeamPtr flib_team_from_ini(String filename); + int flib_team_to_ini(String filename, TeamPtr team); + void flib_team_destroy(TeamPtr team); -// model/weapon.h -WeaponsetListPtr flib_weaponsetlist_from_ini(String filename); -int flib_weaponsetlist_to_ini(String filename, WeaponsetListPtr weaponsets); -void flib_weaponsetlist_destroy(WeaponsetListPtr list); + // model/weapon.h + WeaponsetListPtr flib_weaponsetlist_from_ini(String filename); + int flib_weaponsetlist_to_ini(String filename, WeaponsetListPtr weaponsets); + void flib_weaponsetlist_destroy(WeaponsetListPtr list); -// model/gamesetup.h -void flib_gamesetup_destroy(GameSetupPtr gamesetup); + // model/gamesetup.h + void flib_gamesetup_destroy(GameSetupPtr gamesetup); -// util/logging.h -void flib_log_setLevel(int level); -void flib_log_setCallback(LogCallback callback); + void flib_log_setLevel(int level); + void flib_log_setCallback(LogCallback callback); diff -r d5c880e6d772 -r c92596feac0d project_files/frontlib/ipc/gameconn.c --- a/project_files/frontlib/ipc/gameconn.c Mon Aug 20 17:08:52 2012 +0200 +++ b/project_files/frontlib/ipc/gameconn.c Mon Aug 20 20:16:37 2012 +0200 @@ -294,7 +294,7 @@ uint8_t converted[256]; size_t msglen = strlen(cmdString); if(!log_e_if(msglen>255, "Message too long: %s", cmdString)) { - strcpy(converted+1, cmdString); + strcpy((char*)converted+1, cmdString); converted[0] = msglen; if(!flib_ipcbase_send_raw(conn->ipcBase, converted, msglen+1)) { demo_append(conn, converted, msglen+1); diff -r d5c880e6d772 -r c92596feac0d project_files/frontlib/net/netconn.c --- a/project_files/frontlib/net/netconn.c Mon Aug 20 17:08:52 2012 +0200 +++ b/project_files/frontlib/net/netconn.c Mon Aug 20 20:16:37 2012 +0200 @@ -450,7 +450,7 @@ if(cfg) { flib_scheme_destroy(conn->scheme); conn->scheme = cfg; - conn->onCfgSchemeCb(conn->onCfgSchemeCtx, cfg); + conn->onSchemeChangedCb(conn->onSchemeChangedCtx, cfg); } else { flib_log_e("Error processing CFG SCHEME message"); } diff -r d5c880e6d772 -r c92596feac0d project_files/frontlib/net/netconn.h --- a/project_files/frontlib/net/netconn.h Mon Aug 20 17:08:52 2012 +0200 +++ b/project_files/frontlib/net/netconn.h Mon Aug 20 20:16:37 2012 +0200 @@ -18,39 +18,38 @@ */ /** - * This file contains functions for communicating with a Hedgewars server to chat, prepare - * and play rounds of Hedgewars. + * This file contains functions for communicating with a Hedgewars server to chat, prepare and play + * rounds of Hedgewars. * - * To use this, first create a netconn object by calling flib_netconn_create. This will - * start the connection to the game server (which might fail right away, the function - * returns null then). You should also register your callback functions right at the start - * to ensure you don't miss any callbacks. + * To use this, first create a netconn object by calling flib_netconn_create. This will start the + * connection to the game server (which might fail right away, the function returns null then). You + * should also register your callback functions right at the start to ensure you don't miss any + * callbacks. * * In order to allow the netconn to run, you should regularly call flib_netconn_tick(), which * performs network I/O and calls your callbacks on interesting events. * - * When the connection is closed, you will receive the onDisconnect callback. This is the - * signal to destroy the netconn and stop calling tick(). + * When the connection is closed, you will receive the onDisconnect callback. This is the signal to + * destroy the netconn and stop calling tick(). * * The connection process lasts from the time you create the netconn until you receive the - * onConnected callback (or onDisconnected in case something goes wrong). During that time, - * you might receive the onNickTaken and onPasswordRequest callbacks; see their description - * for more information on how to handle them. You could also receive other callbacks during - * connecting (e.g. about the room list), but it should be safe to ignore them. + * onConnected callback (or onDisconnected in case something goes wrong). During that time, you + * might receive the onNickTaken and onPasswordRequest callbacks; see their description for more + * information on how to handle them. You could also receive other callbacks during connecting (e.g. + * about the room list), but it should be safe to ignore them. * - * Once you are connected, you are in the lobby, and you can enter rooms and leave them again. - * The room and lobby states have different protocols, so many commands only work in either - * one or the other. If you are in a room you might also be in a game, but that does not - * change the protocol. The functions below are grouped by the states in which they make - * sense, or (for the callbacks) the states in which you would typically receive them. + * Once you are connected, you are in the lobby, and you can enter rooms and leave them again. The + * room and lobby states have different protocols, so many commands only work in either one or the + * other. If you are in a room you might also be in a game, but most of the functions behave the + * same ingame as in a room. * - * The state changes from lobby to room when the server tells you that you just entered one, - * which will also trigger the onEnterRoom callback. This usually happens in reply to either - * a joinRoom, createRoom or playerFollow command. + * The state changes from lobby to room when the server tells you that you just entered one, which + * will also trigger the onEnterRoom callback. This usually happens in reply to either a joinRoom, + * createRoom or playerFollow command. * - * The state changes back to lobby when the room is dissolved, when you are kicked from the - * room, or when you actively leave the room using flib_netconn_send_leaveRoom. The first - * two events will trigger the onLeaveRoom callback. + * The state changes back to lobby when the room is dissolved, when you are kicked from the room, or + * when you actively leave the room using flib_netconn_send_leaveRoom. The first two events will + * trigger the onLeaveRoom callback. */ #ifndef NETCONN_H_ @@ -92,7 +91,6 @@ #define NETCONN_MAPCHANGE_THEME 6 #define NETCONN_MAPCHANGE_SEED 7 -// TODO: Order these functions, and match the order in netconn.c typedef struct _flib_netconn flib_netconn; /** @@ -115,443 +113,534 @@ bool flib_netconn_is_chief(flib_netconn *conn); /** - * Returns the playername. This is *probably* the one provided on creation, but - * if that name was already taken, a different one could have been set by the - * onNickTaken callback or its default implementation. + * Returns the playername. This is *probably* the one provided on creation, but if that name was + * already taken, a different one could have been set by the onNickTaken callback or its default + * implementation. */ const char *flib_netconn_get_playername(flib_netconn *conn); /** * Generate a game setup from the current room state. - * Returns NULL if the room state does not contain enough information - * for a complete game setup, or if an error occurs. + * Returns NULL if the room state does not contain enough information for a complete game setup, + * or if an error occurs. * * The new gamesetup must be destroyed with flib_gamesetup_destroy(). */ flib_gamesetup *flib_netconn_create_gamesetup(flib_netconn *conn); -/** - * quitmsg may be null - */ -int flib_netconn_send_quit(flib_netconn *conn, const char *quitmsg); -int flib_netconn_send_chat(flib_netconn *conn, const char *chat); + + + +// Send functions needed when connecting and disconnecting + + /** + * Request a different nickname. + * This function only makes sense in reaction to an onNickTaken callback, because the netconn + * automatically requests the nickname you provide on creation, and once the server accepts the + * nickname it can no longer be changed. + */ + int flib_netconn_send_nick(flib_netconn *conn, const char *nick); -/** - * Send a teamchat message, forwarded from the engine. Only makes sense ingame. - * The server does not send a reply. In contrast to a Chat message, the server - * automatically converts this into an engine message and passes it on to the other - * clients. - */ -int flib_netconn_send_teamchat(flib_netconn *conn, const char *msg); + /** + * Send the password in reply to a password request. + * If the server does not accept the password, you will be disconnected + * (NETCONN_DISCONNECT_AUTH_FAILED) + */ + int flib_netconn_send_password(flib_netconn *conn, const char *passwd); -/** - * Send the password in reply to a password request. - * If the server does not accept the password, you will be disconnected (NETCONN_DISCONNECT_AUTH_FAILED) - */ -int flib_netconn_send_password(flib_netconn *conn, const char *passwd); + /** + * Tell the server that you want to leave. If successful, the server will disconnect you. + */ + int flib_netconn_send_quit(flib_netconn *conn, const char *quitmsg); + + +// Send functions that make sense both in the lobby and in rooms -/** - * Request a different nickname. - * This function only makes sense in reaction to an onNickTaken callback, because the netconn automatically - * requests the nickname you provide on creation, and once the server accepts the nickname it can no longer - * be changed. - */ -int flib_netconn_send_nick(flib_netconn *conn, const char *nick); + /** + * Send a chat message. This message is either sent to the lobby or the room, depending on + * whether you are in a room at the moment. The message is not echoed back to you. + */ + int flib_netconn_send_chat(flib_netconn *conn, const char *chat); -/** - * Request an update of the room list. Only makes sense when in lobby state. - * If the action succeeds, you will receive an onRoomlist callback containing the current room data. - */ -int flib_netconn_send_request_roomlist(flib_netconn *conn); + /** + * Kick a player. This has different meanings in the lobby and in a room; + * In the lobby, it will kick the player from the server, and you need to be a server admin to + * do it. In a room, it will kick the player from the room, and you need to be room chief. + */ + int flib_netconn_send_kick(flib_netconn *conn, const char *playerName); -/** - * Join a room as guest (not chief). Only makes sense when in lobby state. If the action succeeds, you will - * receive an onEnterRoom callback with chief=false. - */ -int flib_netconn_send_joinRoom(flib_netconn *conn, const char *room); + /** + * Request information about a player (e.g. current room, version, partial IP). If the action + * succeeds, you will receive an onMessage callback with NETCONN_MSG_TYPE_PLAYERINFO containing + * the requested information. + */ + int flib_netconn_send_playerInfo(flib_netconn *conn, const char *playerName); + + +// Send functions that only make sense in the lobby -/** - * Create and join a new room. Only makes sense when in lobby state. If the action succeeds, you will - * receive an onEnterRoom callback with chief=true. - */ -int flib_netconn_send_createRoom(flib_netconn *conn, const char *room); + /** + * Request an update of the room list. Only makes sense when in lobby state. + * If the action succeeds, you will receive an onRoomlist callback containing the current room + * data. + */ + int flib_netconn_send_request_roomlist(flib_netconn *conn); -/** - * Rename the current room. Only makes sense in room state and if you are chief. If the action succeeds, you will - * receive an onRoomUpdate callback containing the change. - */ -int flib_netconn_send_renameRoom(flib_netconn *conn, const char *roomName); + /** + * Join a room as guest (not chief). Only makes sense when in lobby state. If the action + * succeeds, you will receive an onEnterRoom callback with chief=false. + */ + int flib_netconn_send_joinRoom(flib_netconn *conn, const char *room); -/** - * Leave the room for the lobby. Only makes sense in room state. msg can be NULL if you don't want to - * send a message. The server always accepts a part message, so once you send it off, you can just - * assume that you are back in the lobby. - */ -int flib_netconn_send_leaveRoom(flib_netconn *conn, const char *msg); + /** + * Follow a player. Only valid in the lobby. If the player is in a room (or in a game), this + * command is analogous to calling flib_netconn_send_joinRoom with that room. + */ + int flib_netconn_send_playerFollow(flib_netconn *conn, const char *playerName); -/** - * Change your "ready" status in the room. Only makes sense when in room state. If the action succeeds, you will - * receive an onReadyState callback containing the change. - */ -int flib_netconn_send_toggleReady(flib_netconn *conn); + /** + * Create and join a new room. Only makes sense when in lobby state. If the action succeeds, + * you will receive an onEnterRoom callback with chief=true. + */ + int flib_netconn_send_createRoom(flib_netconn *conn, const char *room); -/** - * Add a team to the current room. Apart from the "fixed" team information, this also includes - * the color, but not the number of hogs. Only makes sense when in room state. If the action - * succeeds, you will receive an onTeamAccepted callback with the name of the team. - */ -int flib_netconn_send_addTeam(flib_netconn *conn, const flib_team *team); + /** + * Ban a player. You need to be in the lobby and a server admin for this to work. + */ + int flib_netconn_send_ban(flib_netconn *conn, const char *playerName); -/** - * Remove the team with the name teamname. Only makes sense when in room state. - * The server does not send a reply on success. - */ -int flib_netconn_send_removeTeam(flib_netconn *conn, const char *teamname); + /** + * Does something administrator-y. At any rate you need to be an administrator and in the lobby + * to use this command. + */ + int flib_netconn_send_clearAccountsCache(flib_netconn *conn); + + /** + * Sets a server variable to the indicated value. Only makes sense if you are server admin and + * in the lobby. Known variables are MOTD_NEW, MOTD_OLD and LATEST_PROTO. MOTD_OLD is shown to + * players with older protocol versions, to inform them that they might want to update. + */ + int flib_netconn_send_setServerVar(flib_netconn *conn, const char *name, const char *value); -/** - * Send an engine message. Only makes sense when ingame. In a networked game, you have to - * pass all the engine messages from the engine here, and they will be spread to all other - * clients in the game to keep the game in sync. - */ -int flib_netconn_send_engineMessage(flib_netconn *conn, const uint8_t *message, size_t size); + /** + * Queries all server variables. Only makes sense if you are server admin and in the lobby. + * If the action succeeds, you will receive several onServerVar callbacks with the + * current values of all server variables. + */ + int flib_netconn_send_getServerVars(flib_netconn *conn); + -/** - * Set the number of hogs for a team. Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_teamHogCount(flib_netconn *conn, const char *teamname, int hogcount); +// Send functions that only make sense in a room + + /** + * Leave the room for the lobby. Only makes sense in room state. msg can be NULL if you don't + * want to send a message. The server always accepts a part message, so once you send it off, + * you can just assume that you are back in the lobby. + */ + int flib_netconn_send_leaveRoom(flib_netconn *conn, const char *msg); -/** - * Set the teamcolor of a team. Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_teamColor(flib_netconn *conn, const char *teamname, int colorIndex); - -/** - * Set the weaponset for the room. Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_weaponset(flib_netconn *conn, const flib_weaponset *weaponset); + /** + * Change your "ready" status in the room. Only makes sense when in room state. If the action + * succeeds, you will receive an onReadyState callback containing the change. + */ + int flib_netconn_send_toggleReady(flib_netconn *conn); -/** - * Set the map for the room. Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_map(flib_netconn *conn, const flib_map *map); - -/** - * Set the mapname. Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_mapName(flib_netconn *conn, const char *mapName); + /** + * Add a team to the current room. Apart from the "fixed" team information, this also includes + * the color, but not the number of hogs. Only makes sense when in room state. If the action + * succeeds, you will receive an onTeamAccepted callback with the name of the team. + * + * Notes: Technically, sending a color here is the only way for a non-chief to set the color of + * her own team. The server remembers this color and even generates a separate teamColor message + * to inform everyone of it. However, at the moment the frontends generally override this color + * with one they choose themselves in order to deal with unfortunate behavior of the QtFrontend, + * which always sends color index 0 when adding a team but thinks that the team has a random + * color. The chief always sends a new color in order to bring the QtFrontend back into sync. + */ + int flib_netconn_send_addTeam(flib_netconn *conn, const flib_team *team); -/** - * Set the map generator. Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_mapGen(flib_netconn *conn, int mapGen); + /** + * Remove the team with the name teamname. Only makes sense when in room state. + * The server does not send a reply on success. + */ + int flib_netconn_send_removeTeam(flib_netconn *conn, const char *teamname); -/** - * Set the map template for regular maps. Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_mapTemplate(flib_netconn *conn, int templateFilter); + +// Send functions that only make sense in a room and if you are room chief -/** - * Set the maze template (maze size) for mazes. Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_mapMazeSize(flib_netconn *conn, int mazeSize); + /** + * Rename the current room. Only makes sense in room state and if you are chief. If the action + * succeeds, you (and everyone else on the server) will receive an onRoomUpdate message + * containing the change. + */ + int flib_netconn_send_renameRoom(flib_netconn *conn, const char *roomName); -/** - * Set the seed for the map. Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_mapSeed(flib_netconn *conn, const char *seed); + /** + * Set the number of hogs for a team. Only makes sense in room state and if you are chief. + * The server does not send a reply. + */ + int flib_netconn_send_teamHogCount(flib_netconn *conn, const char *teamname, int hogcount); + + /** + * Set the teamcolor of a team. Only makes sense in room state and if you are chief. + * The server does not send a reply. + */ + int flib_netconn_send_teamColor(flib_netconn *conn, const char *teamname, int colorIndex); -/** - * Set the theme for the map. Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_mapTheme(flib_netconn *conn, const char *theme); + /** + * Set the weaponset for the room. Only makes sense in room state and if you are chief. + * The server does not send a reply. + */ + int flib_netconn_send_weaponset(flib_netconn *conn, const flib_weaponset *weaponset); -/** - * Set the draw data for the drawn map. Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_mapDrawdata(flib_netconn *conn, const uint8_t *drawData, size_t size); + /** + * Set the map for the room. Only makes sense in room state and if you are chief. + * The server does not send a reply. + */ + int flib_netconn_send_map(flib_netconn *conn, const flib_map *map); + + /** + * Set the mapname. Only makes sense in room state and if you are chief. + * The server does not send a reply. + */ + int flib_netconn_send_mapName(flib_netconn *conn, const char *mapName); -/** - * Set the script (game style). Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_script(flib_netconn *conn, const char *scriptName); + /** + * Set the map generator (regular, maze, drawn, named). Only makes sense in room state and if + * you are chief. + * The server does not send a reply. + */ + int flib_netconn_send_mapGen(flib_netconn *conn, int mapGen); -/** - * Set the scheme. Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_scheme(flib_netconn *conn, const flib_scheme *scheme); + /** + * Set the map template for regular maps. Only makes sense in room state and if you are chief. + * The server does not send a reply. + */ + int flib_netconn_send_mapTemplate(flib_netconn *conn, int templateFilter); -/** - * Inform the server that the round has ended. Call this when the engine - * has disconnected, passing 1 if the round ended normally, 0 otherwise. - */ -int flib_netconn_send_roundfinished(flib_netconn *conn, bool withoutError); - -/** - * Ban a player. You need to be in the lobby and a server admin for this to work. - */ -int flib_netconn_send_ban(flib_netconn *conn, const char *playerName); + /** + * Set the maze template (maze size) for mazes. Only makes sense in room state and if you are + * chief. The server does not send a reply. + */ + int flib_netconn_send_mapMazeSize(flib_netconn *conn, int mazeSize); -/** - * Kick a player. This has different meanings in the lobby and in a room; - * In the lobby, it will kick the player from the server, and you need to be a server admin to do it. - * In a room, it will kick the player from the room, and you need to be room chief. - */ -int flib_netconn_send_kick(flib_netconn *conn, const char *playerName); + /** + * Set the seed for the map. Only makes sense in room state and if you are chief. + * The server does not send a reply. + */ + int flib_netconn_send_mapSeed(flib_netconn *conn, const char *seed); -/** - * Request information about a player. If the action succeeds, you will - * receive an onMessage callback with NETCONN_MSG_TYPE_PLAYERINFO containing - * the requested information. - */ -int flib_netconn_send_playerInfo(flib_netconn *conn, const char *playerName); + /** + * Set the theme for the map. Only makes sense in room state and if you are chief. + * The server does not send a reply. + */ + int flib_netconn_send_mapTheme(flib_netconn *conn, const char *theme); -/** - * Follow a player. Only valid in the lobby. If the player is in a room (or in a game), - * this command is analogous to calling flib_netconn_send_joinRoom with that room. - */ -int flib_netconn_send_playerFollow(flib_netconn *conn, const char *playerName); + /** + * Set the draw data for the drawn map. Only makes sense in room state and if you are chief. + * The server does not send a reply. + */ + int flib_netconn_send_mapDrawdata(flib_netconn *conn, const uint8_t *drawData, size_t size); -/** - * Signal that you want to start the game. Only makes sense in room state and if you are chief. - * The server will check whether all players are ready and whether it believes the setup makes - * sense (e.g. more than one clan). If the server is satisfied, you will receive an onRunGame - * callback (all other clients in the room are notified the same way). Otherwise the server - * might answer with a warning, or might not answer at all. - */ -int flib_netconn_send_startGame(flib_netconn *conn); + /** + * Set the script (game style). Only makes sense in room state and if you are chief. + * The server does not send a reply. + */ + int flib_netconn_send_script(flib_netconn *conn, const char *scriptName); + + /** + * Set the scheme. Only makes sense in room state and if you are chief. + * The server does not send a reply. + */ + int flib_netconn_send_scheme(flib_netconn *conn, const flib_scheme *scheme); -/** - * Allow/forbid players to join the room. Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_toggleRestrictJoins(flib_netconn *conn); + /** + * Signal that you want to start the game. Only makes sense in room state and if you are chief. + * The server will check whether all players are ready and whether it believes the setup makes + * sense (e.g. more than one clan). If the server is satisfied, you will receive an onRunGame + * callback (all other clients in the room are notified the same way). Otherwise the server + * might answer with a warning, or might not answer at all. + */ + int flib_netconn_send_startGame(flib_netconn *conn); -/** - * Allow/forbid adding teams to the room. Only makes sense in room state and if you are chief. - * The server does not send a reply. - */ -int flib_netconn_send_toggleRestrictTeams(flib_netconn *conn); + /** + * Allow/forbid players to join the room. Only makes sense in room state and if you are chief. + * The server does not send a reply. + */ + int flib_netconn_send_toggleRestrictJoins(flib_netconn *conn); + + /** + * Allow/forbid adding teams to the room. Only makes sense in room state and if you are chief. + * The server does not send a reply. + */ + int flib_netconn_send_toggleRestrictTeams(flib_netconn *conn); + -/** - * Does something administrator-y. At any rate you need to be an administrator and in the lobby - * to use this command. - */ -int flib_netconn_send_clearAccountsCache(flib_netconn *conn); +// Send functions that are only needed for running a game + + /** + * Send a teamchat message, forwarded from the engine. Only makes sense ingame. + * The server does not send a reply. In contrast to a Chat message, the server + * automatically converts this into an engine message and passes it on to the other + * clients. + */ + int flib_netconn_send_teamchat(flib_netconn *conn, const char *msg); -/** - * Sets a server variable to the indicated value. Only makes sense if you are server admin. - * Known variables are MOTD_NEW, MOTD_OLD and LATEST_PROTO. - */ -int flib_netconn_send_setServerVar(flib_netconn *conn, const char *name, const char *value); + /** + * Send an engine message. Only makes sense when ingame. In a networked game, you have to pass + * all the engine messages from the engine here, and they will be spread to all other clients + * in the game to keep the game in sync. + */ + int flib_netconn_send_engineMessage(flib_netconn *conn, const uint8_t *message, size_t size); -/** - * Queries all server variables. Only makes sense if you are server admin. - * If the action succeeds, you will receive several onServerVar callbacks with the - * current values of all server variables. - */ -int flib_netconn_send_getServerVars(flib_netconn *conn); + /** + * Inform the server that the round has ended. Call this when the engine has disconnected, + * passing 1 if the round ended normally, 0 otherwise. + */ + int flib_netconn_send_roundfinished(flib_netconn *conn, bool withoutError); +// Callbacks that are important for connecting/disconnecting + /** + * onNickTaken is called when connecting to the server, if it turns out that there is already a + * player with the same nick. + * In order to proceed, a new nickname needs to be sent to the server using + * flib_netconn_send_nick() (or of course you can bail out and send a QUIT). + * If you don't set a callback, the netconn will automatically react by generating a new name. + */ + void flib_netconn_onNickTaken(flib_netconn *conn, void (*callback)(void *context, const char *nick), void* context); + /** + * When connecting with a registered nickname, the server will ask for a password before + * admitting you in. This callback is called when that happens. As a reaction, you can send the + * password using flib_netconn_send_password. If you don't register a callback, the default + * behavior is to just quit in a way that will cause a disconnect with + * NETCONN_DISCONNECT_AUTH_FAILED. + * + * You can't just choose a new nickname when you receive this callback, because at that point + * the server has already accepted your nick. + */ + void flib_netconn_onPasswordRequest(flib_netconn *conn, void (*callback)(void *context, const char *nick), void* context); + /** + * This is called when the server has accepted our nickname (and possibly password) and we have + * entered the lobby. + */ + void flib_netconn_onConnected(flib_netconn *conn, void (*callback)(void *context), void* context); + + /** + * This is always the last callback (unless the netconn is destroyed early), and the netconn + * should be destroyed when it is received. The reason for the disconnect is passed as one of + * the NETCONN_DISCONNECT_ constants. Sometimes a message is included as well, but that + * parameter might also be NULL. + */ + void flib_netconn_onDisconnected(flib_netconn *conn, void (*callback)(void *context, int reason, const char *message), void* context); -/** - * Callback for several informational messages that should be displayed to the user - * (e.g. in the chat window), but do not require a reaction. If a game is running, you might - * want to redirect some of these messages to the engine as well so the user will see them. - */ -void flib_netconn_onMessage(flib_netconn *conn, void (*callback)(void *context, int msgtype, const char *msg), void* context); +// Callbacks that make sense in most situations -/** - * We received a chat message. Where this message belongs depends on the current state (lobby/room/game). In particular, - * if a game is running the message should be passed to the engine. - */ -void flib_netconn_onChat(flib_netconn *conn, void (*callback)(void *context, const char *nick, const char *msg), void* context); + /** + * Callback for several informational messages that should be displayed to the user + * (e.g. in the chat window), but do not require a reaction. If a game is running, you might + * want to redirect some of these messages to the engine as well so the user will see them. + */ + void flib_netconn_onMessage(flib_netconn *conn, void (*callback)(void *context, int msgtype, const char *msg), void* context); + + /** + * We received a chat message. Where this message belongs depends on the current state + * (lobby/room). If a game is running the message should be passed to the engine. + */ + void flib_netconn_onChat(flib_netconn *conn, void (*callback)(void *context, const char *nick, const char *msg), void* context); -/** - * This is called when we receive a CONNECTED message from the server, which should be the first - * message arriving from the server. - */ -void flib_netconn_onConnected(flib_netconn *conn, void (*callback)(void *context), void* context); + /** + * Callbacks for incremental room list updates. They will fire whenever these events occur, + * even before you first query the actual roomlist - so be sure not to blindly reference your + * room list in these callbacks. The server currently only sends updates when a room changes + * its name, so in order to update other room information you need to query the roomlist again + * (see send_request_roomlist / onRoomlist). + */ + void flib_netconn_onRoomAdd(flib_netconn *conn, void (*callback)(void *context, const flib_room *room), void* context); + void flib_netconn_onRoomDelete(flib_netconn *conn, void (*callback)(void *context, const char *name), void* context); + void flib_netconn_onRoomUpdate(flib_netconn *conn, void (*callback)(void *context, const char *oldName, const flib_room *room), void* context); -/** - * This is *always* the last callback (unless the netconn is destroyed early), and the netconn should be destroyed when it is received. - * The reason is one of the NETCONN_DISCONNECT_ constants. Sometime a message is included as well, but that parameter might - * also be NULL. - */ -void flib_netconn_onDisconnected(flib_netconn *conn, void (*callback)(void *context, int reason, const char *message), void* context); + /** + * Callbacks for players joining or leaving the lobby. In contrast to the roomlist updates, you + * will get a JOIN callback for every player already on the server when you join (and there is + * no direct way to query the current playerlist) + * + * NOTE: partMessage may be NULL. + */ + void flib_netconn_onLobbyJoin(flib_netconn *conn, void (*callback)(void *context, const char *nick), void* context); + void flib_netconn_onLobbyLeave(flib_netconn *conn, void (*callback)(void *context, const char *nick, const char *partMessage), void* context); -/** - * Callbacks for room list updates. The roomlist can be queried with flib_netconn_send_request_roomlist(), which will - * trigger flib_netconn_onRoomlist once the server replies. Additionally, the roomAdd/delete/update callbacks will fire - * whenever the server informs about these events, which can happen *before* the roomlist is first received - so be sure - * not to blindly reference your room list in these callbacks. The server currently only sends updates when a room changes - * its name, so in order to update other room information you need to query the roomlist again. - */ -void flib_netconn_onRoomlist(flib_netconn *conn, void (*callback)(void *context, const flib_room **rooms, int roomCount), void* context); -void flib_netconn_onRoomAdd(flib_netconn *conn, void (*callback)(void *context, const flib_room *room), void* context); -void flib_netconn_onRoomDelete(flib_netconn *conn, void (*callback)(void *context, const char *name), void* context); -void flib_netconn_onRoomUpdate(flib_netconn *conn, void (*callback)(void *context, const char *oldName, const flib_room *room), void* context); + +// Callbacks that happen only in response to specific requests -/** - * Callbacks for players joining or leaving the lobby. If join is true it's a join, otherwise a leave. - * NOTE: partMessage is null if no parting message was given. - */ -void flib_netconn_onLobbyJoin(flib_netconn *conn, void (*callback)(void *context, const char *nick), void* context); -void flib_netconn_onLobbyLeave(flib_netconn *conn, void (*callback)(void *context, const char *nick, const char *partMessage), void* context); + /** + * Response to flib_netconn_send_request_roomlist(). + * The rooms array contains the current state of all rooms on the server. + */ + void flib_netconn_onRoomlist(flib_netconn *conn, void (*callback)(void *context, const flib_room **rooms, int roomCount), void* context); -/** - * onNickTaken is called on connecting to the server, if it turns out that there is already a player with the same nick. - * In order to proceed, a new nickname needs to be sent to the server using flib_netconn_send_nick() (or of course you can - * bail out and send a QUIT). If you don't set a callback, the netconn will automatically react by generating a new name. - * Once the server accepts a name, you will be informed with an onNickAccept callback. - */ -void flib_netconn_onNickTaken(flib_netconn *conn, void (*callback)(void *context, const char *nick), void* context); + /** + * Response to flib_netconn_send_joinRoom, flib_netconn_send_playerFollow or + * flib_netconn_send_createRoom. + * + * You just left the lobby and entered a room. + * If chief is true, you can and should send a full configuration for the room now. This + * consists of ammo, scheme, script and map, where map apparently has to come last. + */ + void flib_netconn_onEnterRoom(flib_netconn *conn, void (*callback)(void *context, bool chief), void *context); -/** - * When connecting with a registered nickname, the server will ask for a password before admitting you in. - * This callback is called when that happens. As a reaction, you can send the password using - * flib_netconn_send_password or choose a different nick. If you don't register a callback, - * the default behavior is to just quit in a way that will cause a disconnect with NETCONN_DISCONNECT_AUTH_FAILED. - */ -void flib_netconn_onPasswordRequest(flib_netconn *conn, void (*callback)(void *context, const char *nick), void* context); + /** + * Response to flib_netconn_send_addTeam. + * The server might reject your team for several reasons, e.g. because it has the same name as + * an existing team, or because the room chief restricted adding new teams. If the team is + * accepted by the server, this callback is fired. + * + * If you are the room chief, you are expected to provide the hog count for your own team now + * using flib_netconn_send_teamHogCount. The color of the team is already set to the one you + * provided in addTeam. + */ + void flib_netconn_onTeamAccepted(flib_netconn *conn, void (*callback)(void *context, const char *team), void *context); -/** - * You just left the lobby and entered a room. - * If chief is true, you can and should send a full configuration for the room now. - * This consists of ammo, scheme, script and map, where map apparently has to come last. - */ -void flib_netconn_onEnterRoom(flib_netconn *conn, void (*callback)(void *context, bool chief), void *context); + /** + * When you query the server vars with flib_netconn_send_getServerVars (only works as admin), + * the server replies with a list of them. This callback is called for each entry in that list. + */ + void flib_netconn_onServerVar(flib_netconn *conn, void (*callback)(void *context, const char *name, const char *value), void *context); -/** - * The following callbacks are only relevant in room state. - */ +// Callbacks that are only relevant in a room -/** - * This callback informs about changes to your room chief status, i.e. whether you are allowed to - * modify the current room. Generally when you create a room you start out being room chief, and - * when you join an existing room you are not. However, in some situations room ownership can change, - * and if that happens this callback is called with the new status. - * - * Note: This callback does not automatically fire when joining a room. You can always query the - * current chief status using flib_netconn_is_chief(). - */ -void flib_netconn_onRoomChiefStatus(flib_netconn *conn, void (*callback)(void *context, bool chief), void* context); + /** + * This callback informs about changes to your room chief status, i.e. whether you are allowed + * to modify the current room. Generally when you create a room you start out being room chief, + * and when you join an existing room you are not. However, if the original chief leaves a room, + * the server can choose a new chief, and if that happens this callback is called with the new + * status. + * + * Note: This callback does not automatically fire when joining a room. You can always query the + * current chief status using flib_netconn_is_chief(). + */ + void flib_netconn_onRoomChiefStatus(flib_netconn *conn, void (*callback)(void *context, bool chief), void* context); -/** - * One of the players in the room (possibly you!) changed their ready state. - */ -void flib_netconn_onReadyState(flib_netconn *conn, void (*callback)(void *context, const char *nick, bool ready), void* context); + /** + * One of the players in the room (possibly you) changed their ready state. + */ + void flib_netconn_onReadyState(flib_netconn *conn, void (*callback)(void *context, const char *nick, bool ready), void* context); + + /** + * You just left a room and entered the lobby again. + * reason is one of the NETCONN_ROOMLEAVE_ constants (usually a kick). + * This will not be called when you actively leave a room using PART. + * Don't confuse with onRoomLeave, which indicates that *someone else* left the room. + */ + void flib_netconn_onLeaveRoom(flib_netconn *conn, void (*callback)(void *context, int reason, const char *message), void *context); -/** - * You just left a room and entered the lobby again. - * reason is one of the NETCONN_ROOMLEAVE_ constants. - * This will not be called when you actively leave a room using PART. - */ -void flib_netconn_onLeaveRoom(flib_netconn *conn, void (*callback)(void *context, int reason, const char *message), void *context); + /** + * Someone joined or left the room you are currently in. + * Analogous to onLobbyJoin/leave, you will receive the join callback for all players that are + * already in the room when you join, including for yourself (this is actually how it is + * determined that you joined a room). + * + * However, you will *not* receive onRoomLeave messages for everyone when you leave the room. + */ + void flib_netconn_onRoomJoin(flib_netconn *conn, void (*callback)(void *context, const char *nick), void* context); + void flib_netconn_onRoomLeave(flib_netconn *conn, void (*callback)(void *context, const char *nick, const char *partMessage), void* context); -/** - * A new team was added to the room. The person who adds a team does NOT receive this callback (he gets onTeamAccepted instead). - * The team does not contain bindings, stats, weaponset, color or the number of hogs. - * - * If you receive this message and you are the room chief, you are expected to provide a color and hog count for this team using - * flib_netconn_send_teamHogCount / teamColor. - */ -void flib_netconn_onTeamAdd(flib_netconn *conn, void (*callback)(void *context, const flib_team *team), void *context); + /** + * A new team was added to the room. The person who adds a team does NOT receive this callback + * (he gets onTeamAccepted instead). + * + * The team does not contain bindings, stats, weaponset, color or the number of hogs (but it is + * assumed to be the default of 4). + * + * If you receive this message and you are the room chief, you may want to send a color and hog + * count for this team using flib_netconn_send_teamHogCount / teamColor for QtFrontend + * compatibility. + * + * The server currently sends another message with the color of the team to the same recipients + * as this teamAdd message, which will trigger an onTeamColorChanged callback. See the + * description of flib_netconn_send_addTeam for more information. + */ + void flib_netconn_onTeamAdd(flib_netconn *conn, void (*callback)(void *context, const flib_team *team), void *context); -/** - * A team was removed from the room. - */ -void flib_netconn_onTeamDelete(flib_netconn *conn, void (*callback)(void *context, const char *teamname), void *context); - -void flib_netconn_onRoomJoin(flib_netconn *conn, void (*callback)(void *context, const char *nick), void* context); -void flib_netconn_onRoomLeave(flib_netconn *conn, void (*callback)(void *context, const char *nick, const char *partMessage), void* context); - -/** - * The game is starting. Fire up the engine and join in! - * You can let the netconn generate the right game setup using flib_netconn_create_gamesetup - */ -void flib_netconn_onRunGame(flib_netconn *conn, void (*callback)(void *context), void *context); + /** + * A team was removed from the room. The person who removed the team will not receive this + * callback. + */ + void flib_netconn_onTeamDelete(flib_netconn *conn, void (*callback)(void *context, const char *teamname), void *context); -/** - * When you ask for a team to be added, the server might reject it for several reasons, e.g. because it has the same name - * as an existing team, or because the room chief restricted adding new teams. If the team is accepted by the server, - * this callback is fired. - * - * If you are the room chief, you are expected to provide the hog count for your own team now using flib_netconn_send_teamHogCount. - * The color of the team is already set to the one you provided in addTeam, but the QtFrontend apparently always uses 0 there and - * instead sets the color after the team is accepted. - */ -void flib_netconn_onTeamAccepted(flib_netconn *conn, void (*callback)(void *context, const char *team), void *context); + /** + * The number of hogs in a team has been changed by the room chief. If you are the chief and + * change the number of hogs yourself, you will not receive this callback. + */ + void flib_netconn_onHogCountChanged(flib_netconn *conn, void (*callback)(void *context, const char *teamName, int hogs), void *context); -/** - * The number of hogs in a team has been changed by the room chief. If you are the chief and change the number of hogs yourself, - * you will not receive this callback! - */ -void flib_netconn_onHogCountChanged(flib_netconn *conn, void (*callback)(void *context, const char *teamName, int hogs), void *context); + /** + * The color of a team has been set or changed. The client who set or changed the color will + * not receive this callback. + * + * Normally, only the chief can change the color of a team. However, this message is also + * generated when a team is added, so you can receive it even as chief. + */ + void flib_netconn_onTeamColorChanged(flib_netconn *conn, void (*callback)(void *context, const char *teamName, int colorIndex), void *context); -/** - * The color of a team has been changed by the room chief. If you are the chief and change the color yourself, - * you will not receive this callback! - */ -void flib_netconn_onTeamColorChanged(flib_netconn *conn, void (*callback)(void *context, const char *teamName, int colorIndex), void *context); - -void flib_netconn_onEngineMessage(flib_netconn *conn, void (*callback)(void *context, const uint8_t *message, size_t size), void *context); - -void flib_netconn_onCfgScheme(flib_netconn *conn, void (*callback)(void *context, const flib_scheme *scheme), void *context); + /** + * The room chief has changed the game scheme (or you just joined a room). + * You will not receive this callback if you changed the scheme yourself. + */ + void flib_netconn_onSchemeChanged(flib_netconn *conn, void (*callback)(void *context, const flib_scheme *scheme), void *context); -/** - * This is called when the map configuration in a room is changed (or first received). Only non-chiefs receive these messages. - * To reduce the number of callback functions, the netconn keeps track of the current map settings and always passes the entire - * current map config, but informs the callee about what has changed (see the NETCONN_MAPCHANGE_ constants). - * The map parameter passed to the callback is an internally held map config. If you want to keep it around, best make a copy - * or it may or may not change while you are not looking. - * - * Caution: Due to the way the protocol works, the map might not be complete at this point if it is a hand-drawn map, because - * the "full" map config does not include the drawn map data. - */ -void flib_netconn_onMapChanged(flib_netconn *conn, void (*callback)(void *context, const flib_map *map, int changetype), void *context); + /** + * The room chief has changed the map (or you just joined a room). Only non-chiefs receive these + * messages. + * + * To reduce the number of callback functions, the netconn keeps track of the current map + * settings and always passes the entire current map config, but informs the callee about what + * has changed (see the NETCONN_MAPCHANGE_ constants). + * + * Caution: Due to the way the protocol works, the map might not be complete at this point if it + * is a hand-drawn map, because the "full" map config does not include the drawn map data. + */ + void flib_netconn_onMapChanged(flib_netconn *conn, void (*callback)(void *context, const flib_map *map, int changetype), void *context); + + /** + * The room chief has changed the game style (or you just joined a room). If you are the chief + * and change the style yourself, you will not receive this callback. + */ + void flib_netconn_onScriptChanged(flib_netconn *conn, void (*callback)(void *context, const char *script), void *context); -/** - * The "game style" script has been changed by the room chief. If you are the chief and change the script yourself, - * you will not receive this callback! - */ -void flib_netconn_onScriptChanged(flib_netconn *conn, void (*callback)(void *context, const char *script), void *context); + /** + * The room chief has changed the weaponset (or you just joined a room). If you are the chief + * and change the weaponset yourself, you will not receive this callback. + */ + void flib_netconn_onWeaponsetChanged(flib_netconn *conn, void (*callback)(void *context, const flib_weaponset *weaponset), void *context); + + /** + * The game is starting. Fire up the engine and join in! + * You can let the netconn generate the right game setup using flib_netconn_create_gamesetup + */ + void flib_netconn_onRunGame(flib_netconn *conn, void (*callback)(void *context), void *context); -/** - * The weaponset has been changed by the room chief. If you are the chief and change the weaponset yourself, - * you will not receive this callback! - */ -void flib_netconn_onWeaponsetChanged(flib_netconn *conn, void (*callback)(void *context, const flib_weaponset *weaponset), void *context); + /** + * You are in a room, a game is in progress, and the server is sending you the new input for the + * engine to keep up to date with the current happenings. Pass it on to the engine using + * flib_gameconn_send_enginemsg. + */ + void flib_netconn_onEngineMessage(flib_netconn *conn, void (*callback)(void *context, const uint8_t *message, size_t size), void *context); -/** - * This callback is called if the server informs us that we have admin rights. - */ -void flib_netconn_onAdminAccess(flib_netconn *conn, void (*callback)(void *context), void *context); + +// Callbacks only needed for admin stuffs -/** - * When you query the server vars with flib_netconn_send_getServerVars (only works as admin), the server - * replies with a list of them. This callback is called for each entry in that list. - */ -void flib_netconn_onServerVar(flib_netconn *conn, void (*callback)(void *context, const char *name, const char *value), void *context); + /** + * This callback is called if the server informs us that we have admin rights. + */ + void flib_netconn_onAdminAccess(flib_netconn *conn, void (*callback)(void *context), void *context); #endif diff -r d5c880e6d772 -r c92596feac0d project_files/frontlib/net/netconn_callbacks.c --- a/project_files/frontlib/net/netconn_callbacks.c Mon Aug 20 17:08:52 2012 +0200 +++ b/project_files/frontlib/net/netconn_callbacks.c Mon Aug 20 20:16:37 2012 +0200 @@ -86,7 +86,7 @@ flib_netconn_onHogCountChanged(conn, NULL, NULL); flib_netconn_onTeamColorChanged(conn, NULL, NULL); flib_netconn_onEngineMessage(conn, NULL, NULL); - flib_netconn_onCfgScheme(conn, NULL, NULL); + flib_netconn_onSchemeChanged(conn, NULL, NULL); flib_netconn_onMapChanged(conn, NULL, NULL); flib_netconn_onScriptChanged(conn, NULL, NULL); flib_netconn_onWeaponsetChanged(conn, NULL, NULL); @@ -142,7 +142,7 @@ GENERATE_CB_SETTER_AND_DEFAULT(onHogCountChanged, (void *context, const char *teamName, int hogs)); GENERATE_CB_SETTER_AND_DEFAULT(onTeamColorChanged, (void *context, const char *teamName, int colorIndex)); GENERATE_CB_SETTER_AND_DEFAULT(onEngineMessage, (void *context, const uint8_t *message, size_t size)); -GENERATE_CB_SETTER_AND_DEFAULT(onCfgScheme, (void *context, const flib_scheme *scheme)); +GENERATE_CB_SETTER_AND_DEFAULT(onSchemeChanged, (void *context, const flib_scheme *scheme)); GENERATE_CB_SETTER_AND_DEFAULT(onMapChanged, (void *context, const flib_map *map, int changetype)); GENERATE_CB_SETTER_AND_DEFAULT(onScriptChanged, (void *context, const char *script)); GENERATE_CB_SETTER_AND_DEFAULT(onWeaponsetChanged, (void *context, const flib_weaponset *weaponset)); diff -r d5c880e6d772 -r c92596feac0d project_files/frontlib/net/netconn_internal.h --- a/project_files/frontlib/net/netconn_internal.h Mon Aug 20 17:08:52 2012 +0200 +++ b/project_files/frontlib/net/netconn_internal.h Mon Aug 20 20:16:37 2012 +0200 @@ -126,8 +126,8 @@ void (*onEngineMessageCb)(void *context, const uint8_t *message, size_t size); void *onEngineMessageCtx; - void (*onCfgSchemeCb)(void *context, const flib_scheme *scheme); - void *onCfgSchemeCtx; + void (*onSchemeChangedCb)(void *context, const flib_scheme *scheme); + void *onSchemeChangedCtx; void (*onMapChangedCb)(void *context, const flib_map *map, int changetype); void *onMapChangedCtx; diff -r d5c880e6d772 -r c92596feac0d project_files/frontlib/net/netconn_send.c --- a/project_files/frontlib/net/netconn_send.c Mon Aug 20 17:08:52 2012 +0200 +++ b/project_files/frontlib/net/netconn_send.c Mon Aug 20 20:16:37 2012 +0200 @@ -54,24 +54,6 @@ return flib_netbase_sendf(conn->netBase, "%s\n%i\n\n", cmdname, param); } -int flib_netconn_send_quit(flib_netconn *conn, const char *quitmsg) { - return sendStr(conn, "QUIT", (quitmsg && *quitmsg) ? quitmsg : "User quit"); -} - -int flib_netconn_send_chat(flib_netconn *conn, const char *chat) { - if(!flib_strempty(chat)) { - return sendStr(conn, "CHAT", chat); - } - return 0; -} - -int flib_netconn_send_teamchat(flib_netconn *conn, const char *chat) { - if(!flib_strempty(chat)) { - return sendStr(conn, "TEAMCHAT", chat); - } - return 0; -} - int flib_netconn_send_nick(flib_netconn *conn, const char *nick) { int result = -1; if(!log_badargs_if2(conn==NULL, flib_strempty(nick))) { @@ -107,6 +89,25 @@ return result; } +int flib_netconn_send_quit(flib_netconn *conn, const char *quitmsg) { + return sendStr(conn, "QUIT", (quitmsg && *quitmsg) ? quitmsg : "User quit"); +} + +int flib_netconn_send_chat(flib_netconn *conn, const char *chat) { + if(!flib_strempty(chat)) { + return sendStr(conn, "CHAT", chat); + } + return 0; +} + +int flib_netconn_send_kick(flib_netconn *conn, const char *playerName) { + return sendStr(conn, "KICK", playerName); +} + +int flib_netconn_send_playerInfo(flib_netconn *conn, const char *playerName) { + return sendStr(conn, "INFO", playerName); +} + int flib_netconn_send_request_roomlist(flib_netconn *conn) { return sendVoid(conn, "LIST"); } @@ -119,6 +120,10 @@ return -1; } +int flib_netconn_send_playerFollow(flib_netconn *conn, const char *playerName) { + return sendStr(conn, "FOLLOW", playerName); +} + int flib_netconn_send_createRoom(flib_netconn *conn, const char *room) { if(!sendStr(conn, "CREATE_ROOM", room)) { conn->isChief = true; @@ -127,10 +132,24 @@ return -1; } -int flib_netconn_send_renameRoom(flib_netconn *conn, const char *roomName) { - return sendStr(conn, "ROOM_NAME", roomName); +int flib_netconn_send_ban(flib_netconn *conn, const char *playerName) { + return sendStr(conn, "BAN", playerName); +} + +int flib_netconn_send_clearAccountsCache(flib_netconn *conn) { + return sendVoid(conn, "CLEAR_ACCOUNTS_CACHE"); } +int flib_netconn_send_setServerVar(flib_netconn *conn, const char *name, const char *value) { + if(log_badargs_if3(conn==NULL, flib_strempty(name), flib_strempty(value))) { + return -1; + } + return flib_netbase_sendf(conn->netBase, "%s\n%s\n%s\n\n", "SET_SERVER_VAR", name, value); +} + +int flib_netconn_send_getServerVars(flib_netconn *conn) { + return sendVoid(conn, "GET_SERVER_VAR"); +} int flib_netconn_send_leaveRoom(flib_netconn *conn, const char *str) { int result = -1; if(conn->netconnState==NETCONN_STATE_ROOM) { @@ -198,17 +217,8 @@ return -1; } -int flib_netconn_send_engineMessage(flib_netconn *conn, const uint8_t *message, size_t size) { - int result = -1; - if(!log_badargs_if2(conn==NULL, message==NULL && size>0)) { - char *base64encout = NULL; - base64_encode_alloc((const char*)message, size, &base64encout); - if(base64encout) { - result = flib_netbase_sendf(conn->netBase, "EM\n%s\n\n", base64encout); - } - free(base64encout); - } - return result; +int flib_netconn_send_renameRoom(flib_netconn *conn, const char *roomName) { + return sendStr(conn, "ROOM_NAME", roomName); } int flib_netconn_send_teamHogCount(flib_netconn *conn, const char *teamname, int hogcount) { @@ -447,26 +457,6 @@ return result; } -int flib_netconn_send_roundfinished(flib_netconn *conn, bool withoutError) { - return sendInt(conn, "ROUNDFINISHED", withoutError ? 1 : 0); -} - -int flib_netconn_send_ban(flib_netconn *conn, const char *playerName) { - return sendStr(conn, "BAN", playerName); -} - -int flib_netconn_send_kick(flib_netconn *conn, const char *playerName) { - return sendStr(conn, "KICK", playerName); -} - -int flib_netconn_send_playerInfo(flib_netconn *conn, const char *playerName) { - return sendStr(conn, "INFO", playerName); -} - -int flib_netconn_send_playerFollow(flib_netconn *conn, const char *playerName) { - return sendStr(conn, "FOLLOW", playerName); -} - int flib_netconn_send_startGame(flib_netconn *conn) { return sendVoid(conn, "START_GAME"); } @@ -479,17 +469,27 @@ return sendVoid(conn, "TOGGLE_RESTRICT_TEAMS"); } -int flib_netconn_send_clearAccountsCache(flib_netconn *conn) { - return sendVoid(conn, "CLEAR_ACCOUNTS_CACHE"); +int flib_netconn_send_teamchat(flib_netconn *conn, const char *chat) { + if(!flib_strempty(chat)) { + return sendStr(conn, "TEAMCHAT", chat); + } + return 0; } -int flib_netconn_send_setServerVar(flib_netconn *conn, const char *name, const char *value) { - if(log_badargs_if3(conn==NULL, flib_strempty(name), flib_strempty(value))) { - return -1; +int flib_netconn_send_engineMessage(flib_netconn *conn, const uint8_t *message, size_t size) { + int result = -1; + if(!log_badargs_if2(conn==NULL, message==NULL && size>0)) { + char *base64encout = NULL; + base64_encode_alloc((const char*)message, size, &base64encout); + if(base64encout) { + result = flib_netbase_sendf(conn->netBase, "EM\n%s\n\n", base64encout); + } + free(base64encout); } - return flib_netbase_sendf(conn->netBase, "%s\n%s\n%s\n\n", "SET_SERVER_VAR", name, value); + return result; } -int flib_netconn_send_getServerVars(flib_netconn *conn) { - return sendVoid(conn, "GET_SERVER_VAR"); +int flib_netconn_send_roundfinished(flib_netconn *conn, bool withoutError) { + return sendInt(conn, "ROUNDFINISHED", withoutError ? 1 : 0); } +