MdePkg/Include/Protocol/Ip4Config2.h

   1 /** @file
   2   This file provides a definition of the EFI IPv4 Configuration II
   3   Protocol.
   4
   5 Copyright (c) 2015 - 2018, 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 @par Revision Reference:
  15 This Protocol is introduced in UEFI Specification 2.5
  16
  17 **/
  18 #ifndef __EFI_IP4CONFIG2_PROTOCOL_H__
  19 #define __EFI_IP4CONFIG2_PROTOCOL_H__
  20
  21 #include <Protocol/Ip4.h>
  22
  23 #define EFI_IP4_CONFIG2_PROTOCOL_GUID \
  24   { \
  25     0x5b446ed1, 0xe30b, 0x4faa, {0x87, 0x1a, 0x36, 0x54, 0xec, 0xa3, 0x60, 0x80 } \
  26   }
  27
  28 typedef struct _EFI_IP4_CONFIG2_PROTOCOL EFI_IP4_CONFIG2_PROTOCOL;
  29
  30
  31 ///
  32 /// EFI_IP4_CONFIG2_DATA_TYPE
  33 ///
  34 typedef enum {
  35   ///
  36   /// The interface information of the communication device this EFI
  37   /// IPv4 Configuration II Protocol instance manages. This type of
  38   /// data is read only. The corresponding Data is of type
  39   /// EFI_IP4_CONFIG2_INTERFACE_INFO.
  40   ///
  41   Ip4Config2DataTypeInterfaceInfo,
  42   ///
  43   /// The general configuration policy for the EFI IPv4 network stack
  44   /// running on the communication device this EFI IPv4
  45   /// Configuration II Protocol instance manages. The policy will
  46   /// affect other configuration settings. The corresponding Data is of
  47   /// type EFI_IP4_CONFIG2_POLICY.
  48   ///
  49   Ip4Config2DataTypePolicy,
  50   ///
  51   /// The station addresses set manually for the EFI IPv4 network
  52   /// stack. It is only configurable when the policy is
  53   /// Ip4Config2PolicyStatic. The corresponding Data is of
  54   /// type EFI_IP4_CONFIG2_MANUAL_ADDRESS. When DataSize
  55   /// is 0 and Data is NULL, the existing configuration is cleared
  56   /// from the EFI IPv4 Configuration II Protocol instance.
  57   ///
  58   Ip4Config2DataTypeManualAddress,
  59   ///
  60   /// The gateway addresses set manually for the EFI IPv4 network
  61   /// stack running on the communication device this EFI IPv4
  62   /// Configuration II Protocol manages. It is not configurable when
  63   /// the policy is Ip4Config2PolicyDhcp. The gateway
  64   /// addresses must be unicast IPv4 addresses. The corresponding
  65   /// Data is a pointer to an array of EFI_IPv4_ADDRESS instances.
  66   /// When DataSize is 0 and Data is NULL, the existing configuration
  67   /// is cleared from the EFI IPv4 Configuration II Protocol instance.
  68   ///
  69   Ip4Config2DataTypeGateway,
  70   ///
  71   /// The DNS server list for the EFI IPv4 network stack running on
  72   /// the communication device this EFI IPv4 Configuration II
  73   /// Protocol manages. It is not configurable when the policy is
  74   /// Ip4Config2PolicyDhcp. The DNS server addresses must be
  75   /// unicast IPv4 addresses. The corresponding Data is a pointer to
  76   /// an array of EFI_IPv4_ADDRESS instances. When DataSize
  77   /// is 0 and Data is NULL, the existing configuration is cleared
  78   /// from the EFI IPv4 Configuration II Protocol instance.
  79   ///
  80   Ip4Config2DataTypeDnsServer,
  81   Ip4Config2DataTypeMaximum
  82 } EFI_IP4_CONFIG2_DATA_TYPE;
  83
  84 ///
  85 /// EFI_IP4_CONFIG2_INTERFACE_INFO related definitions
  86 ///
  87 #define EFI_IP4_CONFIG2_INTERFACE_INFO_NAME_SIZE 32
  88
  89 ///
  90 /// EFI_IP4_CONFIG2_INTERFACE_INFO
  91 ///
  92 typedef struct {
  93   ///
  94   /// The name of the interface. It is a NULL-terminated Unicode string.
  95   ///
  96   CHAR16                Name[EFI_IP4_CONFIG2_INTERFACE_INFO_NAME_SIZE];
  97   ///
  98   /// The interface type of the network interface. See RFC 1700,
  99   /// section "Number Hardware Type".
 100   ///
 101   UINT8                 IfType;
 102   ///
 103   /// The size, in bytes, of the network interface's hardware address.
 104   ///
 105   UINT32                HwAddressSize;
 106   ///
 107   /// The hardware address for the network interface.
 108   ///
 109   EFI_MAC_ADDRESS       HwAddress;
 110   ///
 111   /// The station IPv4 address of this EFI IPv4 network stack.
 112   ///
 113   EFI_IPv4_ADDRESS      StationAddress;
 114   ///
 115   /// The subnet address mask that is associated with the station address.
 116   ///
 117   EFI_IPv4_ADDRESS      SubnetMask;
 118   ///
 119   /// Size of the following RouteTable, in bytes. May be zero.
 120   ///
 121   UINT32                RouteTableSize;
 122   ///
 123   /// The route table of the IPv4 network stack runs on this interface.
 124   /// Set to NULL if RouteTableSize is zero. Type EFI_IP4_ROUTE_TABLE is defined in
 125   /// EFI_IP4_PROTOCOL.GetModeData().
 126   ///
 127   EFI_IP4_ROUTE_TABLE   *RouteTable     OPTIONAL;
 128 } EFI_IP4_CONFIG2_INTERFACE_INFO;
 129
 130 ///
 131 /// EFI_IP4_CONFIG2_POLICY
 132 ///
 133 typedef enum {
 134   ///
 135   /// Under this policy, the Ip4Config2DataTypeManualAddress,
 136   /// Ip4Config2DataTypeGateway and Ip4Config2DataTypeDnsServer configuration
 137   /// data are required to be set manually. The EFI IPv4 Protocol will get all
 138   /// required configuration such as IPv4 address, subnet mask and
 139   /// gateway settings from the EFI IPv4 Configuration II protocol.
 140   ///
 141   Ip4Config2PolicyStatic,
 142   ///
 143   /// Under this policy, the Ip4Config2DataTypeManualAddress,
 144   /// Ip4Config2DataTypeGateway and Ip4Config2DataTypeDnsServer configuration data are
 145   /// not allowed to set via SetData(). All of these configurations are retrieved from DHCP
 146   /// server or other auto-configuration mechanism.
 147   ///
 148   Ip4Config2PolicyDhcp,
 149   Ip4Config2PolicyMax
 150 } EFI_IP4_CONFIG2_POLICY;
 151
 152 ///
 153 /// EFI_IP4_CONFIG2_MANUAL_ADDRESS
 154 ///
 155 typedef struct {
 156   ///
 157   /// The IPv4 unicast address.
 158   ///
 159   EFI_IPv4_ADDRESS        Address;
 160   ///
 161   /// The subnet mask.
 162   ///
 163   EFI_IPv4_ADDRESS        SubnetMask;
 164 } EFI_IP4_CONFIG2_MANUAL_ADDRESS;
 165
 166 /**
 167   Set the configuration for the EFI IPv4 network stack running on the communication device this EFI
 168   IPv4 Configuration II Protocol instance manages.
 169
 170   This function is used to set the configuration data of type DataType for the EFI IPv4 network stack
 171   running on the communication device this EFI IPv4 Configuration II Protocol instance manages.
 172   The successfully configured data is valid after system reset or power-off.
 173   The DataSize is used to calculate the count of structure instances in the Data for some
 174   DataType that multiple structure instances are allowed.
 175   This function is always non-blocking. When setting some typeof configuration data, an
 176   asynchronous process is invoked to check the correctness of the data, such as doing address conflict
 177   detection on the manually set local IPv4 address. EFI_NOT_READY is returned immediately to
 178   indicate that such an asynchronous process is invoked and the process is not finished yet. The caller
 179   willing to get the result of the asynchronous process is required to call RegisterDataNotify()
 180   to register an event on the specified configuration data. Once the event is signaled, the caller can call
 181   GetData()to get back the configuration data in order to know the result. For other types of
 182   configuration data that do not require an asynchronous configuration process, the result of the
 183   operation is immediately returned.
 184
 185   @param[in]   This               Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance.
 186   @param[in]   DataType           The type of data to set.
 187   @param[in]   DataSize           Size of the buffer pointed to by Data in bytes.
 188   @param[in]   Data               The data buffer to set. The type ofthe data buffer is associated
 189                                   with the DataType.
 190
 191   @retval EFI_SUCCESS             The specified configuration data for the EFI IPv4 network stack is set
 192                                   successfully.
 193   @retval EFI_INVALID_PARAMETER   One or more of the following are TRUE:
 194                                   This is NULL.
 195                                   One or more fields in Data and DataSize do not match the
 196                                   requirement of the data type indicated by DataType.
 197   @retval EFI_WRITE_PROTECTED     The specified configuration data is read-only or the specified configuration
 198                                   data can not be set under the current policy.
 199   @retval EFI_ACCESS_DENIED       Another set operation on the specified configuration data is already in process.
 200   @retval EFI_NOT_READY           An asynchronous process is invoked to set the specified configuration data and
 201                                   the process is not finished yet.
 202   @retval EFI_BAD_BUFFER_SIZE     The DataSize does not match the size of the type indicated by DataType.
 203   @retval EFI_UNSUPPORTED         This DataType is not supported.
 204   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.
 205   @retval EFI_DEVICE_ERROR        An unexpected system error or network error occurred.
 206 **/
 207 typedef
 208 EFI_STATUS
 209 (EFIAPI *EFI_IP4_CONFIG2_SET_DATA) (
 210   IN EFI_IP4_CONFIG2_PROTOCOL   *This,
 211   IN EFI_IP4_CONFIG2_DATA_TYPE  DataType,
 212   IN UINTN                      DataSize,
 213   IN VOID                       *Data
 214   );
 215
 216 /**
 217   Get the configuration data for the EFI IPv4 network stack running on the communication device this
 218   EFI IPv4 Configuration II Protocol instance manages.
 219
 220   This function returns the configuration data of type DataType for the EFI IPv4 network stack
 221   running on the communication device this EFI IPv4 Configuration II Protocol instance manages.
 222   The caller is responsible for allocating the buffer usedto return the specified configuration data and
 223   the required size will be returned to the caller if the size of the buffer is too small.
 224   EFI_NOT_READY is returned if the specified configuration data is not ready due to an already in
 225   progress asynchronous configuration process. The caller can call RegisterDataNotify() to
 226   register an event on the specified configuration data. Once the asynchronous configuration process is
 227   finished, the event will be signaled and a subsequent GetData() call will return the specified
 228   configuration data.
 229
 230   @param[in]   This               Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance.
 231   @param[in]   DataType           The type of data to get.
 232   @param[out]  DataSize           On input, in bytes, the size of Data. On output, in bytes, the size
 233                                   of buffer required to store the specified configuration data.
 234   @param[in]   Data               The data buffer in which the configuration data is returned. The
 235                                   type of the data buffer is associated with the DataType. Ignored
 236                                   if DataSize is 0.
 237
 238   @retval EFI_SUCCESS             The specified configuration data is got successfully.
 239   @retval EFI_INVALID_PARAMETER   One or more of the followings are TRUE:
 240                                   This is NULL.
 241                                   DataSize is NULL.
 242                                   Data is NULL if *DataSizeis not zero.
 243   @retval EFI_BUFFER_TOO_SMALL    The size of Data is too small for the specified configuration data
 244                                   and the required size is returned in DataSize.
 245   @retval EFI_NOT_READY           The specified configuration data is not ready due to an already in
 246                                   progress asynchronous configuration process.
 247   @retval EFI_NOT_FOUND           The specified configuration data is not found.
 248 **/
 249 typedef
 250 EFI_STATUS
 251 (EFIAPI *EFI_IP4_CONFIG2_GET_DATA) (
 252   IN EFI_IP4_CONFIG2_PROTOCOL     *This,
 253   IN EFI_IP4_CONFIG2_DATA_TYPE    DataType,
 254   IN OUT UINTN                    *DataSize,
 255   IN VOID                         *Data        OPTIONAL
 256   );
 257
 258 /**
 259   Register an event that is to be signaled whenever a configuration process on the specified
 260   configuration data is done.
 261
 262   This function registers an event that is to be signaled whenever a configuration process on the
 263   specified configuration data is done. An event can be registered for different DataType
 264   simultaneously and the caller is responsible for determining which type of configuration data causes
 265   the signaling of the event in such case.
 266
 267   @param[in]   This               Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance.
 268   @param[in]   DataType           The type of data to unregister the event for.
 269   @param[in]   Event              The event to register.
 270
 271   @retval EFI_SUCCESS             The notification event for the specified configuration data is
 272                                   registered.
 273   @retval EFI_INVALID_PARAMETER   This is NULL or Event is NULL.
 274   @retval EFI_UNSUPPORTED         The configuration data type specified by DataType is not supported.
 275   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.
 276   @retval EFI_ACCESS_DENIED       The Event is already registered for the DataType.
 277 **/
 278 typedef
 279 EFI_STATUS
 280 (EFIAPI *EFI_IP4_CONFIG2_REGISTER_NOTIFY) (
 281   IN EFI_IP4_CONFIG2_PROTOCOL     *This,
 282   IN EFI_IP4_CONFIG2_DATA_TYPE    DataType,
 283   IN EFI_EVENT                    Event
 284   );
 285
 286 /**
 287   Remove a previously registered event for the specified configuration data.
 288
 289   This function removes a previously registeredevent for the specified configuration data.
 290
 291   @param[in]   This               Pointer to the EFI_IP4_CONFIG2_PROTOCOL instance.
 292   @param[in]   DataType           The type of data to remove the previously registered event for.
 293   @param[in]   Event              The event to unregister.
 294
 295   @retval EFI_SUCCESS             The event registered for the specified configuration data is removed.
 296   @retval EFI_INVALID_PARAMETER   This is NULL or Event is NULL.
 297   @retval EFI_NOT_FOUND           The Eventhas not been registered for the specified DataType.
 298 **/
 299 typedef
 300 EFI_STATUS
 301 (EFIAPI *EFI_IP4_CONFIG2_UNREGISTER_NOTIFY) (
 302   IN EFI_IP4_CONFIG2_PROTOCOL     *This,
 303   IN EFI_IP4_CONFIG2_DATA_TYPE    DataType,
 304   IN EFI_EVENT                    Event
 305   );
 306
 307 ///
 308 /// The EFI_IP4_CONFIG2_PROTOCOL is designed to be the central repository for the common
 309 /// configurations and the administrator configurable settings for the EFI IPv4 network stack.
 310 /// An EFI IPv4 Configuration II Protocol instance will be installed on each communication device that
 311 /// the EFI IPv4 network stack runs on.
 312 ///
 313 struct _EFI_IP4_CONFIG2_PROTOCOL {
 314   EFI_IP4_CONFIG2_SET_DATA           SetData;
 315   EFI_IP4_CONFIG2_GET_DATA           GetData;
 316   EFI_IP4_CONFIG2_REGISTER_NOTIFY    RegisterDataNotify;
 317   EFI_IP4_CONFIG2_UNREGISTER_NOTIFY  UnregisterDataNotify;
 318 };
 319
 320 extern EFI_GUID gEfiIp4Config2ProtocolGuid;
 321
 322 #endif
 323