MdePkg/Include/Protocol/HiiDatabase.h

   1 /** @file
   2   The file provides Database manager for HII-related data
   3   structures.
   4
   5   Copyright (c) 2006 - 2008, 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 #define EFI_HII_DATABASE_NOTIFY_NEW_PACK    0x00000001
  31 #define EFI_HII_DATABASE_NOTIFY_REMOVE_PACK 0x00000002
  32 #define EFI_HII_DATABASE_NOTIFY_EXPORT_PACK 0x00000004
  33 #define EFI_HII_DATABASE_NOTIFY_ADD_PACK    0x00000008
  34 /**
  35
  36   Functions which are registered to receive notification of
  37   database events have this prototype. The actual event is encoded
  38   in NotifyType. The following table describes how PackageType,
  39   PackageGuid, Handle, and Package are used for each of the
  40   notification types.
  41
  42   @param PackageType  Package type of the notification.
  43
  44   @param PackageGuid  If PackageType is
  45                       EFI_HII_PACKAGE_TYPE_GUID, then this is
  46                       the pointer to the GUID from the Guid
  47                       field of EFI_HII_PACKAGE_GUID_HEADER.
  48                       Otherwise, it must be NULL.
  49
  50   @param Package  Points to the package referred to by the
  51                   notification Handle The handle of the package
  52                   list which contains the specified package.
  53
  54   @param NotifyType   The type of change concerning the
  55                       database. See
  56                       EFI_HII_DATABASE_NOTIFY_TYPE.
  57
  58 **/
  59 typedef
  60 EFI_STATUS
  61 (EFIAPI *EFI_HII_DATABASE_NOTIFY)(
  62   IN        UINT8                         PackageType,
  63   IN CONST  EFI_GUID                      *PackageGuid,
  64   IN CONST  EFI_HII_PACKAGE_HEADER        *Package,
  65   IN        EFI_HII_HANDLE                 Handle,
  66   IN        EFI_HII_DATABASE_NOTIFY_TYPE  NotifyType
  67 );
  68
  69 /**
  70
  71   This function adds the packages in the package list to the
  72   database and returns a handle. If there is a
  73   EFI_DEVICE_PATH_PROTOCOL associated with the DriverHandle, then
  74   this function will create a package of type
  75   EFI_PACKAGE_TYPE_DEVICE_PATH and add it to the package list. For
  76   each package in the package list, registered functions with the
  77   notification type NEW_PACK and having the same package type will
  78   be called. For each call to NewPackageList(), there should be a
  79   corresponding call to
  80   EFI_HII_DATABASE_PROTOCOL.RemovePackageList().
  81
  82   @param This   A pointer to the EFI_HII_DATABASE_PROTOCOL
  83                 instance.
  84
  85   @param PackageList  A pointer to an
  86                       EFI_HII_PACKAGE_LIST_HEADER structure.
  87
  88   @param DriverHandle   Associate the package list with this EFI
  89                         handle Handle A pointer to the
  90                         EFI_HII_HANDLE  instance.
  91
  92   @retval EFI_SUCCESS   The package list associated with the
  93                         Handle was added to the HII database.
  94
  95   @retval EFI_OUT_OF_RESOURCES  Unable to allocate necessary
  96                                 resources for the new database
  97                                 contents.
  98
  99   @retval EFI_INVALID_PARAMETER   PackageList is NULL or Handle
 100                                   is NULL.
 101
 102 **/
 103 typedef
 104 EFI_STATUS
 105 (EFIAPI *EFI_HII_DATABASE_NEW_PACK)(
 106   IN CONST  EFI_HII_DATABASE_PROTOCOL   *This,
 107   IN CONST  EFI_HII_PACKAGE_LIST_HEADER *PackageList,
 108   IN        EFI_HANDLE                  DriverHandle,
 109   OUT       EFI_HII_HANDLE               *Handle
 110 );
 111
 112
 113 /**
 114
 115   This function removes the package list that is associated with a
 116   handle Handle from the HII database. Before removing the
 117   package, any registered functions with the notification type
 118   REMOVE_PACK and the same package type will be called. For each
 119   call to EFI_HII_DATABASE_PROTOCOL.NewPackageList(), there should
 120   be a corresponding call to RemovePackageList.
 121
 122   @param This   A pointer to the EFI_HII_DATABASE_PROTOCOL
 123                 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 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
 165                 instance.
 166
 167   @param Handle   The handle that was registered to the data
 168                   that is requested for removal.
 169
 170   @param PackageList  A pointer to an EFI_HII_PACKAGE_LIST
 171                       package.
 172
 173   @retval EFI_SUCCESS   The HII database was successfully
 174                         updated.
 175
 176   @retval EFI_OUT_OF_RESOURCES  Unable to allocate enough memory
 177                                 for the updated database.
 178
 179   @retval EFI_INVALID_PARAMETER  PackageList was NULL.
 180   @retval EFI_NOT_FOUND          The specified Handle is not in database.
 181
 182 **/
 183 typedef
 184 EFI_STATUS
 185 (EFIAPI *EFI_HII_DATABASE_UPDATE_PACK)(
 186   IN CONST  EFI_HII_DATABASE_PROTOCOL   *This,
 187   IN        EFI_HII_HANDLE               Handle,
 188   IN CONST  EFI_HII_PACKAGE_LIST_HEADER *PackageList
 189 );
 190
 191
 192 /**
 193
 194   This function returns a list of the package handles of the
 195   specified type that are currently active in the database. The
 196   pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package
 197   handles to be listed.
 198
 199   @param This   A pointer to the EFI_HII_DATABASE_PROTOCOL
 200                 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
 217                               found.
 218
 219   @param Handle   An array of EFI_HII_HANDLE  instances returned.
 220
 221
 222   @retval EFI_SUCCESS The matching handles are outputed successfully.
 223                            HandleBufferLength is updated with the actual length.
 224
 225   @retval EFI_BUFFER_TOO_SMALL The HandleBufferLength parameter
 226                                 indicates that Handle is too
 227                                 small to support the number of
 228                                 handles. HandleBufferLength is
 229                                 updated with a value that will
 230                                 enable the data to fit.
 231   @retval EFI_NOT_FOUND No matching handle could not be found in database.
 232   @retval EFI_INVALID_PARAMETER  Handle or HandleBufferLength was NULL.
 233   @retval EFI_INVALID_PARAMETER  PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but
 234                           PackageGuid is not NULL, PackageType is a EFI_HII_
 235                            PACKAGE_TYPE_GUID but PackageGuid is NULL.
 236
 237
 238 **/
 239 typedef
 240 EFI_STATUS
 241 (EFIAPI *EFI_HII_DATABASE_LIST_PACKS)(
 242   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 243   IN        UINT8                     PackageType,
 244   IN CONST  EFI_GUID                  *PackageGuid,
 245   IN OUT    UINTN                     *HandleBufferLength,
 246   OUT       EFI_HII_HANDLE             *Handle
 247 );
 248
 249
 250
 251
 252
 253
 254 /**
 255
 256   This function will export one or all package lists in the
 257   database to a buffer. For each package list exported, this
 258   function will call functions registered with EXPORT_PACK and
 259   then copy the package list to the buffer. The registered
 260   functions may call EFI_HII_DATABASE_PROTOCOL.UpdatePackageList()
 261   to modify the package list before it is copied to the buffer. If
 262   the specified BufferSize is too small, then the status
 263   EFI_OUT_OF_RESOURCES will be returned and the actual package
 264   size will be returned in BufferSize.
 265
 266   @param This   A pointer to the EFI_HII_DATABASE_PROTOCOL
 267                 instance.
 268
 269   @param Handle   An EFI_HII_HANDLE  that corresponds to the
 270                   desired package list in the HII database to
 271                   export or NULL to indicate all package lists
 272                   should be exported.
 273
 274   @param BufferSize   On input, a pointer to the length of the
 275                       buffer. On output, the length of the
 276                       buffer that is required for the exported
 277                       data.
 278
 279   @param Buffer   A pointer to a buffer that will contain the
 280                   results of the export function.
 281
 282
 283   @retval EFI_SUCCESS   Package exported.
 284
 285   @retval EFI_OUT_OF_RESOURCES  BufferSize is too small to hold
 286                                 the package.
 287
 288 **/
 289 typedef
 290 EFI_STATUS
 291 (EFIAPI *EFI_HII_DATABASE_EXPORT_PACKS)(
 292   IN CONST  EFI_HII_DATABASE_PROTOCOL      *This,
 293   IN        EFI_HII_HANDLE                 Handle,
 294   IN OUT    UINTN                          *BufferSize,
 295   OUT       EFI_HII_PACKAGE_LIST_HEADER    *Buffer
 296 );
 297
 298
 299 /**
 300
 301
 302   This function registers a function which will be called when
 303   specified actions related to packages of the specified type
 304   occur in the HII database. By registering a function, other
 305   HII-related drivers are notified when specific package types
 306   are added, removed or updated in the HII database. Each driver
 307   or application which registers a notification should use
 308   EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() before
 309   exiting.
 310
 311
 312   @param This   A pointer to the EFI_HII_DATABASE_PROTOCOL
 313                 instance.
 314
 315   @param PackageType  The package type. See
 316                       EFI_HII_PACKAGE_TYPE_x in EFI_HII_PACKAGE_HEADER.
 317
 318   @param PackageGuid  If PackageType is
 319                       EFI_HII_PACKAGE_TYPE_GUID, then this is
 320                       the pointer to the GUID which must match
 321                       the Guid field of
 322                       EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
 323                       must be NULL.
 324
 325   @param PackageNotifyFn  Points to the function to be called
 326                           when the event specified by
 327                           NotificationType occurs. See
 328                           EFI_HII_DATABASE_NOTIFY.
 329
 330   @param NotifyType   Describes the types of notification which
 331                       this function will be receiving. See
 332                       EFI_HII_DATABASE_NOTIFY_TYPE for more a
 333                       list of types.
 334
 335   @param NotifyHandle   Points to the unique handle assigned to
 336                         the registered notification. Can be used
 337                         in
 338                         EFI_HII_DATABASE_PROTOCOL.UnregisterPack
 339                         to stop notifications.
 340
 341
 342   @retval EFI_SUCCESS   Notification registered successfully.
 343
 344   @retval EFI_OUT_OF_RESOURCES  Unable to allocate necessary
 345                                 data structures.
 346
 347   @retval EFI_INVALID_PARAMETER   PackageGuid is not NULL when
 348                                   PackageType is not
 349                                   EFI_HII_PACKAGE_TYPE_GUID.
 350
 351 **/
 352 typedef
 353 EFI_STATUS
 354 (EFIAPI *EFI_HII_DATABASE_REGISTER_NOTIFY)(
 355   IN CONST  EFI_HII_DATABASE_PROTOCOL     *This,
 356   IN        UINT8                         PackageType,
 357   IN CONST  EFI_GUID                      *PackageGuid,
 358   IN        EFI_HII_DATABASE_NOTIFY       PackageNotifyFn,
 359   IN        EFI_HII_DATABASE_NOTIFY_TYPE  NotifyType,
 360   OUT       EFI_HANDLE                    *NotifyHandle
 361 );
 362
 363
 364 /**
 365
 366   Removes the specified HII database package-related notification.
 367
 368   @param This   A pointer to the EFI_HII_DATABASE_PROTOCOL
 369                 instance.
 370
 371   @param NotificationHandle   The handle of the notification
 372                               function being unregistered.
 373
 374   @retval EFI_SUCCESS   Unregister the notification
 375                         Successsfully
 376
 377   @retval EFI_NOT_FOUND The incoming notification handle does not exist
 378                          in current hii database.
 379
 380 **/
 381 typedef
 382 EFI_STATUS
 383 (EFIAPI *EFI_HII_DATABASE_UNREGISTER_NOTIFY)(
 384   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 385   IN        EFI_HANDLE                NotificationHandle
 386 );
 387
 388
 389 /**
 390
 391   This routine retrieves an array of GUID values for each keyboard
 392   layout that was previously registered in the system.
 393
 394   @param This   A pointer to the EFI_HII_PROTOCOL instance.
 395
 396   @param KeyGuidBufferLength  On input, a pointer to the length
 397                               of the keyboard GUID buffer. On
 398                               output, the length of the handle
 399                               buffer that is required for the
 400                               handles found. KeyGuidBuffer An
 401                               array of keyboard layout GUID
 402                               instances returned.
 403
 404   @retval EFI_SUCCESS   KeyGuidBuffer was updated successfully.
 405
 406   @retval EFI_BUFFER_TOO_SMALL  The KeyGuidBufferLength
 407                                 parameter indicates that
 408                                 KeyGuidBuffer is too small to
 409                                 support the number of GUIDs.
 410                                 KeyGuidBufferLength is updated
 411                                 with a value that will enable
 412                                 the data to fit.
 413
 414 **/
 415 typedef
 416 EFI_STATUS
 417 (EFIAPI *EFI_HII_FIND_KEYBOARD_LAYOUTS)(
 418   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 419   IN OUT    UINT16                    *KeyGuidBufferLength,
 420   OUT       EFI_GUID                  *KeyGuidBuffer
 421 );
 422
 423
 424 /**
 425
 426   This routine retrieves the requested keyboard layout. The layout
 427   is a physical description of the keys on a keyboard and the
 428   character(s) that are associated with a particular set of key
 429   strokes.
 430
 431   @param This   A pointer to the EFI_HII_PROTOCOL instance.
 432
 433   @param KeyGuid  A pointer to the unique ID associated with a
 434                   given keyboard layout. If KeyGuid is NULL then
 435                   the current layout will be retrieved.
 436
 437   @param KeyboardLayout A pointer to a buffer containing the
 438                         retrieved keyboard layout. below.
 439
 440   @retval EFI_SUCCESS   The keyboard layout was retrieved
 441                         successfully.
 442
 443   @retval EFI_NOT_FOUND   The requested keyboard layout was not
 444                           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_DATABASE_PROTOCOL
 466                 instance.
 467
 468   @param KeyGuid  A pointer to the unique ID associated with a
 469                   given keyboard layout.
 470
 471
 472   @retval EFI_SUCCESS   The current keyboard layout was
 473                         successfully set.
 474
 475   @retval EFI_NOT_FOUND   The referenced keyboard layout was not
 476                           found, so action was taken.
 477
 478 **/
 479 typedef
 480 EFI_STATUS
 481 (EFIAPI *EFI_HII_SET_KEYBOARD_LAYOUT)(
 482   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 483   IN CONST  EFI_GUID                  *KeyGuid
 484 );
 485
 486 /**
 487
 488   Return the EFI handle associated with a package list.
 489
 490   @param This   A pointer to the EFI_HII_DATABASE_PROTOCOL
 491                 instance.
 492
 493   @param PackageListHandle  An EFI_HII_HANDLE  that corresponds
 494                             to the desired package list in the
 495                             HIIdatabase.
 496
 497   @param DriverHandle   On return, contains the EFI_HANDLE which
 498                         was registered with the package list in
 499                         NewPackageList().
 500
 501   @retval EFI_SUCCESS   The DriverHandle was returned
 502                         successfully.
 503
 504   @retval EFI_INVALID_PARAMETER   The PackageListHandle was not
 505                                   valid.
 506
 507 **/
 508 typedef
 509 EFI_STATUS
 510 (EFIAPI *EFI_HII_DATABASE_GET_PACK_HANDLE)(
 511   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 512   IN        EFI_HII_HANDLE             PackageListHandle,
 513   OUT       EFI_HANDLE                *DriverHandle
 514 );
 515
 516 /**
 517
 518   @param NewPackageList Add a new package list to the HII
 519                         database.
 520
 521   @param RemovePackageList  Remove a package list from the HII
 522                             database.
 523
 524   @param UpdatePackageList  Update a package list in the HII
 525                             database.
 526
 527   @param ListPackageLists   List the handles of the package
 528                             lists within the HII database.
 529
 530   @param ExportPackageLists Export package lists from the HII
 531                             database.
 532
 533   @param RegisterPackageNotify  Register notification when
 534                                 packages of a certain type are
 535                                 installed.
 536
 537   @param UnregisterPackageNotify  Unregister notification of
 538                                   packages.
 539
 540   @param FindKeyboardLayouts  Retrieves a list of the keyboard
 541                               layouts in the system.
 542
 543   @param GetKeyboardLayout  Allows a program to extract the
 544                             current keyboard layout. See the
 545                             GetKeyboardLayout() function
 546                             description.
 547
 548   @param SetKeyboardLayout  Changes the current keyboard layout.
 549                             See the SetKeyboardLayout() function
 550
 551
 552 **/
 553 struct _EFI_HII_DATABASE_PROTOCOL {
 554   EFI_HII_DATABASE_NEW_PACK                    NewPackageList;
 555   EFI_HII_DATABASE_REMOVE_PACK                 RemovePackageList;
 556   EFI_HII_DATABASE_UPDATE_PACK        UpdatePackageList;
 557   EFI_HII_DATABASE_LIST_PACKS         ListPackageLists;
 558   EFI_HII_DATABASE_EXPORT_PACKS       ExportPackageLists;
 559   EFI_HII_DATABASE_REGISTER_NOTIFY    RegisterPackageNotify;
 560   EFI_HII_DATABASE_UNREGISTER_NOTIFY  UnregisterPackageNotify;
 561   EFI_HII_FIND_KEYBOARD_LAYOUTS       FindKeyboardLayouts;
 562   EFI_HII_GET_KEYBOARD_LAYOUT         GetKeyboardLayout;
 563   EFI_HII_SET_KEYBOARD_LAYOUT         SetKeyboardLayout;
 564   EFI_HII_DATABASE_GET_PACK_HANDLE    GetPackageListHandle;
 565 };
 566
 567 extern EFI_GUID gEfiHiiDatabaseProtocolGuid;
 568
 569 #endif
 570
 571