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