[mirror_edk2.git] / IntelFrameworkPkg / Include / Protocol / SectionExtraction.h

/** @file\r
  This file declares Section Extraction Protocol.\r
\r
  This interface provides a means of decoding a set of sections into a linked list of\r
  leaf sections.  This provides for an extensible and flexible file format.\r
\r
Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
This program and the accompanying materials are licensed and made available under\r
the terms and conditions of the BSD License that accompanies this distribution.\r
The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php.\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
  @par Revision Reference:\r
  This protocol is defined in Firmware Volume Specification.\r
  Version 0.9.\r
\r
**/\r
\r
#ifndef _SECTION_EXTRACTION_PROTOCOL_H_\r
#define _SECTION_EXTRACTION_PROTOCOL_H_\r
\r
//\r
// Protocol GUID definition\r
//\r
#define EFI_SECTION_EXTRACTION_PROTOCOL_GUID \\r
  { \\r
    0x448F5DA4, 0x6DD7, 0x4FE1, {0x93, 0x07, 0x69, 0x22, 0x41, 0x92, 0x21, 0x5D } \\r
  }\r
\r
typedef struct _EFI_SECTION_EXTRACTION_PROTOCOL EFI_SECTION_EXTRACTION_PROTOCOL;\r
\r
//\r
// Protocol member functions\r
//\r
/**\r
  Creates and returns a new section stream handle to represent the new section stream.\r
\r
  @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.\r
  @param  SectionStreamLength   The size in bytes of the section stream.\r
  @param  SectionStream         A buffer containing the new section stream.\r
  @param  SectionStreamHandle   A pointer to a caller-allocated UINTN that,\r
                                on output, contains the new section stream handle.\r
\r
  @retval EFI_SUCCESS           The SectionStream was successfully processed, and\r
                                the section stream handle was returned.\r
  @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to\r
                                process the request.\r
  @retval EFI_INVALID_PARAMETER The section stream may be corrupt or the value\r
                                of SectionStreamLength may be incorrect.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_OPEN_SECTION_STREAM)(\r
  IN  EFI_SECTION_EXTRACTION_PROTOCOL                   *This,\r
  IN  UINTN                                             SectionStreamLength,\r
  IN  VOID                                              *SectionStream,\r
  OUT UINTN                                             *SectionStreamHandle\r
  );\r
\r
/**\r
  Reads and returns a single section from a section stream.\r
\r
  @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.\r
  @param  SectionStreamHandle   Indicates from which section stream to read.\r
  @param  SectionType           The pointer to an EFI_SECTION_TYPE. If SectionType == NULL,\r
                                the contents of the entire section stream are returned\r
                                in Buffer. If SectionType is not NULL, only the\r
                                requested section is returned. EFI_SECTION_ALL\r
                                matches all section types and can be used as a\r
                                wild card to extract all sections in order.\r
  @param  SectionDefinitionGuid The pointer to an EFI_GUID. If SectionType ==\r
                                EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid\r
                                indicates what section GUID to search for. If\r
                                SectionType !=EFI_SECTION_GUID_DEFINED, then\r
                                SectionDefinitionGuid is unused and is ignored.\r
  @param  SectionInstance       Indicates which instance of the requested section\r
                                type to return when SectionType is not NULL.\r
  @param  SectionStreamHandle   A pointer to a caller-allocated UINTN that, on output,\r
                                contains the new section stream handle.\r
  @param  Buffer                Pointer to a pointer to a buffer in which the section\r
                                contents are returned.\r
  @param  BufferSize            A pointer to a caller-allocated UINTN.\r
  @param  AuthenticationStatus  A pointer to a caller-allocated UINT32 in\r
                                which any meta-data from encapsulation GUID-defined\r
                                sections is returned.\r
\r
  @retval EFI_SUCCESS           The SectionStream was successfully processed and\r
                                the section contents were returned in Buffer.\r
  @retval EFI_PROTOCOL_ERROR    A GUID-defined section was encountered inthe section\r
                                stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED\r
                                bit set, but there was no corresponding GUIDed\r
                                Section Extraction Protocol in the handle database.\r
  @retval EFI_NOT_FOUND         An error was encountered when parsing the SectionStream,\r
                                which indicates that the SectionStream is not\r
                                correctly formatted. Or, the requested section does not exist.\r
  @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to process\r
                                the request.\r
  @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.\r
  @retval EFI_WARN_BUFFER_TOO_SMALL The size of the input buffer is insufficient\r
                                    to contain the requested section. The input\r
                                    buffer is filled and section contents are truncated.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_GET_SECTION)(\r
  IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,\r
  IN UINTN                                              SectionStreamHandle,\r
  IN EFI_SECTION_TYPE                                   *SectionType,\r
  IN EFI_GUID                                           *SectionDefinitionGuid,\r
  IN UINTN                                              SectionInstance,\r
  IN VOID                                               **Buffer,\r
  IN OUT UINTN                                          *BufferSize,\r
  OUT UINT32                                            *AuthenticationStatus\r
  );\r
\r
/**\r
  Deletes a section stream handle and returns all associated resources to the system.\r
\r
  @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.\r
  @param  SectionStreamHandle   Indicates the section stream to close.\r
  @retval EFI_SUCCESS           The SectionStream was successfully processed and\r
                                the section stream handle was returned.\r
  @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_CLOSE_SECTION_STREAM)(\r
  IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,\r
  IN UINTN                                              SectionStreamHandle\r
  );\r
\r
//\r
// Protocol definition\r
//\r
struct _EFI_SECTION_EXTRACTION_PROTOCOL {\r
  ///\r
  ///  Takes a bounded stream of sections and returns a section stream handle.\r
  ///\r
  EFI_OPEN_SECTION_STREAM   OpenSectionStream;\r
\r
  ///\r
  ///  Given a section stream handle, retrieves the requested section and\r
  ///  meta-data from the section stream.\r
  ///\r
  EFI_GET_SECTION           GetSection;\r
\r
  ///\r
  ///  Given a section stream handle, closes the section stream.\r
  ///\r
  EFI_CLOSE_SECTION_STREAM  CloseSectionStream;\r
};\r
\r
extern EFI_GUID gEfiSectionExtractionProtocolGuid;\r
\r
#endif\r
Commit	Line	Data
79964ac8	1	/** @file\r
b4124f44	2	This file declares Section Extraction Protocol.\r
79964ac8	3	\r
	4	This interface provides a means of decoding a set of sections into a linked list of\r
	5	leaf sections. This provides for an extensible and flexible file format.\r
	6	\r
1c2f052d LG	7	Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
	8	This program and the accompanying materials are licensed and made available under\r
	9	the terms and conditions of the BSD License that accompanies this distribution.\r
f22f941e	10	The full text of the license may be found at\r
1c2f052d LG	11	http://opensource.org/licenses/bsd-license.php.\r
	12	\r
	13	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
f22f941e	14	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
79964ac8	15	\r
79964ac8	16	@par Revision Reference:\r
79964ac8	17	This protocol is defined in Firmware Volume Specification.\r
f22f941e	18	Version 0.9.\r
79964ac8	19	\r
	20	**/\r
	21	\r
	22	#ifndef _SECTION_EXTRACTION_PROTOCOL_H_\r
	23	#define _SECTION_EXTRACTION_PROTOCOL_H_\r
	24	\r
