IntelFrameworkPkg/Include/Protocol/SectionExtraction.h

   1 /** @file
   2   This file declares Section Extraction Protocol.
   3
   4   This interface provides a means of decoding a set of sections into a linked list of
   5   leaf sections.  This provides for an extensible and flexible file format.
   6
   7 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>
   8 This program and the accompanying materials are licensed and made available under
   9 the terms and conditions of the BSD License that accompanies this distribution.
  10 The full text of the license may be found at
  11 http://opensource.org/licenses/bsd-license.php.
  12
  13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16   @par Revision Reference:
  17   This protocol is defined in Firmware Volume Specification.
  18   Version 0.9.
  19
  20 **/
  21
  22 #ifndef _SECTION_EXTRACTION_PROTOCOL_H_
  23 #define _SECTION_EXTRACTION_PROTOCOL_H_
  24
  25 //
  26 // Protocol GUID definition
  27 //
  28 #define EFI_SECTION_EXTRACTION_PROTOCOL_GUID \
  29   { \
  30     0x448F5DA4, 0x6DD7, 0x4FE1, {0x93, 0x07, 0x69, 0x22, 0x41, 0x92, 0x21, 0x5D } \
  31   }
  32
  33 typedef struct _EFI_SECTION_EXTRACTION_PROTOCOL EFI_SECTION_EXTRACTION_PROTOCOL;
  34
  35 //
  36 // Protocol member functions
  37 //
  38 /**
  39   Creates and returns a new section stream handle to represent the new section stream.
  40
  41   @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
  42   @param  SectionStreamLength   The size in bytes of the section stream.
  43   @param  SectionStream         A buffer containing the new section stream.
  44   @param  SectionStreamHandle   A pointer to a caller-allocated UINTN that,
  45                                 on output, contains the new section stream handle.
  46
  47   @retval EFI_SUCCESS           The SectionStream was successfully processed, and
  48                                 the section stream handle was returned.
  49   @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to
  50                                 process the request.
  51   @retval EFI_INVALID_PARAMETER The section stream may be corrupt or the value
  52                                 of SectionStreamLength may be incorrect.
  53
  54 **/
  55 typedef
  56 EFI_STATUS
  57 (EFIAPI *EFI_OPEN_SECTION_STREAM)(
  58   IN  EFI_SECTION_EXTRACTION_PROTOCOL                   *This,
  59   IN  UINTN                                             SectionStreamLength,
  60   IN  VOID                                              *SectionStream,
  61   OUT UINTN                                             *SectionStreamHandle
  62   );
  63
  64 /**
  65   Reads and returns a single section from a section stream.
  66
  67   @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
  68   @param  SectionStreamHandle   Indicates from which section stream to read.
  69   @param  SectionType           The pointer to an EFI_SECTION_TYPE. If SectionType == NULL,
  70                                 the contents of the entire section stream are returned
  71                                 in Buffer. If SectionType is not NULL, only the
  72                                 requested section is returned. EFI_SECTION_ALL
  73                                 matches all section types and can be used as a
  74                                 wild card to extract all sections in order.
  75   @param  SectionDefinitionGuid The pointer to an EFI_GUID. If SectionType ==
  76                                 EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid
  77                                 indicates what section GUID to search for. If
  78                                 SectionType !=EFI_SECTION_GUID_DEFINED, then
  79                                 SectionDefinitionGuid is unused and is ignored.
  80   @param  SectionInstance       Indicates which instance of the requested section
  81                                 type to return when SectionType is not NULL.
  82   @param  SectionStreamHandle   A pointer to a caller-allocated UINTN that, on output,
  83                                 contains the new section stream handle.
  84   @param  Buffer                Pointer to a pointer to a buffer in which the section
  85                                 contents are returned.
  86   @param  BufferSize            A pointer to a caller-allocated UINTN.
  87   @param  AuthenticationStatus  A pointer to a caller-allocated UINT32 in
  88                                 which any meta-data from encapsulation GUID-defined
  89                                 sections is returned.
  90
  91   @retval EFI_SUCCESS           The SectionStream was successfully processed and
  92                                 the section contents were returned in Buffer.
  93   @retval EFI_PROTOCOL_ERROR    A GUID-defined section was encountered inthe section
  94                                 stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED
  95                                 bit set, but there was no corresponding GUIDed
  96                                 Section Extraction Protocol in the handle database.
  97   @retval EFI_NOT_FOUND         An error was encountered when parsing the SectionStream,
  98                                 which indicates that the SectionStream is not
  99                                 correctly formatted. Or, the requested section does not exist.
 100   @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to process
 101                                 the request.
 102   @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
 103   @retval EFI_WARN_BUFFER_TOO_SMALL The size of the input buffer is insufficient
 104                                     to contain the requested section. The input
 105                                     buffer is filled and section contents are truncated.
 106
 107 **/
 108 typedef
 109 EFI_STATUS
 110 (EFIAPI *EFI_GET_SECTION)(
 111   IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,
 112   IN UINTN                                              SectionStreamHandle,
 113   IN EFI_SECTION_TYPE                                   *SectionType,
 114   IN EFI_GUID                                           *SectionDefinitionGuid,
 115   IN UINTN                                              SectionInstance,
 116   IN VOID                                               **Buffer,
 117   IN OUT UINTN                                          *BufferSize,
 118   OUT UINT32                                            *AuthenticationStatus
 119   );
 120
 121 /**
 122   Deletes a section stream handle and returns all associated resources to the system.
 123
 124   @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
 125   @param  SectionStreamHandle   Indicates the section stream to close.
 126   @retval EFI_SUCCESS           The SectionStream was successfully processed and
 127                                 the section stream handle was returned.
 128   @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
 129
 130 **/
 131 typedef
 132 EFI_STATUS
 133 (EFIAPI *EFI_CLOSE_SECTION_STREAM)(
 134   IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,
 135   IN UINTN                                              SectionStreamHandle
 136   );
 137
 138 //
 139 // Protocol definition
 140 //
 141 struct _EFI_SECTION_EXTRACTION_PROTOCOL {
 142   ///
 143   ///  Takes a bounded stream of sections and returns a section stream handle.
 144   ///
 145   EFI_OPEN_SECTION_STREAM   OpenSectionStream;
 146
 147   ///
 148   ///  Given a section stream handle, retrieves the requested section and
 149   ///  meta-data from the section stream.
 150   ///
 151   EFI_GET_SECTION           GetSection;
 152
 153   ///
 154   ///  Given a section stream handle, closes the section stream.
 155   ///
 156   EFI_CLOSE_SECTION_STREAM  CloseSectionStream;
 157 };
 158
 159 extern EFI_GUID gEfiSectionExtractionProtocolGuid;
 160
 161 #endif