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