Clarify @pram b in Base.h. Accepted and edited in Qing Huang changes for @retval...

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

diff --git a/IntelFrameworkPkg/Include/Protocol/SectionExtraction.h b/IntelFrameworkPkg/Include/Protocol/SectionExtraction.h
index 5a91a924681b4e39503b78aae3c33921f36bb93c..025695bb67ab146c74c684d60103ff95ed938bd8 100644 (file)
--- a/IntelFrameworkPkg/Include/Protocol/SectionExtraction.h
+++ b/IntelFrameworkPkg/Include/Protocol/SectionExtraction.h
@@ -1,21 +1,19 @@
 /** @file\r
-  This file declares Section Extraction protocols.\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 - 2007, Intel Corporation All rights\r
-  reserved. This program and the accompanying materials are\r
-  licensed and made available under the terms and conditions of\r
-  the BSD License which accompanies this distribution.  The full\r
-  text of the license may be found at\r
+  Copyright (c) 2006 - 2009, 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
@@ -25,8 +23,6 @@
 #ifndef _SECTION_EXTRACTION_PROTOCOL_H_\r
 #define _SECTION_EXTRACTION_PROTOCOL_H_\r
 \r
-#include <PiDxe.h>\r
-\r
 //\r
 // Protocol GUID definition\r
 //\r
@@ -59,7 +55,7 @@ typedef struct _EFI_SECTION_EXTRACTION_PROTOCOL EFI_SECTION_EXTRACTION_PROTOCOL;
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_OPEN_SECTION_STREAM) (\r
+(EFIAPI *EFI_OPEN_SECTION_STREAM)(\r
   IN  EFI_SECTION_EXTRACTION_PROTOCOL                   *This,\r
   IN  UINTN                                             SectionStreamLength,\r
   IN  VOID                                              *SectionStream,\r
@@ -71,10 +67,13 @@ EFI_STATUS
 \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
+  @param  SectionType           Pointer to an EFI_SECTION_TYPE. If SectionType == NULL, the contents of the \r
+                                entire section stream are returned in Buffer. If SectionType is not NULL, \r
+                                only the requested section is returned. EFI_SECTION_ALL matches all section \r
+                                types and can be used as a wild card to extract all sections in order.\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
+                                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
@@ -98,13 +97,13 @@ EFI_STATUS
   @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
+  @retval EFI_WARN_BUFFER_TOO_SMALL The size of the input buffer is insufficient to contain the requested\r
+                                    section. The input buffer is filled and section contents are truncated.\r
 \r
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_GET_SECTION) (\r
+(EFIAPI *EFI_GET_SECTION)(\r
   IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,\r
   IN UINTN                                              SectionStreamHandle,\r
   IN EFI_SECTION_TYPE                                   *SectionType,\r
@@ -127,7 +126,7 @@ EFI_STATUS
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_CLOSE_SECTION_STREAM) (\r
+(EFIAPI *EFI_CLOSE_SECTION_STREAM)(\r
   IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,\r
   IN UINTN                                              SectionStreamHandle\r
   );\r
@@ -135,25 +134,21 @@ EFI_STATUS
 //\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
+  ///\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