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 162