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