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;
|
||||
|
||||
/**
|
||||
* wmud_db_init:
|
||||
* @error: a GError to put error messages in it
|
||||
*
|
||||
* Initializes the wMUD database system. Checks and opens database files.
|
||||
*/
|
||||
gboolean
|
||||
wmud_db_init(GError **err)
|
||||
{
|
||||
@ -43,6 +49,12 @@ wmud_db_init(GError **err)
|
||||
return TRUE;
|
||||
}
|
||||
|
||||
/**
|
||||
* wmud_db_players_load:
|
||||
* @error: a GError to put error messages in it
|
||||
*
|
||||
* Loads all player records from the database
|
||||
*/
|
||||
gboolean
|
||||
wmud_db_players_load(GError **err)
|
||||
{
|
||||
@ -95,6 +107,16 @@ wmud_db_players_load(GError **err)
|
||||
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
|
||||
wmud_db_save_player(wmudPlayer *player, GError **err)
|
||||
{
|
||||
|
@ -33,12 +33,25 @@ static wmudCommand command_list[] = {
|
||||
{ NULL, NULL },
|
||||
};
|
||||
|
||||
/**
|
||||
* destroy_string:
|
||||
* @string: a GString to destroy
|
||||
*
|
||||
* Callback function to destroy a list of GStrings
|
||||
*/
|
||||
static void
|
||||
destroy_string(GString *string)
|
||||
{
|
||||
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
|
||||
wmud_interpret_game_command(wmudClient *client)
|
||||
{
|
||||
@ -176,7 +189,12 @@ wmud_interpret_game_command(wmudClient *client)
|
||||
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] ");
|
||||
client->state = WMUD_CLIENT_STATE_QUITWAIT;
|
||||
|
@ -21,9 +21,25 @@
|
||||
|
||||
#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);
|
||||
#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 {
|
||||
gchar *command;
|
||||
wmudCommandFunc commandFunc;
|
||||
|
97
src/main.c
97
src/main.c
@ -33,11 +33,30 @@
|
||||
#include "db.h"
|
||||
#include "players.h"
|
||||
|
||||
/**
|
||||
* debug_context_loc:
|
||||
*
|
||||
* This variable holds the location of the last context marker
|
||||
*/
|
||||
struct {
|
||||
char *file;
|
||||
int line;
|
||||
} 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;
|
||||
guint32 elapsed_seconds = 0;
|
||||
guint32 elapsed_cycle = 0;
|
||||
@ -48,10 +67,12 @@ guint port = 0;
|
||||
gchar *database_file = 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
|
||||
* design, but it doesn't actually matter.
|
||||
* Keeps track of elapsed real-world time. It is inaccurate by design, but it
|
||||
* doesn't actually matter.
|
||||
*/
|
||||
gboolean
|
||||
rl_sec_elapsed(gpointer user_data)
|
||||
@ -71,6 +92,12 @@ rl_sec_elapsed(gpointer user_data)
|
||||
return TRUE;
|
||||
}
|
||||
|
||||
/**
|
||||
* wmud_random_string:
|
||||
* @len: the desired length of the generated random string
|
||||
*
|
||||
* Generates a random string of %len characters.
|
||||
*/
|
||||
gchar *
|
||||
wmud_random_string(gint len)
|
||||
{
|
||||
@ -91,6 +118,14 @@ wmud_random_string(gint len)
|
||||
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
|
||||
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
|
||||
wmud_maintenance(gpointer user_data)
|
||||
{
|
||||
@ -135,11 +176,16 @@ wmud_maintenance(gpointer user_data)
|
||||
|
||||
#ifdef DEBUG
|
||||
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
|
||||
* debugging, as during a SIGSEGV or such signal this will print out the last
|
||||
* place of DebugContext in the code.
|
||||
*
|
||||
* THIS FUNCTION SHOULD NEVER BE CALLED DIRECTLY!
|
||||
*/
|
||||
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.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__)
|
||||
#else
|
||||
#define DebugContext
|
||||
#endif
|
||||
|
||||
/**
|
||||
* wmud_type_init:
|
||||
*
|
||||
* Initializes the wMUD types.
|
||||
*/
|
||||
void
|
||||
wmud_type_init(void)
|
||||
{
|
||||
@ -161,6 +218,15 @@ wmud_type_init(void)
|
||||
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
|
||||
wmud_config_init(GError **err)
|
||||
{
|
||||
@ -240,6 +306,14 @@ wmud_config_init(GError **err)
|
||||
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
|
||||
game_thread_func(GMainLoop *game_loop)
|
||||
{
|
||||
@ -249,6 +323,14 @@ game_thread_func(GMainLoop *game_loop)
|
||||
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
|
||||
maint_thread_func(GMainLoop *maint_loop)
|
||||
{
|
||||
@ -257,6 +339,13 @@ maint_thread_func(GMainLoop *maint_loop)
|
||||
return NULL;
|
||||
}
|
||||
|
||||
/**
|
||||
* main:
|
||||
* @argc: The number of arguments on the command line
|
||||
* @argv: The command line arguments themselves
|
||||
*
|
||||
* The Main Function (TM)
|
||||
*/
|
||||
int
|
||||
main(int argc, char **argv)
|
||||
{
|
||||
|
@ -41,6 +41,15 @@ GSList *clients;
|
||||
void wmud_client_interpret_newplayer_email(wmudClient *client);
|
||||
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
|
||||
wmud_client_close(wmudClient *client, gboolean send_goodbye)
|
||||
{
|
||||
@ -57,6 +66,14 @@ wmud_client_close(wmudClient *client, gboolean send_goodbye)
|
||||
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
|
||||
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;
|
||||
}
|
||||
|
||||
/* 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
|
||||
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;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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
|
||||
wmud_networking_init(guint port_number, GError **err)
|
||||
{
|
||||
@ -338,6 +372,14 @@ wmud_networking_init(guint port_number, GError **err)
|
||||
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
|
||||
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);
|
||||
}
|
||||
|
||||
/**
|
||||
* 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
|
||||
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
|
||||
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
|
||||
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
|
||||
wmud_client_interpret_newplayer_mailconfirm(wmudClient *client)
|
||||
{
|
||||
|
Loading…
Reference in New Issue
Block a user