MdePkg/Include/Protocol/HiiDatabase.h

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