[mirror_edk2.git] / EdkCompatibilityPkg / Compatibility / FrameworkHiiOnUefiHiiThunk / Utility.h

/** @file\r
\r
  This file contains utility functions by HII Thunk Modules.\r
  \r
Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>\r
This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
which accompanies this distribution.  The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#ifndef _HII_THUNK_UTILITY_H_\r
#define _HII_THUNK_UTILITY_H_\r
\r
/**\r
  \r
  This function returns a list of the package handles of the   \r
  specified type that are currently active in the HII database. The   \r
  pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package   \r
  handles to be listed.\r
\r
  If HandleBufferLength is NULL, then ASSERT.\r
  If HandleBuffer is NULL, the ASSERT.\r
  If PackageType is EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is\r
  NULL, then ASSERT.\r
  If PackageType is not EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is not\r
  NULL, then ASSERT.\r
  \r
  \r
  @param PackageType          Specifies the package type of the packages\r
                              to list or EFI_HII_PACKAGE_TYPE_ALL for\r
                              all packages to be listed.\r
  \r
  @param PackageGuid          If PackageType is\r
                              EFI_HII_PACKAGE_TYPE_GUID, then this is\r
                              the pointer to the GUID which must match\r
                              the Guid field of\r
                              EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it\r
                              must be NULL.\r
  \r
  @param HandleBufferLength   On output, the length of the handle buffer\r
                              that is required for the handles found.\r
\r
  @param HandleBuffer         On output, an array of EFI_HII_HANDLE  instances returned.\r
                              The caller is responcible to free this pointer allocated.\r
\r
  @retval EFI_SUCCESS           The matching handles are outputted successfully.\r
                                HandleBufferLength is updated with the actual length.\r
  @retval EFI_OUT_OF_RESOURCES  Not enough resource to complete the operation.\r
  @retval EFI_NOT_FOUND         No matching handle could not be found in database.\r
**/\r
EFI_STATUS\r
EFIAPI\r
ListPackageLists (\r
  IN        UINT8                     PackageType,\r
  IN CONST  EFI_GUID                  *PackageGuid,\r
  IN OUT    UINTN                     *HandleBufferLength,\r
  OUT       EFI_HII_HANDLE            **HandleBuffer\r
  )\r
;\r
\r
/**\r
  Exports the contents of one or all package lists in the HII database into a buffer.\r
\r
  If Handle is not NULL and not a valid EFI_HII_HANDLE registered in the database, \r
  then ASSERT.\r
  If PackageListHeader is NULL, then ASSERT.\r
  If PackageListSize is NULL, then ASSERT.\r
\r
  @param  Handle                 The HII Handle.\r
  @param  PackageListHeader      A pointer to a buffer that will contain the results of \r
                                 the export function.\r
  @param  PackageListSize        On output, the length of the buffer that is required for the exported data.\r
\r
  @retval EFI_SUCCESS            Package exported.\r
\r
  @retval EFI_OUT_OF_RESOURCES   Not enought memory to complete the operations.\r
\r
**/\r
EFI_STATUS \r
EFIAPI\r
ExportPackageLists (\r
  IN EFI_HII_HANDLE                    Handle,\r
  OUT EFI_HII_PACKAGE_LIST_HEADER      **PackageListHeader,\r
  OUT UINTN                            *PackageListSize\r
  )\r
