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

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

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;
}

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: