ucs2-lib/inc/ucs_obs.h

   1 /*------------------------------------------------------------------------------------------------*/
   2 /* UNICENS V2.1.0-3491                                                                            */
   3 /* Copyright (c) 2017 Microchip Technology Germany II GmbH & Co. KG.                              */
   4 /*                                                                                                */
   5 /* This program is free software: you can redistribute it and/or modify                           */
   6 /* it under the terms of the GNU General Public License as published by                           */
   7 /* the Free Software Foundation, either version 2 of the License, or                              */
   8 /* (at your option) any later version.                                                            */
   9 /*                                                                                                */
  10 /* This program is distributed in the hope that it will be useful,                                */
  11 /* but WITHOUT ANY WARRANTY; without even the implied warranty of                                 */
  12 /* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the                                  */
  13 /* GNU General Public License for more details.                                                   */
  14 /*                                                                                                */
  15 /* You should have received a copy of the GNU General Public License                              */
  16 /* along with this program.  If not, see <http://www.gnu.org/licenses/>.                          */
  17 /*                                                                                                */
  18 /* You may also obtain this software under a propriety license from Microchip.                    */
  19 /* Please contact Microchip for further information.                                              */
  20 /*------------------------------------------------------------------------------------------------*/
  21
  22 /*!
  23  * \file
  24  * \brief Internal header file of the observer library module. The module consists of the two
  25  *        classes CSubject and CObserver.
  26  *
  27  * \cond UCS_INTERNAL_DOC
  28  * \addtogroup G_OBS
  29  * @{
  30  */
  31
  32 #ifndef UCS_OBS_H
  33 #define UCS_OBS_H
  34
  35 /*------------------------------------------------------------------------------------------------*/
  36 /* Includes                                                                                       */
  37 /*------------------------------------------------------------------------------------------------*/
  38 #include "ucs_types_cfg.h"
  39 #include "ucs_dl.h"
  40 #include "ucs_ret_pb.h"
  41
  42 #ifdef __cplusplus
  43 extern "C"
  44 {
  45 #endif
  46
  47 /*------------------------------------------------------------------------------------------------*/
  48 /* Type definitions                                                                               */
  49 /*------------------------------------------------------------------------------------------------*/
  50 /*! \brief Function signature used for callback functions which notifies the observers.
  51  *  \param self     Instance pointer
  52  *  \param data_ptr Reference to optional data
  53  */
  54 typedef void (*Obs_UpdateCb_t)(void *self, void *data_ptr);
  55
  56 /*! \brief Function signature used for callback functions which notifies the single-observers.
  57  *  \param self     Instance pointer
  58  *  \param data_ptr Reference to optional data
  59  */
  60 typedef void (*Sobs_UpdateCb_t)(void *self, void *data_ptr);
  61
  62 /*------------------------------------------------------------------------------------------------*/
  63 /* Enumerators                                                                                    */
  64 /*------------------------------------------------------------------------------------------------*/
  65 /*! \brief Standard return values of the subject class. */
  66 typedef enum Sub_Ret_
  67 {
  68     SUB_OK,                 /*!< \brief No error */
  69     SUB_DELAYED,            /*!< \brief Operation is queued since notification is still active */
  70     SUB_ALREADY_ADDED,      /*!< \brief Observer already added */
  71     SUB_UNKNOWN_OBSERVER,   /*!< \brief Unknown observer */
  72     SUB_INVALID_OPERATION   /*!< \brief Invalid operation */
  73
  74 } Sub_Ret_t;
  75
  76 /*! \brief Standard return values of the single-subject class. */
  77 typedef enum Ssub_Ret_
  78 {
  79     SSUB_OK,                /*!< \brief No error */
  80     SSUB_ALREADY_ADDED,     /*!< \brief Observer already added */
  81     SSUB_UNKNOWN_OBSERVER   /*!< \brief Unknown observer */
  82
  83 } Ssub_Ret_t;
  84
  85 /*------------------------------------------------------------------------------------------------*/
  86 /* Structures                                                                                     */
  87 /*------------------------------------------------------------------------------------------------*/
  88 /*! \brief Class structure of observers which are notified by subjects. */
  89 typedef struct CObserver_
  90 {
  91     CDlNode node;               /*!< \brief Node element to be able to add observer to list */
  92     void *inst_ptr;             /*!< \brief Reference to instance used by update_fptr() */
  93     Obs_UpdateCb_t update_fptr; /*!< \brief Callback function to update the observer */
  94     bool valid;                 /*!< \brief Used for queued remove operation */
  95
  96 } CObserver;
  97
  98 /*! \brief Class structure of subjects. */
  99 typedef struct CSubject_
 100 {
 101     CDlList list;               /*!< \brief Doubly linked list to manage observers */
 102     CDlList add_list;           /*!< \brief List to manage delayed add operations */
 103     uint8_t num_observers;      /*!< \brief Number of added observers */
 104     bool notify;                /*!< \brief Signals that the notification is in progress */
 105     bool changed;               /*!< \brief Signals that an add- or a remove-operation
 106                                             has been queued */
 107     void *ucs_user_ptr;         /*!< \brief User reference that needs to be passed in every callback function */
 108
 109 } CSubject;
 110
 111 /*! \brief Class structure of a single-observer which is notified by a single-subject. */
 112 typedef struct CSingleObserver_
 113 {
 114     void *inst_ptr;             /*!< \brief Reference to instance used by update_fptr() */
 115     Obs_UpdateCb_t update_fptr; /*!< \brief Callback function to update the observer */
 116
 117 } CSingleObserver;
 118
 119 /*! \brief Class structure of a single-subject. */
 120 typedef struct CSingleSubject_
 121 {
 122     CSingleObserver *observer_ptr;  /*!< \brief Reference to the assigned single-observer */
 123     void *ucs_user_ptr;         /*!< \brief User reference that needs to be passed in every callback function */
 124     uint32_t user_mask;             /*!< \brief Current user mask to the single observer */
 125
 126 } CSingleSubject;
 127
 128 /*! \brief Class structure of masked observers which are notified by subjects. */
 129 typedef struct CMaskedObserver_
 130 {
 131     CObserver parent;               /*!< \brief Parent class instance */
 132     uint32_t notification_mask;     /*!< \brief Notification bitmask */
 133
 134 } CMaskedObserver;
 135
 136 /*------------------------------------------------------------------------------------------------*/
 137 /* Prototypes of class CSubject                                                                   */
 138 /*------------------------------------------------------------------------------------------------*/
 139 extern void Sub_Ctor(CSubject *self, void *ucs_user_ptr);
 140 extern Sub_Ret_t Sub_AddObserver(CSubject *self, CObserver *obs_ptr);
 141 extern Sub_Ret_t Sub_RemoveObserver(CSubject *self, CObserver *obs_ptr);
 142 extern void Sub_Notify(CSubject *self, void *data_ptr);
 143 extern uint8_t Sub_GetNumObservers(CSubject *self);
 144 extern Sub_Ret_t Sub_SwitchObservers(CSubject *sub_target, CSubject *sub_source);
 145
 146 /*------------------------------------------------------------------------------------------------*/
 147 /* Prototypes of class CObserver                                                                  */
 148 /*------------------------------------------------------------------------------------------------*/
 149 extern void Obs_Ctor(CObserver *self, void *inst_ptr, Obs_UpdateCb_t update_fptr);
 150
 151 /*------------------------------------------------------------------------------------------------*/
 152 /* Prototypes of class CSingleSubject                                                             */
 153 /*------------------------------------------------------------------------------------------------*/
 154 extern void Ssub_Ctor(CSingleSubject *self, void *ucs_user_ptr);
 155 extern Ssub_Ret_t Ssub_AddObserver(CSingleSubject *self, CSingleObserver *obs_ptr);
 156 extern void Ssub_RemoveObserver(CSingleSubject *self);
 157 extern void Ssub_Notify(CSingleSubject *self, void *data_ptr, bool auto_remove);
 158
 159 /*------------------------------------------------------------------------------------------------*/
 160 /* Prototypes of class CSingleObserver                                                            */
 161 /*------------------------------------------------------------------------------------------------*/
 162 extern void Sobs_Ctor(CSingleObserver *self, void *inst_ptr, Sobs_UpdateCb_t update_fptr);
 163
 164 /*------------------------------------------------------------------------------------------------*/
 165 /* Prototypes of class CMaskedObserver                                                            */
 166 /*------------------------------------------------------------------------------------------------*/
 167 extern void Mobs_Ctor(CMaskedObserver *self,
 168                       void *inst_ptr,
 169                       uint32_t notification_mask,
 170                       Obs_UpdateCb_t update_fptr);
 171 extern void Mobs_SetNotificationMask(CMaskedObserver *self, uint32_t mask);
 172 extern uint32_t Mobs_GetNotificationMask(CMaskedObserver *self);
 173
 174 /*------------------------------------------------------------------------------------------------*/
 175 /* Additional prototypes of class CSubject used in combination with CMaskedObserver               */
 176 /*------------------------------------------------------------------------------------------------*/
 177 extern Sub_Ret_t Msub_AddObserver(CSubject *self, CMaskedObserver *obs_ptr);
 178 extern Sub_Ret_t Msub_RemoveObserver(CSubject *self, CMaskedObserver *obs_ptr);
 179 extern void Msub_Notify(CSubject *self, void *data_ptr, uint32_t notification_mask);
 180
 181 #ifdef __cplusplus
 182 }   /* extern "C" */
 183 #endif
 184
 185 #endif  /* #ifndef UCS_OBS_H */
 186
 187 /*!
 188  * @}
 189  * \endcond
 190  */
 191
 192 /*------------------------------------------------------------------------------------------------*/
 193 /* End of file                                                                                    */
 194 /*------------------------------------------------------------------------------------------------*/
 195