;\r
\r
/**\r
  Extract Hii package list GUID for given HII handle.\r
\r
  If HiiHandle could not be found in the HII database, then ASSERT.\r
  If Guid is NULL, then ASSERT.\r
\r
  @param  Handle              Hii handle\r
  @param  Guid                Package list GUID\r
\r
  @retval EFI_SUCCESS            Successfully extract GUID from Hii database.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
ExtractGuidFromHiiHandle (\r
  IN      EFI_HII_HANDLE      Handle,\r
  OUT     EFI_GUID            *Guid\r
  )\r
;\r
\r
/**\r
  Find the corressponding UEFI HII Handle from a Framework HII Handle given.\r
\r
  @param Private      The HII Thunk Module Private context.\r
  @param FwHiiHandle  The Framemwork HII Handle.\r
\r
  @return NULL        If Framework HII Handle is invalid.\r
  @return The corresponding UEFI HII Handle.\r
**/\r
EFI_HII_HANDLE\r
FwHiiHandleToUefiHiiHandle (\r
  IN CONST HII_THUNK_PRIVATE_DATA      *Private,\r
  IN FRAMEWORK_EFI_HII_HANDLE          FwHiiHandle\r
  );\r
\r
/**\r
  Find the corressponding HII Thunk Context from a Framework HII Handle given.\r
\r
  @param Private      The HII Thunk Module Private context.\r
  @param FwHiiHandle  The Framemwork HII Handle.\r
\r
  @return NULL        If Framework HII Handle is invalid.\r
  @return The corresponding HII Thunk Context.\r
**/\r
HII_THUNK_CONTEXT *\r
FwHiiHandleToThunkContext (\r
  IN CONST HII_THUNK_PRIVATE_DATA      *Private,\r
  IN FRAMEWORK_EFI_HII_HANDLE          FwHiiHandle\r
  );\r
\r
/**\r
  Find the corressponding HII Thunk Context from a UEFI HII Handle given.\r
\r
  @param Private        The HII Thunk Module Private context.\r
  @param UefiHiiHandle  The UEFI HII Handle.\r
\r
  @return NULL        If UEFI HII Handle is invalid.\r
  @return The corresponding HII Thunk Context.\r
**/\r
HII_THUNK_CONTEXT *\r
UefiHiiHandleToThunkContext (\r
  IN CONST HII_THUNK_PRIVATE_DATA     *Private,\r
  IN EFI_HII_HANDLE                   UefiHiiHandle\r
  );\r
\r
/**\r
  Find the corressponding HII Thunk Context from a Tag GUID.\r
\r
  @param Private      The HII Thunk Module Private context.\r
  @param Guid         The Tag GUID.\r
\r
  @return NULL        No HII Thunk Context matched the Tag GUID.\r
  @return The corresponding HII Thunk Context.\r
**/\r
HII_THUNK_CONTEXT *\r
TagGuidToIfrPackThunkContext (\r
  IN CONST HII_THUNK_PRIVATE_DATA *Private,\r
  IN CONST EFI_GUID                   *Guid\r
  );\r
\r
/**\r
  This function create a HII_THUNK_CONTEXT for the input UEFI HiiHandle\r
  that is created when a package list registered by a module calling \r
  EFI_HII_DATABASE_PROTOCOL.NewPackageList. \r
  This function records the PackageListGuid of EFI_HII_PACKAGE_LIST_HEADER \r
  into the TagGuid of the created HII_THUNK_CONTEXT.\r
\r
  @param UefiHiiHandle  The UEFI HII Handle.\r
  \r
  @return the new created Hii thunk context.\r
\r
**/\r
HII_THUNK_CONTEXT *\r
CreateThunkContextForUefiHiiHandle (\r
  IN  EFI_HII_HANDLE             UefiHiiHandle\r
  );\r
\r
/**\r
  Clean up the HII Thunk Context for a UEFI HII Handle.\r
\r
  @param Private        The HII Thunk Module Private context.\r
  @param UefiHiiHandle  The UEFI HII Handle.\r
\r
**/\r
VOID\r
DestroyThunkContextForUefiHiiHandle (\r
  IN HII_THUNK_PRIVATE_DATA     *Private,\r
  IN EFI_HII_HANDLE             UefiHiiHandle\r
  );\r
\r
/**\r
  Get the number of HII Package for a Package type.\r
\r
  @param PackageListHeader      The Package List.\r
  @param PackageType            The Package Type.\r
\r
  @return The number of Package for given type.\r
**/\r
UINTN\r
GetPackageCountByType (\r
  IN CONST EFI_HII_PACKAGE_LIST_HEADER     *PackageListHeader,\r
  IN       UINT8                           PackageType\r
  );\r
