Vlv2TbltDevicePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / Vlv2TbltDevicePkg / Include / Protocol / Observable.h

/*++\r
\r
  Copyright (c) 2004  - 2014, Intel Corporation. All rights reserved.<BR>\r
                                                                                   \r\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
                                                                                   \r\r
\r
\r
Module Name:\r
\r
  Observable.h\r
\r
Abstract:\r
\r
  Interface and GUID definitions for Observable protocol.\r
\r
**/\r
\r
#ifndef _OBSERVABLE_PROTOCOL_H_\r
#define _OBSERVABLE_PROTOCOL_H_\r
\r
//\r
// GUID Definitions\r
//\r
#define OBSERVABLE_PROTOCOL_GUID \\r
  { \\r
    0xe227c522, 0xd5fe, 0x4a53, 0x87, 0xb1, 0x0f, 0xbe, 0x57, 0x0f, 0x98, 0xe9 \\r
  }\r
\r
extern EFI_GUID gObservableProtocolGuid;\r
\r
typedef struct _OBS_OBSERVABLE_PROTOCOL OBS_OBSERVABLE_PROTOCOL;\r
\r
//\r
// Interface Definitions\r
//\r
\r
/**\r
  Remove all observables.\r
\r
  Remove all observable guids and all interfaces subscribed to them.\r
\r
  @param   VOID          No Parameters.\r
\r
  @return  EFI_SUCCESS   Successfully removed all observables and subscribed interfaces.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *OBS_REMOVE_ALL_OBSERVABLES) (\r
  VOID\r
  );\r
\r
/**\r
  Interface for notification functions.\r
\r
  Functions that are to be used as callbacks must inherit this interface in order to be used properly.\r
\r
  @param   VOID*   Data  Parameter context to be passed to the notification function.\r
\r
  @return  EFI_STATUS    Varies depending on implementation.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *OBS_CALLBACK) (\r
  IN  OUT VOID*   Data\r
  );\r
\r
/**\r
  Subscribe an interface with an observable guid.\r
\r
  Use this to register a callback function with a guid. The function provided by CallbackInterface will be executed\r
  whenever the appropriate observable instance specified by ReferenceGuid calls Publish.\r
\r
  @param   EFI_GUID                ReferenceGuid       The observable guid that the callback interface will subscribe to.\r
           OBS_NOTIFY_INTERFACE    CallbackInterface   A pointer to the function that is subscribing to the observable.\r
\r
  @return  EFI_SUCCESS           Successfully subscribed the interface to the observable guid.\r
           EFI_NOT_FOUND         No match could be found between the provided guid and existing observables.\r
           EFI_OUT_OF_RESOURCES  Could not subscribe to this observer due to resource limitations.\r
           EFI_INVALID_PARAMETER Interface is already subscribed to this observer.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *OBS_SUBSCRIBE) (\r
  IN      EFI_GUID        ReferenceGuid,\r
  IN      OBS_CALLBACK    CallbackInterface\r
  );\r
\r
/**\r
  Unsubscribe an interface with an observable guid.\r
\r
  Use this to remove an interface from the callback list associated with an observable guid.\r
\r
  @param   EFI_GUID                ReferenceGuid   The observable guid to unsubscribe the interface from.\r
           OBS_NOTIFY_INTERFACE    NotifyCallback  A pointer to the interface that is being unsubscribed.\r
\r
  @return  EFI_SUCCESS           Successfully unsubscribed the interface from the observable guid.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *OBS_UNSUBSCRIBE) (\r
  IN      EFI_GUID        ReferenceGuid,\r
  IN      OBS_CALLBACK    CallbackInterface\r
  );\r
\r
/**\r
  Notify observing functions.\r
\r
  Use this to notify all functions who are subscribed to the guid specified by ReferenceGuid.\r
\r
  @param   EFI_GUID          ReferenceGuid   The observable guid that contains the the list of interfaces to be notified.\r
           VOID*             Data            Parameter context to be passed to the notification function.\r
\r
  @return  EFI_SUCCESS       Successfully notified all observers listening to this guid.\r
           EFI_NOT_FOUND     No match could be found between the provided guid and existing observables.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *OBS_PUBLISH) (\r
  IN      EFI_GUID        ReferenceGuid,\r
  IN  OUT VOID*           Data\r
  );\r
\r
/**\r
  Creates a new observable.\r
\r
  Create a new observable that can be observed with the use of Subscribe function.\r
\r
  @param   EFI_GUID              ReferenceGuid   The observable guid to add.\r
\r
  @return  EFI_SUCCESS           Successfully added observable.\r
           EFI_INVALID_PARAMETER Observable already exists.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *OBS_ADD_OBSERVABLE) (\r
  IN      EFI_GUID        ReferenceGuid\r
  );\r
\r
/**\r
  Remove an observable.\r
\r
  Remove an observable so that it can no longer be subscribed to. In addition, unsubscribe any functions\r
  that are subscribed to this guid.\r
\r
  @param   EFI_GUID              ReferenceGuid   The observable guid to remove.\r
\r
  @return  EFI_SUCCESS           Successfully removed observable.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *OBS_REMOVE_OBSERVABLE) (\r
  IN      EFI_GUID        ReferenceGuid\r
  );\r
\r
//\r
// Protocol Definitions\r
//\r
typedef struct _OBS_LEAF {\r
  OBS_CALLBACK      Observer;\r
  struct _OBS_LEAF* Next;\r
} OBS_LEAF;\r
\r
typedef struct _OBS_TREE {\r
  EFI_GUID              ObservableGuid;\r
  OBS_LEAF*             Leaf;\r
  struct _OBS_TREE*     Next;\r
} OBS_TREE;\r
\r
struct _OBS_OBSERVABLE_PROTOCOL {\r
  OBS_ADD_OBSERVABLE          AddObservable;\r
  OBS_REMOVE_OBSERVABLE       RemoveObservable;\r
  OBS_SUBSCRIBE               Subscribe;\r
  OBS_UNSUBSCRIBE             Unsubscribe;\r
  OBS_PUBLISH                 Publish;\r
  OBS_REMOVE_ALL_OBSERVABLES  RemoveAllObservables;\r
} ;\r
\r
#endif\r