Added GtkDoc style in-code documentation
This commit is contained in:
parent
604c4c4589
commit
7e78b2b7de
22
src/db.c
22
src/db.c
@ -25,6 +25,12 @@
|
|||||||
|
|
||||||
sqlite3 *dbh = NULL;
|
sqlite3 *dbh = NULL;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_db_init:
|
||||||
|
* @error: a GError to put error messages in it
|
||||||
|
*
|
||||||
|
* Initializes the wMUD database system. Checks and opens database files.
|
||||||
|
*/
|
||||||
gboolean
|
gboolean
|
||||||
wmud_db_init(GError **err)
|
wmud_db_init(GError **err)
|
||||||
{
|
{
|
||||||
@ -43,6 +49,12 @@ wmud_db_init(GError **err)
|
|||||||
return TRUE;
|
return TRUE;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_db_players_load:
|
||||||
|
* @error: a GError to put error messages in it
|
||||||
|
*
|
||||||
|
* Loads all player records from the database
|
||||||
|
*/
|
||||||
gboolean
|
gboolean
|
||||||
wmud_db_players_load(GError **err)
|
wmud_db_players_load(GError **err)
|
||||||
{
|
{
|
||||||
@ -95,6 +107,16 @@ wmud_db_players_load(GError **err)
|
|||||||
return FALSE;
|
return FALSE;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_db_save_player:
|
||||||
|
* @player: the player record to save
|
||||||
|
* @error: a GError to put error messages in it
|
||||||
|
*
|
||||||
|
* Saves a player record to the database backend.
|
||||||
|
*
|
||||||
|
* Return value: %TRUE on success. Upon failure, %FALSE is returned, and err is
|
||||||
|
* set accordingly.
|
||||||
|
*/
|
||||||
gboolean
|
gboolean
|
||||||
wmud_db_save_player(wmudPlayer *player, GError **err)
|
wmud_db_save_player(wmudPlayer *player, GError **err)
|
||||||
{
|
{
|
||||||
|
@ -33,12 +33,25 @@ static wmudCommand command_list[] = {
|
|||||||
{ NULL, NULL },
|
{ NULL, NULL },
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* destroy_string:
|
||||||
|
* @string: a GString to destroy
|
||||||
|
*
|
||||||
|
* Callback function to destroy a list of GStrings
|
||||||
|
*/
|
||||||
static void
|
static void
|
||||||
destroy_string(GString *string)
|
destroy_string(GString *string)
|
||||||
{
|
{
|
||||||
g_string_free(string, TRUE);
|
g_string_free(string, TRUE);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_interpret_game_command:
|
||||||
|
* @client: the wmudClient whose command should be processed
|
||||||
|
*
|
||||||
|
* Processes a wmudClient's buffer, and executes the game command if there is
|
||||||
|
* one
|
||||||
|
*/
|
||||||
void
|
void
|
||||||
wmud_interpret_game_command(wmudClient *client)
|
wmud_interpret_game_command(wmudClient *client)
|
||||||
{
|
{
|
||||||
@ -176,7 +189,12 @@ wmud_interpret_game_command(wmudClient *client)
|
|||||||
g_slist_free(matches);
|
g_slist_free(matches);
|
||||||
}
|
}
|
||||||
|
|
||||||
WMUD_COMMAND(gcmd_quit)
|
/**
|
||||||
|
* gcmd_quit:
|
||||||
|
*
|
||||||
|
* The QUIT game command's handler
|
||||||
|
*/
|
||||||
|
WMUD_COMMAND(quit)
|
||||||
{
|
{
|
||||||
wmud_client_send(client, "Are you sure you want to get back to that freaky other reality? [y/N] ");
|
wmud_client_send(client, "Are you sure you want to get back to that freaky other reality? [y/N] ");
|
||||||
client->state = WMUD_CLIENT_STATE_QUITWAIT;
|
client->state = WMUD_CLIENT_STATE_QUITWAIT;
|
||||||
|
@ -21,9 +21,25 @@
|
|||||||
|
|
||||||
#include "networking.h"
|
#include "networking.h"
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmudCommandFunc:
|
||||||
|
* @client: the client from whom the command arrived
|
||||||
|
* @command: the command itself
|
||||||
|
* @token_list: the command arguments
|
||||||
|
*
|
||||||
|
* Command handler function type
|
||||||
|
*/
|
||||||
typedef void (*wmudCommandFunc)(wmudClient *client, gchar *command, GSList *token_list);
|
typedef void (*wmudCommandFunc)(wmudClient *client, gchar *command, GSList *token_list);
|
||||||
#define WMUD_COMMAND(name) void name(wmudClient *client, gchar *command, GSList *token_list)
|
#define WMUD_COMMAND(name) void name(wmudClient *client, gchar *command, GSList *token_list)
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmudCommand:
|
||||||
|
* @command: the command itself. Should be in uppercase, but doesn't actually
|
||||||
|
* matter
|
||||||
|
* @commandFunc: the command handler function for this command
|
||||||
|
*
|
||||||
|
* This structure holds the different properties of the in-game commands.
|
||||||
|
*/
|
||||||
typedef struct _wmudCommand {
|
typedef struct _wmudCommand {
|
||||||
gchar *command;
|
gchar *command;
|
||||||
wmudCommandFunc commandFunc;
|
wmudCommandFunc commandFunc;
|
||||||
|
97
src/main.c
97
src/main.c
@ -33,11 +33,30 @@
|
|||||||
#include "db.h"
|
#include "db.h"
|
||||||
#include "players.h"
|
#include "players.h"
|
||||||
|
|
||||||
|
/**
|
||||||
|
* debug_context_loc:
|
||||||
|
*
|
||||||
|
* This variable holds the location of the last context marker
|
||||||
|
*/
|
||||||
struct {
|
struct {
|
||||||
char *file;
|
char *file;
|
||||||
int line;
|
int line;
|
||||||
} debug_context_loc = {NULL, 0};
|
} debug_context_loc = {NULL, 0};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @game_context: the game thread's main context
|
||||||
|
* @elapsed_seconds: the number of seconds elapsed since game boot. May be
|
||||||
|
* inaccurate, as it simply gets updated by a timeout
|
||||||
|
* function which should run every second
|
||||||
|
* @elapsed_cycle: yes, I'm optimistic. This counter is increased if, for some
|
||||||
|
* reason, #elapsed_seconds reaches the maximum value
|
||||||
|
* @main_rand: the main random generator
|
||||||
|
* @WMUD_CONFIG_ERROR: the GQuark for the config error GError
|
||||||
|
* @WMUD_DB_ERROR: the GQuark for the database error GError
|
||||||
|
* @port: the port number to listen on
|
||||||
|
* @database_file: the filename of the world database
|
||||||
|
* @admin_email: e-mail address of the MUD's administrator
|
||||||
|
*/
|
||||||
GMainContext *game_context;
|
GMainContext *game_context;
|
||||||
guint32 elapsed_seconds = 0;
|
guint32 elapsed_seconds = 0;
|
||||||
guint32 elapsed_cycle = 0;
|
guint32 elapsed_cycle = 0;
|
||||||
@ -48,10 +67,12 @@ guint port = 0;
|
|||||||
gchar *database_file = NULL;
|
gchar *database_file = NULL;
|
||||||
gchar *admin_email = NULL;
|
gchar *admin_email = NULL;
|
||||||
|
|
||||||
/* rl_sec_elapsed()
|
/**
|
||||||
|
* rl_sec_elapsed:
|
||||||
|
* @user_data: non-used pointer to callback's user data
|
||||||
*
|
*
|
||||||
* This function keeps track of elapsed real-world time. It is inaccurate by
|
* Keeps track of elapsed real-world time. It is inaccurate by design, but it
|
||||||
* design, but it doesn't actually matter.
|
* doesn't actually matter.
|
||||||
*/
|
*/
|
||||||
gboolean
|
gboolean
|
||||||
rl_sec_elapsed(gpointer user_data)
|
rl_sec_elapsed(gpointer user_data)
|
||||||
@ -71,6 +92,12 @@ rl_sec_elapsed(gpointer user_data)
|
|||||||
return TRUE;
|
return TRUE;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_random_string:
|
||||||
|
* @len: the desired length of the generated random string
|
||||||
|
*
|
||||||
|
* Generates a random string of %len characters.
|
||||||
|
*/
|
||||||
gchar *
|
gchar *
|
||||||
wmud_random_string(gint len)
|
wmud_random_string(gint len)
|
||||||
{
|
{
|
||||||
@ -91,6 +118,14 @@ wmud_random_string(gint len)
|
|||||||
return ret;
|
return ret;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_maintenance_check_new_players:
|
||||||
|
* @player: #wmudPLayer structure of the player record to check
|
||||||
|
* @user_data: not used
|
||||||
|
*
|
||||||
|
* Callback called from within the maintenance loop. Checks if the player has
|
||||||
|
* an unset password, and generate one for them, if so.
|
||||||
|
*/
|
||||||
void
|
void
|
||||||
wmud_maintenance_check_new_players(wmudPlayer *player, gpointer user_data)
|
wmud_maintenance_check_new_players(wmudPlayer *player, gpointer user_data)
|
||||||
{
|
{
|
||||||
@ -120,6 +155,12 @@ wmud_maintenance_check_new_players(wmudPlayer *player, gpointer user_data)
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_maintenance:
|
||||||
|
* @user_data: not used
|
||||||
|
*
|
||||||
|
* Timeout source function for maintenance tasks
|
||||||
|
*/
|
||||||
gboolean
|
gboolean
|
||||||
wmud_maintenance(gpointer user_data)
|
wmud_maintenance(gpointer user_data)
|
||||||
{
|
{
|
||||||
@ -135,11 +176,16 @@ wmud_maintenance(gpointer user_data)
|
|||||||
|
|
||||||
#ifdef DEBUG
|
#ifdef DEBUG
|
||||||
void
|
void
|
||||||
/* debug_context()
|
/**
|
||||||
|
* debug_context:
|
||||||
|
* @file: the source file name, where the context marker was found
|
||||||
|
* @line: the line number where the context marker was found
|
||||||
*
|
*
|
||||||
* This function keeps track of the code flow in some way. It can help with
|
* This function keeps track of the code flow in some way. It can help with
|
||||||
* debugging, as during a SIGSEGV or such signal this will print out the last
|
* debugging, as during a SIGSEGV or such signal this will print out the last
|
||||||
* place of DebugContext in the code.
|
* place of DebugContext in the code.
|
||||||
|
*
|
||||||
|
* THIS FUNCTION SHOULD NEVER BE CALLED DIRECTLY!
|
||||||
*/
|
*/
|
||||||
debug_context(char *file, int line)
|
debug_context(char *file, int line)
|
||||||
{
|
{
|
||||||
@ -149,11 +195,22 @@ debug_context(char *file, int line)
|
|||||||
debug_context_loc.file = g_strdup(file);
|
debug_context_loc.file = g_strdup(file);
|
||||||
debug_context_loc.line = line;
|
debug_context_loc.line = line;
|
||||||
}
|
}
|
||||||
|
/**
|
||||||
|
* DebugContext:
|
||||||
|
*
|
||||||
|
* Marks the current line of the source file with a context marker. Deadly
|
||||||
|
* signals should print the place of the last marker.
|
||||||
|
*/
|
||||||
#define DebugContext debug_context(__FILE__, __LINE__)
|
#define DebugContext debug_context(__FILE__, __LINE__)
|
||||||
#else
|
#else
|
||||||
#define DebugContext
|
#define DebugContext
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_type_init:
|
||||||
|
*
|
||||||
|
* Initializes the wMUD types.
|
||||||
|
*/
|
||||||
void
|
void
|
||||||
wmud_type_init(void)
|
wmud_type_init(void)
|
||||||
{
|
{
|
||||||
@ -161,6 +218,15 @@ wmud_type_init(void)
|
|||||||
WMUD_DB_ERROR = g_quark_from_string("wmud_db_error");
|
WMUD_DB_ERROR = g_quark_from_string("wmud_db_error");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_config_init:
|
||||||
|
* @err: The GError in which the config handling status should be returned
|
||||||
|
*
|
||||||
|
* Parses the default configuration file, and sets different variables
|
||||||
|
* according to it.
|
||||||
|
*
|
||||||
|
* Return value: %TRUE if parsing was successful. %FALSE otherwise.
|
||||||
|
*/
|
||||||
gboolean
|
gboolean
|
||||||
wmud_config_init(GError **err)
|
wmud_config_init(GError **err)
|
||||||
{
|
{
|
||||||
@ -240,6 +306,14 @@ wmud_config_init(GError **err)
|
|||||||
return TRUE;
|
return TRUE;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* game_thread_func:
|
||||||
|
* @game_loop: the main loop to be associated with the game thread
|
||||||
|
*
|
||||||
|
* The game thread's main function.
|
||||||
|
*
|
||||||
|
* Return value: This function always returns %NULL.
|
||||||
|
*/
|
||||||
gpointer
|
gpointer
|
||||||
game_thread_func(GMainLoop *game_loop)
|
game_thread_func(GMainLoop *game_loop)
|
||||||
{
|
{
|
||||||
@ -249,6 +323,14 @@ game_thread_func(GMainLoop *game_loop)
|
|||||||
return NULL;
|
return NULL;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* maint_thread_func:
|
||||||
|
* @main_loop: the main loop to be associated with the maintenance thread
|
||||||
|
*
|
||||||
|
* The maintenance thread's main function.
|
||||||
|
*
|
||||||
|
* Return value: This function always returns %NULL.
|
||||||
|
*/
|
||||||
gpointer
|
gpointer
|
||||||
maint_thread_func(GMainLoop *maint_loop)
|
maint_thread_func(GMainLoop *maint_loop)
|
||||||
{
|
{
|
||||||
@ -257,6 +339,13 @@ maint_thread_func(GMainLoop *maint_loop)
|
|||||||
return NULL;
|
return NULL;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* main:
|
||||||
|
* @argc: The number of arguments on the command line
|
||||||
|
* @argv: The command line arguments themselves
|
||||||
|
*
|
||||||
|
* The Main Function (TM)
|
||||||
|
*/
|
||||||
int
|
int
|
||||||
main(int argc, char **argv)
|
main(int argc, char **argv)
|
||||||
{
|
{
|
||||||
|
@ -41,6 +41,15 @@ GSList *clients;
|
|||||||
void wmud_client_interpret_newplayer_email(wmudClient *client);
|
void wmud_client_interpret_newplayer_email(wmudClient *client);
|
||||||
void wmud_client_interpret_newplayer_mailconfirm(wmudClient *client_data);
|
void wmud_client_interpret_newplayer_mailconfirm(wmudClient *client_data);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_client_close:
|
||||||
|
* @client: the client whose connection should be dropped
|
||||||
|
* @send_goodbye: if set to %TRUE, we will send a nice good-bye message to the
|
||||||
|
* client before dropping the connection
|
||||||
|
*
|
||||||
|
* Closes a client connection. If send_goodbye is set to %TRUE, a good-bye
|
||||||
|
* message will be sent to the client.
|
||||||
|
*/
|
||||||
void
|
void
|
||||||
wmud_client_close(wmudClient *client, gboolean send_goodbye)
|
wmud_client_close(wmudClient *client, gboolean send_goodbye)
|
||||||
{
|
{
|
||||||
@ -57,6 +66,14 @@ wmud_client_close(wmudClient *client, gboolean send_goodbye)
|
|||||||
g_free(client);
|
g_free(client);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_client_callback:
|
||||||
|
* @client: the socket of the client on which the data arrived
|
||||||
|
* @condition: the condition available on the client socket
|
||||||
|
* @client: the wmudClient structure of the client
|
||||||
|
*
|
||||||
|
* Processes incoming client data, and client hangup
|
||||||
|
*/
|
||||||
static gboolean
|
static gboolean
|
||||||
wmud_client_callback(GSocket *client, GIOCondition condition, wmudClient *client_data)
|
wmud_client_callback(GSocket *client, GIOCondition condition, wmudClient *client_data)
|
||||||
{
|
{
|
||||||
@ -195,9 +212,16 @@ wmud_client_callback(GSocket *client, GIOCondition condition, wmudClient *client
|
|||||||
return TRUE;
|
return TRUE;
|
||||||
}
|
}
|
||||||
|
|
||||||
/* game_source_callback()
|
/**
|
||||||
|
* game_source_callback:
|
||||||
|
* @socket: the listener socket on which the new connection arrived
|
||||||
|
* @condition: not used
|
||||||
|
* @accept_data: the AcceptData structure of the game listener
|
||||||
*
|
*
|
||||||
* This function is called whenever a new connection is available on the game socket
|
* Callback function to be called when a new connection is available on the
|
||||||
|
* game listener socket.
|
||||||
|
*
|
||||||
|
* Return value: this function always returns %TRUE
|
||||||
*/
|
*/
|
||||||
gboolean
|
gboolean
|
||||||
game_source_callback(GSocket *socket, GIOCondition condition, struct AcceptData *accept_data)
|
game_source_callback(GSocket *socket, GIOCondition condition, struct AcceptData *accept_data)
|
||||||
@ -226,6 +250,16 @@ game_source_callback(GSocket *socket, GIOCondition condition, struct AcceptData
|
|||||||
return TRUE;
|
return TRUE;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_networking_init:
|
||||||
|
* @port_number: the port number on which the game listener should listen
|
||||||
|
* @err: the GError in which possible errors will be reported
|
||||||
|
*
|
||||||
|
* Initializes the game network listener
|
||||||
|
*
|
||||||
|
* Return value: Returns %TRUE on success. Upon failure, %FALSE is return, and
|
||||||
|
* err is set accordingly (if not NULL)
|
||||||
|
*/
|
||||||
gboolean
|
gboolean
|
||||||
wmud_networking_init(guint port_number, GError **err)
|
wmud_networking_init(guint port_number, GError **err)
|
||||||
{
|
{
|
||||||
@ -338,6 +372,14 @@ wmud_networking_init(guint port_number, GError **err)
|
|||||||
return TRUE;
|
return TRUE;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_client_send:
|
||||||
|
* @client: the client to which the message will be sent
|
||||||
|
* @fmt: the printf() style format string of the message
|
||||||
|
* @...: optional parameters to the format string
|
||||||
|
*
|
||||||
|
* Sends a formatted message to a game client
|
||||||
|
*/
|
||||||
void
|
void
|
||||||
wmud_client_send(wmudClient *client, const gchar *fmt, ...)
|
wmud_client_send(wmudClient *client, const gchar *fmt, ...)
|
||||||
{
|
{
|
||||||
@ -353,6 +395,13 @@ wmud_client_send(wmudClient *client, const gchar *fmt, ...)
|
|||||||
g_string_free(buf, TRUE);
|
g_string_free(buf, TRUE);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_client_start_login:
|
||||||
|
* @client: the client from which the login name came from
|
||||||
|
*
|
||||||
|
* This function is currently called when the freshly connected client sends a
|
||||||
|
* non-empty string (a player name).
|
||||||
|
*/
|
||||||
void
|
void
|
||||||
wmud_client_start_login(wmudClient *client)
|
wmud_client_start_login(wmudClient *client)
|
||||||
{
|
{
|
||||||
@ -382,6 +431,13 @@ wmud_client_start_login(wmudClient *client)
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_client_interpret_newplayer_answer:
|
||||||
|
* @client: the client from which the answer came from
|
||||||
|
*
|
||||||
|
* Interprets a yes/no answer from the client to the question if they are new
|
||||||
|
* to the game.
|
||||||
|
*/
|
||||||
void
|
void
|
||||||
wmud_client_interpret_newplayer_answer(wmudClient *client)
|
wmud_client_interpret_newplayer_answer(wmudClient *client)
|
||||||
{
|
{
|
||||||
@ -402,6 +458,12 @@ wmud_client_interpret_newplayer_answer(wmudClient *client)
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_client_interpret_newplayer_email:
|
||||||
|
* @client: the client from which the e-mail address arrived from
|
||||||
|
*
|
||||||
|
* Checks for the validity of the new player's e-mail address
|
||||||
|
*/
|
||||||
void
|
void
|
||||||
wmud_client_interpret_newplayer_email(wmudClient *client)
|
wmud_client_interpret_newplayer_email(wmudClient *client)
|
||||||
{
|
{
|
||||||
@ -430,6 +492,13 @@ wmud_client_interpret_newplayer_email(wmudClient *client)
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* wmud_client_interpret_newplayer_mailconfirm:
|
||||||
|
* @client: the client from which the confirmation e-mail arrived
|
||||||
|
*
|
||||||
|
* Check if the confirmed e-mail address is the same as the previously entered
|
||||||
|
* one.
|
||||||
|
*/
|
||||||
void
|
void
|
||||||
wmud_client_interpret_newplayer_mailconfirm(wmudClient *client)
|
wmud_client_interpret_newplayer_mailconfirm(wmudClient *client)
|
||||||
{
|
{
|
||||||
|
Loading…
Reference in New Issue
Block a user