NeoMutt  2020-11-20
Teaching an old dog new tricks
DOXYGEN
notify.h File Reference

Notification API. More...

#include <stdbool.h>
#include "notify_type.h"
#include "observer.h"
+ Include dependency graph for notify.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

struct Notifynotify_new (void)
 Create a new notifications handler. More...
 
void notify_free (struct Notify **ptr)
 Free a notification handler. More...
 
void notify_set_parent (struct Notify *notify, struct Notify *parent)
 Set the parent notification handler. More...
 
bool notify_send (struct Notify *notify, enum NotifyType event_type, int event_subtype, void *event_data)
 Send out a notification message. More...
 
bool notify_observer_add (struct Notify *notify, enum NotifyType type, observer_t callback, void *global_data)
 Add an observer to an object. More...
 
bool notify_observer_remove (struct Notify *notify, observer_t callback, void *global_data)
 Remove an observer from an object. More...
 
void notify_observer_remove_all (struct Notify *notify)
 Remove all the observers from an object. More...
 

Detailed Description

Notification API.

Authors
  • Richard Russon

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file notify.h.

Function Documentation

◆ notify_new()

struct Notify* notify_new ( void  )

Create a new notifications handler.

Return values
ptrNew notification handler

Definition at line 49 of file notify.c.

50 {
51  struct Notify *notify = mutt_mem_calloc(1, sizeof(*notify));
52 
53  STAILQ_INIT(&notify->observers);
54 
55  return notify;
56 }
void * mutt_mem_calloc(size_t nmemb, size_t size)
Allocate zeroed memory on the heap.
Definition: memory.c:50
#define STAILQ_INIT(head)
Definition: queue.h:369
struct ObserverList observers
Definition: notify.c:42
Notification API.
Definition: notify.c:39
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ notify_free()

void notify_free ( struct Notify **  ptr)

Free a notification handler.

Parameters
ptrNotification handler to free

Definition at line 62 of file notify.c.

63 {
64  if (!ptr || !*ptr)
65  return;
66 
67  struct Notify *notify = *ptr;
68  // NOTIFY observers
69 
71 
72  FREE(ptr);
73 }
Notification API.
Definition: notify.c:39
void notify_observer_remove_all(struct Notify *notify)
Remove all the observers from an object.
Definition: notify.c:232
#define FREE(x)
Definition: memory.h:40
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ notify_set_parent()

void notify_set_parent ( struct Notify notify,
struct Notify parent 
)

Set the parent notification handler.

Parameters
notifyNotification handler to alter
parentParent notification handler

Notifications are passed up the tree of handlers.

Definition at line 82 of file notify.c.

83 {
84  if (!notify)
85  return;
86 
87  notify->parent = parent;
88 }
struct Notify * parent
Definition: notify.c:41
+ Here is the caller graph for this function:

◆ notify_send()

bool notify_send ( struct Notify notify,
enum NotifyType  event_type,
int  event_subtype,
void *  event_data 
)

Send out a notification message.

Parameters
notifyNotification handler
event_typeType of event, e.g. NT_ACCOUNT
event_subtypeSubtype, e.g. NT_ACCOUNT_ADD
event_dataPrivate data associated with the event
Return values
trueIf successfully sent

See send() for more details.

Definition at line 152 of file notify.c.

154 {
155  return send(notify, notify, event_type, event_subtype, event_data);
156 }
static bool send(struct Notify *source, struct Notify *current, enum NotifyType event_type, int event_subtype, void *event_data)
Send out a notification message.
Definition: notify.c:107
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ notify_observer_add()

bool notify_observer_add ( struct Notify notify,
enum NotifyType  type,
observer_t  callback,
void *  global_data 
)

Add an observer to an object.

Parameters
notifyNotification handler
typeNotification type to observe, e.g. NT_WINDOW
callbackFunction to call on a matching event, see observer_t
global_dataPrivate data associated with the observer
Return values
trueIf successful

