audk/IntelFrameworkPkg/Include/Protocol/SectionExtraction.h

/** @file
  This file declares Section Extraction Protocol.

  This interface provides a means of decoding a set of sections into a linked list of
  leaf sections.  This provides for an extensible and flexible file format.

Copyright (c) 2006 - 2010, Intel Corporation.  All rights reserved<BR>
This program and the accompanying materials are licensed and made available under 
the terms and conditions of the BSD License that accompanies this distribution.  
The full text of the license may be found at
http://opensource.org/licenses/bsd-license.php.                                          
    
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

  @par Revision Reference:
  This protocol is defined in Firmware Volume Specification.
  Version 0.9.

**/

#ifndef _SECTION_EXTRACTION_PROTOCOL_H_
#define _SECTION_EXTRACTION_PROTOCOL_H_

//
// Protocol GUID definition
//
#define EFI_SECTION_EXTRACTION_PROTOCOL_GUID \
  { \
    0x448F5DA4, 0x6DD7, 0x4FE1, {0x93, 0x07, 0x69, 0x22, 0x41, 0x92, 0x21, 0x5D } \
  }

typedef struct _EFI_SECTION_EXTRACTION_PROTOCOL EFI_SECTION_EXTRACTION_PROTOCOL;

//
// Protocol member functions
//
/**
  Creates and returns a new section stream handle to represent the new section stream.

  @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
  @param  SectionStreamLength   The size in bytes of the section stream.
  @param  SectionStream         A buffer containing the new section stream.
  @param  SectionStreamHandle   A pointer to a caller-allocated UINTN that,
                                on output, contains the new section stream handle.

  @retval EFI_SUCCESS           The SectionStream was successfully processed, and
                                the section stream handle was returned.
  @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to
                                process the request.
  @retval EFI_INVALID_PARAMETER The section stream may be corrupt or the value
                                of SectionStreamLength may be incorrect.

**/
typedef
EFI_STATUS
(EFIAPI *EFI_OPEN_SECTION_STREAM)(
  IN  EFI_SECTION_EXTRACTION_PROTOCOL                   *This,
  IN  UINTN                                             SectionStreamLength,
  IN  VOID                                              *SectionStream,
  OUT UINTN                                             *SectionStreamHandle
  );

/**
  Reads and returns a single section from a section stream.

  @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
  @param  SectionStreamHandle   Indicates from which section stream to read.
  @param  SectionType           The pointer to an EFI_SECTION_TYPE. If SectionType == NULL, 
                                the contents of the entire section stream are returned 
                                in Buffer. If SectionType is not NULL, only the 
                                requested section is returned. EFI_SECTION_ALL 
                                matches all section types and can be used as a 
                                wild card to extract all sections in order.
  @param  SectionDefinitionGuid The pointer to an EFI_GUID. If SectionType ==
                                EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid 
                                indicates what section GUID to search for. If 
                                SectionType !=EFI_SECTION_GUID_DEFINED, then
                                SectionDefinitionGuid is unused and is ignored.
  @param  SectionInstance       Indicates which instance of the requested section
                                type to return when SectionType is not NULL.
  @param  SectionStreamHandle   A pointer to a caller-allocated UINTN that, on output,
                                contains the new section stream handle.
  @param  Buffer                Pointer to a pointer to a buffer in which the section
                                contents are returned.
  @param  BufferSize            A pointer to a caller-allocated UINTN.
  @param  AuthenticationStatus  A pointer to a caller-allocated UINT32 in
                                which any meta-data from encapsulation GUID-defined 
                                sections is returned.

  @retval EFI_SUCCESS           The SectionStream was successfully processed and
                                the section contents were returned in Buffer.
  @retval EFI_PROTOCOL_ERROR    A GUID-defined section was encountered inthe section
                                stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED 
                                bit set, but there was no corresponding GUIDed 
                                Section Extraction Protocol in the handle database.
  @retval EFI_NOT_FOUND         An error was encountered when parsing the SectionStream,
                                which indicates that the SectionStream is not 
                                correctly formatted. Or, the requested section does not exist.
  @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to process
                                the request.
  @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
  @retval EFI_WARN_BUFFER_TOO_SMALL The size of the input buffer is insufficient 
                                    to contain the requested section. The input 
                                    buffer is filled and section contents are truncated.

**/
typedef
EFI_STATUS
(EFIAPI *EFI_GET_SECTION)(
  IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,
  IN UINTN                                              SectionStreamHandle,
  IN EFI_SECTION_TYPE                                   *SectionType,
  IN EFI_GUID                                           *SectionDefinitionGuid,
  IN UINTN                                              SectionInstance,
  IN VOID                                               **Buffer,
  IN OUT UINTN                                          *BufferSize,
  OUT UINT32                                            *AuthenticationStatus
  );

/**
  Deletes a section stream handle and returns all associated resources to the system.

  @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
  @param  SectionStreamHandle   Indicates the section stream to close.
  @retval EFI_SUCCESS           The SectionStream was successfully processed and
                                the section stream handle was returned.
  @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.

**/
typedef
EFI_STATUS
(EFIAPI *EFI_CLOSE_SECTION_STREAM)(
  IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,
  IN UINTN                                              SectionStreamHandle
  );

//
// Protocol definition
//
struct _EFI_SECTION_EXTRACTION_PROTOCOL {
  ///
  ///  Takes a bounded stream of sections and returns a section stream handle.
  ///
  EFI_OPEN_SECTION_STREAM   OpenSectionStream;

  ///
  ///  Given a section stream handle, retrieves the requested section and
  ///  meta-data from the section stream.
  ///
  EFI_GET_SECTION           GetSection;

  ///
  ///  Given a section stream handle, closes the section stream.
  ///
  EFI_CLOSE_SECTION_STREAM  CloseSectionStream;
};

extern EFI_GUID gEfiSectionExtractionProtocolGuid;

#endif