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