EdkCompatibilityPkg/Foundation/Efi/Protocol/HiiDatabase/HiiDatabase.h

   1 /*++
   2
   3 Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR>
   4 This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13
  14     HiiDatabase.h
  15
  16 Abstract:
  17
  18     EFI_HII_DATABASE_PROTOCOL from UEFI 2.1 specification.
  19
  20     This protocol is a database manager for HII related data structures.
  21
  22 Revision History
  23
  24 --*/
  25
  26 #ifndef __EFI_HII_DATABASE_PROTOCOL_H__
  27 #define __EFI_HII_DATABASE_PROTOCOL_H__
  28
  29 #include "EfiHii.h"
  30
  31 //
  32 // Global ID for the Hii Database Protocol.
  33 //
  34
  35 #define EFI_HII_DATABASE_PROTOCOL_GUID \
  36   { \
  37     0xef9fc172, 0xa1b2, 0x4693, {0xb3, 0x27, 0x6d, 0x32, 0xfc, 0x41, 0x60, 0x42} \
  38   }
  39
  40 #define EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID \
  41   { \
  42     0x14982a4f, 0xb0ed, 0x45b8, {0xa8, 0x11, 0x5a, 0x7a, 0x9b, 0xc2, 0x32, 0xdf} \
  43   }
  44
  45 EFI_FORWARD_DECLARATION (EFI_HII_DATABASE_PROTOCOL);
  46
  47 typedef UINTN EFI_HII_DATABASE_NOTIFY_TYPE;
  48
  49 #define EFI_HII_DATABASE_NOTIFY_NEW_PACK     0x00000001
  50 #define EFI_HII_DATABASE_NOTIFY_REMOVE_PACK  0x00000002
  51 #define EFI_HII_DATABASE_NOTIFY_EXPORT_PACK  0x00000004
  52 #define EFI_HII_DATABASE_NOTIFY_ADD_PACK     0x00000008
  53
  54 typedef
  55 EFI_STATUS
  56 (EFIAPI *EFI_HII_DATABASE_NOTIFY) (
  57   IN UINT8                              PackageType,
  58   IN CONST EFI_GUID                     *PackageGuid,
  59   IN CONST EFI_HII_PACKAGE_HEADER       *Package,
  60   IN EFI_HII_HANDLE                     Handle,
  61   IN EFI_HII_DATABASE_NOTIFY_TYPE       NotifyType
  62   )
  63 /*++
  64
  65   Routine Description:
  66     Functions which are registered to receive notification of database events have this prototype. The
  67     actual event is encoded in NotifyType. The following table describes how PackageType,
  68     PackageGuid, Handle, and Package are used for each of the notification types.
  69
  70   Arguments:
  71     PackageType       - Package type of the notification.
  72     PackageGuid       - If PackageType is EFI_HII_PACKAGE_TYPE_GUID, then this is the pointer to
  73                         the GUID which must match the Guid field of
  74                         EFI_HII_GUID_PACKAGE_GUID_HDR. Otherwise, it must be NULL.
  75     Package           - Points to the package referred to by the notification.
  76     Handle            - The handle of the package list which contains the specified package.
  77     NotifyType        - The type of change concerning the database.
  78
  79   Returns:
  80     EFI status code.
  81
  82 --*/
  83 ;
  84
  85 //
  86 // EFI_HII_DATABASE_PROTOCOL protocol prototypes
  87 //
  88
  89 typedef
  90 EFI_STATUS
  91 (EFIAPI *EFI_HII_DATABASE_NEW_PACK) (
  92   IN CONST EFI_HII_DATABASE_PROTOCOL    *This,
  93   IN CONST EFI_HII_PACKAGE_LIST_HEADER  *PackageList,
  94   IN CONST EFI_HANDLE                   DriverHandle,
  95   OUT EFI_HII_HANDLE                    *Handle
  96   )
  97 /*++
  98
  99   Routine Description:
 100     This function adds the packages in the package list to the database and returns a handle. If there is a
 101     EFI_DEVICE_PATH_PROTOCOL associated with the DriverHandle, then this function will
 102     create a package of type EFI_PACKAGE_TYPE_DEVICE_PATH and add it to the package list.
 103
 104   Arguments:
 105     This              - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 106     PackageList       - A pointer to an EFI_HII_PACKAGE_LIST_HEADER structure.
 107     DriverHandle      - Associate the package list with this EFI handle.
 108     Handle            - A pointer to the EFI_HII_HANDLE instance.
 109
 110   Returns:
 111     EFI_SUCCESS            - The package list associated with the Handle
 112                              was added to the HII database.
 113     EFI_OUT_OF_RESOURCES   - Unable to allocate necessary resources for the
 114                              new database contents.
 115     EFI_INVALID_PARAMETER  - PackageList is NULL or Handle is NULL.
 116
 117 --*/
 118 ;
 119
 120 typedef
 121 EFI_STATUS
 122 (EFIAPI *EFI_HII_DATABASE_REMOVE_PACK) (
 123   IN CONST EFI_HII_DATABASE_PROTOCOL    *This,
 124   IN EFI_HII_HANDLE                     Handle
 125   )
 126 /*++
 127
 128   Routine Description:
 129     This function removes the package list that is associated with a handle Handle
 130     from the HII database. Before removing the package, any registered functions
 131     with the notification type REMOVE_PACK and the same package type will be called.
 132
 133   Arguments:
 134     This              - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 135     Handle            - The handle that was registered to the data that is requested
 136                         for removal.
 137
 138   Returns:
 139     EFI_SUCCESS            - The data associated with the Handle was removed from
 140                              the HII database.
 141     EFI_NOT_FOUND          - The specified Handle is not in database.
 142
 143 --*/
 144 ;
 145
 146 typedef
 147 EFI_STATUS
 148 (EFIAPI *EFI_HII_DATABASE_UPDATE_PACK) (
 149   IN CONST EFI_HII_DATABASE_PROTOCOL    *This,
 150   IN EFI_HII_HANDLE                     Handle,
 151   IN CONST EFI_HII_PACKAGE_LIST_HEADER  *PackageList
 152   )
 153 /*++
 154
 155   Routine Description:
 156     This function updates the existing package list (which has the specified Handle)
 157     in the HII databases, using the new package list specified by PackageList.
 158
 159   Arguments:
 160     This              - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 161     Handle            - The handle that was registered to the data that is
 162                         requested to be updated.
 163     PackageList       - A pointer to an EFI_HII_PACKAGE_LIST_HEADER package.
 164
 165   Returns:
 166     EFI_SUCCESS            - The HII database was successfully updated.
 167     EFI_OUT_OF_RESOURCES   - Unable to allocate enough memory for the updated database.
 168     EFI_INVALID_PARAMETER  - PackageList was NULL.
 169     EFI_NOT_FOUND          - The specified Handle is not in database.
 170
 171 --*/
 172 ;
 173
 174 typedef
 175 EFI_STATUS
 176 (EFIAPI *EFI_HII_DATABASE_LIST_PACKS) (
 177   IN  CONST EFI_HII_DATABASE_PROTOCOL   *This,
 178   IN  UINT8                             PackageType,
 179   IN  CONST EFI_GUID                    *PackageGuid,
 180   IN  OUT UINTN                         *HandleBufferLength,
 181   OUT EFI_HII_HANDLE                    *Handle
 182   )
 183 /*++
 184
 185   Routine Description:
 186     This function returns a list of the package handles of the specified type
 187     that are currently active in the database. The pseudo-type
 188     EFI_HII_PACKAGE_TYPE_ALL will cause all package handles to be listed.
 189
 190   Arguments:
 191     This               - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 192     PackageType        - Specifies the package type of the packages to list or
 193                          EFI_HII_PACKAGE_TYPE_ALL for all packages to be listed.
 194     PackageGuid        - If PackageType is EFI_HII_PACKAGE_TYPE_GUID, then this
 195                          is the pointer to the GUID which must match the Guid
 196                          field of EFI_HII_GUID_PACKAGE_GUID_HDR. Otherwise,
 197                          it must be NULL.
 198     HandleBufferLength - On input, a pointer to the length of the handle buffer.
 199                          On output, the length of the handle buffer that is
 200                          required for the handles found.
 201     Handle             - An array of EFI_HII_HANDLE instances returned.
 202
 203   Returns:
 204     EFI_SUCCESS            - The matching handles are outputted successfully.
 205                              HandleBufferLength is updated with the actual length.
 206     EFI_BUFFER_TO_SMALL    - The HandleBufferLength parameter indicates that
 207                              Handle is too small to support the number of handles.
 208                              HandleBufferLength is updated with a value that will
 209                              enable the data to fit.
 210     EFI_NOT_FOUND          - No matching handle could not be found in database.
 211     EFI_INVALID_PARAMETER  - Handle or HandleBufferLength was NULL.
 212     EFI_INVALID_PARAMETER  - PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but
 213                              PackageGuid is not NULL, PackageType is a EFI_HII_
 214                              PACKAGE_TYPE_GUID but PackageGuid is NULL.
 215
 216 --*/
 217 ;
 218
 219 typedef
 220 EFI_STATUS
 221 (EFIAPI *EFI_HII_DATABASE_EXPORT_PACKS) (
 222   IN  CONST EFI_HII_DATABASE_PROTOCOL   *This,
 223   IN  EFI_HII_HANDLE                    Handle,
 224   IN  OUT UINTN                         *BufferSize,
 225   OUT EFI_HII_PACKAGE_LIST_HEADER       *Buffer
 226   )
 227 /*++
 228
 229   Routine Description:
 230     This function will export one or all package lists in the database to a buffer.
 231     For each package list exported, this function will call functions registered
 232     with EXPORT_PACK and then copy the package list to the buffer.
 233
 234   Arguments:
 235     This               - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 236     Handle             - An EFI_HII_HANDLE that corresponds to the desired package
 237                          list in the HII database to export or NULL to indicate
 238                          all package lists should be exported.
 239     BufferSize         - On input, a pointer to the length of the buffer.
 240                          On output, the length of the buffer that is required for
 241                          the exported data.
 242     Buffer             - A pointer to a buffer that will contain the results of
 243                          the export function.
 244
 245   Returns:
 246     EFI_SUCCESS            - Package exported.
 247     EFI_BUFFER_TO_SMALL    - The HandleBufferLength parameter indicates that Handle
 248                              is too small to support the number of handles.
 249                              HandleBufferLength is updated with a value that will
 250                              enable the data to fit.
 251     EFI_NOT_FOUND          - The specified Handle could not be found in the current
 252                              database.
 253     EFI_INVALID_PARAMETER  - Handle or Buffer or BufferSize was NULL.
 254
 255 --*/
 256 ;
 257
 258 typedef
 259 EFI_STATUS
 260 (EFIAPI *EFI_HII_DATABASE_REGISTER_NOTIFY) (
 261   IN  CONST EFI_HII_DATABASE_PROTOCOL   *This,
 262   IN  UINT8                             PackageType,
 263   IN  CONST EFI_GUID                    *PackageGuid,
 264   IN  CONST EFI_HII_DATABASE_NOTIFY     PackageNotifyFn,
 265   IN  EFI_HII_DATABASE_NOTIFY_TYPE      NotifyType,
 266   OUT EFI_HANDLE                        *NotifyHandle
 267   )
 268 /*++
 269
 270   Routine Description:
 271     This function registers a function which will be called when specified actions related to packages of
 272     the specified type occur in the HII database. By registering a function, other HII-related drivers are
 273     notified when specific package types are added, removed or updated in the HII database.
 274     Each driver or application which registers a notification should use
 275     EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() before exiting.
 276
 277   Arguments:
 278     This               - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 279     PackageType        - Specifies the package type of the packages to list or
 280                          EFI_HII_PACKAGE_TYPE_ALL for all packages to be listed.
 281     PackageGuid        - If PackageType is EFI_HII_PACKAGE_TYPE_GUID, then this is the pointer to
 282                          the GUID which must match the Guid field of
 283                          EFI_HII_GUID_PACKAGE_GUID_HDR. Otherwise, it must be NULL.
 284     PackageNotifyFn    - Points to the function to be called when the event specified by
 285                          NotificationType occurs.
 286     NotifyType         - Describes the types of notification which this function will be receiving.
 287     NotifyHandle       - Points to the unique handle assigned to the registered notification. Can be used in
 288                          EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() to stop notifications.
 289
 290   Returns:
 291     EFI_SUCCESS            - Notification registered successfully.
 292     EFI_OUT_OF_RESOURCES   - Unable to allocate necessary data structures
 293     EFI_INVALID_PARAMETER  - NotifyHandle is NULL.
 294     EFI_INVALID_PARAMETER  - PackageGuid is not NULL when PackageType is not
 295                              EFI_HII_PACKAGE_TYPE_GUID.
 296     EFI_INVALID_PARAMETER  - PackageGuid is NULL when PackageType is EFI_HII_PACKAGE_TYPE_GUID.
 297
 298 --*/
 299 ;
 300
 301 typedef
 302 EFI_STATUS
 303 (EFIAPI *EFI_HII_DATABASE_UNREGISTER_NOTIFY) (
 304   IN CONST EFI_HII_DATABASE_PROTOCOL    *This,
 305   IN EFI_HANDLE                         NotificationHandle
 306   )
 307 /*++
 308
 309   Routine Description:
 310     Removes the specified HII database package-related notification.
 311
 312   Arguments:
 313     This               - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 314     NotifyHandle       - The handle of the notification function being unregistered.
 315
 316   Returns:
 317     EFI_SUCCESS            - Notification is unregistered successfully.
 318     EFI_NOT_FOUND          - The incoming notification handle does not exist
 319                              in current hii database.
 320
 321 --*/
 322 ;
 323
 324 typedef
 325 EFI_STATUS
 326 (EFIAPI *EFI_HII_FIND_KEYBOARD_LAYOUTS) (
 327   IN  EFI_HII_DATABASE_PROTOCOL         *This,
 328   IN  OUT UINT16                        *KeyGuidBufferLength,
 329   OUT EFI_GUID                          *KeyGuidBuffer
 330   )
 331 /*++
 332
 333   Routine Description:
 334     This routine retrieves an array of GUID values for each keyboard layout that
 335     was previously registered in the system.
 336
 337   Arguments:
 338     This                - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 339     KeyGuidBufferLength - On input, a pointer to the length of the keyboard GUID
 340                           buffer. On output, the length of the handle buffer
 341                           that is required for the handles found.
 342     KeyGuidBuffer       - An array of keyboard layout GUID instances returned.
 343
 344   Returns:
 345     EFI_SUCCESS            - KeyGuidBuffer was updated successfully.
 346     EFI_BUFFER_TOO_SMALL   - The KeyGuidBufferLength parameter indicates
 347                              that KeyGuidBuffer is too small to support the
 348                              number of GUIDs. KeyGuidBufferLength is
 349                              updated with a value that will enable the data to fit.
 350     EFI_INVALID_PARAMETER  - The KeyGuidBuffer or KeyGuidBufferLength was NULL.
 351     EFI_NOT_FOUND          - There was no keyboard layout.
 352
 353 --*/
 354 ;
 355
 356 typedef
 357 EFI_STATUS
 358 (EFIAPI *EFI_HII_GET_KEYBOARD_LAYOUT) (
 359   IN  EFI_HII_DATABASE_PROTOCOL         *This,
 360   IN  EFI_GUID                          *KeyGuid,
 361   IN OUT UINT16                         *KeyboardLayoutLength,
 362   OUT EFI_HII_KEYBOARD_LAYOUT           *KeyboardLayout
 363   )
 364 /*++
 365
 366   Routine Description:
 367     This routine retrieves the requested keyboard layout. The layout is a physical description of the keys
 368     on a keyboard and the character(s) that are associated with a particular set of key strokes.
 369
 370   Arguments:
 371     This                 - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 372     KeyGuid              - A pointer to the unique ID associated with a given keyboard layout. If KeyGuid is
 373                            NULL then the current layout will be retrieved.
 374     KeyboardLayoutLength - On input, a pointer to the length of the KeyboardLayout buffer.
 375                            On output, the length of the data placed into KeyboardLayout.
 376     KeyboardLayout       - A pointer to a buffer containing the retrieved keyboard layout.
 377
 378   Returns:
 379     EFI_SUCCESS            - The keyboard layout was retrieved successfully.
 380     EFI_NOT_FOUND          - The requested keyboard layout was not found.
 381     EFI_INVALID_PARAMETER  - The KeyboardLayout or KeyboardLayoutLength was NULL.
 382
 383 --*/
 384 ;
 385
 386 typedef
 387 EFI_STATUS
 388 (EFIAPI *EFI_HII_SET_KEYBOARD_LAYOUT) (
 389   IN EFI_HII_DATABASE_PROTOCOL          *This,
 390   IN EFI_GUID                           *KeyGuid
 391   )
 392 /*++
 393
 394   Routine Description:
 395     This routine sets the default keyboard layout to the one referenced by KeyGuid. When this routine
 396     is called, an event will be signaled of the EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID
 397     group type. This is so that agents which are sensitive to the current keyboard layout being changed
 398     can be notified of this change.
 399
 400   Arguments:
 401     This                - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 402     KeyGuid             - A pointer to the unique ID associated with a given keyboard layout.
 403
 404   Returns:
 405     EFI_SUCCESS            - The current keyboard layout was successfully set.
 406     EFI_NOT_FOUND          - The referenced keyboard layout was not found, so action was taken.
 407     EFI_INVALID_PARAMETER  - The KeyGuid was NULL.
 408
 409 --*/
 410 ;
 411
 412 typedef
 413 EFI_STATUS
 414 (EFIAPI *EFI_HII_DATABASE_GET_PACK_HANDLE) (
 415   IN  EFI_HII_DATABASE_PROTOCOL         *This,
 416   IN  EFI_HII_HANDLE                    PackageListHandle,
 417   OUT EFI_HANDLE                        *DriverHandle
 418   )
 419 /*++
 420
 421   Routine Description:
 422     Return the EFI handle associated with a package list.
 423
 424   Arguments:
 425     This                - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 426     PackageListHandle   - An EFI_HII_HANDLE that corresponds to the desired package list in the
 427                           HIIdatabase.
 428     DriverHandle        - On return, contains the EFI_HANDLE which was registered with the package list in
 429                           NewPackageList().
 430
 431   Returns:
 432     EFI_SUCCESS            - The DriverHandle was returned successfully.
 433     EFI_INVALID_PARAMETER  - The PackageListHandle was not valid or DriverHandle was NULL.
 434
 435 --*/
 436 ;
 437
 438 struct _EFI_HII_DATABASE_PROTOCOL {
 439   EFI_HII_DATABASE_NEW_PACK             NewPackageList;
 440   EFI_HII_DATABASE_REMOVE_PACK          RemovePackageList;
 441   EFI_HII_DATABASE_UPDATE_PACK          UpdatePackageList;
 442   EFI_HII_DATABASE_LIST_PACKS           ListPackageLists;
 443   EFI_HII_DATABASE_EXPORT_PACKS         ExportPackageLists;
 444   EFI_HII_DATABASE_REGISTER_NOTIFY      RegisterPackageNotify;
 445   EFI_HII_DATABASE_UNREGISTER_NOTIFY    UnregisterPackageNotify;
 446   EFI_HII_FIND_KEYBOARD_LAYOUTS         FindKeyboardLayouts;
 447   EFI_HII_GET_KEYBOARD_LAYOUT           GetKeyboardLayout;
 448   EFI_HII_SET_KEYBOARD_LAYOUT           SetKeyboardLayout;
 449   EFI_HII_DATABASE_GET_PACK_HANDLE      GetPackageListHandle;
 450 };
 451
 452 extern EFI_GUID gEfiHiiDatabaseProtocolGuid;
 453
 454 #endif