\r
/**\r
  Creat a Thunk Context.\r
\r
  ASSERT if no FormSet Opcode is found.\r
\r
  @param Private             The HII Thunk Private Context.\r
  @param StringPackageCount  The String package count.\r
  @param IfrPackageCount     The IFR Package count.\r
\r
  @return  A newly created Thunk Context.\r
  @retval  NULL  No resource to create a new Thunk Context.\r
**/\r
HII_THUNK_CONTEXT *\r
CreateThunkContext (\r
  IN  HII_THUNK_PRIVATE_DATA      *Private,\r
  IN  UINTN                       StringPackageCount,\r
  IN  UINTN                       IfrPackageCount\r
  );\r
\r
/**\r
  Destroy the Thunk Context and free up all resource.\r
\r
  @param ThunkContext        The HII Thunk Private Context to be freed.\r
\r
**/\r
VOID\r
DestroyThunkContext (\r
  IN HII_THUNK_CONTEXT          *ThunkContext\r
  );\r
\r
/**\r
  Get FormSet GUID.\r
\r
  ASSERT if no FormSet Opcode is found.\r
\r
  @param Packages             Form Framework Package.\r
  @param FormSetGuid          Return the FormSet Guid.\r
\r
**/\r
VOID\r
GetFormSetGuid (\r
  IN  EFI_HII_PACKAGE_HEADER  *Package,\r
  OUT EFI_GUID                *FormSetGuid\r
  );\r
\r
/**\r
  Get the Form Package from a Framework Package List.\r
\r
  @param Packages               Framework Package List.\r
\r
  @return The Form Package Header found.\r
**/\r
EFI_HII_PACKAGE_HEADER *\r
GetIfrPackage (\r
  IN CONST EFI_HII_PACKAGES               *Packages\r
  );\r
\r
/**\r
  Parse the Form Package and build a FORM_BROWSER_FORMSET structure.\r
\r
  @param  UefiHiiHandle          PackageList Handle\r
\r
  @return A pointer to FORM_BROWSER_FORMSET.\r
\r
**/\r
FORM_BROWSER_FORMSET *\r
ParseFormSet (\r
  IN EFI_HII_HANDLE   UefiHiiHandle\r
  );\r
\r
#endif\r
Commit	Line	Data
26a76fbc	1	/** @file\r
4259256b	2	\r
	3	This file contains utility functions by HII Thunk Modules.\r
	4	\r
584d5652 HT	5	Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>\r
584d5652 HT	6	This program and the accompanying materials\r
4259256b	7	are licensed and made available under the terms and conditions of the BSD License\r
	8	which accompanies this distribution. The full text of the license may be found at\r
	9	http://opensource.org/licenses/bsd-license.php\r
	10	\r
	11	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
	12	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	13	\r
	14	**/\r
	15	\r
