ShellPkg: Add function comments and refine code format to follow EDKII coding style.

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Qiu Shumin <shumin.qiu@intel.com>
Reviewed-by: Ruiyu Ni <ruiyu.ni@intel.com>

git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@18186 6f19259b-4bc3-4df7-8a09-765794883524

1 files changed, 123 insertions, 7 deletions

diff --git a/ShellPkg/Library/UefiShellTftpCommandLib/Tftp.c b/ShellPkg/Library/UefiShellTftpCommandLib/Tftp.c
index b872afdb89..d8374850fb 100644
--- a/ShellPkg/Library/UefiShellTftpCommandLib/Tftp.c
+++ b/ShellPkg/Library/UefiShellTftpCommandLib/Tftp.c
@@ -36,18 +36,69 @@ STATIC CONST CHAR16 mTftpProgressFrame[] = L"[
 // (TFTP_PROGRESS_MESSAGE_SIZE-1) '\b'

 STATIC CONST CHAR16 mTftpProgressDelete[] = L"\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b";

 

-STATIC BOOLEAN StringToUint16 (

+/**

+  Check and convert the UINT16 option values of the 'tftp' command

+

+  @param[in]  ValueStr  Value as an Unicode encoded string

+  @param[out] Value     UINT16 value

+

+  @return     TRUE      The value was returned.

+  @return     FALSE     A parsing error occured.

+**/

+STATIC 

+BOOLEAN 

+StringToUint16 (

   IN   CONST CHAR16  *ValueStr,

   OUT  UINT16        *Value

   );

 

-STATIC EFI_STATUS GetNicName (

+/**

+  Get the name of the NIC.

+

+  @param[in]   ControllerHandle  The network physical device handle.

+  @param[in]   NicNumber         The network physical device number.

+  @param[out]  NicName           Address where to store the NIC name.

+                                 The memory area has to be at least

+                                 IP4_NIC_NAME_LENGTH bytes wide.

+

+  @return  EFI_SUCCESS  The name of the NIC was returned.

+  @return  Others       The creation of the child for the Managed

+                        Network Service failed or the opening of

+                        the Managed Network Protocol failed or

+                        the operational parameters for the

+                        Managed Network Protocol could not be

+                        read.

+**/

+STATIC 

+EFI_STATUS 

+GetNicName (

   IN   EFI_HANDLE  ControllerHandle,

   IN   UINTN       Index,

   OUT  CHAR16      *NicName

   );

 

-STATIC EFI_STATUS CreateServiceChildAndOpenProtocol (

+/**

+  Create a child for the service identified by its service binding protocol GUID

+  and get from the child the interface of the protocol identified by its GUID.

+

+  @param[in]   ControllerHandle            Controller handle.

+  @param[in]   ServiceBindingProtocolGuid  Service binding protocol GUID of the

+                                           service to be created.

+  @param[in]   ProtocolGuid                GUID of the protocol to be open.

+  @param[out]  ChildHandle                 Address where the handler of the

+                                           created child is returned. NULL is

+                                           returned in case of error.

+  @param[out]  Interface                   Address where a pointer to the

+                                           protocol interface is returned in

+                                           case of success.

+

+  @return  EFI_SUCCESS  The child was created and the protocol opened.

+  @return  Others       Either the creation of the child or the opening

+                        of the protocol failed.

+**/

+STATIC 

+EFI_STATUS 

+CreateServiceChildAndOpenProtocol (

   IN   EFI_HANDLE  ControllerHandle,

   IN   EFI_GUID    *ServiceBindingProtocolGuid,

   IN   EFI_GUID    *ProtocolGuid,

@@ -55,20 +106,71 @@ STATIC EFI_STATUS CreateServiceChildAndOpenProtocol (
   OUT  VOID        **Interface

   );

 

-STATIC VOID CloseProtocolAndDestroyServiceChild (

+/**

+  Close the protocol identified by its GUID on the child handle of the service

+  identified by its service binding protocol GUID, then destroy the child

+  handle.

+

+  @param[in]  ControllerHandle            Controller handle.

+  @param[in]  ServiceBindingProtocolGuid  Service binding protocol GUID of the

+                                          service to be destroyed.

+  @param[in]  ProtocolGuid                GUID of the protocol to be closed.

+  @param[in]  ChildHandle                 Handle of the child to be destroyed.

+

+**/

+STATIC 

+VOID 

+CloseProtocolAndDestroyServiceChild (

   IN  EFI_HANDLE  ControllerHandle,

   IN  EFI_GUID    *ServiceBindingProtocolGuid,

   IN  EFI_GUID    *ProtocolGuid,

   IN  EFI_HANDLE  ChildHandle

   );

 

-STATIC EFI_STATUS GetFileSize (

+/**

+  Worker function that gets the size in numbers of bytes of a file from a TFTP

+  server before to download the file.

+

+  @param[in]   Mtftp4    MTFTP4 protocol interface

+  @param[in]   FilePath  Path of the file, ASCII encoded

+  @param[out]  FileSize  Address where to store the file size in number of

+                         bytes.

+

+  @retval  EFI_SUCCESS      The size of the file was returned.

+  @retval  EFI_UNSUPPORTED  The server does not support the "tsize" option.

+  @retval  Others           Error when retrieving the information from the server

+                            (see EFI_MTFTP4_PROTOCOL.GetInfo() status codes)

+                            or error when parsing the response of the server.

+**/

+STATIC 

+EFI_STATUS 

+GetFileSize (

   IN   EFI_MTFTP4_PROTOCOL  *Mtftp4,

   IN   CONST CHAR8          *FilePath,

   OUT  UINTN                *FileSize

   );

 

-STATIC EFI_STATUS DownloadFile (

+/**

+  Worker function that download the data of a file from a TFTP server given

+  the path of the file and its size.

+

+  @param[in]   Mtftp4         MTFTP4 protocol interface

+  @param[in]   FilePath       Path of the file, Unicode encoded

+  @param[in]   AsciiFilePath  Path of the file, ASCII encoded

+  @param[in]   FileSize       Size of the file in number of bytes

+  @param[out]  Data           Address where to store the address of the buffer

+                              where the data of the file were downloaded in

+                              case of success.

+

+  @retval  EFI_SUCCESS           The file was downloaded.

+  @retval  EFI_OUT_OF_RESOURCES  A memory allocation failed.

+  @retval  Others                The downloading of the file from the server failed

+                                 (see EFI_MTFTP4_PROTOCOL.ReadFile() status codes).

+

+**/

+STATIC 

+EFI_STATUS 

+DownloadFile (

   IN   EFI_MTFTP4_PROTOCOL  *Mtftp4,

   IN   CONST CHAR16         *FilePath,

   IN   CONST CHAR8          *AsciiFilePath,

@@ -76,7 +178,21 @@ STATIC EFI_STATUS DownloadFile (
   OUT  VOID                 **Data

   );

 

-STATIC EFI_STATUS CheckPacket (

+/**

+  Update the progress of a file download

+  This procedure is called each time a new TFTP packet is received.

+

+  @param[in]  This       MTFTP4 protocol interface

+  @param[in]  Token      Parameters for the download of the file

+  @param[in]  PacketLen  Length of the packet

+  @param[in]  Packet     Address of the packet

+

+  @retval  EFI_SUCCESS  All packets are accepted.

+

+**/

+STATIC 

+EFI_STATUS 

+CheckPacket (

   IN EFI_MTFTP4_PROTOCOL  *This,

   IN EFI_MTFTP4_TOKEN     *Token,

   IN UINT16               PacketLen,