Vlv2TbltDevicePkg/Include/Protocol/Observable.h

   1 /*++
   2
   3   Copyright (c) 2004  - 2014, Intel Corporation. All rights reserved.<BR>
   4
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7
   8
   9
  10 Module Name:
  11
  12   Observable.h
  13
  14 Abstract:
  15
  16   Interface and GUID definitions for Observable protocol.
  17
  18 **/
  19
  20 #ifndef _OBSERVABLE_PROTOCOL_H_
  21 #define _OBSERVABLE_PROTOCOL_H_
  22
  23 //
  24 // GUID Definitions
  25 //
  26 #define OBSERVABLE_PROTOCOL_GUID \
  27   { \
  28     0xe227c522, 0xd5fe, 0x4a53, 0x87, 0xb1, 0x0f, 0xbe, 0x57, 0x0f, 0x98, 0xe9 \
  29   }
  30
  31 extern EFI_GUID gObservableProtocolGuid;
  32
  33 typedef struct _OBS_OBSERVABLE_PROTOCOL OBS_OBSERVABLE_PROTOCOL;
  34
  35 //
  36 // Interface Definitions
  37 //
  38
  39 /**
  40   Remove all observables.
  41
  42   Remove all observable guids and all interfaces subscribed to them.
  43
  44   @param   VOID          No Parameters.
  45
  46   @return  EFI_SUCCESS   Successfully removed all observables and subscribed interfaces.
  47
  48 **/
  49 typedef
  50 EFI_STATUS
  51 (EFIAPI *OBS_REMOVE_ALL_OBSERVABLES) (
  52   VOID
  53   );
  54
  55 /**
  56   Interface for notification functions.
  57
  58   Functions that are to be used as callbacks must inherit this interface in order to be used properly.
  59
  60   @param   VOID*   Data  Parameter context to be passed to the notification function.
  61
  62   @return  EFI_STATUS    Varies depending on implementation.
  63
  64 **/
  65 typedef
  66 EFI_STATUS
  67 (EFIAPI *OBS_CALLBACK) (
  68   IN  OUT VOID*   Data
  69   );
  70
  71 /**
  72   Subscribe an interface with an observable guid.
  73
  74   Use this to register a callback function with a guid. The function provided by CallbackInterface will be executed
  75   whenever the appropriate observable instance specified by ReferenceGuid calls Publish.
  76
  77   @param   EFI_GUID                ReferenceGuid       The observable guid that the callback interface will subscribe to.
  78            OBS_NOTIFY_INTERFACE    CallbackInterface   A pointer to the function that is subscribing to the observable.
  79
  80   @return  EFI_SUCCESS           Successfully subscribed the interface to the observable guid.
  81            EFI_NOT_FOUND         No match could be found between the provided guid and existing observables.
  82            EFI_OUT_OF_RESOURCES  Could not subscribe to this observer due to resource limitations.
  83            EFI_INVALID_PARAMETER Interface is already subscribed to this observer.
  84 **/
  85 typedef
  86 EFI_STATUS
  87 (EFIAPI *OBS_SUBSCRIBE) (
  88   IN      EFI_GUID        ReferenceGuid,
  89   IN      OBS_CALLBACK    CallbackInterface
  90   );
  91
  92 /**
  93   Unsubscribe an interface with an observable guid.
  94
  95   Use this to remove an interface from the callback list associated with an observable guid.
  96
  97   @param   EFI_GUID                ReferenceGuid   The observable guid to unsubscribe the interface from.
  98            OBS_NOTIFY_INTERFACE    NotifyCallback  A pointer to the interface that is being unsubscribed.
  99
 100   @return  EFI_SUCCESS           Successfully unsubscribed the interface from the observable guid.
 101
 102 **/
 103 typedef
 104 EFI_STATUS
 105 (EFIAPI *OBS_UNSUBSCRIBE) (
 106   IN      EFI_GUID        ReferenceGuid,
 107   IN      OBS_CALLBACK    CallbackInterface
 108   );
 109
 110 /**
 111   Notify observing functions.
 112
 113   Use this to notify all functions who are subscribed to the guid specified by ReferenceGuid.
 114
 115   @param   EFI_GUID          ReferenceGuid   The observable guid that contains the the list of interfaces to be notified.
 116            VOID*             Data            Parameter context to be passed to the notification function.
 117
 118   @return  EFI_SUCCESS       Successfully notified all observers listening to this guid.
 119            EFI_NOT_FOUND     No match could be found between the provided guid and existing observables.
 120
 121 **/
 122 typedef
 123 EFI_STATUS
 124 (EFIAPI *OBS_PUBLISH) (
 125   IN      EFI_GUID        ReferenceGuid,
 126   IN  OUT VOID*           Data
 127   );
 128
 129 /**
 130   Creates a new observable.
 131
 132   Create a new observable that can be observed with the use of Subscribe function.
 133
 134   @param   EFI_GUID              ReferenceGuid   The observable guid to add.
 135
 136   @return  EFI_SUCCESS           Successfully added observable.
 137            EFI_INVALID_PARAMETER Observable already exists.
 138
 139 **/
 140 typedef
 141 EFI_STATUS
 142 (EFIAPI *OBS_ADD_OBSERVABLE) (
 143   IN      EFI_GUID        ReferenceGuid
 144   );
 145
 146 /**
 147   Remove an observable.
 148
 149   Remove an observable so that it can no longer be subscribed to. In addition, unsubscribe any functions
 150   that are subscribed to this guid.
 151
 152   @param   EFI_GUID              ReferenceGuid   The observable guid to remove.
 153
 154   @return  EFI_SUCCESS           Successfully removed observable.
 155
 156 **/
 157 typedef
 158 EFI_STATUS
 159 (EFIAPI *OBS_REMOVE_OBSERVABLE) (
 160   IN      EFI_GUID        ReferenceGuid
 161   );
 162
 163 //
 164 // Protocol Definitions
 165 //
 166 typedef struct _OBS_LEAF {
 167   OBS_CALLBACK      Observer;
 168   struct _OBS_LEAF* Next;
 169 } OBS_LEAF;
 170
 171 typedef struct _OBS_TREE {
 172   EFI_GUID              ObservableGuid;
 173   OBS_LEAF*             Leaf;
 174   struct _OBS_TREE*     Next;
 175 } OBS_TREE;
 176
 177 struct _OBS_OBSERVABLE_PROTOCOL {
 178   OBS_ADD_OBSERVABLE          AddObservable;
 179   OBS_REMOVE_OBSERVABLE       RemoveObservable;
 180   OBS_SUBSCRIBE               Subscribe;
 181   OBS_UNSUBSCRIBE             Unsubscribe;
 182   OBS_PUBLISH                 Publish;
 183   OBS_REMOVE_ALL_OBSERVABLES  RemoveAllObservables;
 184 } ;
 185
 186 #endif