MdePkg/Include/Protocol/SectionExtraction.h

   1 /** @file
   2   This file declares Section Extraction protocol.
   3
   4   The section extraction protocol is referenced in the PI 1.0 specification, but
   5   not defined. It will likely be added in an eratta update.
   6
   7   Copyright (c) 2006, Intel Corporation
   8   All rights reserved. This program and the materials
   9   are licensed and made available under the terms and conditions of the BSD License
  10   which accompanies this distribution.  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 **/
  17
  18 #ifndef __SECTION_EXTRACTION_PROTOCOL_H__
  19 #define __SECTION_EXTRACTION_PROTOCOL_H__
  20
  21
  22
  23 typedef struct _EFI_SECTION_EXTRACTION_PROTOCOL EFI_SECTION_EXTRACTION_PROTOCOL;
  24
  25 //
  26 // Protocol member functions
  27 //
  28 /**
  29   Creates and returns a new section stream handle to represent the new section stream.
  30
  31   @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
  32   @param  SectionStreamLength   Size in bytes of the section stream.
  33   @param  SectionStream         Buffer containing the new section stream.
  34   @param  SectionStreamHandle   A pointer to a caller-allocated UINTN that,
  35                                 on output, contains the new section stream handle.
  36
  37   @retval EFI_SUCCESS           The SectionStream was successfully processed and
  38                                 the section stream handle was returned.
  39   @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to
  40                                 process the request.
  41   @retval EFI_INVALID_PARAMETER The section stream may be corrupt or the value
  42                                 of SectionStreamLength may be incorrect.
  43
  44 **/
  45 typedef
  46 EFI_STATUS
  47 (EFIAPI *EFI_OPEN_SECTION_STREAM) (
  48   IN  EFI_SECTION_EXTRACTION_PROTOCOL                   *This,
  49   IN  UINTN                                             SectionStreamLength,
  50   IN  VOID                                              *SectionStream,
  51   OUT UINTN                                             *SectionStreamHandle
  52   );
  53
  54 /**
  55   Reads and returns a single section from a section stream.
  56
  57   @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
  58   @param  SectionStreamHandle   Indicates from which section stream to read.
  59   @param  SectionType           Pointer to an EFI_SECTION_TYPE.
  60   @param  SectionDefinitionGuid Pointer to an EFI_GUID.If SectionType ==
  61                                 EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid indicates what section GUID
  62                                 to search for.If SectionType !=EFI_SECTION_GUID_DEFINED, then
  63                                 SectionDefinitionGuid is unused and is ignored.
  64   @param  SectionInstance       Indicates which instance of the requested section
  65                                 type to return when SectionType is not NULL.
  66   @param  SectionStreamHandle   A pointer to a caller-allocated UINTN that, on output,
  67                                 contains the new section stream handle.
  68   @param  Buffer                Pointer to a pointer to a buffer in which the section
  69                                 contents are returned.
  70   @param  BufferSize            Pointer to a caller-allocated UINTN.
  71   @param  AuthenticationStatus  Pointer to a caller-allocated UINT32 in
  72                                 which any meta-data from encapsulation GUID-defined sections is returned.
  73
  74   @retval EFI_SUCCESS           The SectionStream was successfully processed and
  75                                 the section contents were returned in Buffer.
  76   @retval EFI_PROTOCOL_ERROR    A GUID-defined section was encountered in
  77                                 the section stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED bit set,
  78                                 but there was no corresponding GUIDed Section Extraction Protocol in
  79                                 the handle database.
  80   @retval EFI_NOT_FOUND         An error was encountered when parsing the SectionStream,
  81                                 which indicates that the SectionStream is not correctly formatted.
  82                                 Or The requested section does not exist.
  83   @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to process
  84                                 the request.
  85   @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
  86   @retval EFI_BUFFER_TOO_SMALL  The size of the input buffer is insufficient to
  87                                 contain the requested section.
  88
  89 **/
  90 typedef
  91 EFI_STATUS
  92 (EFIAPI *EFI_GET_SECTION) (
  93   IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,
  94   IN UINTN                                              SectionStreamHandle,
  95   IN EFI_SECTION_TYPE                                   *SectionType,
  96   IN EFI_GUID                                           *SectionDefinitionGuid,
  97   IN UINTN                                              SectionInstance,
  98   IN VOID                                               **Buffer,
  99   IN OUT UINTN                                          *BufferSize,
 100   OUT UINT32                                            *AuthenticationStatus
 101   );
 102
 103 /**
 104   Deletes a section stream handle and returns all associated resources to the system.
 105
 106   @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
 107   @param  SectionStreamHandle   Indicates the section stream to close.
 108   @retval EFI_SUCCESS           The SectionStream was successfully processed and
 109                                 the section stream handle was returned.
 110   @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
 111
 112 **/
 113 typedef
 114 EFI_STATUS
 115 (EFIAPI *EFI_CLOSE_SECTION_STREAM) (
 116   IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,
 117   IN UINTN                                              SectionStreamHandle
 118   );
 119
 120 /**
 121   @par Protocol Description:
 122   The Section Extraction Protocol provides a simple method of extracting
 123   sections from arbitrarily complex files.
 124
 125   @param OpenSectionStream
 126   Takes a bounded stream of sections and returns a section stream handle.
 127
 128   @param GetSection
 129   Given a section stream handle, retrieves the requested section and
 130   meta-data from the section stream.
 131
 132   @param CloseSectionStream
 133   Given a section stream handle, closes the section stream.
 134
 135 **/
 136 struct _EFI_SECTION_EXTRACTION_PROTOCOL {
 137   EFI_OPEN_SECTION_STREAM   OpenSectionStream;
 138   EFI_GET_SECTION           GetSection;
 139   EFI_CLOSE_SECTION_STREAM  CloseSectionStream;
 140 };
 141
 142 #endif