79964ac8	25	//\r
	26	// Protocol GUID definition\r
	27	//\r
	28	#define EFI_SECTION_EXTRACTION_PROTOCOL_GUID \\r
	29	{ \\r
	30	0x448F5DA4, 0x6DD7, 0x4FE1, {0x93, 0x07, 0x69, 0x22, 0x41, 0x92, 0x21, 0x5D } \\r
	31	}\r
	32	\r
	33	typedef struct _EFI_SECTION_EXTRACTION_PROTOCOL EFI_SECTION_EXTRACTION_PROTOCOL;\r
	34	\r
	35	//\r
	36	// Protocol member functions\r
	37	//\r
	38	/**\r
	39	Creates and returns a new section stream handle to represent the new section stream.\r
	40	\r
	41	@param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.\r
f22f941e	42	@param SectionStreamLength The size in bytes of the section stream.\r
f22f941e	43	@param SectionStream A buffer containing the new section stream.\r
79964ac8	44	@param SectionStreamHandle A pointer to a caller-allocated UINTN that,\r
	45	on output, contains the new section stream handle.\r
	46	\r
f22f941e	47	@retval EFI_SUCCESS The SectionStream was successfully processed, and\r
79964ac8	48	the section stream handle was returned.\r
	49	@retval EFI_OUT_OF_RESOURCES The system has insufficient resources to\r
	50	process the request.\r
	51	@retval EFI_INVALID_PARAMETER The section stream may be corrupt or the value\r
	52	of SectionStreamLength may be incorrect.\r
	53	\r
	54	**/\r
	55	typedef\r
	56	EFI_STATUS\r
