summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTheJackiMonster <thejackimonster@gmail.com>2022-04-19 00:31:14 +0200
committerTheJackiMonster <thejackimonster@gmail.com>2022-04-19 00:31:14 +0200
commitfc56c6148f22d363a27c7a39d8d97a2d4d908a92 (patch)
treea6f7a81785104dbfab204fa3566d243c52415604
parent9ad1e9f834085b034262f9724400bcb52b55b70c (diff)
Added doxygen comments to some headers
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-rw-r--r--src/application.h52
-rw-r--r--src/chat/messenger.h9
-rw-r--r--src/contact.h46
-rw-r--r--src/event.h72
-rw-r--r--src/file.h38
-rw-r--r--src/resources.h6
-rw-r--r--src/ui.h21
7 files changed, 244 insertions, 0 deletions
diff --git a/src/application.h b/src/application.h
index 2c0972b..ab082a0 100644
--- a/src/application.h
+++ b/src/application.h
@@ -134,15 +134,38 @@ typedef struct MESSENGER_Application
} settings;
} MESSENGER_Application;
+/**
+ * Initializes the messenger application with
+ * startup arguments.
+ *
+ * @param app Messenger application
+ * @param argc Amount of arguments
+ * @param argv Arguments
+ */
void
application_init(MESSENGER_Application *app,
int argc,
char **argv);
+/**
+ * Returns the path from resources of the
+ * messenger application relative to its storage.
+ *
+ * @param app Messenger application
+ * @param path Path
+ * @return Resource path
+ */
const gchar*
application_get_resource_path(MESSENGER_Application *app,
const char *path);
+/**
+ * Runs the messenger application starting the
+ * second thread and waiting for the application
+ * to finish.
+ *
+ * @param app Messenger application
+ */
void
application_run(MESSENGER_Application *app);
@@ -156,20 +179,49 @@ typedef void (*MESSENGER_ApplicationMessageEvent) (
const struct GNUNET_CHAT_Message *msg
);
+/**
+ * Calls a given event with the messenger application
+ * asyncronously but explicitly synchronized via mutex.
+ *
+ * @param app Messenger application
+ * @param event Event
+ */
void
application_call_event(MESSENGER_Application *app,
MESSENGER_ApplicationEvent event);
+/**
+ * Calls a given message event with the messenger
+ * application asyncronously but explicitly synchronized
+ * via mutex.
+ *
+ * @param app Messenger application
+ * @param event Message event
+ * @param context Chat context
+ * @param message Message
+ */
void
application_call_message_event(MESSENGER_Application *app,
MESSENGER_ApplicationMessageEvent event,
struct GNUNET_CHAT_Context *context,
const struct GNUNET_CHAT_Message *message);
+/**
+ * Signals the second thread to exit the application.
+ *
+ * @param app Messenger application
+ * @param signal Exit signal
+ */
void
application_exit(MESSENGER_Application *app,
MESSENGER_ApplicationSignal signal);
+/**
+ * Returns the exit status of the messenger application.
+ *
+ * @param app Messenger application
+ * @return Exit status
+ */
int
application_status(MESSENGER_Application *app);
diff --git a/src/chat/messenger.h b/src/chat/messenger.h
index bc07119..4cceec7 100644
--- a/src/chat/messenger.h
+++ b/src/chat/messenger.h
@@ -39,6 +39,15 @@ typedef struct CHAT_MESSENGER_Handle
struct GNUNET_SCHEDULER_Task *idle;
} CHAT_MESSENGER_Handle;
+/**
+ * Startup event of the GNUnet scheduler thread to
+ * handle the messenger application startup.
+ *
+ * @param cls Closure
+ * @param args Arguments
+ * @param cfgfile Configuration file path
+ * @param cfg Configuration
+ */
void
chat_messenger_run(void *cls,
char *const *args,
diff --git a/src/contact.h b/src/contact.h
index 8a6dd4c..61d41e7 100644
--- a/src/contact.h
+++ b/src/contact.h
@@ -35,27 +35,73 @@ typedef struct MESSENGER_ContactInfo
GList *name_avatars;
} MESSENGER_ContactInfo;
+/**
+ * Creates a contact information struct to potentially
+ * update all GUI appearances of a specific contact at
+ * once.
+ *
+ * @param contact Chat contact
+ */
void
contact_create_info(struct GNUNET_CHAT_Contact *contact);
+/**
+ * Destroys and frees resources allocated for a given
+ * contact information struct.
+ *
+ * @param contact Chat contact
+ */
void
contact_destroy_info(struct GNUNET_CHAT_Contact *contact);
+/**
+ * Sets the latest join/leave UI message handle so that
+ * the application can check whether a contact is available.
+ *
+ * @param contact Chat contact
+ * @param message Pointer to UI message handle
+ */
void
contact_set_last_message_to_info(const struct GNUNET_CHAT_Contact *contact,
void *message);
+/**
+ * Returns the latest join/leave UI message handle of
+ * a specific contact.
+ *
+ * @param contact Chat contact
+ */
void*
contact_get_last_message_from_info(const struct GNUNET_CHAT_Contact *contact);
+/**
+ * Adds a GtkLabel to the list of labels
+ * which get updated by state changes.
+ *
+ * @param contact Chat contact
+ * @param label Label
+ */
void
contact_add_name_label_to_info(const struct GNUNET_CHAT_Contact *contact,
GtkLabel *label);
+/**
+ * Adds a HdyAvatar to the list of avatars
+ * which get updated by state changes.
+ *
+ * @param contact Chat contact
+ * @param avatar Avatar
+ */
void
contact_add_name_avatar_to_info(const struct GNUNET_CHAT_Contact *contact,
HdyAvatar *avatar);
+/**
+ * Updates the connected UI elements for a given
+ * contact depending on the current state.
+ *
+ * @param contact Chat contact
+ */
void
contact_update_info(const struct GNUNET_CHAT_Contact *contact);
diff --git a/src/event.h b/src/event.h
index 505309c..d89e453 100644
--- a/src/event.h
+++ b/src/event.h
@@ -27,42 +27,114 @@
#include "application.h"
+/**
+ * Event for the UI to be called whenever the application
+ * causes any issue in back-end throwing a warning. This
+ * might be specific to a given context or none if its
+ * a general warning.
+ *
+ * @param app Messenger application
+ * @param context Chat context or NULL
+ * @param msg Warning message
+ */
void
event_handle_warning(MESSENGER_Application *app,
struct GNUNET_CHAT_Context *context,
const struct GNUNET_CHAT_Message *msg);
+/**
+ * Event for the UI to be called whenever the accounts
+ * might add or remove an account from their list.
+ *
+ * @param app Messenger application
+ */
void
event_refresh_accounts(MESSENGER_Application *app);
+/**
+ * Event for the UI to be called whenever the user
+ * updates their information.
+ *
+ * @param app Messenger application
+ */
void
event_update_profile(MESSENGER_Application *app);
+/**
+ * Event for the UI to be called whenever a the user
+ * joins or leaves a chat (context) via message.
+ *
+ * @param app Messenger application
+ * @param context Chat context
+ * @param msg Join/Leave message
+ */
void
event_update_chats(MESSENGER_Application *app,
struct GNUNET_CHAT_Context *context,
const struct GNUNET_CHAT_Message *msg);
+/**
+ * Event for the UI to be called whenever a contact
+ * joins or leaves a given context via message.
+ *
+ * @param app Messenger application
+ * @param context Chat context
+ * @param msg Join/Leave message
+ */
void
event_presence_contact(MESSENGER_Application *app,
struct GNUNET_CHAT_Context *context,
const struct GNUNET_CHAT_Message *msg);
+/**
+ * Event for the UI to be called whenever a contact
+ * updates their information with a message in a
+ * given context.
+ *
+ * @param app Messenger application
+ * @param context Chat context
+ * @param msg Update message
+ */
void
event_update_contacts(MESSENGER_Application *app,
struct GNUNET_CHAT_Context *context,
const struct GNUNET_CHAT_Message *msg);
+/**
+ * Event for the UI to be called whenever an invitation
+ * message gets received in a given context.
+ *
+ * @param app Messenger application
+ * @param context Chat context
+ * @param msg Invitation message
+ */
void
event_invitation(MESSENGER_Application *app,
struct GNUNET_CHAT_Context *context,
const struct GNUNET_CHAT_Message *msg);
+/**
+ * Event for the UI to be called whenever a content
+ * message (text or file) gets received in a given
+ * context.
+ *
+ * @param app Messenger application
+ * @param context Chat context
+ * @param msg Message
+ */
void
event_receive_message(MESSENGER_Application *app,
struct GNUNET_CHAT_Context *context,
const struct GNUNET_CHAT_Message *msg);
+/**
+ * Event for the UI to be called whenever a message
+ * gets deleted in a given context.
+ *
+ * @param app Messenger application
+ * @param context Chat context
+ * @param msg Delete message
+ */
void
event_delete_message(MESSENGER_Application *app,
struct GNUNET_CHAT_Context *context,
diff --git a/src/file.h b/src/file.h
index d9bb090..939ac34 100644
--- a/src/file.h
+++ b/src/file.h
@@ -33,21 +33,59 @@ typedef struct MESSENGER_FileInfo
GList *file_messages;
} MESSENGER_FileInfo;
+/**
+ * Creates a file information struct to potentially update
+ * all GUI appearances of a specific file at once.
+ *
+ * @param file Chat file
+ */
void
file_create_info(struct GNUNET_CHAT_File *file);
+/**
+ * Destroys and frees resources allocated for a given
+ * file information struct.
+ *
+ * @param file Chat file
+ */
void
file_destroy_info(struct GNUNET_CHAT_File *file);
+/**
+ * Adds a UI message handle to the list of handles
+ * which get updated by state changes.
+ *
+ * @param file Chat file
+ * @param message UI message handle
+ */
void
file_add_ui_message_to_info(const struct GNUNET_CHAT_File *file,
UI_MESSAGE_Handle *message);
+/**
+ * Updates the connected UI elements for a given
+ * file depending on the current state of its upload
+ * process.
+ *
+ * @param file Chat file
+ * @param completed Amount of uploaded bytes
+ * @param size Size of the file in bytes
+ */
void
file_update_upload_info(const struct GNUNET_CHAT_File *file,
uint64_t completed,
uint64_t size);
+/**
+ * Updates the connected UI elements for a given
+ * file depending on the current state of its download
+ * process.
+ *
+ * @param file Chat file
+ * @param app Messenger application
+ * @param completed Amount of downloaded bytes
+ * @param size Size of the file in bytes
+ */
void
file_update_download_info(const struct GNUNET_CHAT_File *file,
MESSENGER_Application *app,
diff --git a/src/resources.h b/src/resources.h
index 82e8534..2080364 100644
--- a/src/resources.h
+++ b/src/resources.h
@@ -25,9 +25,15 @@
#ifndef RESOURCES_H_
#define RESOURCES_H_
+/**
+ * Registers the CSS and UI components for the application.
+ */
void
resources_register();
+/**
+ * Unregisters the CSS and UI components for the application.
+ */
void
resources_unregister();
diff --git a/src/ui.h b/src/ui.h
index 3c06bcc..7547b0c 100644
--- a/src/ui.h
+++ b/src/ui.h
@@ -28,12 +28,33 @@
#include <gtk-3.0/gtk/gtk.h>
#include <libhandy-1/handy.h>
+/**
+ * Sets the text of a GtkLabel applying automatic utf8
+ * conversion.
+ *
+ * @param label Label
+ * @param text Non-utf8 text
+ */
void
ui_label_set_text(GtkLabel *label, const char *text);
+/**
+ * Sets the text of a GtkEntry applying automatic utf8
+ * conversion.
+ *
+ * @param entry Entry
+ * @param text Non-utf8 text
+ */
void
ui_entry_set_text(GtkEntry *entry, const char *text);
+/**
+ * Sets the text of a HdyAvatar applying automatic utf8
+ * conversion.
+ *
+ * @param avatar Avatar
+ * @param text Non-utf8 text
+ */
void
ui_avatar_set_text(HdyAvatar *avatar, const char *text);