EdkCompatibilityPkg/Compatibility/FrameworkHiiOnUefiHiiThunk/Utility.h

   1 /** @file
   2
   3   This file contains utility functions by HII Thunk Modules.
   4
   5 Copyright (c) 2006 - 2010, Intel Corporation
   6 All rights reserved. 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 outputed 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