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