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

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