notify.c File Reference

Notification API. More...

#include "config.h"
#include <stdbool.h>
#include <stddef.h>
#include "notify.h"
#include "logging2.h"
#include "memory.h"
#include "notify_type.h"
#include "observer.h"
#include "queue.h"

Include dependency graph for notify.c:

Go to the source code of this file.

Data Structures
struct	Notify
	Notification API. More...

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

Variables
static const char *	NotifyTypeNames []
	Lookup table for NotifyType Must be the same size and order as NotifyType.

Detailed Description

Notification API.

Authors

• Richard Russon

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

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.c.

Function Documentation

notify_new()

struct Notify * notify_new

(

void

)

Create a new notifications handler.

Return values

ptr	New notification handler

Definition at line 62 of file notify.c.

{
  struct Notify *notify = MUTT_MEM_CALLOC(1, struct Notify);
 
  STAILQ_INIT(&notify->observers);
 
  return notify;
}

notify_free()

void notify_free

(

struct Notify **

ptr

)

Free a notification handler.

Parameters

ptr	Notification handler to free

Definition at line 75 of file notify.c.

{
  if (!ptr || !*ptr)
    return;
 
  struct Notify *notify = *ptr;
  // NOTIFY observers
 
  notify_observer_remove_all(notify);
 
  FREE(ptr);
}

Here is the call graph for this function:

notify_set_parent()

void notify_set_parent	(	struct Notify *	notify,
		struct Notify *	parent )

Set the parent notification handler.

Parameters

notify	Notification handler to alter
parent	Parent notification handler

Notifications are passed up the tree of handlers.

Definition at line 95 of file notify.c.

{
  if (!notify)
    return;
 
  notify->parent = parent;
}

send()

bool send ( struct Notify * source, struct Notify * current, enum NotifyType event_type, int event_subtype, void * event_data )

static

Send out a notification message.

Parameters

source	Source of the event, e.g. Account
current	Current handler, e.g. NeoMutt
event_type	Type of event, e.g. NT_ACCOUNT
event_subtype	Subtype, e.g. NT_ACCOUNT_ADD
event_data	Private data associated with the event type

Return values

true	Successfully sent

Notifications are sent to all observers of the object, then propagated up the handler tree. For example a "new email" notification would be sent to the Mailbox that owns it, the Account (owning the Mailbox) and finally the NeoMutt object.

Note

If Observers call notify_observer_remove(), then we garbage-collect any dead list entries after we've finished.

Definition at line 120 of file notify.c.

{
  if (!source || !current)
    return false;
 
  mutt_debug(LL_NOTIFY, "send: %d, %p\n", event_type, event_data);
  struct ObserverNode *np = NULL;
  STAILQ_FOREACH(np, &current->observers, entries)
  {
    struct Observer *o = np->observer;
    if (!o)
      continue;
 
    if ((o->type == NT_ALL) || (event_type == o->type))
    {
      struct NotifyCallback nc = { current, event_type, event_subtype,
                                   event_data, o->global_data };
      if (o->callback(&nc) < 0)
      {
        mutt_debug(LL_DEBUG1, "failed to send notification: %s/%d, global %p, event %p\n",
                   NotifyTypeNames[event_type], event_subtype, o->global_data, event_data);
      }
    }
  }
 
  if (current->parent)
    return send(source, current->parent, event_type, event_subtype, event_data);
 
  // Garbage collection time
  struct ObserverNode *tmp = NULL;
  STAILQ_FOREACH_SAFE(np, &current->observers, entries, tmp)
  {
    if (np->observer)
      continue;
 
    STAILQ_REMOVE(&current->observers, np, ObserverNode, entries);
    FREE(&np);
  }
 
  return true;
}

Here is the call graph for this function:

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

notify	Notification handler
event_type	Type of event, e.g. NT_ACCOUNT
event_subtype	Subtype, e.g. NT_ACCOUNT_ADD
event_data	Private data associated with the event

Return values

