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 - 2018, Intel Corporation. All rights reserved.<BR>
8 SPDX-License-Identifier: BSD-2-Clause-Patent
10 @par Revision Reference:
11 This protocol is defined in Firmware Volume Specification.
16 #ifndef _SECTION_EXTRACTION_PROTOCOL_H_
17 #define _SECTION_EXTRACTION_PROTOCOL_H_
20 // Protocol GUID definition
22 #define EFI_SECTION_EXTRACTION_PROTOCOL_GUID \
24 0x448F5DA4, 0x6DD7, 0x4FE1, {0x93, 0x07, 0x69, 0x22, 0x41, 0x92, 0x21, 0x5D } \
27 typedef struct _EFI_SECTION_EXTRACTION_PROTOCOL EFI_SECTION_EXTRACTION_PROTOCOL
;
30 // Protocol member functions
33 Creates and returns a new section stream handle to represent the new section stream.
35 @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
36 @param SectionStreamLength The size in bytes of the section stream.
37 @param SectionStream A buffer containing the new section stream.
38 @param SectionStreamHandle A pointer to a caller-allocated UINTN that,
39 on output, contains the new section stream handle.
41 @retval EFI_SUCCESS The SectionStream was successfully processed, and
42 the section stream handle was returned.
43 @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to
45 @retval EFI_INVALID_PARAMETER The section stream may be corrupt or the value
46 of SectionStreamLength may be incorrect.
51 (EFIAPI
*EFI_OPEN_SECTION_STREAM
)(
52 IN EFI_SECTION_EXTRACTION_PROTOCOL
*This
,
53 IN UINTN SectionStreamLength
,
54 IN VOID
*SectionStream
,
55 OUT UINTN
*SectionStreamHandle
59 Reads and returns a single section from a section stream.
61 @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
62 @param SectionStreamHandle Indicates from which section stream to read.
63 @param SectionType The pointer to an EFI_SECTION_TYPE. If SectionType == NULL,
64 the contents of the entire section stream are returned
65 in Buffer. If SectionType is not NULL, only the
66 requested section is returned. EFI_SECTION_ALL
67 matches all section types and can be used as a
68 wild card to extract all sections in order.
69 @param SectionDefinitionGuid The pointer to an EFI_GUID. If SectionType ==
70 EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid
71 indicates what section GUID to search for. If
72 SectionType !=EFI_SECTION_GUID_DEFINED, then
73 SectionDefinitionGuid is unused and is ignored.
74 @param SectionInstance Indicates which instance of the requested section
75 type to return when SectionType is not NULL.
76 @param SectionStreamHandle A pointer to a caller-allocated UINTN that, on output,
77 contains the new section stream handle.
78 @param Buffer Pointer to a pointer to a buffer in which the section
79 contents are returned.
80 @param BufferSize A pointer to a caller-allocated UINTN.
81 @param AuthenticationStatus A pointer to a caller-allocated UINT32 in
82 which any meta-data from encapsulation GUID-defined
85 @retval EFI_SUCCESS The SectionStream was successfully processed and
86 the section contents were returned in Buffer.
87 @retval EFI_PROTOCOL_ERROR A GUID-defined section was encountered inthe section
88 stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED
89 bit set, but there was no corresponding GUIDed
90 Section Extraction Protocol in the handle database.
91 @retval EFI_NOT_FOUND An error was encountered when parsing the SectionStream,
92 which indicates that the SectionStream is not
93 correctly formatted. Or, the requested section does not exist.
94 @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to process
96 @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
97 @retval EFI_WARN_BUFFER_TOO_SMALL The size of the input buffer is insufficient
98 to contain the requested section. The input
99 buffer is filled and section contents are truncated.
104 (EFIAPI
*EFI_GET_SECTION
)(
105 IN EFI_SECTION_EXTRACTION_PROTOCOL
*This
,
106 IN UINTN SectionStreamHandle
,
107 IN EFI_SECTION_TYPE
*SectionType
,
108 IN EFI_GUID
*SectionDefinitionGuid
,
109 IN UINTN SectionInstance
,
111 IN OUT UINTN
*BufferSize
,
112 OUT UINT32
*AuthenticationStatus
116 Deletes a section stream handle and returns all associated resources to the system.
118 @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
119 @param SectionStreamHandle Indicates the section stream to close.
120 @retval EFI_SUCCESS The SectionStream was successfully processed and
121 the section stream handle was returned.
122 @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
127 (EFIAPI
*EFI_CLOSE_SECTION_STREAM
)(
128 IN EFI_SECTION_EXTRACTION_PROTOCOL
*This
,
129 IN UINTN SectionStreamHandle
133 // Protocol definition
135 struct _EFI_SECTION_EXTRACTION_PROTOCOL
{
137 /// Takes a bounded stream of sections and returns a section stream handle.
139 EFI_OPEN_SECTION_STREAM OpenSectionStream
;
142 /// Given a section stream handle, retrieves the requested section and
143 /// meta-data from the section stream.
145 EFI_GET_SECTION GetSection
;
148 /// Given a section stream handle, closes the section stream.
150 EFI_CLOSE_SECTION_STREAM CloseSectionStream
;
153 extern EFI_GUID gEfiSectionExtractionProtocolGuid
;