MdeModulePkg/DxeUdpIoLib: Did some code enhancement for UdpIoLib

* Added some ASSERT descriptions for library APIs.
* Added "Optional" option for Context parameter in UdpIoCancelDgrams().
* Added function return status check for UdpIoFreeIo().

Cc: Ye Ting <ting.ye@intel.com>
Cc: Fu Siyuan <siyuan.fu@intel.com>
Cc: Jiaxin Wu <jiaxin.wu@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Wang Fan <fan.wang@intel.com>
Reviewed-by: Fu Siyuan <siyuan.fu@intel.com>

diff --git a/MdeModulePkg/Include/Library/UdpIoLib.h b/MdeModulePkg/Include/Library/UdpIoLib.h
index e0b44ce18e6a3c93ab2c8259c4d759d367e73065..9bfa80e143630599eda354e2ee0cbc94219eceb7 100644 (file)
--- a/MdeModulePkg/Include/Library/UdpIoLib.h
+++ b/MdeModulePkg/Include/Library/UdpIoLib.h
@@ -2,7 +2,7 @@
   This library is used to share code between UEFI network stack modules.\r
   It provides the helper routines to access UDP service. It is used by both DHCP and MTFTP.\r
 \r
-Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR>\r
+Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
 This program and the accompanying materials\r
 are licensed and made available under the terms and conditions of the BSD License\r
 which accompanies this distribution.  The full text of the license may be found at<BR>\r
