2 This file declares Section Extraction Protocol.
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.
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.
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.
16 @par Revision Reference:
17 This protocol is defined in Firmware Volume Specification.
22 #ifndef _SECTION_EXTRACTION_PROTOCOL_H_
23 #define _SECTION_EXTRACTION_PROTOCOL_H_
26 // Protocol GUID definition
28 #define EFI_SECTION_EXTRACTION_PROTOCOL_GUID \
30 0x448F5DA4, 0x6DD7, 0x4FE1, {0x93, 0x07, 0x69, 0x22, 0x41, 0x92, 0x21, 0x5D } \
33 typedef struct _EFI_SECTION_EXTRACTION_PROTOCOL EFI_SECTION_EXTRACTION_PROTOCOL
;
36 // Protocol member functions
39 Creates and returns a new section stream handle to represent the new section stream.
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.
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
51 @retval EFI_INVALID_PARAMETER The section stream may be corrupt or the value
52 of SectionStreamLength may be incorrect.
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
65 Reads and returns a single section from a section stream.
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
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
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.
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
,
117 IN OUT UINTN
*BufferSize
,
118 OUT UINT32
*AuthenticationStatus
122 Deletes a section stream handle and returns all associated resources to the system.
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.
133 (EFIAPI
*EFI_CLOSE_SECTION_STREAM
)(
134 IN EFI_SECTION_EXTRACTION_PROTOCOL
*This
,
135 IN UINTN SectionStreamHandle
139 // Protocol definition
141 struct _EFI_SECTION_EXTRACTION_PROTOCOL
{
143 /// Takes a bounded stream of sections and returns a section stream handle.
145 EFI_OPEN_SECTION_STREAM OpenSectionStream
;
148 /// Given a section stream handle, retrieves the requested section and
149 /// meta-data from the section stream.
151 EFI_GET_SECTION GetSection
;
154 /// Given a section stream handle, closes the section stream.
156 EFI_CLOSE_SECTION_STREAM CloseSectionStream
;
159 extern EFI_GUID gEfiSectionExtractionProtocolGuid
;