26a76fbc LG	16	#ifndef _HII_THUNK_UTILITY_H_\r
26a76fbc LG	17	#define _HII_THUNK_UTILITY_H_\r
4259256b	18	\r
cb7d01c0	19	/**\r
	20	\r
	21	This function returns a list of the package handles of the \r
	22	specified type that are currently active in the HII database. The \r
	23	pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package \r
	24	handles to be listed.\r
	25	\r
	26	If HandleBufferLength is NULL, then ASSERT.\r
	27	If HandleBuffer is NULL, the ASSERT.\r
	28	If PackageType is EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is\r
	29	NULL, then ASSERT.\r
	30	If PackageType is not EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is not\r
	31	NULL, then ASSERT.\r
	32	\r
	33	\r
	34	@param PackageType Specifies the package type of the packages\r
	35	to list or EFI_HII_PACKAGE_TYPE_ALL for\r
	36	all packages to be listed.\r
	37	\r
	38	@param PackageGuid If PackageType is\r
	39	EFI_HII_PACKAGE_TYPE_GUID, then this is\r
	40	the pointer to the GUID which must match\r
	41	the Guid field of\r
	42	EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it\r
	43	must be NULL.\r
	44	\r
	45	@param HandleBufferLength On output, the length of the handle buffer\r
	46	that is required for the handles found.\r
	47	\r
	48	@param HandleBuffer On output, an array of EFI_HII_HANDLE instances returned.\r
	49	The caller is responcible to free this pointer allocated.\r
	50	\r
4fc0be87	51	@retval EFI_SUCCESS The matching handles are outputted successfully.\r
cb7d01c0	52	HandleBufferLength is updated with the actual length.\r
	53	@retval EFI_OUT_OF_RESOURCES Not enough resource to complete the operation.\r
	54	@retval EFI_NOT_FOUND No matching handle could not be found in database.\r
	55	**/\r
	56	EFI_STATUS\r
	57	EFIAPI\r
	58	ListPackageLists (\r
	59	IN UINT8 PackageType,\r
	60	IN CONST EFI_GUID *PackageGuid,\r
	61	IN OUT UINTN *HandleBufferLength,\r
	62	OUT EFI_HII_HANDLE **HandleBuffer\r
	63	)\r
	64	;\r
	65	\r
	66	/**\r
	67	Exports the contents of one or all package lists in the HII database into a buffer.\r
	68	\r
	69	If Handle is not NULL and not a valid EFI_HII_HANDLE registered in the database, \r
	70	then ASSERT.\r
	71	If PackageListHeader is NULL, then ASSERT.\r
	72	If PackageListSize is NULL, then ASSERT.\r
	73	\r
	74	@param Handle The HII Handle.\r
	75	@param PackageListHeader A pointer to a buffer that will contain the results of \r
	76	the export function.\r
	77	@param PackageListSize On output, the length of the buffer that is required for the exported data.\r
	78	\r
	79	@retval EFI_SUCCESS Package exported.\r
	80	\r
	81	@retval EFI_OUT_OF_RESOURCES Not enought memory to complete the operations.\r
	82	\r
	83	**/\r
	84	EFI_STATUS \r
	85	EFIAPI\r
	86	ExportPackageLists (\r
	87	IN EFI_HII_HANDLE Handle,\r
	88	OUT EFI_HII_PACKAGE_LIST_HEADER **PackageListHeader,\r
	89	OUT UINTN *PackageListSize\r
	90	)\r
	91	;\r
	92	\r
	93	/**\r
	94	Extract Hii package list GUID for given HII handle.\r
	95	\r
	96	If HiiHandle could not be found in the HII database, then ASSERT.\r
	97	If Guid is NULL, then ASSERT.\r
	98	\r
	99	@param Handle Hii handle\r
	100	@param Guid Package list GUID\r
	101	\r
	102	@retval EFI_SUCCESS Successfully extract GUID from Hii database.\r
	103	\r
	104	**/\r
	105	EFI_STATUS\r
	106	EFIAPI\r
	107	ExtractGuidFromHiiHandle (\r
	108	IN EFI_HII_HANDLE Handle,\r
	109	OUT EFI_GUID *Guid\r
	110	)\r
	111	;\r
	112	\r
