EdkCompatibilityPkg/Foundation/Library/Dxe/Include/GetImage.h

   1 /*++
   2
   3 Copyright (c) 2006 - 2007, Intel Corporation
   4 All rights reserved. This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13
  14   GetImage.h
  15
  16 Abstract:
  17
  18   Image data retrieval support for common use.
  19
  20 --*/
  21
  22 #ifndef _GET_IMAGE_H_
  23 #define _GET_IMAGE_H_
  24 #include "EfiImageFormat.h"
  25
  26 EFI_STATUS
  27 GetImage (
  28   IN  EFI_GUID           *NameGuid,
  29   IN  EFI_SECTION_TYPE   SectionType,
  30   OUT VOID               **Buffer,
  31   OUT UINTN              *Size
  32   )
  33 /*++
  34
  35 Routine Description:
  36   Enumerate all the FVs, and fill Buffer with the SectionType section content in NameGuid file.
  37
  38   Note:
  39   1. when SectionType is EFI_SECTION_PE32, it tries to read NameGuid file after failure on
  40       reading EFI_SECTION_PE32 section.
  41   2. when SectionType is EFI_SECTION_TE, it tries to get EFI_SECTION_PE32 section after failure on
  42       reading EFI_SECTION_TE section. If it's failed again, it tries to read NameGuid file.
  43   3. Callee allocates memory, which caller is responsible to free.
  44
  45 Arguments:
  46
  47   NameGuid            - Pointer to EFI_GUID, which is file name.
  48   SectionType         - Required section type.
  49   Buffer              - Pointer to a pointer in which the read content is returned.
  50                           Caller is responsible to free Buffer.
  51   Size                - Pointer to a UINTN, which indicates the size of returned *Buffer.
  52
  53 Returns:
  54   EFI_NOT_FOUND       - Required content can not be found.
  55   EFI_SUCCESS         - Required content can be found, but whether the Buffer is filled
  56                           with section content or not depends on the Buffer and Size.
  57 --*/
  58 ;
  59
  60 EFI_STATUS
  61 GetImageEx (
  62   IN  EFI_HANDLE         ImageHandle,
  63   IN  EFI_GUID           *NameGuid,
  64   IN  EFI_SECTION_TYPE   SectionType,
  65   OUT VOID               **Buffer,
  66   OUT UINTN              *Size,
  67   BOOLEAN                WithinImageFv
  68   )
  69 /*++
  70
  71 Routine Description:
  72   Search FVs, and fill Buffer with the SectionType section content in NameGuid file.
  73   If ImageHandle is not NULL, the FV from which the ImageHandle is loaded is searched
  74   first. If WithinImageFv is TRUE, only the FV from which the ImageHandle is loaded
  75   is searched. If ImageHandle is NULL or WithinImageFv is FALSE, all FVs in the system
  76   is searched.
  77
  78   Note:
  79   1. when SectionType is EFI_SECTION_PE32, it tries to read NameGuid file after failure on
  80       reading EFI_SECTION_PE32 section.
  81   2. when SectionType is EFI_SECTION_TE, it tries to get EFI_SECTION_PE32 section after failure on
  82       reading EFI_SECTION_TE section. If it's failed again, it tries to read NameGuid file.
  83   3. Callee allocates memory, which caller is responsible to free.
  84
  85 Arguments:
  86
  87   ImageHandle         - The caller's driver image handle.
  88   NameGuid            - Pointer to EFI_GUID, which is file name.
  89   SectionType         - Required section type.
  90   Buffer              - Pointer to a pointer in which the read content is returned.
  91                           Caller is responsible to free Buffer.
  92   Size                - Pointer to a UINTN, which indicates the size of returned *Buffer.
  93   WithinImageFv       - Whether the search only performs on the FV from which the caller's
  94                         driver image is loaded.
  95
  96 Returns:
  97   EFI_INVALID_PARAMETER - ImageHandle is NULL and WithinImageFv is TRUE.
  98   EFI_NOT_FOUND         - Required content can not be found.
  99   EFI_SUCCESS           - Required content can be found, but whether the Buffer is filled
 100                           with section content or not depends on the Buffer and Size.
 101 --*/
 102 ;
 103
 104 #endif //_GET_IMAGE_H_