nagbalae/dunst
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add initial doxygen documentation

Browse Source
This commit is contained in:
Benedikt Heine 2018-02-20 17:28:19 +01:00
parent 6bf886d437
commit 422f353243
6 changed files with 202 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
src/dbus.h
View File

@ -5,13 +5,14 @@
#include "notification.h"
/// The reasons according to the notification spec
enum reason {
REASON_MIN = 1,
REASON_TIME = 1,
REASON_USER = 2,
REASON_SIG = 3,
REASON_UNDEF = 4,
REASON_MAX = 4,
REASON_MIN = 1, /**< Minimum value, useful for boundary checking */
REASON_TIME = 1, /**< The notification timed out */
REASON_USER = 2, /**< The user closed the notification */
REASON_SIG = 3, /**< The daemon received a `NotificationClose` signal */
REASON_UNDEF = 4, /**< Undefined reason not matching the previous ones */
REASON_MAX = 4, /**< Maximum value, useful for boundary checking */
};
int initdbus(void);

20
src/log.c
View File

@ -1,11 +1,16 @@
/* copyright 2012 - 2013 Sascha Kruse and contributors (see LICENSE for licensing information) */
/** @file log.c
* @brief logging wrapper to use GLib's logging capabilities
*/
#include "log.h"
#include <glib.h>
static GLogLevelFlags log_level = G_LOG_LEVEL_WARNING;
/* see log.h */
static const char *log_level_to_string(GLogLevelFlags level)
{
switch (level) {
@ -19,6 +24,7 @@ static const char *log_level_to_string(GLogLevelFlags level)
}
}
/* see log.h */
void log_set_level_from_string(const char *level)
{
if (!level)
@ -51,10 +57,13 @@ void log_set_level(GLogLevelFlags level)
log_level = level;
}
/*
/**
* Log handling function for GLib's logging wrapper
*
* If the gpointer is valid, do not do anything
* @param log_domain Used only by GLib
* @param message_level Used only by GLib
* @param message Used only by GLib
* @param testing If not `NULL` (here: `true`), do nothing
*/
static void dunst_log_handler(
const gchar *log_domain,
@ -81,12 +90,7 @@ static void dunst_log_handler(
g_print("%s: %s\n", log_level_str, message);
}
/*
* Initialise log handling. Can be called any time.
*
* If bool is %TRUE, it suppresses all logging output.
* Primarily used for testing
*/
/* see log.h */
void dunst_log_init(bool testing)
{
g_log_set_default_handler(dunst_log_handler, (void*)testing);

18
src/log.h
View File

@ -16,9 +16,27 @@
#define DIE(...) do { LOG_C(__VA_ARGS__); exit(EXIT_FAILURE); } while (0)
/**
* @return the string representation of the given `level`
*/
void log_set_level(GLogLevelFlags level);
/**
* Set the current loglevel to `level`
*
* @param level The desired log level
*
* If `level` is `NULL`, nothing will be done.
* If `level` is an invalid value, nothing will be done.
*/
void log_set_level_from_string(const char* level);
/**
* Initialise log handling. Can be called any time.
*
* @param testing If we're in testing mode and should
* suppress all output
*/
void dunst_log_init(bool testing);
#endif

41
src/notification.h
View File

@ -9,13 +9,14 @@
#define DUNST_NOTIF_MAX_CHARS 5000
/// Representing the urgencies according to the notification spec
enum urgency {
URG_NONE = -1,
URG_MIN = 0,
URG_LOW = 0,
URG_NORM = 1,
URG_CRIT = 2,
URG_MAX = 2,
URG_NONE = -1, /**< Urgency not set (invalid) */
URG_MIN = 0, /**< Minimum value, useful for boundary checking */
URG_LOW = 0, /**< Low urgency */
URG_NORM = 1, /**< Normal urgency */
URG_CRIT = 2, /**< Critical urgency */
URG_MAX = 2, /**< Maximum value, useful for boundary checking */
};
typedef struct _raw_image {
@ -44,12 +45,12 @@ typedef struct _notification {
char *category;
enum urgency urgency;
char *icon; /* plain icon information (may be a path or just a name) */
RawImage *raw_icon; /* passed icon data of notification, takes precedence over icon */
char *icon; /**< plain icon information (may be a path or just a name) */
RawImage *raw_icon; /**< passed icon data of notification, takes precedence over icon */
gint64 start; /* begin of current display */
gint64 timestamp; /* arrival time */
gint64 timeout; /* time to display */
gint64 start; /**< begin of current display */
gint64 timestamp; /**< arrival time */
gint64 timeout; /**< time to display */
Actions *actions;
@ -59,20 +60,20 @@ typedef struct _notification {
char *colors[3];
/* Hints */
bool transient; /* timeout albeit user is idle */
int progress; /* percentage (-1: undefined) */
int history_ignore; /* push to history or free directly */
bool transient; /**< timeout albeit user is idle */
int progress; /**< percentage (-1: undefined) */
int history_ignore; /**< push to history or free directly */
/* internal */
bool redisplayed; /* has been displayed before? */
bool first_render; /* markup has been rendered before? */
int dup_count; /* amount of duplicate notifications stacked onto this */
bool redisplayed; /**< has been displayed before? */
bool first_render; /**< markup has been rendered before? */
int dup_count; /**< amount of duplicate notifications stacked onto this */
int displayed_height;
/* derived fields */
char *msg; /* formatted message */
char *text_to_render; /* formatted message (with age and action indicators) */
char *urls; /* urllist delimited by '\n' */
char *msg; /**< formatted message */
char *text_to_render; /**< formatted message (with age and action indicators) */
char *urls; /**< urllist delimited by '\\n' */
} notification;
notification *notification_create(void);

54
src/queues.c
View File

@ -1,5 +1,18 @@
/* copyright 2013 Sascha Kruse and contributors (see LICENSE for licensing information) */
/**
* @file queues.c
* @brief All important functions to handle the notification queues for
* history, entrance and currently displayed ones.
*
* Every method requires to have executed queues_init() at the start.
*
* A read only representation of the queue with the current notifications
* can get acquired by calling queues_get_displayed().
*
* When ending the program or resetting the queues, tear down the stack with
* queues_teardown(). (And reinit with queues_init() if needed.)
*/
#include "queues.h"
#include <assert.h>
@ -12,9 +25,9 @@
#include "settings.h"
/* notification lists */
static GQueue *waiting = NULL; /* all new notifications get into here */
static GQueue *displayed = NULL; /* currently displayed notifications */
static GQueue *history = NULL; /* history of displayed notifications */
static GQueue *waiting = NULL; /**< all new notifications get into here */
static GQueue *displayed = NULL; /**< currently displayed notifications */
static GQueue *history = NULL; /**< history of displayed notifications */
unsigned int displayed_limit = 0;
int next_notification_id = 1;
@ -22,6 +35,7 @@ bool pause_displayed = false;
static bool queues_stack_duplicate(notification *n);
/* see queues.h */
void queues_init(void)
{
history = g_queue_new();
@ -29,29 +43,37 @@ void queues_init(void)
waiting = g_queue_new();
}
/* see queues.h */
void queues_displayed_limit(unsigned int limit)
{
displayed_limit = limit;
}
/* misc getter functions */
/* see queues.h */
const GList *queues_get_displayed(void)
{
return g_queue_peek_head_link(displayed);
}
/* see queues.h */
unsigned int queues_length_waiting(void)
{
return waiting->length;
}
/* see queues.h */
unsigned int queues_length_displayed(void)
{
return displayed->length;
}
/* see queues.h */
unsigned int queues_length_history(void)
{
return history->length;
}
/* see queues.h */
int queues_notification_insert(notification *n)
{
@ -88,11 +110,11 @@ int queues_notification_insert(notification *n)
return n->id;
}
/*
/**
* Replaces duplicate notification and stacks it
*
* Returns %true, if notification got stacked
* Returns %false, if notification did not get stacked
* @return true, if notification got stacked
* @return false, if notification did not get stacked
*/
static bool queues_stack_duplicate(notification *n)
{
@ -148,6 +170,7 @@ static bool queues_stack_duplicate(notification *n)
return false;
}
/* see queues.h */
bool queues_notification_replace_id(notification *new)
{
@ -179,6 +202,7 @@ bool queues_notification_replace_id(notification *new)
return false;
}
/* see queues.h */
void queues_notification_close_id(int id, enum reason reason)
{
notification *target = NULL;
@ -212,12 +236,14 @@ void queues_notification_close_id(int id, enum reason reason)
}
}
/* see queues.h */
void queues_notification_close(notification *n, enum reason reason)
{
assert(n != NULL);
queues_notification_close_id(n->id, reason);
}
/* see queues.h */
void queues_history_pop(void)
{
if (g_queue_is_empty(history))
@ -230,6 +256,7 @@ void queues_history_pop(void)
g_queue_push_head(waiting, n);
}
/* see queues.h */
void queues_history_push(notification *n)
{
if (!n->history_ignore) {
@ -244,6 +271,7 @@ void queues_history_push(notification *n)
}
}
/* see queues.h */
void queues_history_push_all(void)
{
while (displayed->length > 0) {
@ -255,6 +283,7 @@ void queues_history_push_all(void)
}
}
/* see queues.h */
void queues_check_timeouts(bool idle)
{
/* nothing to do */
@ -290,6 +319,7 @@ void queues_check_timeouts(bool idle)
}
}
/* see queues.h */
void queues_update(void)
{
if (pause_displayed) {
@ -323,6 +353,7 @@ void queues_update(void)
}
}
/* see queues.h */
gint64 queues_get_next_datachange(gint64 time)
{
gint64 sleep = G_MAXINT64;
@ -354,27 +385,36 @@ gint64 queues_get_next_datachange(gint64 time)
return sleep != G_MAXINT64 ? sleep : -1;
}
/* see queues.h */
void queues_pause_on(void)
{
pause_displayed = true;
}
/* see queues.h */
void queues_pause_off(void)
{
pause_displayed = false;
}
/* see queues.h */
bool queues_pause_status(void)
{
return pause_displayed;
}
/**
* Helper function for teardown_queues() to free a single notification
*
* @param data The notification to free
*/
static void teardown_notification(gpointer data)
{
notification *n = data;
notification_free(n);
}
/* see queues.h */
void teardown_queues(void)
{
g_queue_free_full(history, teardown_notification);

134
src/queues.h
View File

@ -1,131 +1,183 @@
/* copyright 2013 Sascha Kruse and contributors (see LICENSE for licensing information) */
/**
* @file queues.c
*/
#ifndef DUNST_QUEUE_H
#define DUNST_QUEUE_H
#include "dbus.h"
#include "notification.h"
/*
* Initialise neccessary queues
/**
* Initialise necessary queues
*
* @pre Do not call consecutively to avoid memory leaks
* or assure to have queues_teardown() executed before
*/
void queues_init(void);
/*
/**
* Set maximum notification count to display
* and store in displayed queue
*
* @param limit The maximum amount
*/
void queues_displayed_limit(unsigned int limit);
/*
* Return read only list of notifications
/**
* Receive the current list of displayed notifications
*
* @return read only list of notifications
*/
const GList *queues_get_displayed(void);
/*
/**
* Returns the current amount of notifications,
* which are shown, waiting or already in history
* which are waiting to get displayed
*/
unsigned int queues_length_waiting(void);
/**
* Returns the current amount of notifications,
* which are shown in the UI
*/
unsigned int queues_length_displayed(void);
/**
* Returns the current amount of notifications,
* which are already in history
*/
unsigned int queues_length_history(void);
/*
/**
* Insert a fully initialized notification into queues
*
* Respects stack_duplicates, and notification replacement
*
* If n->id != 0, n replaces notification with id n->id
* If n->id == 0, n gets a new id assigned
* @param n the notification to insert
*
* Returns the assigned notification id
* If returned id == 0, the message was dismissed
* - If n->id != 0, n replaces notification n with id n->id
* - If n->id == 0, n gets a new id assigned
*
* @return `0`, the notification was dismissed and freed
* @return The new value of `n->id`
*/
int queues_notification_insert(notification *n);
/*
/**
* Replace the notification which matches the id field of
* the new notification. The given notification is inserted
* right in the same position as the old notification.
*
* Returns true, if a matching notification has been found
* and is replaced. Else false.
* @param new replacement for the old notification
*
* @return true, if a matching notification has been found and is replaced
* @return false, else
*/
bool queues_notification_replace_id(notification *new);
/*
/**
* Close the notification that has n->id == id
*
* Sends a signal and pushes it automatically to history.
* Sends a signal and pushes the selected notification automatically to history.
*
* After closing, call wake_up to synchronize the queues with the UI
* @param id The id of the notification to close
* @param reason The #reason to close
*
* @return the reason, why the notification got closed
*
* @post Call wake_up() to synchronize the queues with the UI
* (which closes the notification on screen)
*/
void queues_notification_close_id(int id, enum reason reason);
/* Close the given notification. SEE queues_notification_close_id.
/**
* Close the given notification. \see queues_notification_close_id().
*
* @n: (transfer full): The notification to close
* @reason: The reason to close
* @param n (transfer full) The notification to close
* @param reason The #reason to close
* */
void queues_notification_close(notification *n, enum reason reason);
/*
* Pushed the latest notification of history to the displayed queue
/**
* Pushes the latest notification of history to the displayed queue
* and removes it from history
*/
void queues_history_pop(void);
/*
/**
* Push a single notification to history
* The given notification has to be removed its queue
*
* @n: (transfer full): The notification to push to history
* @param n (transfer full) The notification to push to history
*/
void queues_history_push(notification *n);
/*
/**
* Push all waiting and displayed notifications to history
*/
void queues_history_push_all(void);
/*
* Check timeout of each notification and close it, if neccessary
/**
* Check timeout of each notification and close it, if necessary
*
* @param idle the program's idle status. Important to calculate the
* timeout for transient notifications
*/
void queues_check_timeouts(bool idle);
/*
/**
* Move inserted notifications from waiting queue to displayed queue
* and show them. In displayed queue, the amount of elements is limited
* to the amount set via queues_displayed_limit
* to the amount set via queues_displayed_limit()
*
* @post Call wake_up() to synchronize the queues with the UI
* (which closes old and shows new notifications on screen)
*/
void queues_update(void);
/*
* Return the distance to the next event in the queue,
* which forces an update visible to the user
/**
* Calculate the distance to the next event, when an element in the
* queues changes
*
* This may be:
* @param time the current time
*
* @return the distance to the next event in the queue, which forces
* an update visible to the user. This may be:
* - notification hits timeout
* - notification's age second changes
* - notification's age threshold is hit
*/
gint64 queues_get_next_datachange(gint64 time);
/*
/**
* Pause queue-management of dunst
* pause_on = paused (no notifications displayed)
* pause_off = running
*
* Calling update_lists is neccessary
* @post Calling update_lists() is neccessary
*/
void queues_pause_on(void);
/**
* Unpause (run) queue-management of dunst
*
* @post Calling update_lists() is neccessary
*/
void queues_pause_off(void);
/**
* Get the current status
*
* @return true if paused
* @return false if running
*/
bool queues_pause_status(void);
/*
* Remove all notifications from all lists
* and free the notifications
/**
* Remove all notifications from all list and free the notifications
*
* @pre At least one time queues_init() called
*/
void teardown_queues(void);