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

equal deleted inserted replaced

-:c8c552ee3acb
+:d70a5b0d1190
 * You should have received a copy of the GNU General Public License
 * 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
+* 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.
+*
+* 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().
+*
+* 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.
+*
+* 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.
+*
+* 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.
+*/
 #ifndef NETCONN_H_
 #define NETCONN_H_
 #include "../model/gamesetup.h"
 #include "../model/scheme.h"
 #include <stdbool.h>
 #define NETCONN_STATE_CONNECTING 0
 #define NETCONN_STATE_LOBBY 1
 #define NETCONN_STATE_ROOM 2
-#define NETCONN_STATE_INGAME 3
 #define NETCONN_STATE_DISCONNECTED 10
-#define NETCONN_DISCONNECT_NORMAL 0
+#define NETCONN_DISCONNECT_NORMAL 0				// The connection was closed normally
-#define NETCONN_DISCONNECT_SERVER_TOO_OLD 1
+#define NETCONN_DISCONNECT_SERVER_TOO_OLD 1		// The server has a lower protocol version than we do
-#define NETCONN_DISCONNECT_AUTH_FAILED 2 // TODO can you retry instead?
+#define NETCONN_DISCONNECT_AUTH_FAILED 2		// You sent a password with flib_netconn_send_password that was not accepted
-#define NETCONN_DISCONNECT_CONNLOST 3
+#define NETCONN_DISCONNECT_CONNLOST 3			// The network connection was lost
-#define NETCONN_DISCONNECT_INTERNAL_ERROR 100
+#define NETCONN_DISCONNECT_INTERNAL_ERROR 100	// Something went wrong in frontlib itself
-#define NETCONN_ROOMLEAVE_ABANDONED 0
+#define NETCONN_ROOMLEAVE_ABANDONED 0			// The room was closed because the chief left
-#define NETCONN_ROOMLEAVE_KICKED 1
+#define NETCONN_ROOMLEAVE_KICKED 1				// You have been kicked from the room
-#define NETCONN_MSG_TYPE_PLAYERINFO 0
+#define NETCONN_MSG_TYPE_PLAYERINFO 0			// A response to flib_netconn_send_playerInfo
-#define NETCONN_MSG_TYPE_SERVERMESSAGE 1
+#define NETCONN_MSG_TYPE_SERVERMESSAGE 1		// The welcome message when connecting to the lobby
-#define NETCONN_MSG_TYPE_WARNING 2
+#define NETCONN_MSG_TYPE_WARNING 2				// A general warning message
-#define NETCONN_MSG_TYPE_ERROR 3
+#define NETCONN_MSG_TYPE_ERROR 3				// A general error message
 #define NETCONN_MAPCHANGE_FULL 0
 #define NETCONN_MAPCHANGE_MAP 1
 #define NETCONN_MAPCHANGE_MAPGEN 2
 #define NETCONN_MAPCHANGE_DRAWNMAP 3
 * NETCONN_STATE_ROOM and NETCONN_STATE_INGAME states.
 */
 bool flib_netconn_is_chief(flib_netconn *conn);
 /**
-* Are you in the context of a room, i.e. either in room or ingame state?
-*/
-bool flib_netconn_is_in_room_context(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.
 */
 const char *flib_netconn_get_playername(flib_netconn *conn);
 */
 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);
 /**
 * Request a different nickname.
 * receive an onReadyState callback containing the change.
 */
 int flib_netconn_send_toggleReady(flib_netconn *conn);
 /**
-* Add a team to the current room. The message includes the team color, but not
+* Add a team to the current room. Apart from the "fixed" team information, this also includes
-* the number of hogs. Only makes sense when in room state. If the action succeeds, you will
+* the color, but not the number of hogs. Only makes sense when in room state. If the action
-* receive an onTeamAccepted callback with the name of the team.
+* 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);
 /**
 * Remove the team with the name teamname. Only makes sense when in room state.
 * has disconnected, passing 1 if the round ended normally, 0 otherwise.
 */
 int flib_netconn_send_roundfinished(flib_netconn *conn, bool withoutError);
 /**
-* Ban a player. TODO: Figure out details
+* 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);
 /**
-* Kick a player. TODO: Figure out details
+* 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);
 /**
 * Request information about a player. If the action succeeds, you will
 * the requested information.
 */
 int flib_netconn_send_playerInfo(flib_netconn *conn, const char *playerName);
 /**
-* Follow a player. TODO figure out details
+* 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);
 /**
 * Signal that you want to start the game. Only makes sense in room state and if you are chief.
-* TODO details
+* 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 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_toggleRestrictTeams(flib_netconn *conn);
 /**
-* Probably does something administrator-y.
+* 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.
 * Known variables are MOTD_NEW, MOTD_OLD and LATEST_PROTO.
-* TODO reply?
 */
 int flib_netconn_send_setServerVar(flib_netconn *conn, const char *name, const char *value);
 /**
-* Queries all server variables. Only makes sense if you are server admin. (TODO: try)
+* 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);
 void flib_netconn_onLeaveRoom(flib_netconn *conn, void (*callback)(void *context, int reason, const char *message), 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 team was removed from the 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
 * 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.
-*/
+*
-void flib_netconn_onTeamAccepted(flib_netconn *conn, void (*callback)(void *context, const char *teamName), 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.
+*/
+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!
 */
 * 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);
 /**
-* When you query the server vars with GET_SERVER_VAR (TODO probably only works as admin), the server
+* 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);
 #endif

changeset 7482	d70a5b0d1190
parent 7338	1ed603a54ebd
child 7497	7e1d72fc03c7