iPXE
HiiDatabase.h
Go to the documentation of this file.
00001 /** @file
00002   The file provides Database manager for HII-related data
00003   structures.
00004 
00005 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>
00006 This program and the accompanying materials are licensed and made available under
00007 the terms and conditions of the BSD License that accompanies this distribution.
00008 The full text of the license may be found at
00009 http://opensource.org/licenses/bsd-license.php.
00010 
00011 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00012 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00013 
00014 **/
00015 
00016 #ifndef __HII_DATABASE_H__
00017 #define __HII_DATABASE_H__
00018 
00019 FILE_LICENCE ( BSD3 );
00020 
00021 #define EFI_HII_DATABASE_PROTOCOL_GUID \
00022   { 0xef9fc172, 0xa1b2, 0x4693, { 0xb3, 0x27, 0x6d, 0x32, 0xfc, 0x41, 0x60, 0x42 } }
00023 
00024 
00025 typedef struct _EFI_HII_DATABASE_PROTOCOL EFI_HII_DATABASE_PROTOCOL;
00026 
00027 
00028 ///
00029 /// EFI_HII_DATABASE_NOTIFY_TYPE.
00030 ///
00031 typedef UINTN   EFI_HII_DATABASE_NOTIFY_TYPE;
00032 
00033 #define EFI_HII_DATABASE_NOTIFY_NEW_PACK    0x00000001
00034 #define EFI_HII_DATABASE_NOTIFY_REMOVE_PACK 0x00000002
00035 #define EFI_HII_DATABASE_NOTIFY_EXPORT_PACK 0x00000004
00036 #define EFI_HII_DATABASE_NOTIFY_ADD_PACK    0x00000008
00037 /**
00038 
00039   Functions which are registered to receive notification of
00040   database events have this prototype. The actual event is encoded
00041   in NotifyType. The following table describes how PackageType,
00042   PackageGuid, Handle, and Package are used for each of the
00043   notification types.
00044 
00045   @param PackageType  Package type of the notification.
00046 
00047   @param PackageGuid  If PackageType is
00048                       EFI_HII_PACKAGE_TYPE_GUID, then this is
00049                       the pointer to the GUID from the Guid
00050                       field of EFI_HII_PACKAGE_GUID_HEADER.
00051                       Otherwise, it must be NULL.
00052 
00053   @param Package      Points to the package referred to by the notification.
00054 
00055   @param Handle       The handle of the package
00056                       list which contains the specified package.
00057 
00058   @param NotifyType   The type of change concerning the
00059                       database. See
00060                       EFI_HII_DATABASE_NOTIFY_TYPE.
00061 
00062 **/
00063 typedef
00064 EFI_STATUS
00065 (EFIAPI *EFI_HII_DATABASE_NOTIFY)(
00066   IN        UINT8                         PackageType,
00067   IN CONST  EFI_GUID                      *PackageGuid,
00068   IN CONST  EFI_HII_PACKAGE_HEADER        *Package,
00069   IN        EFI_HII_HANDLE                 Handle,
00070   IN        EFI_HII_DATABASE_NOTIFY_TYPE  NotifyType
00071 );
00072 
00073 /**
00074 
00075   This function adds the packages in the package list to the
00076   database and returns a handle. If there is a
00077   EFI_DEVICE_PATH_PROTOCOL associated with the DriverHandle, then
00078   this function will create a package of type
00079   EFI_PACKAGE_TYPE_DEVICE_PATH and add it to the package list. For
00080   each package in the package list, registered functions with the
00081   notification type NEW_PACK and having the same package type will
00082   be called. For each call to NewPackageList(), there should be a
00083   corresponding call to
00084   EFI_HII_DATABASE_PROTOCOL.RemovePackageList().
00085 
00086   @param This           A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
00087 
00088   @param PackageList    A pointer to an EFI_HII_PACKAGE_LIST_HEADER structure.
00089 
00090   @param DriverHandle   Associate the package list with this EFI handle.
00091                         If a NULL is specified, this data will not be associate
00092                         with any drivers and cannot have a callback induced.
00093 
00094   @param Handle         A pointer to the EFI_HII_HANDLE instance.
00095 
00096   @retval EFI_SUCCESS           The package list associated with the
00097                                 Handle was added to the HII database.
00098 
00099   @retval EFI_OUT_OF_RESOURCES  Unable to allocate necessary
00100                                 resources for the new database
00101                                 contents.
00102 
00103   @retval EFI_INVALID_PARAMETER PackageList is NULL, or Handle is NULL.
00104 
00105 **/
00106 typedef
00107 EFI_STATUS
00108 (EFIAPI *EFI_HII_DATABASE_NEW_PACK)(
00109   IN CONST  EFI_HII_DATABASE_PROTOCOL   *This,
00110   IN CONST  EFI_HII_PACKAGE_LIST_HEADER *PackageList,
00111   IN        EFI_HANDLE                  DriverHandle, OPTIONAL
00112   OUT       EFI_HII_HANDLE               *Handle
00113 );
00114 
00115 
00116 /**
00117 
00118   This function removes the package list that is associated with a
00119   handle Handle from the HII database. Before removing the
00120   package, any registered functions with the notification type
00121   REMOVE_PACK and the same package type will be called. For each
00122   call to EFI_HII_DATABASE_PROTOCOL.NewPackageList(), there should
00123   be a corresponding call to RemovePackageList.
00124 
00125   @param This             A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
00126 
00127   @param Handle           The handle that was registered to the data
00128                           that is requested for removal.
00129 
00130   @retval EFI_SUCCESS     The data associated with the Handle was
00131                           removed from the HII database.
00132   @retval EFI_NOT_FOUND   The specified Handle is not in database.
00133 
00134 **/
00135 typedef
00136 EFI_STATUS
00137 (EFIAPI *EFI_HII_DATABASE_REMOVE_PACK)(
00138   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
00139   IN        EFI_HII_HANDLE             Handle
00140 );
00141 
00142 
00143 /**
00144 
00145   This function updates the existing package list (which has the
00146   specified Handle) in the HII databases, using the new package
00147   list specified by PackageList. The update process has the
00148   following steps: Collect all the package types in the package
00149   list specified by PackageList. A package type consists of the
00150   Type field of EFI_HII_PACKAGE_HEADER and, if the Type is
00151   EFI_HII_PACKAGE_TYPE_GUID, the Guid field, as defined in
00152   EFI_HII_PACKAGE_GUID_HEADER. Iterate through the packages within
00153   the existing package list in the HII database specified by
00154   Handle. If a package's type matches one of the collected types collected
00155   in step 1, then perform the following steps:
00156   - Call any functions registered with the notification type
00157   REMOVE_PACK.
00158   - Remove the package from the package list and the HII
00159   database.
00160   Add all of the packages within the new package list specified
00161   by PackageList, using the following steps:
00162   - Add the package to the package list and the HII database.
00163   - Call any functions registered with the notification type
00164   ADD_PACK.
00165 
00166   @param This         A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
00167 
00168   @param Handle       The handle that was registered to the data
00169                       that is requested for removal.
00170 
00171   @param PackageList  A pointer to an EFI_HII_PACKAGE_LIST
00172                       package.
00173 
00174   @retval EFI_SUCCESS            The HII database was successfully updated.
00175 
00176   @retval EFI_OUT_OF_RESOURCES   Unable to allocate enough memory
00177                                  for the updated database.
00178 
00179   @retval EFI_INVALID_PARAMETER  PackageList was NULL.
00180   @retval EFI_NOT_FOUND          The specified Handle is not in database.
00181 
00182 **/
00183 typedef
00184 EFI_STATUS
00185 (EFIAPI *EFI_HII_DATABASE_UPDATE_PACK)(
00186   IN CONST  EFI_HII_DATABASE_PROTOCOL   *This,
00187   IN        EFI_HII_HANDLE               Handle,
00188   IN CONST  EFI_HII_PACKAGE_LIST_HEADER *PackageList
00189 );
00190 
00191 
00192 /**
00193 
00194   This function returns a list of the package handles of the
00195   specified type that are currently active in the database. The
00196   pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package
00197   handles to be listed.
00198 
00199   @param This                 A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
00200 
00201   @param PackageType          Specifies the package type of the packages
00202                               to list or EFI_HII_PACKAGE_TYPE_ALL for
00203                               all packages to be listed.
00204 
00205   @param PackageGuid          If PackageType is
00206                               EFI_HII_PACKAGE_TYPE_GUID, then this is
00207                               the pointer to the GUID which must match
00208                               the Guid field of
00209                               EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
00210                               must be NULL.
00211 
00212   @param HandleBufferLength   On input, a pointer to the length
00213                               of the handle buffer. On output,
00214                               the length of the handle buffer
00215                               that is required for the handles found.
00216 
00217   @param Handle               An array of EFI_HII_HANDLE instances returned.
00218 
00219   @retval EFI_SUCCESS           The matching handles are outputted successfully.
00220                                 HandleBufferLength is updated with the actual length.
00221   @retval EFI_BUFFER_TOO_SMALL  The HandleBufferLength parameter
00222                                 indicates that Handle is too
00223                                 small to support the number of
00224                                 handles. HandleBufferLength is
00225                                 updated with a value that will
00226                                 enable the data to fit.
00227   @retval EFI_NOT_FOUND         No matching handle could be found in database.
00228   @retval EFI_INVALID_PARAMETER HandleBufferLength was NULL.
00229   @retval EFI_INVALID_PARAMETER The value referenced by HandleBufferLength was not
00230                                 zero and Handle was NULL.
00231   @retval EFI_INVALID_PARAMETER PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but
00232                                 PackageGuid is not NULL, PackageType is a EFI_HII_
00233                                 PACKAGE_TYPE_GUID but PackageGuid is NULL.
00234 **/
00235 typedef
00236 EFI_STATUS
00237 (EFIAPI *EFI_HII_DATABASE_LIST_PACKS)(
00238   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
00239   IN        UINT8                     PackageType,
00240   IN CONST  EFI_GUID                  *PackageGuid,
00241   IN OUT    UINTN                     *HandleBufferLength,
00242   OUT       EFI_HII_HANDLE            *Handle
00243 );
00244 
00245 /**
00246 
00247   This function will export one or all package lists in the
00248   database to a buffer. For each package list exported, this
00249   function will call functions registered with EXPORT_PACK and
00250   then copy the package list to the buffer. The registered
00251   functions may call EFI_HII_DATABASE_PROTOCOL.UpdatePackageList()
00252   to modify the package list before it is copied to the buffer. If
00253   the specified BufferSize is too small, then the status
00254   EFI_OUT_OF_RESOURCES will be returned and the actual package
00255   size will be returned in BufferSize.
00256 
00257   @param This         A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
00258 
00259 
00260   @param Handle       An EFI_HII_HANDLE  that corresponds to the
00261                       desired package list in the HII database to
00262                       export or NULL to indicate all package lists
00263                       should be exported.
00264 
00265   @param BufferSize   On input, a pointer to the length of the
00266                       buffer. On output, the length of the
00267                       buffer that is required for the exported
00268                       data.
00269 
00270   @param Buffer       A pointer to a buffer that will contain the
00271                       results of the export function.
00272 
00273 
00274   @retval EFI_SUCCESS           Package exported.
00275 
00276   @retval EFI_OUT_OF_RESOURCES  BufferSize is too small to hold the package.
00277 
00278   @retval EFI_NOT_FOUND         The specified Handle could not be found in the
00279                                 current database.
00280 
00281   @retval EFI_INVALID_PARAMETER BufferSize was NULL.
00282 
00283   @retval EFI_INVALID_PARAMETER The value referenced by BufferSize was not zero
00284                                 and Buffer was NULL.
00285 **/
00286 typedef
00287 EFI_STATUS
00288 (EFIAPI *EFI_HII_DATABASE_EXPORT_PACKS)(
00289   IN CONST  EFI_HII_DATABASE_PROTOCOL      *This,
00290   IN        EFI_HII_HANDLE                 Handle,
00291   IN OUT    UINTN                          *BufferSize,
00292   OUT       EFI_HII_PACKAGE_LIST_HEADER    *Buffer
00293 );
00294 
00295 
00296 /**
00297 
00298 
00299   This function registers a function which will be called when
00300   specified actions related to packages of the specified type
00301   occur in the HII database. By registering a function, other
00302   HII-related drivers are notified when specific package types
00303   are added, removed or updated in the HII database. Each driver
00304   or application which registers a notification should use
00305   EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() before
00306   exiting.
00307 
00308 
00309   @param This             A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
00310 
00311   @param PackageType      The package type. See
00312                           EFI_HII_PACKAGE_TYPE_x in EFI_HII_PACKAGE_HEADER.
00313 
00314   @param PackageGuid      If PackageType is
00315                           EFI_HII_PACKAGE_TYPE_GUID, then this is
00316                           the pointer to the GUID which must match
00317                           the Guid field of
00318                           EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
00319                           must be NULL.
00320 
00321   @param PackageNotifyFn  Points to the function to be called
00322                           when the event specified by
00323                           NotificationType occurs. See
00324                           EFI_HII_DATABASE_NOTIFY.
00325 
00326   @param NotifyType       Describes the types of notification which
00327                           this function will be receiving. See
00328                           EFI_HII_DATABASE_NOTIFY_TYPE for a
00329                           list of types.
00330 
00331   @param NotifyHandle     Points to the unique handle assigned to
00332                           the registered notification. Can be used
00333                           in EFI_HII_DATABASE_PROTOCOL.UnregisterPack
00334                           to stop notifications.
00335 
00336 
00337   @retval EFI_SUCCESS           Notification registered successfully.
00338 
00339   @retval EFI_OUT_OF_RESOURCES  Unable to allocate necessary
00340                                 data structures.
00341 
00342   @retval EFI_INVALID_PARAMETER PackageGuid is not NULL when
00343                                 PackageType is not
00344                                 EFI_HII_PACKAGE_TYPE_GUID.
00345 
00346 **/
00347 typedef
00348 EFI_STATUS
00349 (EFIAPI *EFI_HII_DATABASE_REGISTER_NOTIFY)(
00350   IN CONST  EFI_HII_DATABASE_PROTOCOL     *This,
00351   IN        UINT8                         PackageType,
00352   IN CONST  EFI_GUID                      *PackageGuid,
00353   IN        EFI_HII_DATABASE_NOTIFY       PackageNotifyFn,
00354   IN        EFI_HII_DATABASE_NOTIFY_TYPE  NotifyType,
00355   OUT       EFI_HANDLE                    *NotifyHandle
00356 );
00357 
00358 
00359 /**
00360 
00361   Removes the specified HII database package-related notification.
00362 
00363   @param This                 A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
00364 
00365   @param NotificationHandle   The handle of the notification
00366                               function being unregistered.
00367 
00368   @retval EFI_SUCCESS   Successsfully unregistered the notification.
00369 
00370   @retval EFI_NOT_FOUND The incoming notification handle does not exist
00371                         in the current hii database.
00372 
00373 **/
00374 typedef
00375 EFI_STATUS
00376 (EFIAPI *EFI_HII_DATABASE_UNREGISTER_NOTIFY)(
00377   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
00378   IN        EFI_HANDLE                NotificationHandle
00379 );
00380 
00381 
00382 /**
00383 
00384   This routine retrieves an array of GUID values for each keyboard
00385   layout that was previously registered in the system.
00386 
00387   @param This                 A pointer to the EFI_HII_PROTOCOL instance.
00388 
00389   @param KeyGuidBufferLength  On input, a pointer to the length
00390                               of the keyboard GUID buffer. On
00391                               output, the length of the handle
00392                               buffer that is required for the
00393                               handles found.
00394 
00395   @param KeyGuidBuffer        An array of keyboard layout GUID
00396                               instances returned.
00397 
00398   @retval EFI_SUCCESS           KeyGuidBuffer was updated successfully.
00399 
00400   @retval EFI_BUFFER_TOO_SMALL  The KeyGuidBufferLength
00401                                 parameter indicates that
00402                                 KeyGuidBuffer is too small to
00403                                 support the number of GUIDs.
00404                                 KeyGuidBufferLength is updated
00405                                 with a value that will enable
00406                                 the data to fit.
00407   @retval EFI_INVALID_PARAMETER The KeyGuidBufferLength is NULL.
00408   @retval EFI_INVALID_PARAMETER The value referenced by
00409                                 KeyGuidBufferLength is not
00410                                 zero and KeyGuidBuffer is NULL.
00411   @retval EFI_NOT_FOUND         There was no keyboard layout.
00412 
00413 **/
00414 typedef
00415 EFI_STATUS
00416 (EFIAPI *EFI_HII_FIND_KEYBOARD_LAYOUTS)(
00417   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
00418   IN OUT    UINT16                    *KeyGuidBufferLength,
00419   OUT       EFI_GUID                  *KeyGuidBuffer
00420 );
00421 
00422 
00423 /**
00424 
00425   This routine retrieves the requested keyboard layout. The layout
00426   is a physical description of the keys on a keyboard, and the
00427   character(s) that are associated with a particular set of key
00428   strokes.
00429 
00430   @param This                   A pointer to the EFI_HII_PROTOCOL instance.
00431 
00432   @param KeyGuid                A pointer to the unique ID associated with a
00433                                 given keyboard layout. If KeyGuid is NULL then
00434                                 the current layout will be retrieved.
00435 
00436   @param KeyboardLayoutLength   On input, a pointer to the length of the
00437                                 KeyboardLayout buffer.  On output, the length of
00438                                 the data placed into KeyboardLayout.
00439 
00440   @param KeyboardLayout         A pointer to a buffer containing the
00441                                 retrieved keyboard layout.
00442 
00443   @retval EFI_SUCCESS   The keyboard layout was retrieved
00444                         successfully.
00445 
00446   @retval EFI_NOT_FOUND The requested keyboard layout was not found.
00447 
00448 **/
00449 typedef
00450 EFI_STATUS
00451 (EFIAPI *EFI_HII_GET_KEYBOARD_LAYOUT)(
00452   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
00453   IN CONST  EFI_GUID                  *KeyGuid,
00454   IN OUT UINT16                       *KeyboardLayoutLength,
00455   OUT       EFI_HII_KEYBOARD_LAYOUT   *KeyboardLayout
00456 );
00457 
00458 /**
00459 
00460   This routine sets the default keyboard layout to the one
00461   referenced by KeyGuid. When this routine is called, an event
00462   will be signaled of the EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID
00463   group type. This is so that agents which are sensitive to the
00464   current keyboard layout being changed can be notified of this
00465   change.
00466 
00467   @param This      A pointer to the EFI_HII_PROTOCOL instance.
00468 
00469   @param KeyGuid   A pointer to the unique ID associated with a
00470                    given keyboard layout.
00471 
00472   @retval EFI_SUCCESS    The current keyboard layout was successfully set.
00473 
00474   @retval EFI_NOT_FOUND  The referenced keyboard layout was not
00475                          found, so action was taken.
00476 
00477 **/
00478 typedef
00479 EFI_STATUS
00480 (EFIAPI *EFI_HII_SET_KEYBOARD_LAYOUT)(
00481   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
00482   IN CONST  EFI_GUID                  *KeyGuid
00483 );
00484 
00485 /**
00486 
00487   Return the EFI handle associated with a package list.
00488 
00489   @param This               A pointer to the EFI_HII_PROTOCOL instance.
00490 
00491   @param PackageListHandle  An EFI_HII_HANDLE  that corresponds
00492                             to the desired package list in the
00493                             HIIdatabase.
00494 
00495   @param DriverHandle       On return, contains the EFI_HANDLE which
00496                             was registered with the package list in
00497                             NewPackageList().
00498 
00499   @retval EFI_SUCCESS            The DriverHandle was returned successfully.
00500 
00501   @retval EFI_INVALID_PARAMETER  The PackageListHandle was not valid.
00502 
00503 **/
00504 typedef
00505 EFI_STATUS
00506 (EFIAPI *EFI_HII_DATABASE_GET_PACK_HANDLE)(
00507   IN CONST  EFI_HII_DATABASE_PROTOCOL *This,
00508   IN        EFI_HII_HANDLE             PackageListHandle,
00509   OUT       EFI_HANDLE                *DriverHandle
00510 );
00511 
00512 ///
00513 /// Database manager for HII-related data structures.
00514 ///
00515 struct _EFI_HII_DATABASE_PROTOCOL {
00516   EFI_HII_DATABASE_NEW_PACK           NewPackageList;
00517   EFI_HII_DATABASE_REMOVE_PACK        RemovePackageList;
00518   EFI_HII_DATABASE_UPDATE_PACK        UpdatePackageList;
00519   EFI_HII_DATABASE_LIST_PACKS         ListPackageLists;
00520   EFI_HII_DATABASE_EXPORT_PACKS       ExportPackageLists;
00521   EFI_HII_DATABASE_REGISTER_NOTIFY    RegisterPackageNotify;
00522   EFI_HII_DATABASE_UNREGISTER_NOTIFY  UnregisterPackageNotify;
00523   EFI_HII_FIND_KEYBOARD_LAYOUTS       FindKeyboardLayouts;
00524   EFI_HII_GET_KEYBOARD_LAYOUT         GetKeyboardLayout;
00525   EFI_HII_SET_KEYBOARD_LAYOUT         SetKeyboardLayout;
00526   EFI_HII_DATABASE_GET_PACK_HANDLE    GetPackageListHandle;
00527 };
00528 
00529 extern EFI_GUID gEfiHiiDatabaseProtocolGuid;
00530 
00531 #endif
00532 
00533