hedgewars: comparison project_files/frontlib/net/netconn.h

equal deleted inserted replaced

-:d5c880e6d772
+:c92596feac0d
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */
 /**
-* This file contains functions for communicating with a Hedgewars server to chat, prepare
+* This file contains functions for communicating with a Hedgewars server to chat, prepare and play
-* and play rounds of Hedgewars.
+* rounds of Hedgewars.
 *
-* To use this, first create a netconn object by calling flib_netconn_create. This will
+* To use this, first create a netconn object by calling flib_netconn_create. This will start the
-* start the connection to the game server (which might fail right away, the function
+* connection to the game server (which might fail right away, the function returns null then). You
-* returns null then). You should also register your callback functions right at the start
+* should also register your callback functions right at the start to ensure you don't miss any
-* to ensure you don't miss any callbacks.
+* 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
+* When the connection is closed, you will receive the onDisconnect callback. This is the signal to
-* signal to destroy the netconn and stop calling tick().
+* 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,
+* onConnected callback (or onDisconnected in case something goes wrong). During that time, you
-* you might receive the onNickTaken and onPasswordRequest callbacks; see their description
+* might receive the onNickTaken and onPasswordRequest callbacks; see their description for more
-* for more information on how to handle them. You could also receive other callbacks during
+* information on how to handle them. You could also receive other callbacks during connecting (e.g.
-* connecting (e.g. about the room list), but it should be safe to ignore them.
+* 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.
+* Once you are connected, you are in the lobby, and you can enter rooms and leave them again. The
-* The room and lobby states have different protocols, so many commands only work in either
+* room and lobby states have different protocols, so many commands only work in either one or the
-* one or the other. If you are in a room you might also be in a game, but that does not
+* other. If you are in a room you might also be in a game, but most of the functions behave the
-* change the protocol. The functions below are grouped by the states in which they make
+* same ingame as in a room.
-* sense, or (for the callbacks) the states in which you would typically receive them.
+*
-*
+* The state changes from lobby to room when the server tells you that you just entered one, which
-* The state changes from lobby to room when the server tells you that you just entered one,
+* will also trigger the onEnterRoom callback. This usually happens in reply to either a joinRoom,
-* which will also trigger the onEnterRoom callback. This usually happens in reply to either
+* createRoom or playerFollow command.
-* 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
-* The state changes back to lobby when the room is dissolved, when you are kicked from the
+* when you actively leave the room using flib_netconn_send_leaveRoom. The first two events will
-* room, or when you actively leave the room using flib_netconn_send_leaveRoom. The first
+* trigger the onLeaveRoom callback.
-* two events will trigger the onLeaveRoom callback.
 */
 #ifndef NETCONN_H_
 #define NETCONN_H_
 #define NETCONN_MAPCHANGE_MAZE_SIZE 4
 #define NETCONN_MAPCHANGE_TEMPLATE 5
 #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;
 /**
 * Create a new netplay connection with these parameters.
 * The path to the data directory must end with a path delimiter (e.g. C:\Games\Hedgewars\Data\)
 * NETCONN_STATE_ROOM and NETCONN_STATE_INGAME states.
 */
 bool flib_netconn_is_chief(flib_netconn *conn);
 /**
-* Returns the playername. This is *probably* the one provided on creation, but
+* Returns the playername. This is *probably* the one provided on creation, but if that name was
-* if that name was already taken, a different one could have been set by the
+* already taken, a different one could have been set by the onNickTaken callback or its default
-* onNickTaken callback or its default implementation.
+* 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
+* Returns NULL if the room state does not contain enough information for a complete game setup,
-* for a complete game setup, or if an error occurs.
+* 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);
+// Send functions needed when connecting and disconnecting
-int flib_netconn_send_chat(flib_netconn *conn, const char *chat);
+	/**
-/**
+	 * Request a different nickname.
-* Send a teamchat message, forwarded from the engine. Only makes sense ingame.
+	 * This function only makes sense in reaction to an onNickTaken callback, because the netconn
-* The server does not send a reply. In contrast to a Chat message, the server
+	 * automatically requests the nickname you provide on creation, and once the server accepts the
-* automatically converts this into an engine message and passes it on to the other
+	 * nickname it can no longer be changed.
-* clients.
+	 */
-*/
+	int flib_netconn_send_nick(flib_netconn *conn, const char *nick);
-int flib_netconn_send_teamchat(flib_netconn *conn, const char *msg);
+	/**
-/**
+	 * Send the password in reply to a password request.
-* Send the password in reply to a password request.
+	 * If the server does not accept the password, you will be disconnected
-* If the server does not accept the password, you will be disconnected (NETCONN_DISCONNECT_AUTH_FAILED)
+	 * (NETCONN_DISCONNECT_AUTH_FAILED)
-*/
+	 */
-int flib_netconn_send_password(flib_netconn *conn, const char *passwd);
+	int flib_netconn_send_password(flib_netconn *conn, const char *passwd);
-/**
+	/**
-* Request a different nickname.
+	 * Tell the server that you want to leave. If successful, the server will disconnect you.
-* 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
+	int flib_netconn_send_quit(flib_netconn *conn, const char *quitmsg);
-* be changed.
-*/
-int flib_netconn_send_nick(flib_netconn *conn, const char *nick);
+// Send functions that make sense both in the lobby and in rooms
-/**
+	/**
-* Request an update of the room list. Only makes sense when in lobby state.
+	 * Send a chat message. This message is either sent to the lobby or the room, depending on
-* If the action succeeds, you will receive an onRoomlist callback containing the current room data.
+	 * whether you are in a room at the moment. The message is not echoed back to you.
-*/
+	 */
-int flib_netconn_send_request_roomlist(flib_netconn *conn);
+	int flib_netconn_send_chat(flib_netconn *conn, const char *chat);
-/**
+	/**
-* Join a room as guest (not chief). Only makes sense when in lobby state. If the action succeeds, you will
+	 * Kick a player. This has different meanings in the lobby and in a room;
-* receive an onEnterRoom callback with chief=false.
+	 * 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_joinRoom(flib_netconn *conn, const char *room);
+	 */
+	int flib_netconn_send_kick(flib_netconn *conn, const char *playerName);
-/**
-* 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.
+	 * 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
-int flib_netconn_send_createRoom(flib_netconn *conn, const char *room);
+	 * the requested information.
+	 */
-/**
+	int flib_netconn_send_playerInfo(flib_netconn *conn, const char *playerName);
-* 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.
-*/
+// Send functions that only make sense in the lobby
-int flib_netconn_send_renameRoom(flib_netconn *conn, const char *roomName);
+	/**
-/**
+	 * Request an update of the room list. Only makes sense when in lobby state.
-* Leave the room for the lobby. Only makes sense in room state. msg can be NULL if you don't want to
+	 * If the action succeeds, you will receive an onRoomlist callback containing the current room
-* send a message. The server always accepts a part message, so once you send it off, you can just
+	 * data.
-* assume that you are back in the lobby.
+	 */
-*/
+	int flib_netconn_send_request_roomlist(flib_netconn *conn);
-int flib_netconn_send_leaveRoom(flib_netconn *conn, const char *msg);
+	/**
-/**
+	 * Join a room as guest (not chief). Only makes sense when in lobby state. If the action
-* Change your "ready" status in the room. Only makes sense when in room state. If the action succeeds, you will
+	 * succeeds, you will receive an onEnterRoom callback with chief=false.
-* receive an onReadyState callback containing the change.
+	 */
-*/
+	int flib_netconn_send_joinRoom(flib_netconn *conn, const char *room);
-int flib_netconn_send_toggleReady(flib_netconn *conn);
+	/**
-/**
+	 * Follow a player. Only valid in the lobby. If the player is in a room (or in a game), this
-* Add a team to the current room. Apart from the "fixed" team information, this also includes
+	 * command is analogous to calling flib_netconn_send_joinRoom with that room.
-* 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_playerFollow(flib_netconn *conn, const char *playerName);
-*/
-int flib_netconn_send_addTeam(flib_netconn *conn, const flib_team *team);
+	/**
+	 * 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.
-* 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_createRoom(flib_netconn *conn, const char *room);
-*/
-int flib_netconn_send_removeTeam(flib_netconn *conn, const char *teamname);
+	/**
+	 * Ban a player. You need to be in the lobby and a server admin for this to work.
-/**
+	 */
-* Send an engine message. Only makes sense when ingame. In a networked game, you have to
+	int flib_netconn_send_ban(flib_netconn *conn, const char *playerName);
-* 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.
+	/**
-*/
+	 * Does something administrator-y. At any rate you need to be an administrator and in the lobby
-int flib_netconn_send_engineMessage(flib_netconn *conn, const uint8_t *message, size_t size);
+	 * to use this command.
+	 */
-/**
+	int flib_netconn_send_clearAccountsCache(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.
+	/**
-*/
+	 * Sets a server variable to the indicated value. Only makes sense if you are server admin and
-int flib_netconn_send_teamHogCount(flib_netconn *conn, const char *teamname, int hogcount);
+	 * 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.
-/**
+	 */
-* Set the teamcolor of a team. Only makes sense in room state and if you are chief.
+	int flib_netconn_send_setServerVar(flib_netconn *conn, const char *name, const char *value);
-* The server does not send a reply.
-*/
+	/**
-int flib_netconn_send_teamColor(flib_netconn *conn, const char *teamname, int colorIndex);
+	 * 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.
-* 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_getServerVars(flib_netconn *conn);
-*/
-int flib_netconn_send_weaponset(flib_netconn *conn, const flib_weaponset *weaponset);
+// Send functions that only make sense in a room
-/**
-* Set the map for the room. Only makes sense in room state and if you are chief.
+	/**
-* The server does not send a reply.
+	 * 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,
-int flib_netconn_send_map(flib_netconn *conn, const flib_map *map);
+	 * you can just assume that you are back in the lobby.
+	 */
-/**
+	int flib_netconn_send_leaveRoom(flib_netconn *conn, const char *msg);
-* Set the mapname. Only makes sense in room state and if you are chief.
-* The server does not send a reply.
+	/**
-*/
+	 * Change your "ready" status in the room. Only makes sense when in room state. If the action
-int flib_netconn_send_mapName(flib_netconn *conn, const char *mapName);
+	 * succeeds, you will receive an onReadyState callback containing the change.
+	 */
-/**
+	int flib_netconn_send_toggleReady(flib_netconn *conn);
-* Set the map generator. Only makes sense in room state and if you are chief.
-* The server does not send a reply.
+	/**
-*/
+	 * Add a team to the current room. Apart from the "fixed" team information, this also includes
-int flib_netconn_send_mapGen(flib_netconn *conn, int mapGen);
+	 * 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.
-/**
+	 *
-* Set the map template for regular maps. Only makes sense in room state and if you are chief.
+	 * Notes: Technically, sending a color here is the only way for a non-chief to set the color of
-* The server does not send a reply.
+	 * 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
-int flib_netconn_send_mapTemplate(flib_netconn *conn, int templateFilter);
+	 * 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.
-* 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_addTeam(flib_netconn *conn, const flib_team *team);
-*/
-int flib_netconn_send_mapMazeSize(flib_netconn *conn, int mazeSize);
+	/**
+	 * Remove the team with the name teamname. Only makes sense when in room state.
-/**
+	 * The server does not send a reply on success.
-* 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_removeTeam(flib_netconn *conn, const char *teamname);
-*/
-int flib_netconn_send_mapSeed(flib_netconn *conn, const char *seed);
+// Send functions that only make sense in a room and if you are room chief
-/**
-* Set the theme for the map. Only makes sense in room state and if you are chief.
+	/**
-* The server does not send a reply.
+	 * 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
-int flib_netconn_send_mapTheme(flib_netconn *conn, const char *theme);
+	 * containing the change.
+	 */
-/**
+	int flib_netconn_send_renameRoom(flib_netconn *conn, const char *roomName);
-* 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.
+	/**
-*/
+	 * Set the number of hogs for a team. Only makes sense in room state and if you are chief.
-int flib_netconn_send_mapDrawdata(flib_netconn *conn, const uint8_t *drawData, size_t size);
+	 * The server does not send a reply.
+	 */
-/**
+	int flib_netconn_send_teamHogCount(flib_netconn *conn, const char *teamname, int hogcount);
-* Set the script (game style). Only makes sense in room state and if you are chief.
-* The server does not send a reply.
+	/**
-*/
+	 * Set the teamcolor of a team. Only makes sense in room state and if you are chief.
-int flib_netconn_send_script(flib_netconn *conn, const char *scriptName);
+	 * The server does not send a reply.
+	 */
-/**
+	int flib_netconn_send_teamColor(flib_netconn *conn, const char *teamname, int colorIndex);
-* Set the scheme. Only makes sense in room state and if you are chief.
-* The server does not send a reply.
+	/**
-*/
+	 * Set the weaponset for the room. Only makes sense in room state and if you are chief.
-int flib_netconn_send_scheme(flib_netconn *conn, const flib_scheme *scheme);
+	 * The server does not send a reply.
+	 */
-/**
+	int flib_netconn_send_weaponset(flib_netconn *conn, const flib_weaponset *weaponset);
-* Inform the server that the round has ended. Call this when the engine
-* has disconnected, passing 1 if the round ended normally, 0 otherwise.
+	/**
-*/
+	 * Set the map for the room. Only makes sense in room state and if you are chief.
-int flib_netconn_send_roundfinished(flib_netconn *conn, bool withoutError);
+	 * The server does not send a reply.
+	 */
-/**
+	int flib_netconn_send_map(flib_netconn *conn, const flib_map *map);
-* 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 mapname. Only makes sense in room state and if you are chief.
+	 * The server does not send a reply.
-/**
+	 */
-* Kick a player. This has different meanings in the lobby and in a room;
+	int flib_netconn_send_mapName(flib_netconn *conn, const char *mapName);
-* 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.
+	/**
-*/
+	 * Set the map generator (regular, maze, drawn, named). Only makes sense in room state and if
-int flib_netconn_send_kick(flib_netconn *conn, const char *playerName);
+	 * you are chief.
+	 * The server does not send a reply.
-/**
+	 */
-* Request information about a player. If the action succeeds, you will
+	int flib_netconn_send_mapGen(flib_netconn *conn, int mapGen);
-* receive an onMessage callback with NETCONN_MSG_TYPE_PLAYERINFO containing
-* the requested information.
+	/**
-*/
+	 * Set the map template for regular maps. Only makes sense in room state and if you are chief.
-int flib_netconn_send_playerInfo(flib_netconn *conn, const char *playerName);
+	 * The server does not send a reply.
+	 */
-/**
+	int flib_netconn_send_mapTemplate(flib_netconn *conn, int templateFilter);
-* 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.
+	/**
-*/
+	 * Set the maze template (maze size) for mazes. Only makes sense in room state and if you are
-int flib_netconn_send_playerFollow(flib_netconn *conn, const char *playerName);
+	 * chief. The server does not send a reply.
+	 */
-/**
+	int flib_netconn_send_mapMazeSize(flib_netconn *conn, int mazeSize);
-* 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
+	 * Set the seed for the map. Only makes sense in room state and if you are chief.
-* callback (all other clients in the room are notified the same way). Otherwise the server
+	 * The server does not send a reply.
-* might answer with a warning, or might not answer at all.
+	 */
-*/
+	int flib_netconn_send_mapSeed(flib_netconn *conn, const char *seed);
-int flib_netconn_send_startGame(flib_netconn *conn);
+	/**
-/**
+	 * Set the theme for the map. Only makes sense in room state and if you are chief.
-* 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.
-* The server does not send a reply.
+	 */
-*/
+	int flib_netconn_send_mapTheme(flib_netconn *conn, const char *theme);
-int flib_netconn_send_toggleRestrictJoins(flib_netconn *conn);
+	/**
-/**
+	 * Set the draw data for the drawn map. Only makes sense in room state and if you are chief.
-* 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.
-* The server does not send a reply.
+	 */
-*/
+	int flib_netconn_send_mapDrawdata(flib_netconn *conn, const uint8_t *drawData, size_t size);
-int flib_netconn_send_toggleRestrictTeams(flib_netconn *conn);
+	/**
-/**
+	 * Set the script (game style). Only makes sense in room state and if you are chief.
-* Does something administrator-y. At any rate you need to be an administrator and in the lobby
+	 * The server does not send a reply.
-* to use this command.
+	 */
-*/
+	int flib_netconn_send_script(flib_netconn *conn, const char *scriptName);
-int flib_netconn_send_clearAccountsCache(flib_netconn *conn);
+	/**
-/**
+	 * Set the scheme. Only makes sense in room state and if you are chief.
-* Sets a server variable to the indicated value. Only makes sense if you are server admin.
+	 * The server does not send a reply.
-* Known variables are MOTD_NEW, MOTD_OLD and LATEST_PROTO.
+	 */
-*/
+	int flib_netconn_send_scheme(flib_netconn *conn, const flib_scheme *scheme);
-int flib_netconn_send_setServerVar(flib_netconn *conn, const char *name, const char *value);
+	/**
-/**
+	 * Signal that you want to start the game. Only makes sense in room state and if you are chief.
-* Queries all server variables. Only makes sense if you are server admin.
+	 * The server will check whether all players are ready and whether it believes the setup makes
-* If the action succeeds, you will receive several onServerVar callbacks with the
+	 * sense (e.g. more than one clan). If the server is satisfied, you will receive an onRunGame
-* current values of all server variables.
+	 * 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_getServerVars(flib_netconn *conn);
+	 */
+	int flib_netconn_send_startGame(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.
-* 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
+	int flib_netconn_send_toggleRestrictTeams(flib_netconn *conn);
-* 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);
+// Send functions that are only needed for running a game
-/**
+	/**
-* We received a chat message. Where this message belongs depends on the current state (lobby/room/game). In particular,
+	 * Send a teamchat message, forwarded from the engine. Only makes sense ingame.
-* if a game is running the message should be passed to the engine.
+	 * 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
-void flib_netconn_onChat(flib_netconn *conn, void (*callback)(void *context, const char *nick, const char *msg), void* context);
+	 * clients.
+	 */
-/**
+	int flib_netconn_send_teamchat(flib_netconn *conn, const char *msg);
-* This is called when we receive a CONNECTED message from the server, which should be the first
-* message arriving from the server.
+	/**
-*/
+	 * Send an engine message. Only makes sense when ingame. In a networked game, you have to pass
-void flib_netconn_onConnected(flib_netconn *conn, void (*callback)(void *context), void* context);
+	 * 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.
-/**
+	 */
-* This is *always* the last callback (unless the netconn is destroyed early), and the netconn should be destroyed when it is received.
+	int flib_netconn_send_engineMessage(flib_netconn *conn, const uint8_t *message, size_t size);
-* The reason is one of the NETCONN_DISCONNECT_ constants. Sometime a message is included as well, but that parameter might
-* also be NULL.
+	/**
-*/
+	 * Inform the server that the round has ended. Call this when the engine has disconnected,
-void flib_netconn_onDisconnected(flib_netconn *conn, void (*callback)(void *context, int reason, const char *message), void* context);
+	 * passing 1 if the round ended normally, 0 otherwise.
+	 */
-/**
+	int flib_netconn_send_roundfinished(flib_netconn *conn, bool withoutError);
-* 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.
-*/
+// Callbacks that are important for connecting/disconnecting
-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);
+	 * onNickTaken is called when connecting to the server, if it turns out that there is already a
-void flib_netconn_onRoomUpdate(flib_netconn *conn, void (*callback)(void *context, const char *oldName, const flib_room *room), void* context);
+	 * 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).
-* Callbacks for players joining or leaving the lobby. If join is true it's a join, otherwise a leave.
+	 * If you don't set a callback, the netconn will automatically react by generating a new name.
-* NOTE: partMessage is null if no parting message was given.
+	 */
-*/
+	void flib_netconn_onNickTaken(flib_netconn *conn, void (*callback)(void *context, const char *nick), void* context);
-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);
+	/**
+	 * 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
-* onNickTaken is called on connecting to the server, if it turns out that there is already a player with the same nick.
+	 * password using flib_netconn_send_password. If you don't register a callback, the default
-* In order to proceed, a new nickname needs to be sent to the server using flib_netconn_send_nick() (or of course you can
+	 * behavior is to just quit in a way that will cause a disconnect with
-* bail out and send a QUIT). If you don't set a callback, the netconn will automatically react by generating a new name.
+	 * NETCONN_DISCONNECT_AUTH_FAILED.
-* Once the server accepts a name, you will be informed with an onNickAccept callback.
+	 *
-*/
+	 * You can't just choose a new nickname when you receive this callback, because at that point
-void flib_netconn_onNickTaken(flib_netconn *conn, void (*callback)(void *context, const char *nick), void* context);
+	 * the server has already accepted your nick.
+	 */
-/**
+	void flib_netconn_onPasswordRequest(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 or choose a different nick. If you don't register a callback,
+	 * This is called when the server has accepted our nickname (and possibly password) and we have
-* the default behavior is to just quit in a way that will cause a disconnect with NETCONN_DISCONNECT_AUTH_FAILED.
+	 * entered the lobby.
-*/
+	 */
-void flib_netconn_onPasswordRequest(flib_netconn *conn, void (*callback)(void *context, const char *nick), void* context);
+	void flib_netconn_onConnected(flib_netconn *conn, void (*callback)(void *context), void* context);
-/**
+	/**
-* You just left the lobby and entered a room.
+	 * This is always the last callback (unless the netconn is destroyed early), and the netconn
-* If chief is true, you can and should send a full configuration for the room now.
+	 * should be destroyed when it is received. The reason for the disconnect is passed as one of
-* This consists of ammo, scheme, script and map, where map apparently has to come last.
+	 * the NETCONN_DISCONNECT_ constants. Sometimes a message is included as well, but that
-*/
+	 * parameter might also be NULL.
-void flib_netconn_onEnterRoom(flib_netconn *conn, void (*callback)(void *context, bool chief), void *context);
+	 */
+	void flib_netconn_onDisconnected(flib_netconn *conn, void (*callback)(void *context, int reason, const char *message), void* context);
-/**
-* The following callbacks are only relevant in room state.
+// Callbacks that make sense in most situations
-*/
+	/**
-/**
+	 * Callback for several informational messages that should be displayed to the user
-* This callback informs about changes to your room chief status, i.e. whether you are allowed to
+	 * (e.g. in the chat window), but do not require a reaction. If a game is running, you might
-* modify the current room. Generally when you create a room you start out being room chief, and
+	 * want to redirect some of these messages to the engine as well so the user will see them.
-* 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.
+	void flib_netconn_onMessage(flib_netconn *conn, void (*callback)(void *context, int msgtype, const char *msg), void* context);
-*
-* Note: This callback does not automatically fire when joining a room. You can always query the
+	/**
-* current chief status using flib_netconn_is_chief().
+	 * 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_onRoomChiefStatus(flib_netconn *conn, void (*callback)(void *context, bool chief), void* context);
+	 */
+	void flib_netconn_onChat(flib_netconn *conn, void (*callback)(void *context, const char *nick, const char *msg), void* context);
-/**
-* One of the players in the room (possibly you!) changed their ready state.
+	/**
-*/
+	 * Callbacks for incremental room list updates. They will fire whenever these events occur,
-void flib_netconn_onReadyState(flib_netconn *conn, void (*callback)(void *context, const char *nick, bool ready), void* context);
+	 * 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
-* You just left a room and entered the lobby again.
+	 * (see send_request_roomlist / onRoomlist).
-* reason is one of the NETCONN_ROOMLEAVE_ constants.
+	 */
-* This will not be called when you actively leave a room using PART.
+	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_onLeaveRoom(flib_netconn *conn, void (*callback)(void *context, int reason, const char *message), void *context);
+	void flib_netconn_onRoomUpdate(flib_netconn *conn, void (*callback)(void *context, const char *oldName, const flib_room *room), 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).
+	 * Callbacks for players joining or leaving the lobby. In contrast to the roomlist updates, you
-* The team does not contain bindings, stats, weaponset, color or the number of hogs.
+	 * 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)
-* 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.
+	 * NOTE: partMessage may be NULL.
-*/
+	 */
-void flib_netconn_onTeamAdd(flib_netconn *conn, void (*callback)(void *context, const flib_team *team), void *context);
+	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);
-/**
-* A team was removed from the room.
-*/
+// Callbacks that happen only in response to specific requests
-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);
+	 * Response to flib_netconn_send_request_roomlist().
-void flib_netconn_onRoomLeave(flib_netconn *conn, void (*callback)(void *context, const char *nick, const char *partMessage), void* context);
+	 * 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);
-* 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
+	/**
-*/
+	 * Response to flib_netconn_send_joinRoom, flib_netconn_send_playerFollow or
-void flib_netconn_onRunGame(flib_netconn *conn, void (*callback)(void *context), void *context);
+	 * flib_netconn_send_createRoom.
+	 *
-/**
+	 * You just left the lobby and entered a room.
-* 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
+	 * If chief is true, you can and should send a full configuration for the room now. This
-* as an existing team, or because the room chief restricted adding new teams. If the team is accepted by the server,
+	 * consists of ammo, scheme, script and map, where map apparently has to come last.
-* this callback is fired.
+	 */
-*
+	void flib_netconn_onEnterRoom(flib_netconn *conn, void (*callback)(void *context, bool chief), void *context);
-* 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.
+	 * Response to flib_netconn_send_addTeam.
-*/
+	 * The server might reject your team for several reasons, e.g. because it has the same name as
-void flib_netconn_onTeamAccepted(flib_netconn *conn, void (*callback)(void *context, const char *team), void *context);
+	 * an existing team, or because the room chief restricted adding new teams. If the team is
+	 * accepted by the server, this callback is fired.
-/**
+	 *
-* 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,
+	 * If you are the room chief, you are expected to provide the hog count for your own team now
-* you will not receive this callback!
+	 * using flib_netconn_send_teamHogCount. The color of the team is already set to the one you
-*/
+	 * provided in addTeam.
-void flib_netconn_onHogCountChanged(flib_netconn *conn, void (*callback)(void *context, const char *teamName, int hogs), void *context);
+	 */
+	void flib_netconn_onTeamAccepted(flib_netconn *conn, void (*callback)(void *context, const char *team), 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!
+	 * 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_onTeamColorChanged(flib_netconn *conn, void (*callback)(void *context, const char *teamName, int colorIndex), void *context);
+	 */
+	void flib_netconn_onServerVar(flib_netconn *conn, void (*callback)(void *context, const char *name, const char *value), 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);
+// Callbacks that are only relevant in a room
-/**
+	/**
-* This is called when the map configuration in a room is changed (or first received). Only non-chiefs receive these messages.
+	 * This callback informs about changes to your room chief status, i.e. whether you are allowed
-* To reduce the number of callback functions, the netconn keeps track of the current map settings and always passes the entire
+	 * to modify the current room. Generally when you create a room you start out being room chief,
-* current map config, but informs the callee about what has changed (see the NETCONN_MAPCHANGE_ constants).
+	 * and when you join an existing room you are not. However, if the original chief leaves a room,
-* The map parameter passed to the callback is an internally held map config. If you want to keep it around, best make a copy
+	 * the server can choose a new chief, and if that happens this callback is called with the new
-* or it may or may not change while you are not looking.
+	 * status.
-*
+	 *
-* 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
+	 * Note: This callback does not automatically fire when joining a room. You can always query the
-* the "full" map config does not include the drawn map data.
+	 * current chief status using flib_netconn_is_chief().
-*/
+	 */
-void flib_netconn_onMapChanged(flib_netconn *conn, void (*callback)(void *context, const flib_map *map, int changetype), void *context);
+	void flib_netconn_onRoomChiefStatus(flib_netconn *conn, void (*callback)(void *context, bool chief), void* context);
-/**
+	/**
-* The "game style" script has been changed by the room chief. If you are the chief and change the script yourself,
+	 * One of the players in the room (possibly you) changed their ready state.
-* you will not receive this callback!
+	 */
-*/
+	void flib_netconn_onReadyState(flib_netconn *conn, void (*callback)(void *context, const char *nick, bool ready), void* context);
-void flib_netconn_onScriptChanged(flib_netconn *conn, void (*callback)(void *context, const char *script), void *context);
+	/**
-/**
+	 * You just left a room and entered the lobby again.
-* The weaponset has been changed by the room chief. If you are the chief and change the weaponset yourself,
+	 * reason is one of the NETCONN_ROOMLEAVE_ constants (usually a kick).
-* you will not receive this callback!
+	 * 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_onWeaponsetChanged(flib_netconn *conn, void (*callback)(void *context, const flib_weaponset *weaponset), void *context);
+	 */
+	void flib_netconn_onLeaveRoom(flib_netconn *conn, void (*callback)(void *context, int reason, const char *message), void *context);
-/**
-* This callback is called if the server informs us that we have admin rights.
+	/**
-*/
+	 * Someone joined or left the room you are currently in.
-void flib_netconn_onAdminAccess(flib_netconn *conn, void (*callback)(void *context), void *context);
+	 * 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).
-* 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.
+	 * However, you will *not* receive onRoomLeave messages for everyone when you leave the room.
-*/
+	 */
-void flib_netconn_onServerVar(flib_netconn *conn, void (*callback)(void *context, const char *name, const char *value), 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);
+	/**
+	 * 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. 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);
+	/**
+	 * 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 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);
+	/**
+	 * 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 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);
+	/**
+	 * 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);
+// Callbacks only needed for admin stuffs
+	/**
+	 * 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

changeset 7580	c92596feac0d
parent 7497	7e1d72fc03c7
child 7689	855eeee4166f