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