69686d56	57	(EFIAPI *EFI_OPEN_SECTION_STREAM)(\r
79964ac8	58	IN EFI_SECTION_EXTRACTION_PROTOCOL *This,\r
	59	IN UINTN SectionStreamLength,\r
	60	IN VOID *SectionStream,\r
	61	OUT UINTN *SectionStreamHandle\r
	62	);\r
	63	\r
	64	/**\r
	65	Reads and returns a single section from a section stream.\r
	66	\r
	67	@param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.\r
	68	@param SectionStreamHandle Indicates from which section stream to read.\r
1c2f052d LG	69	@param SectionType The pointer to an EFI_SECTION_TYPE. If SectionType == NULL,\r
	70	the contents of the entire section stream are returned\r
	71	in Buffer. If SectionType is not NULL, only the\r
	72	requested section is returned. EFI_SECTION_ALL\r
	73	matches all section types and can be used as a\r
f22f941e	74	wild card to extract all sections in order.\r
f22f941e	75	@param SectionDefinitionGuid The pointer to an EFI_GUID. If SectionType ==\r
1c2f052d LG	76	EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid\r
1c2f052d LG	77	indicates what section GUID to search for. If\r
f22f941e	78	SectionType !=EFI_SECTION_GUID_DEFINED, then\r
79964ac8	79	SectionDefinitionGuid is unused and is ignored.\r
	80	@param SectionInstance Indicates which instance of the requested section\r
	81	type to return when SectionType is not NULL.\r
	82	@param SectionStreamHandle A pointer to a caller-allocated UINTN that, on output,\r
	83	contains the new section stream handle.\r
	84	@param Buffer Pointer to a pointer to a buffer in which the section\r
	85	contents are returned.\r
f22f941e	86	@param BufferSize A pointer to a caller-allocated UINTN.\r
f22f941e	87	@param AuthenticationStatus A pointer to a caller-allocated UINT32 in\r
1c2f052d	88	which any meta-data from encapsulation GUID-defined\r
f22f941e	89	sections is returned.\r
79964ac8	90	\r
	91	@retval EFI_SUCCESS The SectionStream was successfully processed and\r
	92	the section contents were returned in Buffer.\r
f22f941e	93	@retval EFI_PROTOCOL_ERROR A GUID-defined section was encountered inthe section\r
1c2f052d LG	94	stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED\r
1c2f052d LG	95	bit set, but there was no corresponding GUIDed\r
f22f941e	96	Section Extraction Protocol in the handle database.\r
79964ac8	97	@retval EFI_NOT_FOUND An error was encountered when parsing the SectionStream,\r
1c2f052d	98	which indicates that the SectionStream is not\r
f22f941e	99	correctly formatted. Or, the requested section does not exist.\r
79964ac8	100	@retval EFI_OUT_OF_RESOURCES The system has insufficient resources to process\r
	101	the request.\r
	102	@retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.\r
1c2f052d LG	103	@retval EFI_WARN_BUFFER_TOO_SMALL The size of the input buffer is insufficient\r
1c2f052d LG	104	to contain the requested section. The input\r
f22f941e	105	buffer is filled and section contents are truncated.\r
79964ac8	106	\r
	107	**/\r
	108	typedef\r
	109	EFI_STATUS\r
69686d56	110	(EFIAPI *EFI_GET_SECTION)(\r
79964ac8	111	IN EFI_SECTION_EXTRACTION_PROTOCOL *This,\r
	112	IN UINTN SectionStreamHandle,\r
	113	IN EFI_SECTION_TYPE *SectionType,\r
	114	IN EFI_GUID *SectionDefinitionGuid,\r
	115	IN UINTN SectionInstance,\r
	116	IN VOID **Buffer,\r
	117	IN OUT UINTN *BufferSize,\r
	118	OUT UINT32 *AuthenticationStatus\r
	119	);\r
	120	\r
	121	/**\r
	122	Deletes a section stream handle and returns all associated resources to the system.\r
	123	\r
	124	@param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.\r
	125	@param SectionStreamHandle Indicates the section stream to close.\r
	126	@retval EFI_SUCCESS The SectionStream was successfully processed and\r
	127	the section stream handle was returned.\r
	128	@retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.\r
	129	\r
	130	**/\r
	131	typedef\r
	132	EFI_STATUS\r
69686d56	133	(EFIAPI *EFI_CLOSE_SECTION_STREAM)(\r
79964ac8	134	IN EFI_SECTION_EXTRACTION_PROTOCOL *This,\r
	135	IN UINTN SectionStreamHandle\r
	136	);\r
	137	\r
	138	//\r
	139	// Protocol definition\r
	140	//\r
79964ac8	141	struct _EFI_SECTION_EXTRACTION_PROTOCOL {\r
2bbaeb0d	142	///\r
	143	/// Takes a bounded stream of sections and returns a section stream handle.\r
	144	///\r
79964ac8	145	EFI_OPEN_SECTION_STREAM OpenSectionStream;\r
2bbaeb0d	146	\r
	147	///\r
	148	/// Given a section stream handle, retrieves the requested section and\r
	149	/// meta-data from the section stream.\r
	150	///\r
79964ac8	151	EFI_GET_SECTION GetSection;\r
2bbaeb0d	152	\r
	153	///\r
	154	/// Given a section stream handle, closes the section stream.\r
	155	///\r
79964ac8	156	EFI_CLOSE_SECTION_STREAM CloseSectionStream;\r
	157	};\r
	158	\r
	159	extern EFI_GUID gEfiSectionExtractionProtocolGuid;\r
	160	\r
	161	#endif\r