X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=MdePkg%2FInclude%2FProtocol%2FFormBrowser.h;h=61d7e8f871eedeb88b9e104360eed97a03cfd6fe;hb=09f0ddd026676f12faea599ebdca4f5c8186bf90;hp=0e52f1edaabb613c74ced7948281fad709710e93;hpb=0647c9adf92c6a8712091607a73b2768327a865d;p=mirror_edk2.git diff --git a/MdePkg/Include/Protocol/FormBrowser.h b/MdePkg/Include/Protocol/FormBrowser.h index 0e52f1edaa..61d7e8f871 100644 --- a/MdePkg/Include/Protocol/FormBrowser.h +++ b/MdePkg/Include/Protocol/FormBrowser.h @@ -1,11 +1,9 @@ /** @file - The EFI_FORM_BROWSER_PROTOCOL is the interface to the EFI - Configuration Driver. This will allow the caller to direct the - configuration driver to use either the HII database or use the passed - in packet of data. This will also allow the caller to post messages - into the configuration drivers internal mailbox. - Copyright (c) 2006, Intel Corporation + The file provides services to call for drivers to leverage the + EFI configuration driver interface. + + Copyright (c) 2006 - 2007, Intel Corporation All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at @@ -14,147 +12,196 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - Module Name: FormBrowser.h - - @par Revision Reference: - This protocol is defined in HII spec 0.92. + Module Name: FormBrowser.h **/ -#ifndef __FORM_BROWSER_H__ -#define __FORM_BROWSER_H__ +#ifndef __EFI_FORM_BROWSER_H__ +#define __EFI_FORM_BROWSER_H__ #define EFI_FORM_BROWSER_PROTOCOL_GUID \ - { \ - 0xe5a1333e, 0xe1b4, 0x4d55, {0xce, 0xeb, 0x35, 0xc3, 0xef, 0x13, 0x34, 0x43 } \ - } + { 0xe5a1333e, 0xe1b4, 0x4e55, { 0xce, 0xeb, 0x35, 0xc3, 0xef, 0x13, 0x34, 0x43 } } -typedef struct _EFI_FORM_BROWSER_PROTOCOL EFI_FORM_BROWSER_PROTOCOL; -typedef struct { - UINT32 Length; - UINT16 Type; - UINT8 Data[1]; -} EFI_HII_PACKET; +typedef struct _EFI_FORM_BROWSER_PROTOCOL EFI_FORM_BROWSER_PROTOCOL; -typedef struct { - EFI_HII_IFR_PACK *IfrData; - EFI_HII_STRING_PACK *StringData; -} EFI_IFR_PACKET; + +/** + + @param LeftColumn Value that designates the text column + where the browser window will begin from + the left-hand side of the screen + RightColumn Value that designates the text + column where the browser window will end + on the right-hand side of the screen. + + @param TopRow Value that designates the text row from the + top of the screen where the browser window + will start. + + @param BottomRow Value that designates the text row from the + bottom of the screen where the browser + window will end. +**/ typedef struct { - UINTN LeftColumn; - UINTN RightColumn; - UINTN TopRow; - UINTN BottomRow; + UINTN LeftColumn; + UINTN RightColumn; + UINTN TopRow; + UINTN BottomRow; } EFI_SCREEN_DESCRIPTOR; /** - Provides direction to the configuration driver whether to use the HII - database or a passed-in set of data. This function also establishes a - pointer to the calling driver¡¯s callback interface. - - @param This A pointer to the EFI_FORM_BROWSER_PROTOCOL instance. - @param UseDatabase Determines whether the HII database is to be - used to gather information. If the value is FALSE, the configuration - driver will get the information provided in the passed-in Packet parameters. - @param Handle A pointer to an array of HII handles to display. This value - should correspond to the value of the HII form package that is required to - be displayed. - @param HandleCount The number of handles in the array specified by Handle. - @param Packet A pointer to a set of data containing pointers to IFR - and/or string data. - @param CallbackHandle The handle to the driver¡¯s callback interface. - This parameter is used only when the UseDatabase parameter is FALSE - and an application wants to register a callback with the browser - @param NvMapOverride This buffer is used only when there is no NV variable - to define the current settings and the caller needs to provide to the browser - the current settings for the "fake" NV variable. - @param ScreenDimensions Allows the browser to be called so that it occupies - a portion of the physical screen instead of dynamically determining the - screen dimensions. - @param ResetRequired This BOOLEAN value will tell the caller if a reset - is required based on the data that might have been changed. The ResetRequired - parameter is primarily applicable for configuration applications, and is an - optional parameter. - - @retval EFI_SUCCESS The function completed successfully - @retval EFI_NOT_FOUND The variable was not found. - @retval EFI_BUFFER_TOO_SMALL The DataSize is too small for the result. - DataSize has been updated with the size needed to complete the request. - @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. - @retval EFI_DEVICE_ERROR The variable could not be saved due to a hardware failure. - + + This function is the primary interface to the internal + forms-based browser. By calling this routine, one is directing + the browser to use a variety of passed-in information or + primarily use the HII database as the source of information. + + @param This A pointer to the EFI_FORM_BROWSER_PROTOCOL + instance. + + @param Handle A pointer to an array of HII handles to + display. This value should correspond to the + value of the HII form package that is required + to be displayed. + + @param HandleCount The number of handles in the array + specified by Handle. + + @param SingleUse If FALSE, the browser operates as a standard + forms processor and exits only when + explicitly requested by the user. If TRUE, + the browser will return immediately after + processing the first user-generated + selection. + + @param ScreenDimensions Allows the browser to be called so + that it occupies a portion of the + physical screen instead of + dynamically determining the screen + dimensions. If the input values + violate the platform policy then the + dimensions will be dynamically + adjusted to comply. + + @param ResetRequired This BOOLEAN value will tell the caller + if a reset is required based on the data + that might have been changed. The + ResetRequired parameter is primarily + applicable for configuration + applications, and is an optional + parameter. + + @retval EFI_SUCCESS The function completed successfully + + @retval EFI_NOT_FOUND The variable was not found. + + @retval EFI_BUFFER_TOO_SMALL The DataSize is too small for + the result. DataSize has been + updated with the size needed to + complete the request. + + @retval EFI_INVALID_PARAMETER One of the parameters has an + invalid value. + + @retval EFI_DEVICE_ERROR The variable could not be saved due + to a hardware failure. + **/ typedef EFI_STATUS (EFIAPI *EFI_SEND_FORM) ( - IN EFI_FORM_BROWSER_PROTOCOL *This, - IN BOOLEAN UseDatabase, - IN EFI_HII_HANDLE *Handle, - IN UINTN HandleCount, - IN EFI_IFR_PACKET *Packet, OPTIONAL - IN EFI_HANDLE CallbackHandle, OPTIONAL - IN UINT8 *NvMapOverride, OPTIONAL - IN EFI_SCREEN_DESCRIPTOR *ScreenDimensions, OPTIONAL - OUT BOOLEAN *ResetRequired OPTIONAL - ); + IN CONST EFI_FORM_BROWSER_PROTOCOL *This, + IN CONST EFI_HII_HANDLE *Handle, + IN CONST UINTN HandleCount, + IN CONST BOOLEAN SingleUse, + IN CONST EFI_SCREEN_DESCRIPTOR *ScreenDimensions, OPTIONAL + OUT BOOLEAN *ResetRequired OPTIONAL +); + /** - Routine used to abstract a generic dialog interface and return the selected - key or string. - - @param NumberOfLines The number of lines for the dialog box. - @param HotKey Defines whether a single character is parsed (TRUE) - and returned in KeyValue or if a string is returned in StringBuffer. - @param MaximumStringSize The maximum size in bytes of a typed-in string. - Because each character is a CHAR16, the minimum string returned is two bytes. - @param StringBuffer The passed-in pointer to the buffer that will hold - the typed in string if HotKey is FALSE. - @param KeyValue The EFI_INPUT_KEY value returned if HotKey is TRUE. - @param String The pointer to the first string in the list of strings - that comprise the dialog box. - @param ... A series of NumberOfLines text strings that will be used - to construct the dialog box. - - @retval EFI_SUCCESS The dialog was displayed and user interaction was received. - @retval EFI_DEVICE_ERROR The user typed in an ESC character to exit the routine. - @retval EFI_INVALID_PARAMETER One of the parameters was invalid + + This routine is called by a routine which was called by the + browser. This routine called this service in the browser to + retrieve or set certain uncommitted state information. + + @param This A pointer to the EFI_FORM_BROWSER_PROTOCOL + instance. + + @param ResultsDataSize A pointer to the size of the buffer + associated with ResultsData. + + @param ResultsData A string returned from an IFR browser or + equivalent. The results string will have + no routing information in them. + + @param RetrieveData A BOOLEAN field which allows an agent to + retrieve (if RetrieveData = TRUE) data + from the uncommitted browser state + information or set (if RetrieveData = + FALSE) data in the uncommitted browser + state information. + + @param VariableGuid An optional field to indicate the target + variable GUID name to use. + + @param VariableName An optional field to indicate the target + human-readable variable name. + + + @retval EFI_SUCCESS The results have been distributed or are + awaiting distribution. + + @retval EFI_OUT_OF_RESOURCES The ResultsDataSize specified + was too small to contain the + results data. **/ typedef EFI_STATUS -(EFIAPI *EFI_CREATE_POP_UP) ( - IN UINTN NumberOfLines, - IN BOOLEAN HotKey, - IN UINTN MaximumStringSize, - OUT CHAR16 *StringBuffer, - OUT EFI_INPUT_KEY *KeyValue, - IN CHAR16 *String, - ... - ); +(EFIAPI *EFI_BROWSER_CALLBACK ) ( + IN CONST EFI_FORM_BROWSER_PROTOCOL *This, + IN OUT UINTN *ResultsDataSize, + IN OUT EFI_STRING ResultsData, + IN CONST BOOLEAN RetrieveData, + IN CONST EFI_GUID *VariableGuid, OPTIONAL + IN CONST CHAR16 *VariableName OPTIONAL +); /** - @par Protocol Description: - The EFI_FORM_BROWSER_PROTOCOL is the interface to call for drivers to - leverage the EFI configuration driver interface. - - @param SendForm - Provides direction to the configuration driver whether to use the HII - database or to use a passed-in set of data. This functions also establishes - a pointer to the calling driver¡¯s callback interface. - - @param CreatePopUp - Routine used to abstract a generic dialog interface and return the - selected key or string. + + This protocol is the interface to call for drivers to leverage + the EFI configuration driver interface. + + @param SendForm Provides direction to the configuration + driver whether to use the HII database or to + use a passed-in set of data. This functions + also establishes a pointer to the calling + driver's callback interface. See the + SendForm() function description. + + @param BrowserCallback Routine used to expose internal + configuration state of the browser. + This is primarily used by callback + handler routines which were called by + the browser and in-turn need to get + additional information from the + browser itself. See the + BrowserCallback() function + description. **/ struct _EFI_FORM_BROWSER_PROTOCOL { - EFI_SEND_FORM SendForm; - EFI_CREATE_POP_UP CreatePopUp; -}; + EFI_SEND_FORM SendForm; + EFI_BROWSER_CALLBACK BrowserCallback; +} ; + extern EFI_GUID gEfiFormBrowserProtocolGuid; #endif + +