Vlv2TbltDevicePkg/Include/Protocol/Observable.h

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