123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533 |
- /** @file
- The file provides Database manager for HII-related data
- structures.
-
- Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>
- This program and the accompanying materials are licensed and made available under
- the terms and conditions of the BSD License that accompanies this distribution.
- The full text of the license may be found at
- http://opensource.org/licenses/bsd-license.php.
-
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
-
- **/
-
- #ifndef __HII_DATABASE_H__
- #define __HII_DATABASE_H__
-
- FILE_LICENCE ( BSD3 );
-
- #define EFI_HII_DATABASE_PROTOCOL_GUID \
- { 0xef9fc172, 0xa1b2, 0x4693, { 0xb3, 0x27, 0x6d, 0x32, 0xfc, 0x41, 0x60, 0x42 } }
-
-
- typedef struct _EFI_HII_DATABASE_PROTOCOL EFI_HII_DATABASE_PROTOCOL;
-
-
- ///
- /// EFI_HII_DATABASE_NOTIFY_TYPE.
- ///
- typedef UINTN EFI_HII_DATABASE_NOTIFY_TYPE;
-
- #define EFI_HII_DATABASE_NOTIFY_NEW_PACK 0x00000001
- #define EFI_HII_DATABASE_NOTIFY_REMOVE_PACK 0x00000002
- #define EFI_HII_DATABASE_NOTIFY_EXPORT_PACK 0x00000004
- #define EFI_HII_DATABASE_NOTIFY_ADD_PACK 0x00000008
- /**
-
- Functions which are registered to receive notification of
- database events have this prototype. The actual event is encoded
- in NotifyType. The following table describes how PackageType,
- PackageGuid, Handle, and Package are used for each of the
- notification types.
-
- @param PackageType Package type of the notification.
-
- @param PackageGuid If PackageType is
- EFI_HII_PACKAGE_TYPE_GUID, then this is
- the pointer to the GUID from the Guid
- field of EFI_HII_PACKAGE_GUID_HEADER.
- Otherwise, it must be NULL.
-
- @param Package Points to the package referred to by the notification.
-
- @param Handle The handle of the package
- list which contains the specified package.
-
- @param NotifyType The type of change concerning the
- database. See
- EFI_HII_DATABASE_NOTIFY_TYPE.
-
- **/
- typedef
- EFI_STATUS
- (EFIAPI *EFI_HII_DATABASE_NOTIFY)(
- IN UINT8 PackageType,
- IN CONST EFI_GUID *PackageGuid,
- IN CONST EFI_HII_PACKAGE_HEADER *Package,
- IN EFI_HII_HANDLE Handle,
- IN EFI_HII_DATABASE_NOTIFY_TYPE NotifyType
- );
-
- /**
-
- This function adds the packages in the package list to the
- database and returns a handle. If there is a
- EFI_DEVICE_PATH_PROTOCOL associated with the DriverHandle, then
- this function will create a package of type
- EFI_PACKAGE_TYPE_DEVICE_PATH and add it to the package list. For
- each package in the package list, registered functions with the
- notification type NEW_PACK and having the same package type will
- be called. For each call to NewPackageList(), there should be a
- corresponding call to
- EFI_HII_DATABASE_PROTOCOL.RemovePackageList().
-
- @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
-
- @param PackageList A pointer to an EFI_HII_PACKAGE_LIST_HEADER structure.
-
- @param DriverHandle Associate the package list with this EFI handle.
- If a NULL is specified, this data will not be associate
- with any drivers and cannot have a callback induced.
-
- @param Handle A pointer to the EFI_HII_HANDLE instance.
-
- @retval EFI_SUCCESS The package list associated with the
- Handle was added to the HII database.
-
- @retval EFI_OUT_OF_RESOURCES Unable to allocate necessary
- resources for the new database
- contents.
-
- @retval EFI_INVALID_PARAMETER PackageList is NULL, or Handle is NULL.
-
- **/
- typedef
- EFI_STATUS
- (EFIAPI *EFI_HII_DATABASE_NEW_PACK)(
- IN CONST EFI_HII_DATABASE_PROTOCOL *This,
- IN CONST EFI_HII_PACKAGE_LIST_HEADER *PackageList,
- IN EFI_HANDLE DriverHandle, OPTIONAL
- OUT EFI_HII_HANDLE *Handle
- );
-
-
- /**
-
- This function removes the package list that is associated with a
- handle Handle from the HII database. Before removing the
- package, any registered functions with the notification type
- REMOVE_PACK and the same package type will be called. For each
- call to EFI_HII_DATABASE_PROTOCOL.NewPackageList(), there should
- be a corresponding call to RemovePackageList.
-
- @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
-
- @param Handle The handle that was registered to the data
- that is requested for removal.
-
- @retval EFI_SUCCESS The data associated with the Handle was
- removed from the HII database.
- @retval EFI_NOT_FOUND The specified Handle is not in database.
-
- **/
- typedef
- EFI_STATUS
- (EFIAPI *EFI_HII_DATABASE_REMOVE_PACK)(
- IN CONST EFI_HII_DATABASE_PROTOCOL *This,
- IN EFI_HII_HANDLE Handle
- );
-
-
- /**
-
- This function updates the existing package list (which has the
- specified Handle) in the HII databases, using the new package
- list specified by PackageList. The update process has the
- following steps: Collect all the package types in the package
- list specified by PackageList. A package type consists of the
- Type field of EFI_HII_PACKAGE_HEADER and, if the Type is
- EFI_HII_PACKAGE_TYPE_GUID, the Guid field, as defined in
- EFI_HII_PACKAGE_GUID_HEADER. Iterate through the packages within
- the existing package list in the HII database specified by
- Handle. If a package's type matches one of the collected types collected
- in step 1, then perform the following steps:
- - Call any functions registered with the notification type
- REMOVE_PACK.
- - Remove the package from the package list and the HII
- database.
- Add all of the packages within the new package list specified
- by PackageList, using the following steps:
- - Add the package to the package list and the HII database.
- - Call any functions registered with the notification type
- ADD_PACK.
-
- @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
-
- @param Handle The handle that was registered to the data
- that is requested for removal.
-
- @param PackageList A pointer to an EFI_HII_PACKAGE_LIST
- package.
-
- @retval EFI_SUCCESS The HII database was successfully updated.
-
- @retval EFI_OUT_OF_RESOURCES Unable to allocate enough memory
- for the updated database.
-
- @retval EFI_INVALID_PARAMETER PackageList was NULL.
- @retval EFI_NOT_FOUND The specified Handle is not in database.
-
- **/
- typedef
- EFI_STATUS
- (EFIAPI *EFI_HII_DATABASE_UPDATE_PACK)(
- IN CONST EFI_HII_DATABASE_PROTOCOL *This,
- IN EFI_HII_HANDLE Handle,
- IN CONST EFI_HII_PACKAGE_LIST_HEADER *PackageList
- );
-
-
- /**
-
- This function returns a list of the package handles of the
- specified type that are currently active in the database. The
- pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package
- handles to be listed.
-
- @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
-
- @param PackageType Specifies the package type of the packages
- to list or EFI_HII_PACKAGE_TYPE_ALL for
- all packages to be listed.
-
- @param PackageGuid If PackageType is
- EFI_HII_PACKAGE_TYPE_GUID, then this is
- the pointer to the GUID which must match
- the Guid field of
- EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
- must be NULL.
-
- @param HandleBufferLength On input, a pointer to the length
- of the handle buffer. On output,
- the length of the handle buffer
- that is required for the handles found.
-
- @param Handle An array of EFI_HII_HANDLE instances returned.
-
- @retval EFI_SUCCESS The matching handles are outputted successfully.
- HandleBufferLength is updated with the actual length.
- @retval EFI_BUFFER_TOO_SMALL The HandleBufferLength parameter
- indicates that Handle is too
- small to support the number of
- handles. HandleBufferLength is
- updated with a value that will
- enable the data to fit.
- @retval EFI_NOT_FOUND No matching handle could be found in database.
- @retval EFI_INVALID_PARAMETER HandleBufferLength was NULL.
- @retval EFI_INVALID_PARAMETER The value referenced by HandleBufferLength was not
- zero and Handle was NULL.
- @retval EFI_INVALID_PARAMETER PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but
- PackageGuid is not NULL, PackageType is a EFI_HII_
- PACKAGE_TYPE_GUID but PackageGuid is NULL.
- **/
- typedef
- EFI_STATUS
- (EFIAPI *EFI_HII_DATABASE_LIST_PACKS)(
- IN CONST EFI_HII_DATABASE_PROTOCOL *This,
- IN UINT8 PackageType,
- IN CONST EFI_GUID *PackageGuid,
- IN OUT UINTN *HandleBufferLength,
- OUT EFI_HII_HANDLE *Handle
- );
-
- /**
-
- This function will export one or all package lists in the
- database to a buffer. For each package list exported, this
- function will call functions registered with EXPORT_PACK and
- then copy the package list to the buffer. The registered
- functions may call EFI_HII_DATABASE_PROTOCOL.UpdatePackageList()
- to modify the package list before it is copied to the buffer. If
- the specified BufferSize is too small, then the status
- EFI_OUT_OF_RESOURCES will be returned and the actual package
- size will be returned in BufferSize.
-
- @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
-
-
- @param Handle An EFI_HII_HANDLE that corresponds to the
- desired package list in the HII database to
- export or NULL to indicate all package lists
- should be exported.
-
- @param BufferSize On input, a pointer to the length of the
- buffer. On output, the length of the
- buffer that is required for the exported
- data.
-
- @param Buffer A pointer to a buffer that will contain the
- results of the export function.
-
-
- @retval EFI_SUCCESS Package exported.
-
- @retval EFI_OUT_OF_RESOURCES BufferSize is too small to hold the package.
-
- @retval EFI_NOT_FOUND The specified Handle could not be found in the
- current database.
-
- @retval EFI_INVALID_PARAMETER BufferSize was NULL.
-
- @retval EFI_INVALID_PARAMETER The value referenced by BufferSize was not zero
- and Buffer was NULL.
- **/
- typedef
- EFI_STATUS
- (EFIAPI *EFI_HII_DATABASE_EXPORT_PACKS)(
- IN CONST EFI_HII_DATABASE_PROTOCOL *This,
- IN EFI_HII_HANDLE Handle,
- IN OUT UINTN *BufferSize,
- OUT EFI_HII_PACKAGE_LIST_HEADER *Buffer
- );
-
-
- /**
-
-
- This function registers a function which will be called when
- specified actions related to packages of the specified type
- occur in the HII database. By registering a function, other
- HII-related drivers are notified when specific package types
- are added, removed or updated in the HII database. Each driver
- or application which registers a notification should use
- EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() before
- exiting.
-
-
- @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
-
- @param PackageType The package type. See
- EFI_HII_PACKAGE_TYPE_x in EFI_HII_PACKAGE_HEADER.
-
- @param PackageGuid If PackageType is
- EFI_HII_PACKAGE_TYPE_GUID, then this is
- the pointer to the GUID which must match
- the Guid field of
- EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
- must be NULL.
-
- @param PackageNotifyFn Points to the function to be called
- when the event specified by
- NotificationType occurs. See
- EFI_HII_DATABASE_NOTIFY.
-
- @param NotifyType Describes the types of notification which
- this function will be receiving. See
- EFI_HII_DATABASE_NOTIFY_TYPE for a
- list of types.
-
- @param NotifyHandle Points to the unique handle assigned to
- the registered notification. Can be used
- in EFI_HII_DATABASE_PROTOCOL.UnregisterPack
- to stop notifications.
-
-
- @retval EFI_SUCCESS Notification registered successfully.
-
- @retval EFI_OUT_OF_RESOURCES Unable to allocate necessary
- data structures.
-
- @retval EFI_INVALID_PARAMETER PackageGuid is not NULL when
- PackageType is not
- EFI_HII_PACKAGE_TYPE_GUID.
-
- **/
- typedef
- EFI_STATUS
- (EFIAPI *EFI_HII_DATABASE_REGISTER_NOTIFY)(
- IN CONST EFI_HII_DATABASE_PROTOCOL *This,
- IN UINT8 PackageType,
- IN CONST EFI_GUID *PackageGuid,
- IN EFI_HII_DATABASE_NOTIFY PackageNotifyFn,
- IN EFI_HII_DATABASE_NOTIFY_TYPE NotifyType,
- OUT EFI_HANDLE *NotifyHandle
- );
-
-
- /**
-
- Removes the specified HII database package-related notification.
-
- @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance.
-
- @param NotificationHandle The handle of the notification
- function being unregistered.
-
- @retval EFI_SUCCESS Successsfully unregistered the notification.
-
- @retval EFI_NOT_FOUND The incoming notification handle does not exist
- in the current hii database.
-
- **/
- typedef
- EFI_STATUS
- (EFIAPI *EFI_HII_DATABASE_UNREGISTER_NOTIFY)(
- IN CONST EFI_HII_DATABASE_PROTOCOL *This,
- IN EFI_HANDLE NotificationHandle
- );
-
-
- /**
-
- This routine retrieves an array of GUID values for each keyboard
- layout that was previously registered in the system.
-
- @param This A pointer to the EFI_HII_PROTOCOL instance.
-
- @param KeyGuidBufferLength On input, a pointer to the length
- of the keyboard GUID buffer. On
- output, the length of the handle
- buffer that is required for the
- handles found.
-
- @param KeyGuidBuffer An array of keyboard layout GUID
- instances returned.
-
- @retval EFI_SUCCESS KeyGuidBuffer was updated successfully.
-
- @retval EFI_BUFFER_TOO_SMALL The KeyGuidBufferLength
- parameter indicates that
- KeyGuidBuffer is too small to
- support the number of GUIDs.
- KeyGuidBufferLength is updated
- with a value that will enable
- the data to fit.
- @retval EFI_INVALID_PARAMETER The KeyGuidBufferLength is NULL.
- @retval EFI_INVALID_PARAMETER The value referenced by
- KeyGuidBufferLength is not
- zero and KeyGuidBuffer is NULL.
- @retval EFI_NOT_FOUND There was no keyboard layout.
-
- **/
- typedef
- EFI_STATUS
- (EFIAPI *EFI_HII_FIND_KEYBOARD_LAYOUTS)(
- IN CONST EFI_HII_DATABASE_PROTOCOL *This,
- IN OUT UINT16 *KeyGuidBufferLength,
- OUT EFI_GUID *KeyGuidBuffer
- );
-
-
- /**
-
- This routine retrieves the requested keyboard layout. The layout
- is a physical description of the keys on a keyboard, and the
- character(s) that are associated with a particular set of key
- strokes.
-
- @param This A pointer to the EFI_HII_PROTOCOL instance.
-
- @param KeyGuid A pointer to the unique ID associated with a
- given keyboard layout. If KeyGuid is NULL then
- the current layout will be retrieved.
-
- @param KeyboardLayoutLength On input, a pointer to the length of the
- KeyboardLayout buffer. On output, the length of
- the data placed into KeyboardLayout.
-
- @param KeyboardLayout A pointer to a buffer containing the
- retrieved keyboard layout.
-
- @retval EFI_SUCCESS The keyboard layout was retrieved
- successfully.
-
- @retval EFI_NOT_FOUND The requested keyboard layout was not found.
-
- **/
- typedef
- EFI_STATUS
- (EFIAPI *EFI_HII_GET_KEYBOARD_LAYOUT)(
- IN CONST EFI_HII_DATABASE_PROTOCOL *This,
- IN CONST EFI_GUID *KeyGuid,
- IN OUT UINT16 *KeyboardLayoutLength,
- OUT EFI_HII_KEYBOARD_LAYOUT *KeyboardLayout
- );
-
- /**
-
- This routine sets the default keyboard layout to the one
- referenced by KeyGuid. When this routine is called, an event
- will be signaled of the EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID
- group type. This is so that agents which are sensitive to the
- current keyboard layout being changed can be notified of this
- change.
-
- @param This A pointer to the EFI_HII_PROTOCOL instance.
-
- @param KeyGuid A pointer to the unique ID associated with a
- given keyboard layout.
-
- @retval EFI_SUCCESS The current keyboard layout was successfully set.
-
- @retval EFI_NOT_FOUND The referenced keyboard layout was not
- found, so action was taken.
-
- **/
- typedef
- EFI_STATUS
- (EFIAPI *EFI_HII_SET_KEYBOARD_LAYOUT)(
- IN CONST EFI_HII_DATABASE_PROTOCOL *This,
- IN CONST EFI_GUID *KeyGuid
- );
-
- /**
-
- Return the EFI handle associated with a package list.
-
- @param This A pointer to the EFI_HII_PROTOCOL instance.
-
- @param PackageListHandle An EFI_HII_HANDLE that corresponds
- to the desired package list in the
- HIIdatabase.
-
- @param DriverHandle On return, contains the EFI_HANDLE which
- was registered with the package list in
- NewPackageList().
-
- @retval EFI_SUCCESS The DriverHandle was returned successfully.
-
- @retval EFI_INVALID_PARAMETER The PackageListHandle was not valid.
-
- **/
- typedef
- EFI_STATUS
- (EFIAPI *EFI_HII_DATABASE_GET_PACK_HANDLE)(
- IN CONST EFI_HII_DATABASE_PROTOCOL *This,
- IN EFI_HII_HANDLE PackageListHandle,
- OUT EFI_HANDLE *DriverHandle
- );
-
- ///
- /// Database manager for HII-related data structures.
- ///
- struct _EFI_HII_DATABASE_PROTOCOL {
- EFI_HII_DATABASE_NEW_PACK NewPackageList;
- EFI_HII_DATABASE_REMOVE_PACK RemovePackageList;
- EFI_HII_DATABASE_UPDATE_PACK UpdatePackageList;
- EFI_HII_DATABASE_LIST_PACKS ListPackageLists;
- EFI_HII_DATABASE_EXPORT_PACKS ExportPackageLists;
- EFI_HII_DATABASE_REGISTER_NOTIFY RegisterPackageNotify;
- EFI_HII_DATABASE_UNREGISTER_NOTIFY UnregisterPackageNotify;
- EFI_HII_FIND_KEYBOARD_LAYOUTS FindKeyboardLayouts;
- EFI_HII_GET_KEYBOARD_LAYOUT GetKeyboardLayout;
- EFI_HII_SET_KEYBOARD_LAYOUT SetKeyboardLayout;
- EFI_HII_DATABASE_GET_PACK_HANDLE GetPackageListHandle;
- };
-
- extern EFI_GUID gEfiHiiDatabaseProtocolGuid;
-
- #endif
-
|