2 This file contains 'Framework Code' and is licensed as such
3 under the terms of your license agreement with Intel or your
4 vendor. This file may not be modified, except as allowed by
5 additional terms of your license agreement.
9 Copyright (c) 2010 - 2014, Intel Corporation. All rights reserved
11 This program and the accompanying materials are licensed and made available under
12 the terms and conditions of the BSD License that accompanies this distribution.
13 The full text of the license may be found at
14 http://opensource.org/licenses/bsd-license.php.
16 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
17 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
27 The following contains all of the implementation for the Observable protocol. The
28 protocol uses the observer design pattern to provide a way to publish events and
29 to subscribe to those events so that a callback will be performed at the time of
30 the event. The observables and subscribers are maintained by the static tree,
31 mObservableDb. The difference between this protocol and the existing event protocol
32 that exists within the EFI framework is that this protocol allows for parameters
33 to be passed to the subscribed callbacks that can contain up to date context.
37 #include "Observable.h"
39 static OBS_TREE
* mObservableDb
= NULL
;
40 static EFI_HANDLE mObservableHandle
= NULL
;
41 static OBS_OBSERVABLE_PROTOCOL mObservable
= {
50 /** Install observable protocol.
52 * Install interface and initialize the observable protocol.
54 * @param VOID No parameters.
56 * @return EFI_SUCCESS Successfully installed and initialized the protocol.
59 InitializeObservableProtocol(
68 Status
= gBS
->InstallProtocolInterface (
70 &gObservableProtocolGuid
,
78 /** Deletes a subscriber
80 * This function removes the subscriber pointed to by Head.
82 * @param OBS_TREE* Head Points to the current subscriber.
84 * @return OBS_TREE* Returns the tree after successfully removing the subscriber.
102 /** Finds and deletes all subscribers
104 * This function iterates recursively through the existing subscribers and delets them all.
106 * @param OBS_TREE* Head Points to the current subscriber.
108 * @return OBS_TREE* Returns the tree after successfully removing the subscribers.
111 DeleteAllSubscribers(
118 // We aren't at the end of the list yet.
120 Head
->Next
= DeleteAllSubscribers(Head
->Next
);
124 // At the end, so delete the subscriber.
126 Head
= DeleteSubscriber(Head
);
132 /** Deletes an observable
134 * This function removes the observable pointed to by Head.
136 * @param OBS_TREE* Head Points to the current observable.
138 * @return OBS_TREE* Returns the tree after successfully removing the observable.
156 /** Finds and deletes all observables
158 * This function iterates recursively through the existing observables database and, starting with
159 * the last most observable, deletes all of its subscribers, then deletes the observable itself.
161 * @param OBS_TREE* Head Points to the current observable.
163 * @return OBS_TREE* Returns the tree after successfully removing the observables.
166 DeleteAllObservables(
173 // We aren't at the end of the list yet.
175 Head
->Next
= DeleteAllObservables(Head
->Next
);
179 // This is the end of the list of observables.
181 Head
->Leaf
= DeleteAllSubscribers(Head
->Leaf
);
184 // Subscribers are deleted, so now delete the observable.
186 Head
= DeleteObservable(Head
);
192 /** Finds and deletes observable
194 * This function iterates recursively through the existing observable database in order to find the one
195 * specified by ReferenceGuid so that it can be deleted. If the requested observable is found, before it
196 * is deleted, all of the subscribers that are listening to this observable are deleted.
198 * @param OBS_TREE* Head Points to the current observable.
199 * EFI_GUID ReferenceGuid Corresponds to the observable that we're looking for.
201 * @return OBS_TREE* Returns the tree after successfully removing (or not finding) the observable.
204 FindAndDeleteObservable(
206 EFI_GUID ReferenceGuid
210 if (CompareMem(&(Head
->ObservableGuid
), &ReferenceGuid
, sizeof(ReferenceGuid
)) == 0) {
212 // We found the observable. Delete all of it's subscribers, first.
214 Head
->Leaf
= DeleteAllSubscribers(Head
->Leaf
);
216 // Now we can safely remove the observable.
218 Head
= DeleteObservable(Head
);
221 // Not found. Keep searching.
223 Head
->Next
= FindAndDeleteObservable(Head
->Next
, ReferenceGuid
);
230 /** Finds and deletes subscriber
232 * This function iterates recursively through the existing subscribers that are listening to the
233 * observable that was found when this function was called.
235 * @param OBS_TREE* Head Points to the current subscriber.
236 * OBS_CALLBACK CallbackInterface This is the subscriber that is requested be removed.
238 * @return OBS_TREE* Returns the tree after successfully removing (or not finding) the subscriber.
241 _FindAndDeleteSubscriber(
243 OBS_CALLBACK CallbackInterface
247 if (Head
->Observer
== CallbackInterface
) {
249 // Found it. Now let's delete it.
251 Head
= DeleteSubscriber(Head
);
254 // Not found. Keep searching.
256 Head
->Next
= _FindAndDeleteSubscriber(Head
->Next
, CallbackInterface
);
263 /** Finds and deletes subscriber
265 * This function iterates recursively through the existing observables database until it either finds
266 * a matching guid or reaches the end of the list. After finding a match, it calls a helper function,
267 * _FindAndDeleteSubscriber. At this point, all responsibility for finding and deleting the subscriber
268 * lies on the helper function.
270 * @param OBS_TREE* Head Points to the current observable.
271 * EFI_GUID ReferenceGuid Corresponds to the observable that we're looking for.
272 * OBS_CALLBACK CallbackInterface This is the subscriber that is requested be removed.
274 * @return OBS_TREE* Returns the tree after successfully removing (or not finding) the subscriber.
277 FindAndDeleteSubscriber(
278 IN OUT OBS_TREE
* Head
,
279 IN EFI_GUID ReferenceGuid
,
280 IN OBS_CALLBACK CallbackInterface
284 if (CompareMem(&(Head
->ObservableGuid
), &ReferenceGuid
, sizeof(ReferenceGuid
)) == 0) {
286 // We found the observer that matches ReferenceGuid. Find and delete the subscriber that is
289 Head
->Leaf
= _FindAndDeleteSubscriber(Head
->Leaf
, CallbackInterface
);
292 // Not found. Keep searching.
294 Head
->Next
= FindAndDeleteSubscriber(Head
->Next
, ReferenceGuid
, CallbackInterface
);
301 /** Remove all observables.
303 * Remove all observable guids and all interfaces subscribed to them.
305 * @param VOID No parameters.
307 * @return EFI_SUCCESS Successfully removed all observables and subscribed interfaces.
311 RemoveAllObservables(
315 mObservableDb
= DeleteAllObservables(mObservableDb
);
320 /** Subscribe an interface with an observable guid.
322 * Use this to register a callback function with a guid. The function provided by CallbackInterface will be executed
323 * whenever the appropriate observable instance specified by ReferenceGuid calls Publish.
325 * @param EFI_GUID ReferenceGuid The observable guid that the callback interface will subscribe to.
326 * OBS_CASLLBACK CallbackInterface A pointer to the function that is subscribing to the observable.
328 * @return EFI_SUCCESS Successfully subscribed the interface to the observable guid.
329 * EFI_NOT_FOUND No match could be found between the provided guid and existing observables.
330 * EFI_OUT_OF_RESOURCES Could not subscribe to this observer due to resource limitations.
331 * EFI_INVALID_PARAMETER Interface is already subscribed to this observer.
336 IN EFI_GUID ReferenceGuid
,
337 IN OBS_CALLBACK CallbackInterface
340 EFI_STATUS Status
= EFI_SUCCESS
;
341 OBS_TREE
* TempTree
= NULL
;
342 OBS_LEAF
* Last
= NULL
;
343 OBS_LEAF
* TempLeaf
= NULL
;
344 OBS_LEAF
* NewLeaf
= NULL
;
345 BOOLEAN Found
= FALSE
;
347 if (mObservableDb
!= NULL
) {
349 // Find the observable guid that we're looking for.
351 for (TempTree
= mObservableDb
; TempTree
!= NULL
; TempTree
= TempTree
->Next
) {
352 if (CompareMem(&(TempTree
->ObservableGuid
), &ReferenceGuid
, sizeof(ReferenceGuid
)) == 0) {
359 // Prepare to add a new leaf.
361 NewLeaf
= AllocateZeroPool(sizeof(OBS_LEAF
));
363 Status
= EFI_OUT_OF_RESOURCES
;
365 NewLeaf
->Next
= NULL
;
366 NewLeaf
->Observer
= CallbackInterface
;
368 // Go to the end of the list of observers.
370 if (TempTree
->Leaf
!= NULL
) {
372 // First check to see if this is a duplicate observer.
375 TempLeaf
= TempTree
->Leaf
;
378 if (TempLeaf
->Observer
== CallbackInterface
) {
380 // It is, so let's abort this process.
385 TempLeaf
= TempLeaf
->Next
;
386 } while (TempLeaf
!= NULL
);
390 // Check for duplicates.
393 gBS
->FreePool(NewLeaf
);
394 Status
= EFI_INVALID_PARAMETER
;
397 // At this point, TempLeaf->Next will be the end of the list.
399 TempLeaf
->Next
= NewLeaf
;
403 // There are no observers listening to this guid. Start a new list.
405 TempTree
->Leaf
= NewLeaf
;
409 Status
= EFI_NOT_FOUND
;
412 Status
= EFI_NOT_FOUND
;
418 /** Unsubscribe an interface with an observable guid.
420 * Use this to remove an interface from the callback list associated with an observable guid.
422 * @param EFI_GUID ReferenceGuid The observable guid to unsubscribe the interface from.
423 * OBS_NOTIFY_INTERFACE NotifyCallback A pointer to the interface that is being unsubscribed.
425 * @return EFI_SUCCESS Successfully unsubscribed the interface from the observable guid.
430 IN EFI_GUID ReferenceGuid
,
431 IN OBS_CALLBACK CallbackInterface
434 mObservableDb
= FindAndDeleteSubscriber(mObservableDb
, ReferenceGuid
, CallbackInterface
);
439 /** Notify observing functions.
441 * Use this to notify all functions who are subscribed to the guid specified by ReferenceGuid.
443 * @param EFI_GUID ReferenceGuid The observable guid that contains the the list of interfaces to be notified.
444 * VOID* Data Parameter context to be passed to the notification function.
446 * @return EFI_SUCCESS Successfully notified all observers listening to this guid.
447 * EFI_NOT_FOUND No match could be found between the provided guid and existing observables.
452 IN EFI_GUID ReferenceGuid
,
456 EFI_STATUS Status
= EFI_SUCCESS
;
457 OBS_TREE
* TempTree
= NULL
;
458 OBS_LEAF
* TempLeaf
= NULL
;
459 BOOLEAN Found
= FALSE
;
461 if (mObservableDb
!= NULL
) {
463 // Find the observable guid that we're looking for.
465 for (TempTree
= mObservableDb
; TempTree
!= NULL
; TempTree
= TempTree
->Next
) {
466 if (CompareMem(&(TempTree
->ObservableGuid
), &ReferenceGuid
, sizeof(ReferenceGuid
)) == 0) {
473 // Notify every listener by performing each provided callback.
475 for (TempLeaf
= TempTree
->Leaf
; TempLeaf
!= NULL
; TempLeaf
= TempLeaf
->Next
) {
476 if (TempLeaf
->Observer
!= NULL
) {
478 // Execute the callback.
480 TempLeaf
->Observer(Data
);
484 Status
= EFI_NOT_FOUND
;
487 Status
= EFI_NOT_FOUND
;
493 /** Creates a new observable.
495 * Create a new observable that can be observed with the use of Subscribe function.
497 * @param EFI_GUID ReferenceGuid The observable guid to add.
499 * @return EFI_SUCCESS Successfully added observable.
500 * EFI_INVALID_PARAMETER Observable already exists.
505 IN EFI_GUID ReferenceGuid
508 EFI_STATUS Status
= EFI_SUCCESS
;
509 OBS_TREE
* TempTree
= NULL
;
510 OBS_TREE
* Last
= NULL
;
511 OBS_TREE
* NewTree
= NULL
;
512 BOOLEAN Found
= FALSE
;
514 if (mObservableDb
!= NULL
) {
515 if (mObservableDb
->Next
!= NULL
) {
517 // Iterate to the end of the observable list while checking to see if we aren't creating a duplicate.
519 TempTree
= mObservableDb
->Next
;
522 if (CompareMem(&(TempTree
->ObservableGuid
), &ReferenceGuid
, sizeof(ReferenceGuid
)) == 0) {
526 TempTree
= TempTree
->Next
;
527 } while (TempTree
!= NULL
);
530 TempTree
= mObservableDb
;
534 // Duplicate, so reject the parameter.
536 Status
= EFI_INVALID_PARAMETER
;
539 // TempTree->Next is our target. Prepare to add a new tree link.
541 NewTree
= AllocateZeroPool(sizeof(OBS_TREE
));
543 NewTree
->Next
= NULL
;
544 NewTree
->Leaf
= NULL
;
545 CopyMem(&(NewTree
->ObservableGuid
), &ReferenceGuid
, sizeof(ReferenceGuid
));
546 TempTree
->Next
= NewTree
;
548 Status
= EFI_OUT_OF_RESOURCES
;
553 // mObservableDb has not been created yet. Let's do that.
555 NewTree
= AllocateZeroPool(sizeof(OBS_TREE
));
557 NewTree
->Next
= NULL
;
558 NewTree
->Leaf
= NULL
;
559 CopyMem(&(NewTree
->ObservableGuid
), &ReferenceGuid
, sizeof(ReferenceGuid
));
560 mObservableDb
= NewTree
;
562 Status
= EFI_OUT_OF_RESOURCES
;
569 /** Remove an observable.
571 * Remove an observable so that it can no longer be subscribed to. In addition, unsubscribe any functions
572 * that are subscribed to this guid.
574 * @param EFI_GUID ReferenceGuid The observable guid to remove.
576 * @return EFI_SUCCESS Successfully removed observable.
581 IN EFI_GUID ReferenceGuid
584 mObservableDb
= FindAndDeleteObservable(mObservableDb
, ReferenceGuid
);