@@ -197,7 +197,9 @@ BOOLEAN
 \r
 /**\r
   Cancel all the sent datagram that pass the selection criteria of ToCancel.\r
+\r
   If ToCancel is NULL, all the datagrams are cancelled.\r
+  If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().\r
 \r
   @param[in]  UdpIo                 The UDP_IO to cancel packet.\r
   @param[in]  IoStatus              The IoStatus to return to the packet owners.\r
@@ -212,13 +214,16 @@ UdpIoCancelDgrams (
   IN UDP_IO                 *UdpIo,\r
   IN EFI_STATUS             IoStatus,\r
   IN UDP_IO_TO_CANCEL       ToCancel,        OPTIONAL\r
-  IN VOID                   *Context\r
+  IN VOID                   *Context         OPTIONAL\r
   );\r
 \r
 /**\r
   Creates a UDP_IO to access the UDP service. It creates and configures\r
   a UDP child.\r
 \r
+  If Configure is NULL, then ASSERT().\r
+  If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().\r
+\r
   It locates the UDP service binding prototype on the Controller parameter\r
   uses the UDP service binding prototype to create a UDP child (also known as\r
   a UDP instance) configures the UDP child by calling Configure function prototype.\r
@@ -247,11 +252,14 @@ UdpIoCreateIo (
 /**\r
   Free the UDP_IO and all its related resources.\r
 \r
+  If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().\r
+\r
   The function cancels all sent datagrams and receive requests.\r
 \r
   @param[in]  UdpIo             The UDP_IO to free.\r
 \r
   @retval EFI_SUCCESS           The UDP_IO is freed.\r
+  @retval Others                Failed to free UDP_IO.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -264,6 +272,8 @@ UdpIoFreeIo (
   Cleans up the UDP_IO without freeing it. Call this function\r
   if you intend to later re-use the UDP_IO.\r
 \r
+  If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().\r
+\r
   This function releases all transmitted datagrams and receive requests and configures NULL for the UDP instance.\r
 \r
   @param[in]  UdpIo                 The UDP_IO to clean up.\r
@@ -278,6 +288,8 @@ UdpIoCleanIo (
 /**\r
   Send a packet through the UDP_IO.\r
 \r
+  If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().\r
+\r
   The packet will be wrapped in UDP_TX_TOKEN. Function Callback will be called\r
   when the packet is sent. The optional parameter EndPoint overrides the default\r
   address pair if specified.\r
@@ -324,6 +336,8 @@ UdpIoCancelSentDatagram (
 /**\r
   Issue a receive request to the UDP_IO.\r
 \r
+  If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().\r
+\r
   This function is called when upper-layer needs packet from UDP for processing.\r
   Only one receive request is acceptable at a time. Therefore, one common usage model is\r
   to invoke this function inside its Callback function when the former packet\r

diff --git a/MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.c b/MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.c
index 4861095435e6b13eadd2d83856219addb2344b8d..d8edfe19f59c94b033d7da5325d2d186f9d5632e 100644 (file)
--- a/MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.c
+++ b/MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.c
@@ -1,7 +1,7 @@
 /** @file\r
   Help functions to access UDP service, it is used by both the DHCP and MTFTP.\r
 \r
-Copyright (c) 2005 - 2016, Intel Corporation. All rights reserved.<BR>\r
+Copyright (c) 2005 - 2018, Intel Corporation. All rights reserved.<BR>\r
 This program and the accompanying materials\r
 are licensed and made available under the terms and conditions of the BSD License\r
 which accompanies this distribution.  The full text of the license may be found at<BR>\r
@@ -410,6 +410,9 @@ UdpIoCreateRxToken (
 /**\r
   Wrap a transmit request into a new created UDP_TX_TOKEN.\r
 \r
+  If Packet is NULL, then ASSERT().\r
+  If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().\r
+\r
   @param[in]  UdpIo                 The UdpIo to send packet to.\r
   @param[in]  Packet                The user's packet.\r
   @param[in]  EndPoint              The local and remote access point.\r
@@ -580,6 +583,9 @@ UdpIoCreateTxToken (
   Creates a UDP_IO to access the UDP service. It creates and configures\r
   a UDP child.\r
 \r
+  If Configure is NULL, then ASSERT().\r
+  If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().\r
+\r
   It locates the UDP service binding prototype on the Controller parameter\r
   uses the UDP service binding prototype to create a UDP child (also known as\r
   a UDP instance) configures the UDP child by calling Configure function prototype.\r
@@ -749,7 +755,9 @@ FREE_MEM:
 \r
 /**\r
   Cancel all the sent datagram that pass the selection criteria of ToCancel.\r
+\r
   If ToCancel is NULL, all the datagrams are cancelled.\r
+  If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().\r
 \r
   @param[in]  UdpIo                 The UDP_IO to cancel packet.\r
   @param[in]  IoStatus              The IoStatus to return to the packet owners.\r
@@ -764,7 +772,7 @@ UdpIoCancelDgrams (
   IN UDP_IO                 *UdpIo,\r
   IN EFI_STATUS             IoStatus,\r
   IN UDP_IO_TO_CANCEL       ToCancel,        OPTIONAL\r
-  IN VOID                   *Context\r
+  IN VOID                   *Context         OPTIONAL\r
   )\r
 {\r
   LIST_ENTRY                *Entry;\r
@@ -791,11 +799,14 @@ UdpIoCancelDgrams (
 /**\r
   Free the UDP_IO and all its related resources.\r
 \r
+  If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().\r
+\r
   The function will cancel all sent datagram and receive request.\r
 \r
   @param[in]  UdpIo             The UDP_IO to free.\r
 \r
   @retval EFI_SUCCESS           The UDP_IO is freed.\r
+  @retval Others                Failed to free UDP_IO.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -804,6 +815,7 @@ UdpIoFreeIo (
   IN  UDP_IO           *UdpIo\r
   )\r
 {\r
+  EFI_STATUS           Status;\r
   UDP_RX_TOKEN         *RxToken;\r
 \r
   ASSERT ((UdpIo->UdpVersion == UDP_IO_UDP4_VERSION) ||\r
@@ -822,49 +834,67 @@ UdpIoFreeIo (
   if (UdpIo->UdpVersion == UDP_IO_UDP4_VERSION) {\r
 \r
     if ((RxToken = UdpIo->RecvRequest) != NULL) {\r
-      UdpIo->Protocol.Udp4->Cancel (UdpIo->Protocol.Udp4, &RxToken->Token.Udp4);\r
+      Status = UdpIo->Protocol.Udp4->Cancel (UdpIo->Protocol.Udp4, &RxToken->Token.Udp4);\r
+      if (EFI_ERROR (Status)) {\r
+        return Status;\r
+      }\r
     }\r
 \r
     //\r
     // Close then destroy the Udp4 child\r
     //\r
-    gBS->CloseProtocol (\r
-           UdpIo->UdpHandle,\r
-           &gEfiUdp4ProtocolGuid,\r
-           UdpIo->Image,\r
-           UdpIo->Controller\r
-           );\r
+    Status = gBS->CloseProtocol (\r
+                    UdpIo->UdpHandle,\r
+                    &gEfiUdp4ProtocolGuid,\r
+                    UdpIo->Image,\r
+                    UdpIo->Controller\r
+                    );\r
+    if (EFI_ERROR (Status)) {\r
+      return Status;\r
+    }\r
 \r
-    NetLibDestroyServiceChild (\r
-      UdpIo->Controller,\r
-      UdpIo->Image,\r
-      &gEfiUdp4ServiceBindingProtocolGuid,\r
-      UdpIo->UdpHandle\r
-      );\r
+    Status = NetLibDestroyServiceChild (\r
+               UdpIo->Controller,\r
+               UdpIo->Image,\r
+               &gEfiUdp4ServiceBindingProtocolGuid,\r
+               UdpIo->UdpHandle\r
+               );\r
+    if (EFI_ERROR (Status)) {\r
+      return Status;\r
+    }\r
 \r
   } else {\r
 \r
     if ((RxToken = UdpIo->RecvRequest) != NULL) {\r
-      UdpIo->Protocol.Udp6->Cancel (UdpIo->Protocol.Udp6, &RxToken->Token.Udp6);\r
+      Status = UdpIo->Protocol.Udp6->Cancel (UdpIo->Protocol.Udp6, &RxToken->Token.Udp6);\r
+      if (EFI_ERROR (Status)) {\r
+        return Status;\r
+      }\r
     }\r
 \r
     //\r
     // Close then destroy the Udp6 child\r
     //\r
-    gBS->CloseProtocol (\r
-           UdpIo->UdpHandle,\r
-           &gEfiUdp6ProtocolGuid,\r
-           UdpIo->Image,\r
-           UdpIo->Controller\r
-           );\r
+    Status = gBS->CloseProtocol (\r
+               UdpIo->UdpHandle,\r
+               &gEfiUdp6ProtocolGuid,\r
+               UdpIo->Image,\r
+               UdpIo->Controller\r
+               );\r
+    if (EFI_ERROR (Status)) {\r
+      return Status;\r
+    }\r
 \r
-    NetLibDestroyServiceChild (\r
-      UdpIo->Controller,\r
-      UdpIo->Image,\r
-      &gEfiUdp6ServiceBindingProtocolGuid,\r
-      UdpIo->UdpHandle\r
-      );\r
+    Status = NetLibDestroyServiceChild (\r
+               UdpIo->Controller,\r
+               UdpIo->Image,\r
+               &gEfiUdp6ServiceBindingProtocolGuid,\r
+               UdpIo->UdpHandle\r
+               );\r
+    if (EFI_ERROR (Status)) {\r
+      return Status;\r
     }\r
+  }\r
 \r
   if (!IsListEmpty(&UdpIo->Link)) {\r
     RemoveEntryList (&UdpIo->Link);\r
@@ -879,6 +909,8 @@ UdpIoFreeIo (
   Clean up the UDP_IO without freeing it. The function is called when\r
   user wants to re-use the UDP_IO later.\r
 \r
+  If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().\r
+\r
   It will release all the transmitted datagrams and receive request. It will\r
   also configure NULL for the UDP instance.\r
 \r
@@ -920,6 +952,8 @@ UdpIoCleanIo (
 /**\r
   Send a packet through the UDP_IO.\r
 \r
+  If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().\r
+\r
   The packet will be wrapped in UDP_TX_TOKEN. Function Callback will be called\r
   when the packet is sent. The optional parameter EndPoint overrides the default\r
   address pair if specified.\r
@@ -1030,6 +1064,8 @@ UdpIoCancelSentDatagram (
 /**\r
   Issue a receive request to the UDP_IO.\r
 \r
+  If Udp version is not UDP_IO_UDP4_VERSION or UDP_IO_UDP6_VERSION, then ASSERT().\r
+\r
   This function is called when upper-layer needs packet from UDP for processing.\r
   Only one receive request is acceptable at a time so a common usage model is\r
   to invoke this function inside its Callback function when the former packet\r