BaseTools:Change the path of the file that Binary Cache
[mirror_edk2.git] / MdeModulePkg / Universal / Network / Ip4Dxe / Ip4Igmp.h
index 6c48d6a..0cc9445 100644 (file)
@@ -1,27 +1,24 @@
 /** @file\r
 \r
-Copyright (c) 2005 - 2006, Intel Corporation\r
-All rights reserved. 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\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
-\r
-Module Name:\r
-\r
-  Ip4Igmp.h\r
-\r
-Abstract:\r
-\r
+Copyright (c) 2005 - 2015, Intel Corporation. All rights reserved.<BR>\r
+SPDX-License-Identifier: BSD-2-Clause-Patent\r
 \r
 **/\r
 \r
 #ifndef __EFI_IP4_IGMP_H__\r
 #define __EFI_IP4_IGMP_H__\r
 \r
+//\r
+// IGMP message type\r
+//\r
+#define IGMP_MEMBERSHIP_QUERY      0x11\r
+#define IGMP_V1_MEMBERSHIP_REPORT  0x12\r
+#define IGMP_V2_MEMBERSHIP_REPORT  0x16\r
+#define IGMP_LEAVE_GROUP           0x17\r
+\r
+#define IGMP_V1ROUTER_PRESENT      400\r
+#define IGMP_UNSOLICIATED_REPORT   10\r
+\r
 #pragma pack(1)\r
 typedef struct {\r
   UINT8                   Type;\r
@@ -56,65 +53,149 @@ typedef struct {
   LIST_ENTRY              Groups;\r
 } IGMP_SERVICE_DATA;\r
 \r
-typedef enum {\r
-  //\r
-  // IGMP message type\r
-  //\r
-  IGMP_MEMBERSHIP_QUERY     = 0x11,\r
-  IGMP_V1_MEMBERSHIP_REPORT = 0x12,\r
-  IGMP_V2_MEMBERSHIP_REPORT = 0x16,\r
-  IGMP_LEAVE_GROUP          = 0x17,\r
+/**\r
+  Init the IGMP control data of the IP4 service instance, configure\r
+  MNP to receive ALL SYSTEM multicast.\r
 \r
-  IGMP_V1ROUTER_PRESENT     = 400,\r
-  IGMP_UNSOLICIATED_REPORT  = 10\r
-} IGMP_ENUM_TYPES;\r
+  @param[in, out]  IpSb          The IP4 service whose IGMP is to be initialized.\r
 \r
+  @retval EFI_SUCCESS            IGMP of the IpSb is successfully initialized.\r
+  @retval EFI_OUT_OF_RESOURCES   Failed to allocate resource to initialize IGMP.\r
+  @retval Others                 Failed to initialize the IGMP of IpSb.\r
+\r
+**/\r
 EFI_STATUS\r
 Ip4InitIgmp (\r
-  IN IP4_SERVICE          *IpService\r
+  IN OUT IP4_SERVICE            *IpSb\r
   );\r
 \r
+/**\r
+  Join the multicast group on behalf of this IP4 child\r
+\r
+  @param[in]  IpInstance         The IP4 child that wants to join the group.\r
+  @param[in]  Address            The group to join.\r
+\r
+  @retval EFI_SUCCESS            Successfully join the multicast group.\r
+  @retval EFI_OUT_OF_RESOURCES   Failed to allocate resources.\r
+  @retval Others                 Failed to join the multicast group.\r
+\r
+**/\r
 EFI_STATUS\r
 Ip4JoinGroup (\r
-  IN IP4_PROTOCOL         *IpInstance,\r
-  IN IP4_ADDR             Address\r
+  IN IP4_PROTOCOL           *IpInstance,\r
+  IN IP4_ADDR               Address\r
   );\r
 \r
+/**\r
+  Leave the IP4 multicast group on behalf of IpInstance.\r
+\r
+  @param[in]  IpInstance         The IP4 child that wants to leave the group\r
+                                 address.\r
+  @param[in]  Address            The group address to leave.\r
+\r
+  @retval EFI_NOT_FOUND          The IP4 service instance isn't in the group.\r
+  @retval EFI_SUCCESS            Successfully leave the multicast group.\r
+  @retval Others                 Failed to leave the multicast group.\r
+\r
+**/\r
 EFI_STATUS\r
 Ip4LeaveGroup (\r
-  IN IP4_PROTOCOL         *IpInstance,\r
-  IN IP4_ADDR             Address\r
+  IN IP4_PROTOCOL           *IpInstance,\r
+  IN IP4_ADDR               Address\r
   );\r
 \r
+/**\r
+  Handle the received IGMP message for the IP4 service instance.\r
+\r
+  @param[in]  IpSb               The IP4 service instance that received the message.\r
+  @param[in]  Head               The IP4 header of the received message.\r
+  @param[in]  Packet             The IGMP message, without IP4 header.\r
+\r
+  @retval EFI_INVALID_PARAMETER  The IGMP message is malformated.\r
+  @retval EFI_SUCCESS            The IGMP message is successfully processed.\r
+\r
+**/\r
 EFI_STATUS\r
 Ip4IgmpHandle (\r
-  IN IP4_SERVICE          *IpService,\r
-  IN IP4_HEAD             *Head,\r
-  IN NET_BUF              *Packet\r
+  IN IP4_SERVICE            *IpSb,\r
+  IN IP4_HEAD               *Head,\r
+  IN NET_BUF                *Packet\r
   );\r
 \r
+/**\r
+  The periodical timer function for IGMP. It does the following\r
+  things:\r
+  1. Decrease the Igmpv1QuerySeen to make it possible to refresh\r
+     the IGMP server type.\r
+  2. Decrease the report timer for each IGMP group in "delaying\r
+     member" state.\r
+\r
+  @param[in]  IpSb                   The IP4 service instance that is ticking.\r
+\r
+**/\r
 VOID\r
 Ip4IgmpTicking (\r
-  IN IP4_SERVICE          *IpService\r
+  IN IP4_SERVICE            *IpSb\r
   );\r
 \r
+/**\r
+  Add a group address to the array of group addresses.\r
+  The caller should make sure that no duplicated address\r
+  existed in the array. Although the function doesn't\r
+  assume the byte order of the both Source and Addr, the\r
+  network byte order is used by the caller.\r
+\r
+  @param[in]  Source                 The array of group addresses to add to.\r
+  @param[in]  Count                  The number of group addresses in the Source.\r
+  @param[in]  Addr                   The IP4 multicast address to add.\r
+\r
+  @return NULL if failed to allocate memory for the new groups,\r
+          otherwise the new combined group addresses.\r
+\r
+**/\r
 IP4_ADDR *\r
 Ip4CombineGroups (\r
-  IN  IP4_ADDR            *SourceGroups,\r
-  IN  UINT32              Count,\r
-  IN  IP4_ADDR            Addr\r
+  IN  IP4_ADDR              *Source,\r
+  IN  UINT32                Count,\r
+  IN  IP4_ADDR              Addr\r
   );\r
 \r
+/**\r
+  Remove a group address from the array of group addresses.\r
+  Although the function doesn't assume the byte order of the\r
+  both Groups and Addr, the network byte order is used by\r
+  the caller.\r
+\r
+  @param  Groups            The array of group addresses to remove from.\r
+  @param  Count             The number of group addresses in the Groups.\r
+  @param  Addr              The IP4 multicast address to remove.\r
+\r
+  @return The nubmer of group addresses in the Groups after remove.\r
+          It is Count if the Addr isn't in the Groups.\r
+\r
+**/\r
 INTN\r
 Ip4RemoveGroupAddr (\r
-  IN IP4_ADDR             *Group,\r
-  IN UINT32               GroupCnt,\r
-  IN IP4_ADDR             Addr\r
+  IN OUT IP4_ADDR               *Groups,\r
+  IN     UINT32                 Count,\r
+  IN     IP4_ADDR               Addr\r
   );\r
 \r
+/**\r
+  Find the IGMP_GROUP structure which contains the status of multicast\r
+  group Address in this IGMP control block\r
+\r
+  @param[in]  IgmpCtrl               The IGMP control block to search from.\r
+  @param[in]  Address                The multicast address to search.\r
+\r
+  @return NULL if the multicast address isn't in the IGMP control block. Otherwise\r
+          the point to the IGMP_GROUP which contains the status of multicast group\r
+          for Address.\r
+\r
+**/\r
 IGMP_GROUP *\r
 Ip4FindGroup (\r
-  IN IGMP_SERVICE_DATA    *IgmpCtrl,\r
-  IN IP4_ADDR             Address\r
+  IN IGMP_SERVICE_DATA      *IgmpCtrl,\r
+  IN IP4_ADDR               Address\r
   );\r
 #endif\r