MdePkg/Include/Protocol/HiiDatabase.h

   1 /** @file
   2   The file provides Database manager for HII-related data
   3   structures.
   4
   5 Copyright (c) 2006 - 2010, 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 outputed 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 Handle or HandleBufferLength was NULL.
 227   @retval EFI_INVALID_PARAMETER PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but
 228                                 PackageGuid is not NULL, PackageType is a EFI_HII_
 229                                 PACKAGE_TYPE_GUID but PackageGuid is NULL.
 230 **/
 231 typedef
 232 EFI_STATUS
 233 (EFIAPI *EFI_HII_DATABASE_LIST_PACKS)(
 234   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 235   IN        UINT8                     PackageType,
 236   IN CONST  EFI_GUID                  *PackageGuid,
 237   IN OUT    UINTN                     *HandleBufferLength,
 238   OUT       EFI_HII_HANDLE            *Handle
 239 );
 240
 241 /**
 242
 243   This function will export one or all package lists in the
 244   database to a buffer. For each package list exported, this
 245   function will call functions registered with EXPORT_PACK and
 246   then copy the package list to the buffer. The registered
 247   functions may call EFI_HII_DATABASE_PROTOCOL.UpdatePackageList()
 248   to modify the package list before it is copied to the buffer. If
 249   the specified BufferSize is too small, then the status
 250   EFI_OUT_OF_RESOURCES will be returned and the actual package
 251   size will be returned in BufferSize.
 252
 253   @param This         A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 254
 255
 256   @param Handle       An EFI_HII_HANDLE  that corresponds to the
 257                       desired package list in the HII database to
 258                       export or NULL to indicate all package lists
 259                       should be exported.
 260
 261   @param BufferSize   On input, a pointer to the length of the
 262                       buffer. On output, the length of the
 263                       buffer that is required for the exported
 264                       data.
 265
 266   @param Buffer       A pointer to a buffer that will contain the
 267                       results of the export function.
 268
 269
 270   @retval EFI_SUCCESS           Package exported.
 271
 272   @retval EFI_OUT_OF_RESOURCES  BufferSize is too small to hold the package.
 273
 274 **/
 275 typedef
 276 EFI_STATUS
 277 (EFIAPI *EFI_HII_DATABASE_EXPORT_PACKS)(
 278   IN CONST  EFI_HII_DATABASE_PROTOCOL      *This,
 279   IN        EFI_HII_HANDLE                 Handle,
 280   IN OUT    UINTN                          *BufferSize,
 281   OUT       EFI_HII_PACKAGE_LIST_HEADER    *Buffer
 282 );
 283
 284
 285 /**
 286
 287
 288   This function registers a function which will be called when
 289   specified actions related to packages of the specified type
 290   occur in the HII database. By registering a function, other
 291   HII-related drivers are notified when specific package types
 292   are added, removed or updated in the HII database. Each driver
 293   or application which registers a notification should use
 294   EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() before
 295   exiting.
 296
 297
 298   @param This             A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
 299
 300   @param PackageType      The package type. See
 301                           EFI_HII_PACKAGE_TYPE_x in EFI_HII_PACKAGE_HEADER.
 302
 303   @param PackageGuid      If PackageType is
 304                           EFI_HII_PACKAGE_TYPE_GUID, then this is
 305                           the pointer to the GUID which must match
 306                           the Guid field of
 307                           EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
 308                           must be NULL.
 309
 310   @param PackageNotifyFn  Points to the function to be called
 311                           when the event specified by
 312                           NotificationType occurs. See
 313                           EFI_HII_DATABASE_NOTIFY.
 314
 315   @param NotifyType       Describes the types of notification which
 316                           this function will be receiving. See
 317                           EFI_HII_DATABASE_NOTIFY_TYPE for a
 318                           list of types.
 319
 320   @param NotifyHandle     Points to the unique handle assigned to
 321                           the registered notification. Can be used
 322                           in EFI_HII_DATABASE_PROTOCOL.UnregisterPack
 323                           to stop notifications.
 324
 325
 326   @retval EFI_SUCCESS           Notification registered successfully.
 327
 328   @retval EFI_OUT_OF_RESOURCES  Unable to allocate necessary
 329                                 data structures.
 330
 331   @retval EFI_INVALID_PARAMETER PackageGuid is not NULL when
 332                                 PackageType is not
 333                                 EFI_HII_PACKAGE_TYPE_GUID.
 334
 335 **/
 336 typedef
 337 EFI_STATUS
 338 (EFIAPI *EFI_HII_DATABASE_REGISTER_NOTIFY)(
 339   IN CONST  EFI_HII_DATABASE_PROTOCOL     *This,
 340   IN        UINT8                         PackageType,
 341   IN CONST  EFI_GUID                      *PackageGuid,
 342   IN        EFI_HII_DATABASE_NOTIFY       PackageNotifyFn,
 343   IN        EFI_HII_DATABASE_NOTIFY_TYPE  NotifyType,
 344   OUT       EFI_HANDLE                    *NotifyHandle
 345 );
 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
 373   This routine retrieves an array of GUID values for each keyboard
 374   layout that was previously registered in the system.
 375
 376   @param This                 A pointer to the EFI_HII_PROTOCOL instance.
 377
 378   @param KeyGuidBufferLength  On input, a pointer to the length
 379                               of the keyboard GUID buffer. On
 380                               output, the length of the handle
 381                               buffer that is required for the
 382                               handles found.
 383
 384   @param KeyGuidBuffer        An array of keyboard layout GUID
 385                               instances returned.
 386
 387   @retval EFI_SUCCESS           KeyGuidBuffer was updated successfully.
 388
 389   @retval EFI_BUFFER_TOO_SMALL  The KeyGuidBufferLength
 390                                 parameter indicates that
 391                                 KeyGuidBuffer is too small to
 392                                 support the number of GUIDs.
 393                                 KeyGuidBufferLength is updated
 394                                 with a value that will enable
 395                                 the data to fit.
 396
 397 **/
 398 typedef
 399 EFI_STATUS
 400 (EFIAPI *EFI_HII_FIND_KEYBOARD_LAYOUTS)(
 401   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 402   IN OUT    UINT16                    *KeyGuidBufferLength,
 403   OUT       EFI_GUID                  *KeyGuidBuffer
 404 );
 405
 406
 407 /**
 408
 409   This routine retrieves the requested keyboard layout. The layout
 410   is a physical description of the keys on a keyboard, and the
 411   character(s) that are associated with a particular set of key
 412   strokes.
 413
 414   @param This                   A pointer to the EFI_HII_PROTOCOL instance.
 415
 416   @param KeyGuid                A pointer to the unique ID associated with a
 417                                 given keyboard layout. If KeyGuid is NULL then
 418                                 the current layout will be retrieved.
 419
 420   @param KeyboardLayoutLength   On input, a pointer to the length of the
 421                                 KeyboardLayout buffer.  On output, the length of
 422                                 the data placed into KeyboardLayout.
 423
 424   @param KeyboardLayout         A pointer to a buffer containing the
 425                                 retrieved keyboard layout.
 426
 427   @retval EFI_SUCCESS   The keyboard layout was retrieved
 428                         successfully.
 429
 430   @retval EFI_NOT_FOUND The requested keyboard layout was not found.
 431
 432 **/
 433 typedef
 434 EFI_STATUS
 435 (EFIAPI *EFI_HII_GET_KEYBOARD_LAYOUT)(
 436   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 437   IN CONST  EFI_GUID                  *KeyGuid,
 438   IN OUT UINT16                       *KeyboardLayoutLength,
 439   OUT       EFI_HII_KEYBOARD_LAYOUT   *KeyboardLayout
 440 );
 441
 442 /**
 443
 444   This routine sets the default keyboard layout to the one
 445   referenced by KeyGuid. When this routine is called, an event
 446   will be signaled of the EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID
 447   group type. This is so that agents which are sensitive to the
 448   current keyboard layout being changed can be notified of this
 449   change.
 450
 451   @param This      A pointer to the EFI_HII_PROTOCOL instance.
 452
 453   @param KeyGuid   A pointer to the unique ID associated with a
 454                    given keyboard layout.
 455
 456   @retval EFI_SUCCESS    The current keyboard layout was successfully set.
 457
 458   @retval EFI_NOT_FOUND  The referenced keyboard layout was not
 459                          found, so action was taken.
 460
 461 **/
 462 typedef
 463 EFI_STATUS
 464 (EFIAPI *EFI_HII_SET_KEYBOARD_LAYOUT)(
 465   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 466   IN CONST  EFI_GUID                  *KeyGuid
 467 );
 468
 469 /**
 470
 471   Return the EFI handle associated with a package list.
 472
 473   @param This               A pointer to the EFI_HII_PROTOCOL instance.
 474
 475   @param PackageListHandle  An EFI_HII_HANDLE  that corresponds
 476                             to the desired package list in the
 477                             HIIdatabase.
 478
 479   @param DriverHandle       On return, contains the EFI_HANDLE which
 480                             was registered with the package list in
 481                             NewPackageList().
 482
 483   @retval EFI_SUCCESS            The DriverHandle was returned successfully.
 484
 485   @retval EFI_INVALID_PARAMETER  The PackageListHandle was not valid.
 486
 487 **/
 488 typedef
 489 EFI_STATUS
 490 (EFIAPI *EFI_HII_DATABASE_GET_PACK_HANDLE)(
 491   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
 492   IN        EFI_HII_HANDLE             PackageListHandle,
 493   OUT       EFI_HANDLE                *DriverHandle
 494 );
 495
 496 ///
 497 /// Database manager for HII-related data structures.
 498 ///
 499 struct _EFI_HII_DATABASE_PROTOCOL {
 500   EFI_HII_DATABASE_NEW_PACK           NewPackageList;
 501   EFI_HII_DATABASE_REMOVE_PACK        RemovePackageList;
 502   EFI_HII_DATABASE_UPDATE_PACK        UpdatePackageList;
 503   EFI_HII_DATABASE_LIST_PACKS         ListPackageLists;
 504   EFI_HII_DATABASE_EXPORT_PACKS       ExportPackageLists;
 505   EFI_HII_DATABASE_REGISTER_NOTIFY    RegisterPackageNotify;
 506   EFI_HII_DATABASE_UNREGISTER_NOTIFY  UnregisterPackageNotify;
 507   EFI_HII_FIND_KEYBOARD_LAYOUTS       FindKeyboardLayouts;
 508   EFI_HII_GET_KEYBOARD_LAYOUT         GetKeyboardLayout;
 509   EFI_HII_SET_KEYBOARD_LAYOUT         SetKeyboardLayout;
 510   EFI_HII_DATABASE_GET_PACK_HANDLE    GetPackageListHandle;
 511 };
 512
 513 extern EFI_GUID gEfiHiiDatabaseProtocolGuid;
 514
 515 #endif
 516
 517