// (TFTP_PROGRESS_MESSAGE_SIZE-1) '\b'\r
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";\r
\r
-STATIC BOOLEAN StringToUint16 (\r
+/**\r
+ Check and convert the UINT16 option values of the 'tftp' command\r
+\r
+ @param[in] ValueStr Value as an Unicode encoded string\r
+ @param[out] Value UINT16 value\r
+\r
+ @return TRUE The value was returned.\r
+ @return FALSE A parsing error occured.\r
+**/\r
+STATIC \r
+BOOLEAN \r
+StringToUint16 (\r
IN CONST CHAR16 *ValueStr,\r
OUT UINT16 *Value\r
);\r
\r
-STATIC EFI_STATUS GetNicName (\r
+/**\r
+ Get the name of the NIC.\r
+\r
+ @param[in] ControllerHandle The network physical device handle.\r
+ @param[in] NicNumber The network physical device number.\r
+ @param[out] NicName Address where to store the NIC name.\r
+ The memory area has to be at least\r
+ IP4_NIC_NAME_LENGTH bytes wide.\r
+\r
+ @return EFI_SUCCESS The name of the NIC was returned.\r
+ @return Others The creation of the child for the Managed\r
+ Network Service failed or the opening of\r
+ the Managed Network Protocol failed or\r
+ the operational parameters for the\r
+ Managed Network Protocol could not be\r
+ read.\r
+**/\r
+STATIC \r
+EFI_STATUS \r
+GetNicName (\r
IN EFI_HANDLE ControllerHandle,\r
IN UINTN Index,\r
OUT CHAR16 *NicName\r
);\r
\r
-STATIC EFI_STATUS CreateServiceChildAndOpenProtocol (\r
+/**\r
+ Create a child for the service identified by its service binding protocol GUID\r
+ and get from the child the interface of the protocol identified by its GUID.\r
+\r
+ @param[in] ControllerHandle Controller handle.\r
+ @param[in] ServiceBindingProtocolGuid Service binding protocol GUID of the\r
+ service to be created.\r
+ @param[in] ProtocolGuid GUID of the protocol to be open.\r
+ @param[out] ChildHandle Address where the handler of the\r
+ created child is returned. NULL is\r
+ returned in case of error.\r
+ @param[out] Interface Address where a pointer to the\r
+ protocol interface is returned in\r
+ case of success.\r
+\r
+ @return EFI_SUCCESS The child was created and the protocol opened.\r
+ @return Others Either the creation of the child or the opening\r
+ of the protocol failed.\r
+**/\r
+STATIC \r
+EFI_STATUS \r
+CreateServiceChildAndOpenProtocol (\r
IN EFI_HANDLE ControllerHandle,\r
IN EFI_GUID *ServiceBindingProtocolGuid,\r
IN EFI_GUID *ProtocolGuid,\r
OUT VOID **Interface\r
);\r
\r
-STATIC VOID CloseProtocolAndDestroyServiceChild (\r
+/**\r
+ Close the protocol identified by its GUID on the child handle of the service\r
+ identified by its service binding protocol GUID, then destroy the child\r
+ handle.\r
+\r
+ @param[in] ControllerHandle Controller handle.\r
+ @param[in] ServiceBindingProtocolGuid Service binding protocol GUID of the\r
+ service to be destroyed.\r
+ @param[in] ProtocolGuid GUID of the protocol to be closed.\r
+ @param[in] ChildHandle Handle of the child to be destroyed.\r
+\r
+**/\r
+STATIC \r
+VOID \r
+CloseProtocolAndDestroyServiceChild (\r
IN EFI_HANDLE ControllerHandle,\r
IN EFI_GUID *ServiceBindingProtocolGuid,\r
IN EFI_GUID *ProtocolGuid,\r
IN EFI_HANDLE ChildHandle\r
);\r
\r
-STATIC EFI_STATUS GetFileSize (\r
+/**\r
+ Worker function that gets the size in numbers of bytes of a file from a TFTP\r
+ server before to download the file.\r
+\r
+ @param[in] Mtftp4 MTFTP4 protocol interface\r
+ @param[in] FilePath Path of the file, ASCII encoded\r
+ @param[out] FileSize Address where to store the file size in number of\r
+ bytes.\r
+\r
+ @retval EFI_SUCCESS The size of the file was returned.\r
+ @retval EFI_UNSUPPORTED The server does not support the "tsize" option.\r
+ @retval Others Error when retrieving the information from the server\r
+ (see EFI_MTFTP4_PROTOCOL.GetInfo() status codes)\r
+ or error when parsing the response of the server.\r
+**/\r
+STATIC \r
+EFI_STATUS \r
+GetFileSize (\r
IN EFI_MTFTP4_PROTOCOL *Mtftp4,\r
IN CONST CHAR8 *FilePath,\r
OUT UINTN *FileSize\r
);\r
\r
-STATIC EFI_STATUS DownloadFile (\r
+/**\r
+ Worker function that download the data of a file from a TFTP server given\r
+ the path of the file and its size.\r
+\r
+ @param[in] Mtftp4 MTFTP4 protocol interface\r
+ @param[in] FilePath Path of the file, Unicode encoded\r
+ @param[in] AsciiFilePath Path of the file, ASCII encoded\r
+ @param[in] FileSize Size of the file in number of bytes\r
+ @param[out] Data Address where to store the address of the buffer\r
+ where the data of the file were downloaded in\r
+ case of success.\r
+\r
+ @retval EFI_SUCCESS The file was downloaded.\r
+ @retval EFI_OUT_OF_RESOURCES A memory allocation failed.\r
+ @retval Others The downloading of the file from the server failed\r
+ (see EFI_MTFTP4_PROTOCOL.ReadFile() status codes).\r
+\r
+**/\r
+STATIC \r
+EFI_STATUS \r
+DownloadFile (\r
IN EFI_MTFTP4_PROTOCOL *Mtftp4,\r
IN CONST CHAR16 *FilePath,\r
IN CONST CHAR8 *AsciiFilePath,\r
OUT VOID **Data\r
);\r
\r
-STATIC EFI_STATUS CheckPacket (\r
+/**\r
+ Update the progress of a file download\r
+ This procedure is called each time a new TFTP packet is received.\r
+\r
+ @param[in] This MTFTP4 protocol interface\r
+ @param[in] Token Parameters for the download of the file\r
+ @param[in] PacketLen Length of the packet\r
+ @param[in] Packet Address of the packet\r
+\r
+ @retval EFI_SUCCESS All packets are accepted.\r
+\r
+**/\r
+STATIC \r
+EFI_STATUS \r
+CheckPacket (\r
IN EFI_MTFTP4_PROTOCOL *This,\r
IN EFI_MTFTP4_TOKEN *Token,\r
IN UINT16 PacketLen,\r