/* -----------------------------------------------------------------------------
 * Observable.h                                            (c) 2013 Micro-Key bv
 * -----------------------------------------------------------------------------
 * Micro-Key bv
 * Industrieweg 28, 9804 TG Noordhorn
 * Postbus 92, 9800 AB Zuidhorn
 * The Netherlands
 * Tel: +31 594 503020
 * Fax: +31 594 505825
 * Email: support@microkey.nl
 * Web: www.microkey.nl
 * -----------------------------------------------------------------------------
 * Description: Observer design pattern
 * -----------------------------------------------------------------------------
 * $Id$
 * -----------------------------------------------------------------------------
 */

/**
 * %Observable implementation
 * \defgroup Observable Package Observable
 * \ingroup HAL
 * @{
 */

#ifndef _OBSERVABLE_H_
#define _OBSERVABLE_H_

/* --------------*
 * Include files *
 * --------------*
 */

#include "stm32f10x.h"

#include "Observer.h"

/* -------------------------------*
 * Constant and macro definitions *
 * -------------------------------*
 */

/** 
* Maximal number of Observers for one Observable.
*/
#define OBSERVABLE_MAX_OBSERVERS (10)

/**
* Static initializer for the Observable class.
* Typical usage: struct Observable observable = OBSERVABLE_INITIALIZER;
*/
#define OBSERVABLE_INITIALIZER { .nrOfObservers = 0, .observers = { 0, } }


/* ------------------*
 * Type definitions. *
 * ------------------*
 */

/** 
* The Observable class.
*/
struct Observable
{
	int nrOfObservers;
	Observer observers[OBSERVABLE_MAX_OBSERVERS];
};

/* ----------------------*
 * Function declarations *
 * ----------------------*
 */

/** 
* Initializes the Observable class.
* This is not needed if the Observable has been statically initialized by "struct Observable observable = OBSERVABLE_INITIALIZER".
* @memberof Observable
* @param self: address of the Observable struct.
* @retval none.
*/
void Observable_construct(struct Observable* self);

/** 
* Terminates the Observable class. All Observers are removed.
* @memberof Observable
* @param self: address of the Observable struct.
* @retval none.
*/
void Observable_destruct(struct Observable* self);

/** 
* Adds one Observer to the Observable.
* @memberof Observable
* @param self: address of the Observable struct.
* @param observer: Observer to be added.
* @retval ErrorStatus: returns an error in case the maximum number of Observers have been added.
*/
ErrorStatus Observable_addObserver(struct Observable* self, const Observer observer);

/** 
* Adds one Observer to the Observable at the front of the list.
* This ensures that this Observer is notified before Observers added by Observable_addObserver.
* @memberof Observable
* @param self: address of the Observable struct.
* @param observer: Observer to be added.
* @retval ErrorStatus: returns an error in case the maximum number of Observers have been added.
*/
ErrorStatus Observable_addObserverAtFront(struct Observable* self, const Observer observer);

/** 
* Notifies all Observers by calling the Observer callback function. The parameter void* data will be
* passed as parameter to the Observer.
* @memberof Observable
* @param self: address of the Observable struct.
* @param data: void pointer data to be passed as parameter to the Observer.
* @retval ErrorStatus: returns an error in case one or more of the Observers returned an error.
*/
ErrorStatus Observable_notifyObservers(const struct Observable* self, const void* const data);

/** 
* Deletes one specific Observer added before. If the Observer cannot be found, no action is taken.
* @memberof Observable
* @param self: address of the Observable struct.
* @param observer: Observer to be deleted.
*/
void Observable_deleteObserver(struct Observable* self, const Observer observer);

/** 
* Deletes all Observers added.
* @memberof Observable
* @param self: address of the Observable struct.
*/
void Observable_deleteObservers(struct Observable* self);

/**
* Returns the number of Observers currently subscribed to an Observable.
* @memberof Observable
* @param self: address of the Observable struct.
*/
int Observable_nrOfObservers(struct Observable* self);

#endif

/** @} */