true	Successfully sent

See send() for more details.

Definition at line 173 of file notify.c.

{
  mutt_debug(LL_NOTIFY, "sending: %s/%d\n", NotifyTypeNames[event_type], event_subtype);
  return send(notify, notify, event_type, event_subtype, event_data);
}

Here is the call 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

notify	Notification handler
type	Notification type to observe, e.g. NT_WINDOW
callback	Function to call on a matching event, see observer_t
global_data	Private data associated with the observer

Return values

true	Successful

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

Definition at line 191 of file notify.c.

{
  if (!notify || !callback)
    return false;
 
  struct ObserverNode *np = NULL;
  STAILQ_FOREACH(np, &notify->observers, entries)
  {
    if (!np->observer)
      continue; // LCOV_EXCL_LINE
 
    if ((np->observer->callback == callback) && (np->observer->global_data == global_data))
      return true;
  }
 
  struct Observer *o = MUTT_MEM_CALLOC(1, struct Observer);
  o->type = type;
  o->callback = callback;
  o->global_data = global_data;
 
  np = MUTT_MEM_CALLOC(1, struct ObserverNode);
  np->observer = o;
  STAILQ_INSERT_HEAD(&notify->observers, np, entries);
 
  return true;
}

Here is the caller graph for this function:

notify_observer_remove()

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

Remove an observer from an object.

Parameters

notify	Notification handler
callback	Function to call on a matching event, see observer_t
global_data	Private data to match specific callback

Return values

true	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 230 of file notify.c.

{
  if (!notify || !callback)
    return false;
 
  struct ObserverNode *np = NULL;
  STAILQ_FOREACH(np, &notify->observers, entries)
  {
    if (!np->observer)
      continue; // LCOV_EXCL_LINE
 
    if ((np->observer->callback == callback) && (np->observer->global_data == global_data))
    {
      FREE(&np->observer);
      return true;
    }
  }
 
  return false;
}

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

notify

Notification handler

Definition at line 256 of file notify.c.

{
  if (!notify)
    return;
 
  struct ObserverNode *np = NULL;
  struct ObserverNode *tmp = NULL;
  STAILQ_FOREACH_SAFE(np, &notify->observers, entries, tmp)
  {
    STAILQ_REMOVE(&notify->observers, np, ObserverNode, entries);
    FREE(&np->observer);
    FREE(&np);
  }
}

Here is the caller graph for this function:

Variable Documentation

NotifyTypeNames

const char* NotifyTypeNames[]

static

Initial value:

                                  = {
  "NT_ALL",      "NT_ACCOUNT",   "NT_ALIAS",   "NT_ALTERN", "NT_ATTACH",
  "NT_BINDING",  "NT_COLOR",     "NT_COMMAND", "NT_CONFIG", "NT_EMAIL",
  "NT_ENVELOPE", "NT_GLOBAL",    "NT_HEADER",  "NT_INDEX",  "NT_KEY",
  "NT_MAILBOX",  "NT_MVIEW",     "NT_MENU",    "NT_RESIZE", "NT_PAGER",
  "NT_SCORE",    "NT_SUBJECTRX", "NT_TIMEOUT", "NT_WINDOW",
}

Lookup table for NotifyType Must be the same size and order as NotifyType.

Definition at line 41 of file notify.c.

                                     {
  "NT_ALL",      "NT_ACCOUNT",   "NT_ALIAS",   "NT_ALTERN", "NT_ATTACH",
  "NT_BINDING",  "NT_COLOR",     "NT_COMMAND", "NT_CONFIG", "NT_EMAIL",
  "NT_ENVELOPE", "NT_GLOBAL",    "NT_HEADER",  "NT_INDEX",  "NT_KEY",
  "NT_MAILBOX",  "NT_MVIEW",     "NT_MENU",    "NT_RESIZE", "NT_PAGER",
  "NT_SCORE",    "NT_SUBJECTRX", "NT_TIMEOUT", "NT_WINDOW",
};