]> git.proxmox.com Git - mirror_edk2.git/blob - IntelFrameworkPkg/Include/Protocol/SectionExtraction.h
Comment update.
[mirror_edk2.git] / IntelFrameworkPkg / Include / Protocol / SectionExtraction.h
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 - 2007, Intel Corporation
8 All rights reserved. This program and the accompanying
9 materials are licensed and made available under the terms and
10 conditions of the BSD License which accompanies this
11 distribution. The full text of the license may be found at
12 http://opensource.org/licenses/bsd-license.php
13
14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16
17 Module Name: SectionExtraction.h
18
19 @par Revision Reference:
20 This protocol is defined in Firmware Volume Specification.
21 Version 0.9
22
23 **/
24
25 #ifndef _SECTION_EXTRACTION_PROTOCOL_H_
26 #define _SECTION_EXTRACTION_PROTOCOL_H_
27
28 #include <PiDxe.h>
29
30 //
31 // Protocol GUID definition
32 //
33 #define EFI_SECTION_EXTRACTION_PROTOCOL_GUID \
34 { \
35 0x448F5DA4, 0x6DD7, 0x4FE1, {0x93, 0x07, 0x69, 0x22, 0x41, 0x92, 0x21, 0x5D } \
36 }
37
38 typedef struct _EFI_SECTION_EXTRACTION_PROTOCOL EFI_SECTION_EXTRACTION_PROTOCOL;
39
40 //
41 // Protocol member functions
42 //
43 /**
44 Creates and returns a new section stream handle to represent the new section stream.
45
46 @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
47 @param SectionStreamLength Size in bytes of the section stream.
48 @param SectionStream Buffer containing the new section stream.
49 @param SectionStreamHandle A pointer to a caller-allocated UINTN that,
50 on output, contains the new section stream handle.
51
52 @retval EFI_SUCCESS The SectionStream was successfully processed and
53 the section stream handle was returned.
54 @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to
55 process the request.
56 @retval EFI_INVALID_PARAMETER The section stream may be corrupt or the value
57 of SectionStreamLength may be incorrect.
58
59 **/
60 typedef
61 EFI_STATUS
62 (EFIAPI *EFI_OPEN_SECTION_STREAM)(
63 IN EFI_SECTION_EXTRACTION_PROTOCOL *This,
64 IN UINTN SectionStreamLength,
65 IN VOID *SectionStream,
66 OUT UINTN *SectionStreamHandle
67 );
68
69 /**
70 Reads and returns a single section from a section stream.
71
72 @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
73 @param SectionStreamHandle Indicates from which section stream to read.
74 @param SectionType Pointer to an EFI_SECTION_TYPE. SectionType == NULL, the contents of the
75 entire section stream are returned in Buffer.If SectionType is not NULL,
76 only the requested section is returned. EFI_SECTION_ALL matches all section
77 types and can be used as a wild card to extract all sections in order.
78 @param SectionDefinitionGuid Pointer to an EFI_GUID.If SectionType ==
79 EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid indicates what section GUID
80 to search for.If SectionType !=EFI_SECTION_GUID_DEFINED, then
81 SectionDefinitionGuid is unused and is ignored.
82 @param SectionInstance Indicates which instance of the requested section
83 type to return when SectionType is not NULL.
84 @param SectionStreamHandle A pointer to a caller-allocated UINTN that, on output,
85 contains the new section stream handle.
86 @param Buffer Pointer to a pointer to a buffer in which the section
87 contents are returned.
88 @param BufferSize Pointer to a caller-allocated UINTN.
89 @param AuthenticationStatus Pointer to a caller-allocated UINT32 in
90 which any meta-data from encapsulation GUID-defined sections is returned.
91
92 @retval EFI_SUCCESS The SectionStream was successfully processed and
93 the section contents were returned in Buffer.
94 @retval EFI_PROTOCOL_ERROR A GUID-defined section was encountered in
95 the section stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED bit set,
96 but there was no corresponding GUIDed Section Extraction Protocol in
97 the handle database.
98 @retval EFI_NOT_FOUND An error was encountered when parsing the SectionStream,
99 which indicates that the SectionStream is not correctly formatted.
100 Or The requested section does not exist.
101 @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to process
102 the request.
103 @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
104 @retval EFI_BUFFER_TOO_SMALL The size of the input buffer is insufficient to
105 contain the requested section.
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 /// Given a section stream handle, retrieves the requested section and
148 /// meta-data from the section stream.
149 ///
150 EFI_GET_SECTION GetSection;
151 ///
152 /// Given a section stream handle, closes the section stream.
153 ///
154 EFI_CLOSE_SECTION_STREAM CloseSectionStream;
155 };
156
157 extern EFI_GUID gEfiSectionExtractionProtocolGuid;
158
159 #endif