ee3428bb	113	/**\r
26a76fbc	114	Find the corressponding UEFI HII Handle from a Framework HII Handle given.\r
ee3428bb	115	\r
26a76fbc LG	116	@param Private The HII Thunk Module Private context.\r
26a76fbc LG	117	@param FwHiiHandle The Framemwork HII Handle.\r
ee3428bb	118	\r
26a76fbc LG	119	@return NULL If Framework HII Handle is invalid.\r
26a76fbc LG	120	@return The corresponding UEFI HII Handle.\r
ee3428bb	121	**/\r
ee3428bb	122	EFI_HII_HANDLE\r
0368663f	123	FwHiiHandleToUefiHiiHandle (\r
26a76fbc	124	IN CONST HII_THUNK_PRIVATE_DATA *Private,\r
0368663f	125	IN FRAMEWORK_EFI_HII_HANDLE FwHiiHandle\r
e00e1d46	126	);\r
ebbd2793	127	\r
26a76fbc LG	128	/**\r
	129	Find the corressponding HII Thunk Context from a Framework HII Handle given.\r
	130	\r
	131	@param Private The HII Thunk Module Private context.\r
	132	@param FwHiiHandle The Framemwork HII Handle.\r
	133	\r
	134	@return NULL If Framework HII Handle is invalid.\r
	135	@return The corresponding HII Thunk Context.\r
	136	**/\r
0368663f	137	HII_THUNK_CONTEXT *\r
0368663f	138	FwHiiHandleToThunkContext (\r
26a76fbc	139	IN CONST HII_THUNK_PRIVATE_DATA *Private,\r
0368663f	140	IN FRAMEWORK_EFI_HII_HANDLE FwHiiHandle\r
e00e1d46	141	);\r
ebbd2793	142	\r
26a76fbc LG	143	/**\r
	144	Find the corressponding HII Thunk Context from a UEFI HII Handle given.\r
	145	\r
	146	@param Private The HII Thunk Module Private context.\r
	147	@param UefiHiiHandle The UEFI HII Handle.\r
	148	\r
	149	@return NULL If UEFI HII Handle is invalid.\r
	150	@return The corresponding HII Thunk Context.\r
	151	**/\r
0368663f	152	HII_THUNK_CONTEXT *\r
0368663f	153	UefiHiiHandleToThunkContext (\r
26a76fbc	154	IN CONST HII_THUNK_PRIVATE_DATA *Private,\r
ea58467b	155	IN EFI_HII_HANDLE UefiHiiHandle\r
e00e1d46	156	);\r
99a83b4c	157	\r
26a76fbc LG	158	/**\r
	159	Find the corressponding HII Thunk Context from a Tag GUID.\r
	160	\r
	161	@param Private The HII Thunk Module Private context.\r
	162	@param Guid The Tag GUID.\r
	163	\r
	164	@return NULL No HII Thunk Context matched the Tag GUID.\r
	165	@return The corresponding HII Thunk Context.\r
	166	**/\r
8ea58c07	167	HII_THUNK_CONTEXT *\r
8ea58c07	168	TagGuidToIfrPackThunkContext (\r
0368663f	169	IN CONST HII_THUNK_PRIVATE_DATA *Private,\r
99a83b4c	170	IN CONST EFI_GUID *Guid\r
e00e1d46	171	);\r
99a83b4c	172	\r
26a76fbc LG	173	/**\r
	174	This function create a HII_THUNK_CONTEXT for the input UEFI HiiHandle\r
	175	that is created when a package list registered by a module calling \r
	176	EFI_HII_DATABASE_PROTOCOL.NewPackageList. \r
	177	This function records the PackageListGuid of EFI_HII_PACKAGE_LIST_HEADER \r
	178	into the TagGuid of the created HII_THUNK_CONTEXT.\r
	179	\r
	180	@param UefiHiiHandle The UEFI HII Handle.\r
	181	\r
	182	@return the new created Hii thunk context.\r
	183	\r
	184	**/\r
0368663f	185	HII_THUNK_CONTEXT *\r
0368663f	186	CreateThunkContextForUefiHiiHandle (\r
0368663f	187	IN EFI_HII_HANDLE UefiHiiHandle\r
26a76fbc LG	188	);\r
	189	\r
	190	/**\r
	191	Clean up the HII Thunk Context for a UEFI HII Handle.\r
	192	\r
	193	@param Private The HII Thunk Module Private context.\r
	194	@param UefiHiiHandle The UEFI HII Handle.\r
0368663f	195	\r
26a76fbc	196	**/\r
d4775f2a	197	VOID\r
0368663f	198	DestroyThunkContextForUefiHiiHandle (\r
	199	IN HII_THUNK_PRIVATE_DATA *Private,\r
	200	IN EFI_HII_HANDLE UefiHiiHandle\r
26a76fbc LG	201	);\r
	202	\r
	203	/**\r
	204	Get the number of HII Package for a Package type.\r
0368663f	205	\r
26a76fbc LG	206	@param PackageListHeader The Package List.\r
	207	@param PackageType The Package Type.\r
	208	\r
	209	@return The number of Package for given type.\r
	210	**/\r
