Correct two minor comments

[mirror_edk2.git] / MdePkg / Library / HiiLib / HiiLib.c

diff --git a/MdePkg/Library/HiiLib/HiiLib.c b/MdePkg/Library/HiiLib/HiiLib.c
index db9112026fb6563a8439ad2d6c4dc80451e70fab..29899f5d8c463e7d3f1570871742568311498250 100644 (file)
--- a/MdePkg/Library/HiiLib/HiiLib.c
+++ b/MdePkg/Library/HiiLib/HiiLib.c
@@ -18,29 +18,35 @@ CONST EFI_HII_DATABASE_PROTOCOL   *mHiiDatabaseProt = NULL;
 CONST EFI_HII_STRING_PROTOCOL     *mHiiStringProt = NULL;\r
 \r
 /**\r
-\r
   This function locate Hii relative protocols for later usage.\r
+    \r
+  The constructor function caches the protocol pointer of HII Database Protocol\r
+  and Hii String Protocol.\r
+  \r
+  It will ASSERT() if either of the protocol can't be located.\r
+\r
+  @param  ImageHandle   The firmware allocated handle for the EFI image.\r
+  @param  SystemTable   A pointer to the EFI System Table.\r
+\r
+  @retval EFI_SUCCESS   The constructor always returns EFI_SUCCESS.\r
 \r
 **/\r
