MdePkg/Include/Protocol/Ip6Config.h

   1 /** @file
   2   This file provides a definition of the EFI IPv6 Configuration
   3   Protocol.
   4
   5 Copyright (c) 2008 - 2017, Intel Corporation. All rights reserved.<BR>
   6 This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at<BR>
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15 #ifndef __EFI_IP6CONFIG_PROTOCOL_H__
  16 #define __EFI_IP6CONFIG_PROTOCOL_H__
  17
  18 #include <Protocol/Ip6.h>
  19
  20 #define EFI_IP6_CONFIG_PROTOCOL_GUID \
  21   { \
  22     0x937fe521, 0x95ae, 0x4d1a, {0x89, 0x29, 0x48, 0xbc, 0xd9, 0x0a, 0xd3, 0x1a } \
  23   }
  24
  25 typedef struct _EFI_IP6_CONFIG_PROTOCOL EFI_IP6_CONFIG_PROTOCOL;
  26
  27 ///
  28 /// EFI_IP6_CONFIG_DATA_TYPE
  29 ///
  30 typedef enum {
  31   ///
  32   /// The interface information of the communication
  33   /// device this EFI IPv6 Configuration Protocol instance manages.
  34   /// This type of data is read only.The corresponding Data is of type
  35   /// EFI_IP6_CONFIG_INTERFACE_INFO.
  36   ///
  37   Ip6ConfigDataTypeInterfaceInfo,
  38   ///
  39   /// The alternative interface ID for the
  40   /// communication device this EFI IPv6 Configuration Protocol
  41   /// instance manages if the link local IPv6 address generated from
  42   /// the interfaced ID based on the default source the EFI IPv6
  43   /// Protocol uses is a duplicate address. The length of the interface
  44   /// ID is 64 bit. The corresponding Data is of type
  45   /// EFI_IP6_CONFIG_INTERFACE_ID.
  46   ///
  47   Ip6ConfigDataTypeAltInterfaceId,
  48   ///
  49   /// The general configuration policy for the EFI IPv6 network
  50   /// stack running on the communication device this EFI IPv6
  51   /// Configuration Protocol instance manages. The policy will affect
  52   /// other configuration settings. The corresponding Data is of type
  53   /// EFI_IP6_CONFIG_POLICY.
  54   ///
  55   Ip6ConfigDataTypePolicy,
  56   ///
  57   /// The number of consecutive
  58   /// Neighbor Solicitation messages sent while performing Duplicate
  59   /// Address Detection on a tentative address. A value of zero
  60   /// indicates that Duplicate Address Detection will not be performed
  61   /// on tentative addresses. The corresponding Data is of type
  62   /// EFI_IP6_CONFIG_DUP_ADDR_DETECT_TRANSMITS.
  63   ///
  64   Ip6ConfigDataTypeDupAddrDetectTransmits,
  65   ///
  66   /// The station addresses set manually for the EFI
  67   /// IPv6 network stack. It is only configurable when the policy is
  68   /// Ip6ConfigPolicyManual. The corresponding Data is a
  69   /// pointer to an array of EFI_IPv6_ADDRESS instances. When
  70   /// DataSize is 0 and Data is NULL, the existing configuration
  71   /// is cleared from the EFI IPv6 Configuration Protocol instance.
  72   ///
  73   Ip6ConfigDataTypeManualAddress,
  74   ///
  75   /// The gateway addresses set manually for the EFI IPv6
  76   /// network stack running on the communication device this EFI
  77   /// IPv6 Configuration Protocol manages. It is not configurable when
  78   /// the policy is Ip6ConfigPolicyAutomatic. The gateway
  79   /// addresses must be unicast IPv6 addresses. The corresponding
  80   /// Data is a pointer to an array of EFI_IPv6_ADDRESS instances.
  81   /// When DataSize is 0 and Data is NULL, the existing configuration
  82   /// is cleared from the EFI IPv6 Configuration Protocol instance.
  83   ///
  84   Ip6ConfigDataTypeGateway,
  85   ///
  86   /// The DNS server list for the EFI IPv6 network stack
  87   /// running on the communication device this EFI IPv6
  88   /// Configuration Protocol manages. It is not configurable when the
  89   /// policy is Ip6ConfigPolicyAutomatic.The DNS server
  90   /// addresses must be unicast IPv6 addresses. The corresponding
  91   /// Data is a pointer to an array of EFI_IPv6_ADDRESS instances.
  92   /// When DataSize is 0 and Data is NULL, the existing configuration
  93   /// is cleared from the EFI IPv6 Configuration Protocol instance.
  94   ///
  95   Ip6ConfigDataTypeDnsServer,
  96   ///
  97   /// The number of this enumeration memebers.
  98   ///
  99   Ip6ConfigDataTypeMaximum
 100 } EFI_IP6_CONFIG_DATA_TYPE;
 101
 102 ///
 103 /// EFI_IP6_CONFIG_INTERFACE_INFO
 104 /// describes the operational state of the interface this
 105 /// EFI IPv6 Configuration Protocol instance manages.
 106 ///
 107 typedef struct {
 108   ///
 109   /// The name of the interface. It is a NULL-terminated string.
 110   ///
 111   CHAR16                Name[32];
 112   ///
 113   /// The interface type of the network interface.
 114   ///
 115   UINT8                 IfType;
 116   ///
 117   /// The size, in bytes, of the network interface's hardware address.
 118   ///
 119   UINT32                HwAddressSize;
 120   ///
 121   /// The hardware address for the network interface.
 122   ///
 123   EFI_MAC_ADDRESS       HwAddress;
 124   ///
 125   /// Number of EFI_IP6_ADDRESS_INFO structures pointed to by AddressInfo.
 126   ///
 127   UINT32                AddressInfoCount;
 128   ///
 129   /// Pointer to an array of EFI_IP6_ADDRESS_INFO instances
 130   /// which contain the local IPv6 addresses and the corresponding
 131   /// prefix length information. Set to NULL if AddressInfoCount
 132   /// is zero.
 133   ///
 134   EFI_IP6_ADDRESS_INFO  *AddressInfo;
 135   ///
 136   /// Number of route table entries in the following RouteTable.
 137   ///
 138   UINT32                RouteCount;
 139   ///
 140   /// The route table of the IPv6 network stack runs on this interface.
 141   /// Set to NULL if RouteCount is zero.
 142   ///
 143   EFI_IP6_ROUTE_TABLE   *RouteTable;
 144 } EFI_IP6_CONFIG_INTERFACE_INFO;
 145
 146 ///
 147 /// EFI_IP6_CONFIG_INTERFACE_ID
 148 /// describes the 64-bit interface ID.
 149 ///
 150 typedef struct {
 151   UINT8                 Id[8];
 152 } EFI_IP6_CONFIG_INTERFACE_ID;
 153
 154 ///
 155 /// EFI_IP6_CONFIG_POLICY
 156 /// defines the general configuration policy the EFI IPv6
 157 /// Configuration Protocol supports.
 158 ///
 159 typedef enum {
 160   ///
 161   /// Under this policy, the IpI6ConfigDataTypeManualAddress,
 162   /// Ip6ConfigDataTypeGateway and Ip6ConfigDataTypeDnsServer
 163   /// configuration data are required to be set manually.
 164   /// The EFI IPv6 Protocol will get all required configuration
 165   /// such as address, prefix and gateway settings from the EFI
 166   /// IPv6 Configuration protocol.
 167   ///
 168   Ip6ConfigPolicyManual,
 169   ///
 170   /// Under this policy, the IpI6ConfigDataTypeManualAddress,
 171   /// Ip6ConfigDataTypeGateway and Ip6ConfigDataTypeDnsServer
 172   /// configuration data are not allowed to set via SetData().
 173   /// All of these configurations are retrieved from some auto
 174   /// configuration mechanism.
 175   /// The EFI IPv6 Protocol will use the IPv6 stateless address
 176   /// autoconfiguration mechanism and/or the IPv6 stateful address
 177   /// autoconfiguration mechanism described in the related RFCs to
 178   /// get address and other configuration information
 179   ///
 180   Ip6ConfigPolicyAutomatic
 181 } EFI_IP6_CONFIG_POLICY;
 182
 183 ///
 184 /// EFI_IP6_CONFIG_DUP_ADDR_DETECT_TRANSMITS
 185 /// describes the number of consecutive Neighbor Solicitation messages sent
 186 /// while performing Duplicate Address Detection on a tentative address.
 187 /// The default value for a newly detected communication device is 1.
 188 ///
 189 typedef struct {
 190   UINT32    DupAddrDetectTransmits;  ///< The number of consecutive Neighbor Solicitation messages sent.
 191 } EFI_IP6_CONFIG_DUP_ADDR_DETECT_TRANSMITS;
 192
 193 ///
 194 /// EFI_IP6_CONFIG_MANUAL_ADDRESS
 195 /// is used to set the station address information for the EFI IPv6 network
 196 /// stack manually when the policy is Ip6ConfigPolicyManual.
 197 ///
 198 typedef struct {
 199   EFI_IPv6_ADDRESS      Address;       ///< The IPv6 unicast address.
 200   BOOLEAN               IsAnycast;     ///< Set to TRUE if Address is anycast.
 201   UINT8                 PrefixLength;  ///< The length, in bits, of the prefix associated with this Address.
 202 } EFI_IP6_CONFIG_MANUAL_ADDRESS;
 203
 204
 205 /**
 206   Set the configuration for the EFI IPv6 network stack running on the communication
 207   device this EFI IPv6 Configuration Protocol instance manages.
 208
 209   This function is used to set the configuration data of type DataType for the EFI
 210   IPv6 network stack running on the communication device this EFI IPv6 Configuration
 211   Protocol instance manages.
 212
 213   The DataSize is used to calculate the count of structure instances in the Data for
 214   some DataType that multiple structure instances are allowed.
 215
 216   This function is always non-blocking. When setting some type of configuration data,
 217   an asynchronous process is invoked to check the correctness of the data, such as
 218   doing Duplicate Address Detection on the manually set local IPv6 addresses.
 219   EFI_NOT_READY is returned immediately to indicate that such an asynchronous process
 220   is invoked and the process is not finished yet. The caller willing to get the result
 221   of the asynchronous process is required to call RegisterDataNotify() to register an
 222   event on the specified configuration data. Once the event is signaled, the caller
 223   can call GetData() to get back the configuration data in order to know the result.
 224   For other types of configuration data that do not require an asynchronous configuration
 225   process, the result of the operation is immediately returned.
 226
 227   @param[in]     This           Pointer to the EFI_IP6_CONFIG_PROTOCOL instance.
 228   @param[in]     DataType       The type of data to set.
 229   @param[in]     DataSize       Size of the buffer pointed to by Data in bytes.
 230   @param[in]     Data           The data buffer to set. The type of the data buffer is
 231                                 associated with the DataType.
 232
 233   @retval EFI_SUCCESS           The specified configuration data for the EFI IPv6
 234                                 network stack is set successfully.
 235   @retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
 236                                 - This is NULL.
 237                                 - One or more fields in Data and DataSize do not match the
 238                                   requirement of the data type indicated by DataType.
 239   @retval EFI_WRITE_PROTECTED   The specified configuration data is read-only or the specified
 240                                 configuration data can not be set under the current policy
 241   @retval EFI_ACCESS_DENIED     Another set operation on the specified configuration
 242                                 data is already in process.
 243   @retval EFI_NOT_READY         An asynchronous process is invoked to set the specified
 244                                 configuration data and the process is not finished yet.
 245   @retval EFI_BAD_BUFFER_SIZE   The DataSize does not match the size of the type
 246                                 indicated by DataType.
 247   @retval EFI_UNSUPPORTED       This DataType is not supported.
 248   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 249   @retval EFI_DEVICE_ERROR      An unexpected system error or network error occurred.
 250
 251 **/
 252 typedef
 253 EFI_STATUS
 254 (EFIAPI *EFI_IP6_CONFIG_SET_DATA)(
 255   IN EFI_IP6_CONFIG_PROTOCOL    *This,
 256   IN EFI_IP6_CONFIG_DATA_TYPE   DataType,
 257   IN UINTN                      DataSize,
 258   IN VOID                       *Data
 259   );
 260
 261 /**
 262   Get the configuration data for the EFI IPv6 network stack running on the communication
 263   device this EFI IPv6 Configuration Protocol instance manages.
 264
 265   This function returns the configuration data of type DataType for the EFI IPv6 network
 266   stack running on the communication device this EFI IPv6 Configuration Protocol instance
 267   manages.
 268
 269   The caller is responsible for allocating the buffer used to return the specified
 270   configuration data and the required size will be returned to the caller if the size of
 271   the buffer is too small.
 272
 273   EFI_NOT_READY is returned if the specified configuration data is not ready due to an
 274   already in progress asynchronous configuration process. The caller can call RegisterDataNotify()
 275   to register an event on the specified configuration data. Once the asynchronous configuration
 276   process is finished, the event will be signaled and a subsequent GetData() call will return
 277   the specified configuration data.
 278
 279   @param[in]     This           Pointer to the EFI_IP6_CONFIG_PROTOCOL instance.
 280   @param[in]     DataType       The type of data to get.
 281   @param[in,out] DataSize       On input, in bytes, the size of Data. On output, in bytes, the
 282                                 size of buffer required to store the specified configuration data.
 283   @param[in]     Data           The data buffer in which the configuration data is returned. The
 284                                 type of the data buffer is associated with the DataType.
 285
 286   @retval EFI_SUCCESS           The specified configuration data is got successfully.
 287   @retval EFI_INVALID_PARAMETER One or more of the followings are TRUE:
 288                                 - This is NULL.
 289                                 - DataSize is NULL.
 290                                 - Data is NULL if *DataSize is not zero.
 291   @retval EFI_BUFFER_TOO_SMALL  The size of Data is too small for the specified configuration data
 292                                 and the required size is returned in DataSize.
 293   @retval EFI_NOT_READY         The specified configuration data is not ready due to an already in
 294                                 progress asynchronous configuration process.
 295   @retval EFI_NOT_FOUND         The specified configuration data is not found.
 296
 297 **/
 298 typedef
 299 EFI_STATUS
 300 (EFIAPI *EFI_IP6_CONFIG_GET_DATA)(
 301   IN EFI_IP6_CONFIG_PROTOCOL    *This,
 302   IN EFI_IP6_CONFIG_DATA_TYPE   DataType,
 303   IN OUT UINTN                  *DataSize,
 304   IN VOID                       *Data   OPTIONAL
 305   );
 306
 307 /**
 308   Register an event that is to be signaled whenever a configuration process on the specified
 309   configuration data is done.
 310
 311   This function registers an event that is to be signaled whenever a configuration process
 312   on the specified configuration data is done. An event can be registered for different DataType
 313   simultaneously and the caller is responsible for determining which type of configuration data
 314   causes the signaling of the event in such case.
 315
 316   @param[in]     This           Pointer to the EFI_IP6_CONFIG_PROTOCOL instance.
 317   @param[in]     DataType       The type of data to unregister the event for.
 318   @param[in]     Event          The event to register.
 319
 320   @retval EFI_SUCCESS           The notification event for the specified configuration data is
 321                                 registered.
 322   @retval EFI_INVALID_PARAMETER This is NULL or Event is NULL.
 323   @retval EFI_UNSUPPORTED       The configuration data type specified by DataType is not
 324                                 supported.
 325   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 326   @retval EFI_ACCESS_DENIED     The Event is already registered for the DataType.
 327
 328 **/
 329 typedef
 330 EFI_STATUS
 331 (EFIAPI *EFI_IP6_CONFIG_REGISTER_NOTIFY)(
 332   IN EFI_IP6_CONFIG_PROTOCOL    *This,
 333   IN EFI_IP6_CONFIG_DATA_TYPE   DataType,
 334   IN EFI_EVENT                  Event
 335   );
 336
 337 /**
 338   Remove a previously registered event for the specified configuration data.
 339
 340   This function removes a previously registered event for the specified configuration data.
 341
 342   @param[in]     This           Pointer to the EFI_IP6_CONFIG_PROTOCOL instance.
 343   @param[in]     DataType       The type of data to remove the previously registered event for.
 344   @param[in]     Event          The event to unregister.
 345
 346   @retval EFI_SUCCESS           The event registered for the specified configuration data is removed.
 347   @retval EFI_INVALID_PARAMETER This is NULL or Event is NULL.
 348   @retval EFI_NOT_FOUND         The Event has not been registered for the specified
 349                                 DataType.
 350
 351 **/
 352 typedef
 353 EFI_STATUS
 354 (EFIAPI *EFI_IP6_CONFIG_UNREGISTER_NOTIFY)(
 355   IN EFI_IP6_CONFIG_PROTOCOL    *This,
 356   IN EFI_IP6_CONFIG_DATA_TYPE   DataType,
 357   IN EFI_EVENT                  Event
 358   );
 359
 360 ///
 361 /// The EFI_IP6_CONFIG_PROTOCOL provides the mechanism to set and get various
 362 /// types of configurations for the EFI IPv6 network stack.
 363 ///
 364 struct _EFI_IP6_CONFIG_PROTOCOL {
 365   EFI_IP6_CONFIG_SET_DATA           SetData;
 366   EFI_IP6_CONFIG_GET_DATA           GetData;
 367   EFI_IP6_CONFIG_REGISTER_NOTIFY    RegisterDataNotify;
 368   EFI_IP6_CONFIG_UNREGISTER_NOTIFY  UnregisterDataNotify;
 369 };
 370
 371 extern EFI_GUID gEfiIp6ConfigProtocolGuid;
 372
 373 #endif
 374