0368663f	211	UINTN\r
	212	GetPackageCountByType (\r
	213	IN CONST EFI_HII_PACKAGE_LIST_HEADER *PackageListHeader,\r
	214	IN UINT8 PackageType\r
e00e1d46	215	);\r
0368663f	216	\r
26a76fbc LG	217	/**\r
26a76fbc LG	218	Creat a Thunk Context.\r
0368663f	219	\r
26a76fbc	220	ASSERT if no FormSet Opcode is found.\r
59930165	221	\r
26a76fbc LG	222	@param Private The HII Thunk Private Context.\r
	223	@param StringPackageCount The String package count.\r
	224	@param IfrPackageCount The IFR Package count.\r
0368663f	225	\r
26a76fbc LG	226	@return A newly created Thunk Context.\r
	227	@retval NULL No resource to create a new Thunk Context.\r
	228	**/\r
d4775f2a	229	HII_THUNK_CONTEXT *\r
	230	CreateThunkContext (\r
	231	IN HII_THUNK_PRIVATE_DATA *Private,\r
	232	IN UINTN StringPackageCount,\r
	233	IN UINTN IfrPackageCount\r
e00e1d46	234	);\r
d4775f2a	235	\r
26a76fbc LG	236	/**\r
	237	Destroy the Thunk Context and free up all resource.\r
	238	\r
	239	@param ThunkContext The HII Thunk Private Context to be freed.\r
	240	\r
	241	**/\r
d4775f2a	242	VOID\r
	243	DestroyThunkContext (\r
	244	IN HII_THUNK_CONTEXT *ThunkContext\r
e00e1d46	245	);\r
d4775f2a	246	\r
26a76fbc LG	247	/**\r
	248	Get FormSet GUID.\r
	249	\r
	250	ASSERT if no FormSet Opcode is found.\r
d4775f2a	251	\r
26a76fbc LG	252	@param Packages Form Framework Package.\r
	253	@param FormSetGuid Return the FormSet Guid.\r
	254	\r
	255	**/\r
bc226416	256	VOID\r
	257	GetFormSetGuid (\r
	258	IN EFI_HII_PACKAGE_HEADER *Package,\r
	259	OUT EFI_GUID *FormSetGuid\r
26a76fbc LG	260	);\r
	261	\r
	262	/**\r
	263	Get the Form Package from a Framework Package List.\r
	264	\r
	265	@param Packages Framework Package List.\r
bc226416	266	\r
26a76fbc LG	267	@return The Form Package Header found.\r
26a76fbc LG	268	**/\r
bc226416	269	EFI_HII_PACKAGE_HEADER *\r
	270	GetIfrPackage (\r
	271	IN CONST EFI_HII_PACKAGES *Packages\r
26a76fbc	272	);\r
bc226416	273	\r
26a76fbc LG	274	/**\r
	275	Parse the Form Package and build a FORM_BROWSER_FORMSET structure.\r
	276	\r
	277	@param UefiHiiHandle PackageList Handle\r
	278	\r
	279	@return A pointer to FORM_BROWSER_FORMSET.\r
	280	\r
	281	**/\r
a9d85320	282	FORM_BROWSER_FORMSET *\r
	283	ParseFormSet (\r
	284	IN EFI_HII_HANDLE UefiHiiHandle\r
26a76fbc	285	);\r
a9d85320	286	\r
4259256b	287	#endif\r