EDK2 doxygen online documents - Firmware Encoding Index 1
EDK2 doxygen online documents - Firmware Encoding Index

EdkCompatibilityPkg/Foundation/Efi/Protocol/HiiDatabase/HiiDatabase.h

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