-VOID\r
-LocateHiiProtocols (\r
-  VOID\r
+EFI_STATUS\r
+EFIAPI\r
+HiiLibConstructor (\r
+  IN EFI_HANDLE        ImageHandle,\r
+  IN EFI_SYSTEM_TABLE  *SystemTable\r
   )\r
 {\r
   EFI_STATUS  Status;\r
 \r
-  if (mHiiStringProt != NULL && mHiiDatabaseProt != NULL) {\r
-    //\r
-    // Only need to initialize the protocol instance once.\r
-    //\r
-    return;\r
-  }\r
-\r
   Status = gBS->LocateProtocol (&gEfiHiiDatabaseProtocolGuid, NULL, (VOID **) &mHiiDatabaseProt);\r
   ASSERT_EFI_ERROR (Status);\r
 \r
   Status = gBS->LocateProtocol (&gEfiHiiStringProtocolGuid, NULL, (VOID **) &mHiiStringProt);\r
   ASSERT_EFI_ERROR (Status);\r
+\r
+  return EFI_SUCCESS;\r
 }\r
 \r
 \r
@@ -55,7 +61,7 @@ LocateHiiProtocols (
   typedef struct {\r
     UINT32                  BinaryLength;\r
     EFI_HII_PACKAGE_HEADER  PackageHeader;\r
-  } TIANO_AUTOGEN_PACKAGES_HEADER;\r
+  } EDKII_AUTOGEN_PACKAGES_HEADER;\r
   #pragma pack (pop)\r
 \r
   If there is not enough resource for the new package list,\r
@@ -149,8 +155,7 @@ InternalHiiLibPreparePackages (
   @param  GuidId                 Package GUID.\r
   @param  ...                    Variable argument list for packages to be assembled.\r
 \r
-  @return EFI_HII_PACKAGE_LIST_HEADER Pointer of EFI_HII_PACKAGE_LIST_HEADER. The function will ASSERT if system has\r
-                                      not enough resource to complete the operation.\r
+  @return Pointer of EFI_HII_PACKAGE_LIST_HEADER.\r
 \r
 **/\r
 EFI_HII_PACKAGE_LIST_HEADER *\r
@@ -214,8 +219,6 @@ HiiLibAddPackages (
 \r
   ASSERT (HiiHandle != NULL);\r
 \r
-  LocateHiiProtocols ();\r
-\r
   VA_START (Args, HiiHandle);\r
   PackageListHeader = InternalHiiLibPreparePackages (NumberOfPackages, GuidId, Args);\r
 \r
@@ -251,8 +254,6 @@ HiiLibRemovePackages (
   EFI_STATUS Status;\r
   ASSERT (IsHiiHandleRegistered (HiiHandle));\r
 \r
-  LocateHiiProtocols ();\r
-\r
   Status = mHiiDatabaseProt->RemovePackageList (mHiiDatabaseProt, HiiHandle);\r
   ASSERT_EFI_ERROR (Status);\r
 }\r
@@ -288,8 +289,6 @@ HiiLibGetHiiHandles (
 \r
   BufferLength = 0;\r
 \r
-  LocateHiiProtocols ();\r
-\r
   //\r
   // Try to find the actual buffer size for HiiHandle Buffer.\r
   //\r
@@ -354,8 +353,6 @@ HiiLibExtractGuidFromHiiHandle (
   BufferSize = 0;\r
   HiiPackageList = NULL;\r
 \r
-  LocateHiiProtocols ();\r
-\r
   Status = mHiiDatabaseProt->ExportPackageLists (mHiiDatabaseProt, Handle, &BufferSize, HiiPackageList);\r
   ASSERT (Status != EFI_NOT_FOUND);\r
   \r
@@ -451,8 +448,6 @@ HiiLibDevicePathToHiiHandle (
     return NULL;\r
   }\r
 \r
-  LocateHiiProtocols ();\r
-\r
   //\r
   // Retrieve all Hii Handles from HII database\r
   //\r
@@ -539,8 +534,6 @@ HiiLibExportPackageLists (
   ASSERT (PackageListSize != NULL);\r
   ASSERT (PackageListHeader != NULL);\r
 \r
-  LocateHiiProtocols ();\r
-\r
   if (Handle != NULL) {\r
     ASSERT (IsHiiHandleRegistered (Handle));\r
   }\r
@@ -580,13 +573,49 @@ HiiLibExportPackageLists (
   return Status;\r
 }\r
 \r
+/**\r
+  \r
+  This function returns a list of the package handles of the   \r
+  specified type that are currently active in the HII database. The   \r
+  pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package   \r
+  handles to be listed.\r
+\r
+  If HandleBufferLength is NULL, then ASSERT.\r
+  If HandleBuffer is NULL, the ASSERT.\r
+  If PackageType is EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is\r
+  NULL, then ASSERT.\r
+  If PackageType is not EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is not\r
+  NULL, then ASSERT.\r
+  \r
+  \r
+  @param PackageType          Specifies the package type of the packages\r
+                              to list or EFI_HII_PACKAGE_TYPE_ALL for\r
+                              all packages to be listed.\r
+  \r
+  @param PackageGuid          If PackageType is\r
+                              EFI_HII_PACKAGE_TYPE_GUID, then this is\r
+                              the pointer to the GUID which must match\r
+                              the Guid field of\r
+                              EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it\r
+                              must be NULL.\r
+  \r
+  @param HandleBufferLength   On output, the length of the handle buffer\r
+                              that is required for the handles found.\r
+\r
+  @param HandleBuffer         On output, an array of EFI_HII_HANDLE  instances returned.\r
+                              The caller is responcible to free this pointer allocated.\r
 \r
+  @retval EFI_SUCCESS           The matching handles are outputed successfully.\r
+                                HandleBufferLength is updated with the actual length.\r
+  @retval EFI_OUT_OF_RESOURCES  Not enough resource to complete the operation.\r
+  @retval EFI_NOT_FOUND         No matching handle could not be found in database.\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 HiiLibListPackageLists (\r
   IN        UINT8                     PackageType,\r
   IN CONST  EFI_GUID                  *PackageGuid,\r
-  IN OUT    UINTN                     *HandleBufferLength,\r
+  OUT    UINTN                        *HandleBufferLength,\r
   OUT       EFI_HII_HANDLE            **HandleBuffer\r
   )\r
 {\r
@@ -598,7 +627,11 @@ HiiLibListPackageLists (
   *HandleBufferLength = 0;\r
   *HandleBuffer       = NULL;\r
 \r
-  LocateHiiProtocols ();\r
+  if (PackageType == EFI_HII_PACKAGE_TYPE_GUID) {\r
+    ASSERT (PackageGuid != NULL);\r
+  } else {\r
+    ASSERT (PackageGuid == NULL);\r
+  }\r
 \r
   Status = mHiiDatabaseProt->ListPackageLists (\r
                             mHiiDatabaseProt,\r
@@ -609,7 +642,7 @@ HiiLibListPackageLists (
                             );\r
   if (EFI_ERROR (Status) && (Status != EFI_BUFFER_TOO_SMALL)) {\r
     //\r
-    // No packages is registered to UEFI HII Database, just return EFI_SUCCESS.\r
+    // No packages is registered to UEFI HII Database, just return.\r
     // \r
     //\r
     return Status;\r
@@ -653,8 +686,6 @@ IsHiiHandleRegistered (
   HiiPackageList = NULL;\r
   BufferSize = 0;\r
 \r
-  LocateHiiProtocols ();\r
-\r
   Status = mHiiDatabaseProt->ExportPackageLists (\r
              mHiiDatabaseProt,\r
              HiiHandle,\r