New observers are added to the front of the list, giving them higher priority than existing observers.

Definition at line 169 of file notify.c.

171 {
172  if (!notify || !callback)
173  return false;
174 
175  struct ObserverNode *np = NULL;
176  STAILQ_FOREACH(np, &notify->observers, entries)
177  {
178  if (!np->observer)
179  continue;
180 
181  if (np->observer->callback == callback)
182  return true;
183  }
184 
185  struct Observer *o = mutt_mem_calloc(1, sizeof(*o));
186  o->callback = callback;
188 
189  np = mutt_mem_calloc(1, sizeof(*np));
190  np->observer = o;
191  STAILQ_INSERT_HEAD(&notify->observers, np, entries);
192 
193  return true;
194 }
void * mutt_mem_calloc(size_t nmemb, size_t size)
Allocate zeroed memory on the heap.
Definition: memory.c:50
struct Observer * observer
An Observer.
Definition: observer.h:71
void * global_data
Private data to pass to callback.
Definition: observer.h:63
struct ObserverList observers
Definition: notify.c:42
#define STAILQ_INSERT_HEAD(head, elm, field)
Definition: queue.h:380
An observer of notifications.
Definition: observer.h:59
#define STAILQ_FOREACH(var, head, field)
Definition: queue.h:349
List of Observers.
Definition: observer.h:69
observer_t callback
Callback function for events.
Definition: observer.h:62
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ notify_observer_remove()

bool notify_observer_remove ( struct Notify notify,
observer_t  callback,
void *  global_data 
)

Remove an observer from an object.

Parameters
notifyNotification handler
callbackFunction to call on a matching event, see observer_t
global_dataPrivate data to match specific callback
Return values
trueIf successful
Note
This function frees the Observer, but doesn't free the ObserverNode. If send() is present higher up the call stack, removing multiple entries from the list will cause it to crash.

Definition at line 207 of file notify.c.

208 {
209  if (!notify || !callback)
210  return false;
211 
212  struct ObserverNode *np = NULL;
213  STAILQ_FOREACH(np, &notify->observers, entries)
214  {
215  if (!np->observer)
216  continue;
217 
218  if ((np->observer->callback == callback) && (np->observer->global_data == global_data))
219  {
220  FREE(&np->observer);
221  return true;
222  }
223  }
224 
225  return false;
226 }
struct Observer * observer
An Observer.
Definition: observer.h:71
void * global_data
Private data to pass to callback.
Definition: observer.h:63
struct ObserverList observers
Definition: notify.c:42
#define STAILQ_FOREACH(var, head, field)
Definition: queue.h:349
List of Observers.
Definition: observer.h:69
#define FREE(x)
Definition: memory.h:40
observer_t callback
Callback function for events.
Definition: observer.h:62
+ Here is the caller graph for this function:

◆ notify_observer_remove_all()

void notify_observer_remove_all ( struct Notify notify)

Remove all the observers from an object.

Parameters
notifyNotification handler

Definition at line 232 of file notify.c.

233 {
234  if (!notify)
235  return;
236 
237  struct ObserverNode *np = NULL;
238  struct ObserverNode *tmp = NULL;
239  STAILQ_FOREACH_SAFE(np, &notify->observers, entries, tmp)
240  {
241  STAILQ_REMOVE(&notify->observers, np, ObserverNode, entries);
242  FREE(&np->observer);
243  FREE(&np);
244  }
245 }
#define STAILQ_REMOVE(head, elm, type, field)
Definition: queue.h:399
struct Observer * observer
An Observer.
Definition: observer.h:71
#define STAILQ_FOREACH_SAFE(var, head, field, tvar)
Definition: queue.h:359
struct ObserverList observers
Definition: notify.c:42
List of Observers.
Definition: observer.h:69
#define FREE(x)
Definition: memory.h:40
+ Here is the caller graph for this function: