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

   1 /*++
   2
   3 Copyright (c) 2007, 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 PackageList could not be found in database.
 142     EFI_INVALID_PARAMETER  - The Handle was not valid.
 143
 144 --*/
 145 ;
 146
 147 typedef
 148 EFI_STATUS
 149 (EFIAPI *EFI_HII_DATABASE_UPDATE_PACK) (
 150   IN CONST EFI_HII_DATABASE_PROTOCOL    *This,
 151   IN EFI_HII_HANDLE                     Handle,
 152   IN CONST EFI_HII_PACKAGE_LIST_HEADER  *PackageList
 153   )
 154 /*++
 155
 156   Routine Description:
 157     This function updates the existing package list (which has the specified Handle)
 158     in the HII databases, using the new package list specified by PackageList.
 159
 160   Arguments:
 161     This              - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 162     Handle            - The handle that was registered to the data that is
 163                         requested to be updated.
 164     PackageList       - A pointer to an EFI_HII_PACKAGE_LIST_HEADER package.
 165
 166   Returns:
 167     EFI_SUCCESS            - The HII database was successfully updated.
 168     EFI_OUT_OF_RESOURCES   - Unable to allocate enough memory for the updated database.
 169     EFI_INVALID_PARAMETER  - Handle or PackageList was NULL.
 170     EFI_NOT_FOUND          - The Handle was not valid or could not be found in database.
 171
 172 --*/
 173 ;
 174
 175 typedef
 176 EFI_STATUS
 177 (EFIAPI *EFI_HII_DATABASE_LIST_PACKS) (
 178   IN  CONST EFI_HII_DATABASE_PROTOCOL   *This,
 179   IN  UINT8                             PackageType,
 180   IN  CONST EFI_GUID                    *PackageGuid,
 181   IN  OUT UINTN                         *HandleBufferLength,
 182   OUT EFI_HII_HANDLE                    *Handle
 183   )
 184 /*++
 185
 186   Routine Description:
 187     This function returns a list of the package handles of the specified type
 188     that are currently active in the database. The pseudo-type
 189     EFI_HII_PACKAGE_TYPE_ALL will cause all package handles to be listed.
 190
 191   Arguments:
 192     This               - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 193     PackageType        - Specifies the package type of the packages to list or
 194                          EFI_HII_PACKAGE_TYPE_ALL for all packages to be listed.
 195     PackageGuid        - If PackageType is EFI_HII_PACKAGE_TYPE_GUID, then this
 196                          is the pointer to the GUID which must match the Guid
 197                          field of EFI_HII_GUID_PACKAGE_GUID_HDR. Otherwise,
 198                          it must be NULL.
 199     HandleBufferLength - On input, a pointer to the length of the handle buffer.
 200                          On output, the length of the handle buffer that is
 201                          required for the handles found.
 202     Handle             - An array of EFI_HII_HANDLE instances returned.
 203
 204   Returns:
 205     EFI_SUCCESS            - The matching handles are outputed successfully.
 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
 213 --*/
 214 ;
 215
 216 typedef
 217 EFI_STATUS
 218 (EFIAPI *EFI_HII_DATABASE_EXPORT_PACKS) (
 219   IN  CONST EFI_HII_DATABASE_PROTOCOL   *This,
 220   IN  EFI_HII_HANDLE                    Handle,
 221   IN  OUT UINTN                         *BufferSize,
 222   OUT EFI_HII_PACKAGE_LIST_HEADER       *Buffer
 223   )
 224 /*++
 225
 226   Routine Description:
 227     This function will export one or all package lists in the database to a buffer.
 228     For each package list exported, this function will call functions registered
 229     with EXPORT_PACK and then copy the package list to the buffer.
 230
 231   Arguments:
 232     This               - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 233     Handle             - An EFI_HII_HANDLE that corresponds to the desired package
 234                          list in the HII database to export or NULL to indicate
 235                          all package lists should be exported.
 236     BufferSize         - On input, a pointer to the length of the buffer.
 237                          On output, the length of the buffer that is required for
 238                          the exported data.
 239     Buffer             - A pointer to a buffer that will contain the results of
 240                          the export function.
 241
 242   Returns:
 243     EFI_SUCCESS            - Package exported.
 244     EFI_BUFFER_TO_SMALL    - The HandleBufferLength parameter indicates that Handle
 245                              is too small to support the number of handles.
 246                              HandleBufferLength is updated with a value that will
 247                              enable the data to fit.
 248     EFI_NOT_FOUND          - The specifiecd Handle could not be found in the current
 249                              database.
 250     EFI_INVALID_PARAMETER  - Handle or Buffer or BufferSize was NULL.
 251
 252 --*/
 253 ;
 254
 255 typedef
 256 EFI_STATUS
 257 (EFIAPI *EFI_HII_DATABASE_REGISTER_NOTIFY) (
 258   IN  CONST EFI_HII_DATABASE_PROTOCOL   *This,
 259   IN  UINT8                             PackageType,
 260   IN  CONST EFI_GUID                    *PackageGuid,
 261   IN  CONST EFI_HII_DATABASE_NOTIFY     PackageNotifyFn,
 262   IN  EFI_HII_DATABASE_NOTIFY_TYPE      NotifyType,
 263   OUT EFI_HANDLE                        *NotifyHandle
 264   )
 265 /*++
 266
 267   Routine Description:
 268     This function registers a function which will be called when specified actions related to packages of
 269     the specified type occur in the HII database. By registering a function, other HII-related drivers are
 270     notified when specific package types are added, removed or updated in the HII database.
 271     Each driver or application which registers a notification should use
 272     EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() before exiting.
 273
 274   Arguments:
 275     This               - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 276     PackageType        - Specifies the package type of the packages to list or
 277                          EFI_HII_PACKAGE_TYPE_ALL for all packages to be listed.
 278     PackageGuid        - If PackageType is EFI_HII_PACKAGE_TYPE_GUID, then this is the pointer to
 279                          the GUID which must match the Guid field of
 280                          EFI_HII_GUID_PACKAGE_GUID_HDR. Otherwise, it must be NULL.
 281     PackageNotifyFn    - Points to the function to be called when the event specified by
 282                          NotificationType occurs.
 283     NotifyType         - Describes the types of notification which this function will be receiving.
 284     NotifyHandle       - Points to the unique handle assigned to the registered notification. Can be used in
 285                          EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() to stop notifications.
 286
 287   Returns:
 288     EFI_SUCCESS            - Notification registered successfully.
 289     EFI_OUT_OF_RESOURCES   - Unable to allocate necessary data structures
 290     EFI_INVALID_PARAMETER  - NotifyHandle is NULL.
 291     EFI_INVALID_PARAMETER  - PackageGuid is not NULL when PackageType is not
 292                              EFI_HII_PACKAGE_TYPE_GUID.
 293     EFI_INVALID_PARAMETER  - PackageGuid is NULL when PackageType is EFI_HII_PACKAGE_TYPE_GUID.
 294
 295 --*/
 296 ;
 297
 298 typedef
 299 EFI_STATUS
 300 (EFIAPI *EFI_HII_DATABASE_UNREGISTER_NOTIFY) (
 301   IN CONST EFI_HII_DATABASE_PROTOCOL    *This,
 302   IN EFI_HANDLE                         NotificationHandle
 303   )
 304 /*++
 305
 306   Routine Description:
 307     Removes the specified HII database package-related notification.
 308
 309   Arguments:
 310     This               - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 311     NotifyHandle       - The handle of the notification function being unregistered.
 312
 313   Returns:
 314     EFI_SUCCESS            - Notification is unregistered successfully.
 315     EFI_INVALID_PARAMETER  - The Handle is invalid.
 316
 317 --*/
 318 ;
 319
 320 typedef
 321 EFI_STATUS
 322 (EFIAPI *EFI_HII_FIND_KEYBOARD_LAYOUTS) (
 323   IN  EFI_HII_DATABASE_PROTOCOL         *This,
 324   IN  OUT UINT16                        *KeyGuidBufferLength,
 325   OUT EFI_GUID                          *KeyGuidBuffer
 326   )
 327 /*++
 328
 329   Routine Description:
 330     This routine retrieves an array of GUID values for each keyboard layout that
 331     was previously registered in the system.
 332
 333   Arguments:
 334     This                - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 335     KeyGuidBufferLength - On input, a pointer to the length of the keyboard GUID
 336                           buffer. On output, the length of the handle buffer
 337                           that is required for the handles found.
 338     KeyGuidBuffer       - An array of keyboard layout GUID instances returned.
 339
 340   Returns:
 341     EFI_SUCCESS            - KeyGuidBuffer was updated successfully.
 342     EFI_BUFFER_TOO_SMALL   - The KeyGuidBufferLength parameter indicates
 343                              that KeyGuidBuffer is too small to support the
 344                              number of GUIDs. KeyGuidBufferLength is
 345                              updated with a value that will enable the data to fit.
 346     EFI_INVALID_PARAMETER  - The KeyGuidBuffer or KeyGuidBufferLength was NULL.
 347     EFI_NOT_FOUND          - There was no keyboard layout.
 348
 349 --*/
 350 ;
 351
 352 typedef
 353 EFI_STATUS
 354 (EFIAPI *EFI_HII_GET_KEYBOARD_LAYOUT) (
 355   IN  EFI_HII_DATABASE_PROTOCOL         *This,
 356   IN  EFI_GUID                          *KeyGuid,
 357   IN OUT UINT16                         *KeyboardLayoutLength,
 358   OUT EFI_HII_KEYBOARD_LAYOUT           *KeyboardLayout
 359   )
 360 /*++
 361
 362   Routine Description:
 363     This routine retrieves the requested keyboard layout. The layout is a physical description of the keys
 364     on a keyboard and the character(s) that are associated with a particular set of key strokes.
 365
 366   Arguments:
 367     This                 - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 368     KeyGuid              - A pointer to the unique ID associated with a given keyboard layout. If KeyGuid is
 369                            NULL then the current layout will be retrieved.
 370     KeyboardLayoutLength - On input, a pointer to the length of the KeyboardLayout buffer.
 371                            On output, the length of the data placed into KeyboardLayout.
 372     KeyboardLayout       - A pointer to a buffer containing the retrieved keyboard layout.
 373
 374   Returns:
 375     EFI_SUCCESS            - The keyboard layout was retrieved successfully.
 376     EFI_NOT_FOUND          - The requested keyboard layout was not found.
 377     EFI_INVALID_PARAMETER  - The KeyboardLayout or KeyboardLayoutLength was NULL.
 378
 379 --*/
 380 ;
 381
 382 typedef
 383 EFI_STATUS
 384 (EFIAPI *EFI_HII_SET_KEYBOARD_LAYOUT) (
 385   IN EFI_HII_DATABASE_PROTOCOL          *This,
 386   IN EFI_GUID                           *KeyGuid
 387   )
 388 /*++
 389
 390   Routine Description:
 391     This routine sets the default keyboard layout to the one referenced by KeyGuid. When this routine
 392     is called, an event will be signaled of the EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID
 393     group type. This is so that agents which are sensitive to the current keyboard layout being changed
 394     can be notified of this change.
 395
 396   Arguments:
 397     This                - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 398     KeyGuid             - A pointer to the unique ID associated with a given keyboard layout.
 399
 400   Returns:
 401     EFI_SUCCESS            - The current keyboard layout was successfully set.
 402     EFI_NOT_FOUND          - The referenced keyboard layout was not found, so action was taken.
 403     EFI_INVALID_PARAMETER  - The KeyGuid was NULL.
 404
 405 --*/
 406 ;
 407
 408 typedef
 409 EFI_STATUS
 410 (EFIAPI *EFI_HII_DATABASE_GET_PACK_HANDLE) (
 411   IN  EFI_HII_DATABASE_PROTOCOL         *This,
 412   IN  EFI_HII_HANDLE                    PackageListHandle,
 413   OUT EFI_HANDLE                        *DriverHandle
 414   )
 415 /*++
 416
 417   Routine Description:
 418     Return the EFI handle associated with a package list.
 419
 420   Arguments:
 421     This                - A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 422     PackageListHandle   - An EFI_HII_HANDLE that corresponds to the desired package list in the
 423                           HIIdatabase.
 424     DriverHandle        - On return, contains the EFI_HANDLE which was registered with the package list in
 425                           NewPackageList().
 426
 427   Returns:
 428     EFI_SUCCESS            - The DriverHandle was returned successfully.
 429     EFI_INVALID_PARAMETER  - The PackageListHandle was not valid or DriverHandle was NULL.
 430
 431 --*/
 432 ;
 433
 434 struct _EFI_HII_DATABASE_PROTOCOL {
 435   EFI_HII_DATABASE_NEW_PACK             NewPackageList;
 436   EFI_HII_DATABASE_REMOVE_PACK          RemovePackageList;
 437   EFI_HII_DATABASE_UPDATE_PACK          UpdatePackageList;
 438   EFI_HII_DATABASE_LIST_PACKS           ListPackageLists;
 439   EFI_HII_DATABASE_EXPORT_PACKS         ExportPackageLists;
 440   EFI_HII_DATABASE_REGISTER_NOTIFY      RegisterPackageNotify;
 441   EFI_HII_DATABASE_UNREGISTER_NOTIFY    UnregisterPackageNotify;
 442   EFI_HII_FIND_KEYBOARD_LAYOUTS         FindKeyboardLayouts;
 443   EFI_HII_GET_KEYBOARD_LAYOUT           GetKeyboardLayout;
 444   EFI_HII_SET_KEYBOARD_LAYOUT           SetKeyboardLayout;
 445   EFI_HII_DATABASE_GET_PACK_HANDLE      GetPackageListHandle;
 446 };
 447
 448 extern EFI_GUID gEfiHiiDatabaseProtocolGuid;
 449
 450 #endif