MdePkg/Include/Protocol/HiiDatabase.h

   1 /** @file
   2   The file provides Database manager for HII-related data
   3   structures.
   4
   5   Copyright (c) 2006 - 2007, 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
 131   @retval EFI_INVALID_PARAMETER   The Handle was not valid.
 132
 133 **/
 134 typedef
 135 EFI_STATUS
 136 (EFIAPI *EFI_HII_DATABASE_REMOVE_PACK) (
 137   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 138   IN        EFI_HII_HANDLE             Handle
 139 );
 140
 141
 142 /**
 143
 144   This function updates the existing package list (which has the
 145   specified Handle) in the HII databases, using the new package
 146   list specified by PackageList. The update process has the
 147   following steps: Collect all the package types in the package
 148   list specified by PackageList. A package type consists of the
 149   Type field of EFI_HII_PACKAGE_HEADER and, if the Type is
 150   EFI_HII_PACKAGE_TYPE_GUID, the Guid field, as defined in
 151   EFI_HII_PACKAGE_GUID_HEADER. Iterate through the packages within
 152   the existing package list in the HII database specified by
 153   Handle. If a package??s type matches one of the types collected
 154   in step 1, then perform the following steps:
 155   - Call any functions registered with the notification type
 156   REMOVE_PACK.
 157   - Remove the package from the package list and the HII
 158   database.
 159   Add all of the packages within the new package list specified
 160   by PackageList, using the following steps:
 161   - Add the package to the package list and the HII database.
 162   - Call any functions registered with the notification type
 163   ADD_PACK.
 164
 165   @param This   A pointer to the EFI_HII_DATABASE_PROTOCOL
 166                 instance.
 167
 168   @param Handle   The handle that was registered to the data
 169                   that is requested for removal.
 170
 171   @param PackageList  A pointer to an EFI_HII_PACKAGE_LIST
 172                       package.
 173
 174   @retval EFI_SUCCESS   The HII database was successfully
 175                         updated.
 176
 177   @retval EFI_OUT_OF_RESOURCES  Unable to allocate enough memory
 178                                 for the updated database.
 179
 180   @retval EFI_INVALID_PARAMETER   The Handle was not valid.
 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   Handle was updated successfully.
 223
 224   @retval EFI_BUFFER_TOO_SMALL  The HandleBufferLength parameter
 225                                 indicates that Handle is too
 226                                 small to support the number of
 227                                 handles. HandleBufferLength is
 228                                 updated with a value that will
 229                                 enable the data to fit.
 230
 231
 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
 246
 247
 248 /**
 249
 250   This function will export one or all package lists in the
 251   database to a buffer. For each package list exported, this
 252   function will call functions registered with EXPORT_PACK and
 253   then copy the package list to the buffer. The registered
 254   functions may call EFI_HII_DATABASE_PROTOCOL.UpdatePackageList()
 255   to modify the package list before it is copied to the buffer. If
 256   the specified BufferSize is too small, then the status
 257   EFI_OUT_OF_RESOURCES will be returned and the actual package
 258   size will be returned in BufferSize.
 259
 260   @param This   A pointer to the EFI_HII_DATABASE_PROTOCOL
 261                 instance.
 262
 263   @param Handle   An EFI_HII_HANDLE  that corresponds to the
 264                   desired package list in the HII database to
 265                   export or NULL to indicate all package lists
 266                   should be exported.
 267
 268   @param BufferSize   On input, a pointer to the length of the
 269                       buffer. On output, the length of the
 270                       buffer that is required for the exported
 271                       data.
 272
 273   @param Buffer   A pointer to a buffer that will contain the
 274                   results of the export function.
 275
 276
 277   @retval EFI_SUCCESS   Package exported.
 278
 279   @retval EFI_OUT_OF_RESOURCES  BufferSize is too small to hold
 280                                 the package.
 281
 282 **/
 283 typedef
 284 EFI_STATUS
 285 (EFIAPI *EFI_HII_DATABASE_EXPORT_PACKS) (
 286   IN CONST  EFI_HII_DATABASE_PROTOCOL      *This,
 287   IN        EFI_HII_HANDLE                 Handle,
 288   IN OUT    UINTN                          *BufferSize,
 289   OUT       EFI_HII_PACKAGE_LIST_HEADER    *Buffer
 290 );
 291
 292
 293 /**
 294
 295
 296   This function registers a function which will be called when
 297   specified actions related to packages of the specified type
 298   occur in the HII database. By registering a function, other
 299   HII-related drivers are notified when specific package types
 300   are added, removed or updated in the HII database. Each driver
 301   or application which registers a notification should use
 302   EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() before
 303   exiting.
 304
 305
 306   @param This   A pointer to the EFI_HII_DATABASE_PROTOCOL
 307                 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 more 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
 332                         EFI_HII_DATABASE_PROTOCOL.UnregisterPack
 333                         to stop notifications.
 334
 335
 336   @retval EFI_SUCCESS   Notification registered successfully.
 337
 338   @retval EFI_OUT_OF_RESOURCES  Unable to allocate necessary
 339                                 data structures.
 340
 341   @retval EFI_INVALID_PARAMETER   PackageGuid is not NULL when
 342                                   PackageType is not
 343                                   EFI_HII_PACKAGE_TYPE_GUID.
 344
 345 **/
 346 typedef
 347 EFI_STATUS
 348 (EFIAPI *EFI_HII_DATABASE_REGISTER_NOTIFY) (
 349   IN CONST  EFI_HII_DATABASE_PROTOCOL     *This,
 350   IN        UINT8                         PackageType,
 351   IN CONST  EFI_GUID                      *PackageGuid,
 352   IN        EFI_HII_DATABASE_NOTIFY       PackageNotifyFn,
 353   IN        EFI_HII_DATABASE_NOTIFY_TYPE  NotifyType,
 354   OUT       EFI_HANDLE                    *NotifyHandle
 355 );
 356
 357
 358 /**
 359
 360   Removes the specified HII database package-related notification.
 361
 362   @param This   A pointer to the EFI_HII_DATABASE_PROTOCOL
 363                 instance.
 364
 365   @param NotificationHandle   The handle of the notification
 366                               function being unregistered.
 367
 368   @retval EFI_SUCCESS   Unregister the notification
 369                         Successsfully
 370
 371   @retval EFI_INVALID_PARAMETER   The Handle is invalid.
 372
 373 **/
 374 typedef
 375 EFI_STATUS
 376 (EFIAPI *EFI_HII_DATABASE_UNREGISTER_NOTIFY) (
 377   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 378   IN        EFI_HANDLE                NotificationHandle
 379 );
 380
 381
 382 /**
 383
 384   This routine retrieves an array of GUID values for each keyboard
 385   layout that was previously registered in the system.
 386
 387   @param This   A pointer to the EFI_HII_PROTOCOL instance.
 388
 389   @param KeyGuidBufferLength  On input, a pointer to the length
 390                               of the keyboard GUID buffer. On
 391                               output, the length of the handle
 392                               buffer that is required for the
 393                               handles found. KeyGuidBuffer An
 394                               array of keyboard layout GUID
 395                               instances returned.
 396
 397   @retval EFI_SUCCESS   KeyGuidBuffer was updated successfully.
 398
 399   @retval EFI_BUFFER_TOO_SMALL  The KeyGuidBufferLength
 400                                 parameter indicates that
 401                                 KeyGuidBuffer is too small to
 402                                 support the number of GUIDs.
 403                                 KeyGuidBufferLength is updated
 404                                 with a value that will enable
 405                                 the data to fit.
 406
 407 **/
 408 typedef
 409 EFI_STATUS
 410 (EFIAPI *EFI_HII_FIND_KEYBOARD_LAYOUTS) (
 411   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 412   IN OUT    UINT16                    *KeyGuidBufferLength,
 413   OUT       EFI_GUID                  *KeyGuidBuffer
 414 );
 415
 416
 417 /**
 418
 419   This routine retrieves the requested keyboard layout. The layout
 420   is a physical description of the keys on a keyboard and the
 421   character(s) that are associated with a particular set of key
 422   strokes.
 423
 424   @param This   A pointer to the EFI_HII_PROTOCOL instance.
 425
 426   @param KeyGuid  A pointer to the unique ID associated with a
 427                   given keyboard layout. If KeyGuid is NULL then
 428                   the current layout will be retrieved.
 429
 430   @param KeyboardLayout A pointer to a buffer containing the
 431                         retrieved keyboard layout. below.
 432
 433   @retval EFI_SUCCESS   The keyboard layout was retrieved
 434                         successfully.
 435
 436   @retval EFI_NOT_FOUND   The requested keyboard layout was not
 437                           found.
 438
 439 **/
 440 typedef
 441 EFI_STATUS
 442 (EFIAPI *EFI_HII_GET_KEYBOARD_LAYOUT) (
 443   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 444   IN CONST  EFI_GUID                  *KeyGuid,
 445   IN OUT UINT16                        *KeyboardLayoutLength,
 446   OUT       EFI_HII_KEYBOARD_LAYOUT   *KeyboardLayout
 447 );
 448
 449 /**
 450
 451   This routine sets the default keyboard layout to the one
 452   referenced by KeyGuid. When this routine is called, an event
 453   will be signaled of the EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID
 454   group type. This is so that agents which are sensitive to the
 455   current keyboard layout being changed can be notified of this
 456   change.
 457
 458   @param This   A pointer to the EFI_HII_DATABASE_PROTOCOL
 459                 instance.
 460
 461   @param KeyGuid  A pointer to the unique ID associated with a
 462                   given keyboard layout.
 463
 464
 465   @retval EFI_SUCCESS   The current keyboard layout was
 466                         successfully set.
 467
 468   @retval EFI_NOT_FOUND   The referenced keyboard layout was not
 469                           found, so action was taken.
 470
 471 **/
 472 typedef
 473 EFI_STATUS
 474 (EFIAPI *EFI_HII_SET_KEYBOARD_LAYOUT) (
 475   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 476   IN CONST  EFI_GUID                  *KeyGuid
 477 );
 478
 479 /**
 480
 481   Return the EFI handle associated with a package list.
 482
 483   @param This   A pointer to the EFI_HII_DATABASE_PROTOCOL
 484                 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
 495                         successfully.
 496
 497   @retval EFI_INVALID_PARAMETER   The PackageListHandle was not
 498                                   valid.
 499
 500 **/
 501 typedef
 502 EFI_STATUS
 503 (EFIAPI *EFI_HII_DATABASE_GET_PACK_HANDLE) (
 504   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 505   IN        EFI_HII_HANDLE             PackageListHandle,
 506   OUT       EFI_HANDLE                *DriverHandle
 507 );
 508
 509 /**
 510
 511   @param NewPackageList Add a new package list to the HII
 512                         database.
 513
 514   @param RemovePackageList  Remove a package list from the HII
 515                             database.
 516
 517   @param UpdatePackageList  Update a package list in the HII
 518                             database.
 519
 520   @param ListPackageLists   List the handles of the package
 521                             lists within the HII database.
 522
 523   @param ExportPackageLists Export package lists from the HII
 524                             database.
 525
 526   @param RegisterPackageNotify  Register notification when
 527                                 packages of a certain type are
 528                                 installed.
 529
 530   @param UnregisterPackageNotify  Unregister notification of
 531                                   packages.
 532
 533   @param FindKeyboardLayouts  Retrieves a list of the keyboard
 534                               layouts in the system.
 535
 536   @param GetKeyboardLayout  Allows a program to extract the
 537                             current keyboard layout. See the
 538                             GetKeyboardLayout() function
 539                             description.
 540
 541   @param SetKeyboardLayout  Changes the current keyboard layout.
 542                             See the SetKeyboardLayout() function
 543
 544
 545 **/
 546 struct _EFI_HII_DATABASE_PROTOCOL {
 547   EFI_HII_DATABASE_NEW_PACK                    NewPackageList;
 548   EFI_HII_DATABASE_REMOVE_PACK                 RemovePackageList;
 549   EFI_HII_DATABASE_UPDATE_PACK        UpdatePackageList;
 550   EFI_HII_DATABASE_LIST_PACKS         ListPackageLists;
 551   EFI_HII_DATABASE_EXPORT_PACKS       ExportPackageLists;
 552   EFI_HII_DATABASE_REGISTER_NOTIFY    RegisterPackageNotify;
 553   EFI_HII_DATABASE_UNREGISTER_NOTIFY  UnregisterPackageNotify;
 554   EFI_HII_FIND_KEYBOARD_LAYOUTS       FindKeyboardLayouts;
 555   EFI_HII_GET_KEYBOARD_LAYOUT         GetKeyboardLayout;
 556   EFI_HII_SET_KEYBOARD_LAYOUT         SetKeyboardLayout;
 557   EFI_HII_DATABASE_GET_PACK_HANDLE    GetPackageListHandle;
 558 };
 559
 560 extern EFI_GUID gEfiHiiDatabaseProtocolGuid;
 561
 562 #endif
 563
 564