]> git.proxmox.com Git - mirror_edk2.git/blob - IntelFrameworkPkg/Include/Protocol/SectionExtraction.h
Update to BSD license header.
[mirror_edk2.git] / IntelFrameworkPkg / Include / Protocol / SectionExtraction.h
1 /** @file
2 This file declares Section Extraction protocols.
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) 2007, Intel Corporation
8 All rights reserved. This program and the materials
9 are licensed and made available under the terms and conditions of the BSD License
10 which accompanies this distribution. 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 Module Name: SectionExtraction.h
17
18 @par Revision Reference:
19 This protocol is defined in Firmware Volume Specification.
20 Version 0.9
21
22 **/
23
24 #ifndef _SECTION_EXTRACTION_PROTOCOL_H_
25 #define _SECTION_EXTRACTION_PROTOCOL_H_
26
27 #include <PiDxe.h>
28
29 //
30 // Protocol GUID definition
31 //
32 #define EFI_SECTION_EXTRACTION_PROTOCOL_GUID \
33 { \
34 0x448F5DA4, 0x6DD7, 0x4FE1, {0x93, 0x07, 0x69, 0x22, 0x41, 0x92, 0x21, 0x5D } \
35 }
36
37 typedef struct _EFI_SECTION_EXTRACTION_PROTOCOL EFI_SECTION_EXTRACTION_PROTOCOL;
38
39 //
40 // Protocol member functions
41 //
42 /**
43 Creates and returns a new section stream handle to represent the new section stream.
44
45 @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
46 @param SectionStreamLength Size in bytes of the section stream.
47 @param SectionStream Buffer containing the new section stream.
48 @param SectionStreamHandle A pointer to a caller-allocated UINTN that,
49 on output, contains the new section stream handle.
50
51 @retval EFI_SUCCESS The SectionStream was successfully processed and
52 the section stream handle was returned.
53 @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to
54 process the request.
55 @retval EFI_INVALID_PARAMETER The section stream may be corrupt or the value
56 of SectionStreamLength may be incorrect.
57
58 **/
59 typedef
60 EFI_STATUS
61 (EFIAPI *EFI_OPEN_SECTION_STREAM) (
62 IN EFI_SECTION_EXTRACTION_PROTOCOL *This,
63 IN UINTN SectionStreamLength,
64 IN VOID *SectionStream,
65 OUT UINTN *SectionStreamHandle
66 );
67
68 /**
69 Reads and returns a single section from a section stream.
70
71 @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
72 @param SectionStreamHandle Indicates from which section stream to read.
73 @param SectionType Pointer to an EFI_SECTION_TYPE.
74 @param SectionDefinitionGuid Pointer to an EFI_GUID.If SectionType ==
75 EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid indicates what section GUID
76 to search for.If SectionType !=EFI_SECTION_GUID_DEFINED, then
77 SectionDefinitionGuid is unused and is ignored.
78 @param SectionInstance Indicates which instance of the requested section
79 type to return when SectionType is not NULL.
80 @param SectionStreamHandle A pointer to a caller-allocated UINTN that, on output,
81 contains the new section stream handle.
82 @param Buffer Pointer to a pointer to a buffer in which the section
83 contents are returned.
84 @param BufferSize Pointer to a caller-allocated UINTN.
85 @param AuthenticationStatus Pointer to a caller-allocated UINT32 in
86 which any meta-data from encapsulation GUID-defined sections is returned.
87
88 @retval EFI_SUCCESS The SectionStream was successfully processed and
89 the section contents were returned in Buffer.
90 @retval EFI_PROTOCOL_ERROR A GUID-defined section was encountered in
91 the section stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED bit set,
92 but there was no corresponding GUIDed Section Extraction Protocol in
93 the handle database.
94 @retval EFI_NOT_FOUND An error was encountered when parsing the SectionStream,
95 which indicates that the SectionStream is not correctly formatted.
96 Or The requested section does not exist.
97 @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to process
98 the request.
99 @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
100 @retval EFI_BUFFER_TOO_SMALL The size of the input buffer is insufficient to
101 contain the requested section.
102
103 **/
104 typedef
105 EFI_STATUS
106 (EFIAPI *EFI_GET_SECTION) (
107 IN EFI_SECTION_EXTRACTION_PROTOCOL *This,
108 IN UINTN SectionStreamHandle,
109 IN EFI_SECTION_TYPE *SectionType,
110 IN EFI_GUID *SectionDefinitionGuid,
111 IN UINTN SectionInstance,
112 IN VOID **Buffer,
113 IN OUT UINTN *BufferSize,
114 OUT UINT32 *AuthenticationStatus
115 );
116
117 /**
118 Deletes a section stream handle and returns all associated resources to the system.
119
120 @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
121 @param SectionStreamHandle Indicates the section stream to close.
122 @retval EFI_SUCCESS The SectionStream was successfully processed and
123 the section stream handle was returned.
124 @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
125
126 **/
127 typedef
128 EFI_STATUS
129 (EFIAPI *EFI_CLOSE_SECTION_STREAM) (
130 IN EFI_SECTION_EXTRACTION_PROTOCOL *This,
131 IN UINTN SectionStreamHandle
132 );
133
134 //
135 // Protocol definition
136 //
137 /**
138 @par Protocol Description:
139 The Section Extraction Protocol provides a simple method of extracting
140 sections from arbitrarily complex files.
141
142 @param OpenSectionStream
143 Takes a bounded stream of sections and returns a section stream handle.
144
145 @param GetSection
146 Given a section stream handle, retrieves the requested section and
147 meta-data from the section stream.
148
149 @param CloseSectionStream
150 Given a section stream handle, closes the section stream.
151
152 **/
153 struct _EFI_SECTION_EXTRACTION_PROTOCOL {
154 EFI_OPEN_SECTION_STREAM OpenSectionStream;
155 EFI_GET_SECTION GetSection;
156 EFI_CLOSE_SECTION_STREAM CloseSectionStream;
157 };
158
159 extern EFI_GUID gEfiSectionExtractionProtocolGuid;
160
161 #endif