MdePkg/Include/Protocol/HiiDatabase.h

   1 /** @file
   2   The file provides Database manager for HII-related data
   3   structures.
   4
   5 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8   @par Revision Reference:
   9   This Protocol was introduced in UEFI Specification 2.1.
  10
  11 **/
  12
  13 #ifndef __HII_DATABASE_H__
  14 #define __HII_DATABASE_H__
  15
  16 #define EFI_HII_DATABASE_PROTOCOL_GUID \
  17   { 0xef9fc172, 0xa1b2, 0x4693, { 0xb3, 0x27, 0x6d, 0x32, 0xfc, 0x41, 0x60, 0x42 } }
  18
  19 typedef struct _EFI_HII_DATABASE_PROTOCOL EFI_HII_DATABASE_PROTOCOL;
  20
  21 ///
  22 /// EFI_HII_DATABASE_NOTIFY_TYPE.
  23 ///
  24 typedef UINTN EFI_HII_DATABASE_NOTIFY_TYPE;
  25
  26 #define EFI_HII_DATABASE_NOTIFY_NEW_PACK     0x00000001
  27 #define EFI_HII_DATABASE_NOTIFY_REMOVE_PACK  0x00000002
  28 #define EFI_HII_DATABASE_NOTIFY_EXPORT_PACK  0x00000004
  29 #define EFI_HII_DATABASE_NOTIFY_ADD_PACK     0x00000008
  30
  31 /**
  32
  33   Functions which are registered to receive notification of
  34   database events have this prototype. The actual event is encoded
  35   in NotifyType. The following table describes how PackageType,
  36   PackageGuid, Handle, and Package are used for each of the
  37   notification types.
  38
  39   @param PackageType  Package type of the notification.
  40
  41   @param PackageGuid  If PackageType is
  42                       EFI_HII_PACKAGE_TYPE_GUID, then this is
  43                       the pointer to the GUID from the Guid
  44                       field of EFI_HII_PACKAGE_GUID_HEADER.
  45                       Otherwise, it must be NULL.
  46
  47   @param Package      Points to the package referred to by the notification.
  48
  49   @param Handle       The handle of the package
  50                       list which contains the specified package.
  51
  52   @param NotifyType   The type of change concerning the
  53                       database. See
  54                       EFI_HII_DATABASE_NOTIFY_TYPE.
  55
  56 **/
  57 typedef
  58 EFI_STATUS
  59 (EFIAPI *EFI_HII_DATABASE_NOTIFY)(
  60   IN        UINT8                         PackageType,
  61   IN CONST  EFI_GUID                      *PackageGuid,
  62   IN CONST  EFI_HII_PACKAGE_HEADER        *Package,
  63   IN        EFI_HII_HANDLE                 Handle,
  64   IN        EFI_HII_DATABASE_NOTIFY_TYPE  NotifyType
  65   );
  66
  67 /**
  68
  69   This function adds the packages in the package list to the
  70   database and returns a handle. If there is a
  71   EFI_DEVICE_PATH_PROTOCOL associated with the DriverHandle, then
  72   this function will create a package of type
  73   EFI_PACKAGE_TYPE_DEVICE_PATH and add it to the package list. For
  74   each package in the package list, registered functions with the
  75   notification type NEW_PACK and having the same package type will
  76   be called. For each call to NewPackageList(), there should be a
  77   corresponding call to
  78   EFI_HII_DATABASE_PROTOCOL.RemovePackageList().
  79
  80   @param This           A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
  81
  82   @param PackageList    A pointer to an EFI_HII_PACKAGE_LIST_HEADER structure.
  83
  84   @param DriverHandle   Associate the package list with this EFI handle.
  85                         If a NULL is specified, this data will not be associate
  86                         with any drivers and cannot have a callback induced.
  87
  88   @param Handle         A pointer to the EFI_HII_HANDLE instance.
  89
  90   @retval EFI_SUCCESS           The package list associated with the
  91                                 Handle was added to the HII database.
  92
  93   @retval EFI_OUT_OF_RESOURCES  Unable to allocate necessary
  94                                 resources for the new database
  95                                 contents.
  96
  97   @retval EFI_INVALID_PARAMETER PackageList is NULL, or Handle is NULL.
  98
  99 **/
 100 typedef
 101 EFI_STATUS
 102 (EFIAPI *EFI_HII_DATABASE_NEW_PACK)(
 103   IN CONST  EFI_HII_DATABASE_PROTOCOL   *This,
 104   IN CONST  EFI_HII_PACKAGE_LIST_HEADER *PackageList,
 105   IN        EFI_HANDLE                  DriverHandle  OPTIONAL,
 106   OUT       EFI_HII_HANDLE               *Handle
 107   );
 108
 109 /**
 110
 111   This function removes the package list that is associated with a
 112   handle Handle from the HII database. Before removing the
 113   package, any registered functions with the notification type
 114   REMOVE_PACK and the same package type will be called. For each
 115   call to EFI_HII_DATABASE_PROTOCOL.NewPackageList(), there should
 116   be a corresponding call to RemovePackageList.
 117
 118   @param This             A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 119
 120   @param Handle           The handle that was registered to the data
 121                           that is requested for removal.
 122
 123   @retval EFI_SUCCESS     The data associated with the Handle was
 124                           removed from the HII database.
 125   @retval EFI_NOT_FOUND   The specified Handle is not in database.
 126
 127 **/
 128 typedef
 129 EFI_STATUS
 130 (EFIAPI *EFI_HII_DATABASE_REMOVE_PACK)(
 131   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 132   IN        EFI_HII_HANDLE             Handle
 133   );
 134
 135 /**
 136
 137   This function updates the existing package list (which has the
 138   specified Handle) in the HII databases, using the new package
 139   list specified by PackageList. The update process has the
 140   following steps: Collect all the package types in the package
 141   list specified by PackageList. A package type consists of the
 142   Type field of EFI_HII_PACKAGE_HEADER and, if the Type is
 143   EFI_HII_PACKAGE_TYPE_GUID, the Guid field, as defined in
 144   EFI_HII_PACKAGE_GUID_HEADER. Iterate through the packages within
 145   the existing package list in the HII database specified by
 146   Handle. If a package's type matches one of the collected types collected
 147   in step 1, then perform the following steps:
 148   - Call any functions registered with the notification type
 149   REMOVE_PACK.
 150   - Remove the package from the package list and the HII
 151   database.
 152   Add all of the packages within the new package list specified
 153   by PackageList, using the following steps:
 154   - Add the package to the package list and the HII database.
 155   - Call any functions registered with the notification type
 156   ADD_PACK.
 157
 158   @param This         A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 159
 160   @param Handle       The handle that was registered to the data
 161                       that is requested for removal.
 162
 163   @param PackageList  A pointer to an EFI_HII_PACKAGE_LIST
 164                       package.
 165
 166   @retval EFI_SUCCESS            The HII database was successfully updated.
 167
 168   @retval EFI_OUT_OF_RESOURCES   Unable to allocate enough memory
 169                                  for the updated database.
 170
 171   @retval EFI_INVALID_PARAMETER  PackageList was NULL.
 172   @retval EFI_NOT_FOUND          The specified Handle is not in database.
 173
 174 **/
 175 typedef
 176 EFI_STATUS
 177 (EFIAPI *EFI_HII_DATABASE_UPDATE_PACK)(
 178   IN CONST  EFI_HII_DATABASE_PROTOCOL   *This,
 179   IN        EFI_HII_HANDLE               Handle,
 180   IN CONST  EFI_HII_PACKAGE_LIST_HEADER *PackageList
 181   );
 182
 183 /**
 184
 185   This function returns a list of the package handles of the
 186   specified type that are currently active in the database. The
 187   pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package
 188   handles to be listed.
 189
 190   @param This                 A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 191
 192   @param PackageType          Specifies the package type of the packages
 193                               to list or EFI_HII_PACKAGE_TYPE_ALL for
 194                               all packages to be listed.
 195
 196   @param PackageGuid          If PackageType is
 197                               EFI_HII_PACKAGE_TYPE_GUID, then this is
 198                               the pointer to the GUID which must match
 199                               the Guid field of
 200                               EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
 201                               must be NULL.
 202
 203   @param HandleBufferLength   On input, a pointer to the length
 204                               of the handle buffer. On output,
 205                               the length of the handle buffer
 206                               that is required for the handles found.
 207
 208   @param Handle               An array of EFI_HII_HANDLE instances returned.
 209
 210   @retval EFI_SUCCESS           The matching handles are outputted successfully.
 211                                 HandleBufferLength is updated with the actual length.
 212   @retval EFI_BUFFER_TOO_SMALL  The HandleBufferLength parameter
 213                                 indicates that Handle is too
 214                                 small to support the number of
 215                                 handles. HandleBufferLength is
 216                                 updated with a value that will
 217                                 enable the data to fit.
 218   @retval EFI_NOT_FOUND         No matching handle could be found in database.
 219   @retval EFI_INVALID_PARAMETER HandleBufferLength was NULL.
 220   @retval EFI_INVALID_PARAMETER The value referenced by HandleBufferLength was not
 221                                 zero and Handle was NULL.
 222   @retval EFI_INVALID_PARAMETER PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but
 223                                 PackageGuid is not NULL, PackageType is a EFI_HII_
 224                                 PACKAGE_TYPE_GUID but PackageGuid is NULL.
 225 **/
 226 typedef
 227 EFI_STATUS
 228 (EFIAPI *EFI_HII_DATABASE_LIST_PACKS)(
 229   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 230   IN        UINT8                     PackageType,
 231   IN CONST  EFI_GUID                  *PackageGuid,
 232   IN OUT    UINTN                     *HandleBufferLength,
 233   OUT       EFI_HII_HANDLE            *Handle
 234   );
 235
 236 /**
 237
 238   This function will export one or all package lists in the
 239   database to a buffer. For each package list exported, this
 240   function will call functions registered with EXPORT_PACK and
 241   then copy the package list to the buffer. The registered
 242   functions may call EFI_HII_DATABASE_PROTOCOL.UpdatePackageList()
 243   to modify the package list before it is copied to the buffer. If
 244   the specified BufferSize is too small, then the status
 245   EFI_OUT_OF_RESOURCES will be returned and the actual package
 246   size will be returned in BufferSize.
 247
 248   @param This         A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 249
 250
 251   @param Handle       An EFI_HII_HANDLE  that corresponds to the
 252                       desired package list in the HII database to
 253                       export or NULL to indicate all package lists
 254                       should be exported.
 255
 256   @param BufferSize   On input, a pointer to the length of the
 257                       buffer. On output, the length of the
 258                       buffer that is required for the exported
 259                       data.
 260
 261   @param Buffer       A pointer to a buffer that will contain the
 262                       results of the export function.
 263
 264
 265   @retval EFI_SUCCESS           Package exported.
 266
 267   @retval EFI_OUT_OF_RESOURCES  BufferSize is too small to hold the package.
 268
 269   @retval EFI_NOT_FOUND         The specified Handle could not be found in the
 270                                 current database.
 271
 272   @retval EFI_INVALID_PARAMETER BufferSize was NULL.
 273
 274   @retval EFI_INVALID_PARAMETER The value referenced by BufferSize was not zero
 275                                 and Buffer was NULL.
 276 **/
 277 typedef
 278 EFI_STATUS
 279 (EFIAPI *EFI_HII_DATABASE_EXPORT_PACKS)(
 280   IN CONST  EFI_HII_DATABASE_PROTOCOL      *This,
 281   IN        EFI_HII_HANDLE                 Handle,
 282   IN OUT    UINTN                          *BufferSize,
 283   OUT       EFI_HII_PACKAGE_LIST_HEADER    *Buffer
 284   );
 285
 286 /**
 287
 288
 289   This function registers a function which will be called when
 290   specified actions related to packages of the specified type
 291   occur in the HII database. By registering a function, other
 292   HII-related drivers are notified when specific package types
 293   are added, removed or updated in the HII database. Each driver
 294   or application which registers a notification should use
 295   EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() before
 296   exiting.
 297
 298
 299   @param This             A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 300
 301   @param PackageType      The package type. See
 302                           EFI_HII_PACKAGE_TYPE_x in EFI_HII_PACKAGE_HEADER.
 303
 304   @param PackageGuid      If PackageType is
 305                           EFI_HII_PACKAGE_TYPE_GUID, then this is
 306                           the pointer to the GUID which must match
 307                           the Guid field of
 308                           EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
 309                           must be NULL.
 310
 311   @param PackageNotifyFn  Points to the function to be called
 312                           when the event specified by
 313                           NotificationType occurs. See
 314                           EFI_HII_DATABASE_NOTIFY.
 315
 316   @param NotifyType       Describes the types of notification which
 317                           this function will be receiving. See
 318                           EFI_HII_DATABASE_NOTIFY_TYPE for a
 319                           list of types.
 320
 321   @param NotifyHandle     Points to the unique handle assigned to
 322                           the registered notification. Can be used
 323                           in EFI_HII_DATABASE_PROTOCOL.UnregisterPack
 324                           to stop notifications.
 325
 326
 327   @retval EFI_SUCCESS           Notification registered successfully.
 328
 329   @retval EFI_OUT_OF_RESOURCES  Unable to allocate necessary
 330                                 data structures.
 331
 332   @retval EFI_INVALID_PARAMETER PackageGuid is not NULL when
 333                                 PackageType is not
 334                                 EFI_HII_PACKAGE_TYPE_GUID.
 335
 336 **/
 337 typedef
 338 EFI_STATUS
 339 (EFIAPI *EFI_HII_DATABASE_REGISTER_NOTIFY)(
 340   IN CONST  EFI_HII_DATABASE_PROTOCOL     *This,
 341   IN        UINT8                         PackageType,
 342   IN CONST  EFI_GUID                      *PackageGuid,
 343   IN        EFI_HII_DATABASE_NOTIFY       PackageNotifyFn,
 344   IN        EFI_HII_DATABASE_NOTIFY_TYPE  NotifyType,
 345   OUT       EFI_HANDLE                    *NotifyHandle
 346   );
 347
 348 /**
 349
 350   Removes the specified HII database package-related notification.
 351
 352   @param This                 A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 353
 354   @param NotificationHandle   The handle of the notification
 355                               function being unregistered.
 356
 357   @retval EFI_SUCCESS   Successsfully unregistered the notification.
 358
 359   @retval EFI_NOT_FOUND The incoming notification handle does not exist
 360                         in the current hii database.
 361
 362 **/
 363 typedef
 364 EFI_STATUS
 365 (EFIAPI *EFI_HII_DATABASE_UNREGISTER_NOTIFY)(
 366   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 367   IN        EFI_HANDLE                NotificationHandle
 368   );
 369
 370 /**
 371
 372   This routine retrieves an array of GUID values for each keyboard
 373   layout that was previously registered in the system.
 374
 375   @param This                 A pointer to the EFI_HII_PROTOCOL instance.
 376
 377   @param KeyGuidBufferLength  On input, a pointer to the length
 378                               of the keyboard GUID buffer. On
 379                               output, the length of the handle
 380                               buffer that is required for the
 381                               handles found.
 382
 383   @param KeyGuidBuffer        An array of keyboard layout GUID
 384                               instances returned.
 385
 386   @retval EFI_SUCCESS           KeyGuidBuffer was updated successfully.
 387
 388   @retval EFI_BUFFER_TOO_SMALL  The KeyGuidBufferLength
 389                                 parameter indicates that
 390                                 KeyGuidBuffer is too small to
 391                                 support the number of GUIDs.
 392                                 KeyGuidBufferLength is updated
 393                                 with a value that will enable
 394                                 the data to fit.
 395   @retval EFI_INVALID_PARAMETER The KeyGuidBufferLength is NULL.
 396   @retval EFI_INVALID_PARAMETER The value referenced by
 397                                 KeyGuidBufferLength is not
 398                                 zero and KeyGuidBuffer is NULL.
 399   @retval EFI_NOT_FOUND         There was no keyboard layout.
 400
 401 **/
 402 typedef
 403 EFI_STATUS
 404 (EFIAPI *EFI_HII_FIND_KEYBOARD_LAYOUTS)(
 405   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 406   IN OUT    UINT16                    *KeyGuidBufferLength,
 407   OUT       EFI_GUID                  *KeyGuidBuffer
 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