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 Module Name:
24 
25   Observable.h
26 
27 Abstract:
28 
29   Prototypes for Observable protocol implementation
30 --*/
31 
32 #ifndef _OBSERVABLE_H_
33 #define _OBSERVABLE_H_
34 #include "PlatformDxe.h"
35 #include "Protocol/Observable.h"
36 
37 //
38 // Prototypes
39 //
40 
41 /** Install observable protocol.
42  *
43  * Install interface and initialize the observable protocol.
44  *
45  * @param   VOID          No parameters.
46  *
47  * @return  EFI_SUCCESS   Successfully installed and initialized the protocol.
48  **/
49 EFI_STATUS
50 InitializeObservableProtocol(
51   VOID
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 EFI_STATUS
63 EFIAPI
64 RemoveAllObservables(
65   VOID
66   );
67 
68 /** Subscribe an interface with an observable guid.
69  *
70  * Use this to register a callback function with a guid. The function provided by CallbackInterface will be executed
71  * whenever the appropriate observable instance specified by ReferenceGuid calls Publish.
72  *
73  * @param   EFI_GUID              ReferenceGuid       The observable guid that the callback interface will subscribe to.
74  *          OBS_CALLBACK          CallbackInterface   A pointer to the function that is subscribing to the observable.
75  *
76  * @return  EFI_SUCCESS           Successfully subscribed the interface to the observable guid.
77  *          EFI_NOT_FOUND         No match could be found between the provided guid and existing observables.
78  *          EFI_OUT_OF_RESOURCES  Could not subscribe to this observer due to resource limitations.
79  *          EFI_INVALID_PARAMETER Interface is already subscribed to this observer.
80  **/
81 EFI_STATUS
82 EFIAPI
83 Subscribe (
84   IN      EFI_GUID        ReferenceGuid,
85   IN      OBS_CALLBACK    CallbackInterface
86   );
87 
88 /** Unsubscribe an interface with an observable guid.
89  *
90  * Use this to remove an interface from the callback list associated with an observable guid.
91  *
92  * @param   EFI_GUID              ReferenceGuid      The observable guid to unsubscribe the interface from.
93  *          OBS_CALLBACK          CallbackInterface  A pointer to the interface that is being unsubscribed.
94  *
95  * @return  EFI_SUCCESS           Successfully unsubscribed the interface from the observable guid.
96  **/
97 EFI_STATUS
98 EFIAPI
99 Unsubscribe (
100   IN      EFI_GUID            ReferenceGuid,
101   IN      OBS_CALLBACK    CallbackInterface
102   );
103 
104 /** Notify observing functions.
105  *
106  * Use this to notify all functions who are subscribed to the guid specified by ReferenceGuid.
107  *
108  * @param   EFI_GUID          ReferenceGuid   The observable guid that contains the list of interfaces to be notified.
109  *          VOID*             Data            Parameter context to be passed to the subscribed function.
110  *
111  * @return  EFI_SUCCESS       Successfully notified all observers listening to this guid.
112  *          EFI_NOT_FOUND     No match could be found between the provided guid and existing observables.
113  **/
114 EFI_STATUS
115 EFIAPI
116 Publish (
117   IN      EFI_GUID        ReferenceGuid,
118   IN  OUT VOID*           Data
119   );
120 
121 /** Creates a new observable.
122  *
123  * Create a new observable that can be observed with the use of Subscribe function.
124  *
125  * @param   EFI_GUID              ReferenceGuid   The observable guid to add.
126  *
127  * @return  EFI_SUCCESS           Successfully added observable.
128  *          EFI_INVALID_PARAMETER Observable already exists.
129  **/
130 EFI_STATUS
131 EFIAPI
132 AddObservable (
133   IN      EFI_GUID        ReferenceGuid
134   );
135 
136 /** Remove an observable.
137  *
138  * Remove an observable so that it can no longer be subscribed to. In addition, unsubscribe any functions
139  * that are subscribed to this guid.
140  *
141  * @param   EFI_GUID              ReferenceGuid   The observable guid to remove.
142  *
143  * @return  EFI_SUCCESS           Successfully removed observable.
144  **/
145 EFI_STATUS
146 EFIAPI
147 RemoveObservable (
148   IN      EFI_GUID        ReferenceGuid
149   );
150 
151 #endif
152