MdePkg/Include/Protocol/WiFi2.h

   1 /** @file
   2   This file defines the EFI Wireless MAC Connection II Protocol.
   3
   4   Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7   @par Revision Reference:
   8   This Protocol is introduced in UEFI Specification 2.6
   9
  10 **/
  11
  12 #ifndef __EFI_WIFI2_PROTOCOL_H__
  13 #define __EFI_WIFI2_PROTOCOL_H__
  14
  15 #define EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL_GUID \
  16   { \
  17     0x1b0fb9bf, 0x699d, 0x4fdd, { 0xa7, 0xc3, 0x25, 0x46, 0x68, 0x1b, 0xf6, 0x3b } \
  18   }
  19
  20 typedef struct _EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL;
  21
  22 ///
  23 /// EFI_80211_BSS_TYPE
  24 ///
  25 typedef enum {
  26   IeeeInfrastructureBSS,
  27   IeeeIndependentBSS,
  28   IeeeMeshBSS,
  29   IeeeAnyBss
  30 } EFI_80211_BSS_TYPE;
  31
  32 ///
  33 /// EFI_80211_CONNECT_NETWORK_RESULT_CODE
  34 ///
  35 typedef enum {
  36   //
  37   // The connection establishment operation finished successfully.
  38   //
  39   ConnectSuccess,
  40   //
  41   // The connection was refused by the Network.
  42   //
  43   ConnectRefused,
  44   //
  45   // The connection establishment operation failed (i.e, Network is not
  46   // detected).
  47   //
  48   ConnectFailed,
  49   //
  50   // The connection establishment operation was terminated on timeout.
  51   //
  52   ConnectFailureTimeout,
  53   //
  54   // The connection establishment operation failed on other reason.
  55   //
  56   ConnectFailedReasonUnspecified
  57 } EFI_80211_CONNECT_NETWORK_RESULT_CODE;
  58
  59 ///
  60 /// EFI_80211_MAC_ADDRESS
  61 ///
  62 typedef struct {
  63   UINT8                              Addr[6];
  64 } EFI_80211_MAC_ADDRESS;
  65
  66 #define EFI_MAX_SSID_LEN 32
  67
  68 ///
  69 /// EFI_80211_SSID
  70 ///
  71 typedef struct {
  72   //
  73   // Length in bytes of the SSId. If zero, ignore SSId field.
  74   //
  75   UINT8                                     SSIdLen;
  76   //
  77   // Specifies the service set identifier.
  78   //
  79   UINT8                                     SSId[EFI_MAX_SSID_LEN];
  80 } EFI_80211_SSID;
  81
  82 ///
  83 /// EFI_80211_GET_NETWORKS_DATA
  84 ///
  85 typedef struct {
  86   //
  87   // The number of EFI_80211_SSID in SSIDList. If zero, SSIDList should be
  88   // ignored.
  89   //
  90   UINT32                                    NumOfSSID;
  91   //
  92   // The SSIDList is a pointer to an array of EFI_80211_SSID instances. The
  93   // number of entries is specified by NumOfSSID. The array should only include
  94   // SSIDs of hidden networks. It is suggested that the caller inputs less than
  95   // 10 elements in the SSIDList. It is the caller's responsibility to free
  96   // this buffer.
  97   //
  98   EFI_80211_SSID                            SSIDList[1];
  99 } EFI_80211_GET_NETWORKS_DATA;
 100
 101 ///
 102 /// EFI_80211_SUITE_SELECTOR
 103 ///
 104 typedef struct {
 105   //
 106   // Organization Unique Identifier, as defined in IEEE 802.11 standard,
 107   // usually set to 00-0F-AC.
 108   //
 109   UINT8                                     Oui[3];
 110   //
 111   // Suites types, as defined in IEEE 802.11 standard.
 112   //
 113   UINT8                                     SuiteType;
 114 } EFI_80211_SUITE_SELECTOR;
 115
 116 ///
 117 /// EFI_80211_AKM_SUITE_SELECTOR
 118 ///
 119 typedef struct {
 120   //
 121   // Indicates the number of AKM suite selectors that are contained in
 122   // AKMSuiteList. If zero, the AKMSuiteList is ignored.
 123   //
 124   UINT16                                    AKMSuiteCount;
 125   //
 126   // A variable-length array of AKM suites, as defined in IEEE 802.11 standard,
 127   // Table 8-101. The number of entries is specified by AKMSuiteCount.
 128   //
 129   EFI_80211_SUITE_SELECTOR                  AKMSuiteList[1];
 130 } EFI_80211_AKM_SUITE_SELECTOR;
 131
 132 ///
 133 /// EFI_80211_CIPHER_SUITE_SELECTOR
 134 ///
 135 typedef struct {
 136   //
 137   // Indicates the number of cipher suites that are contained in
 138   // CipherSuiteList. If zero, the CipherSuiteList is ignored.
 139   //
 140   UINT16                                    CipherSuiteCount;
 141   //
 142   // A variable-length array of cipher suites, as defined in IEEE 802.11
 143   // standard, Table 8-99. The number of entries is specified by
 144   // CipherSuiteCount.
 145   //
 146   EFI_80211_SUITE_SELECTOR                  CipherSuiteList[1];
 147 } EFI_80211_CIPHER_SUITE_SELECTOR;
 148
 149 ///
 150 /// EFI_80211_NETWORK
 151 ///
 152 typedef struct {
 153   //
 154   // Specifies the type of the BSS.
 155   //
 156   EFI_80211_BSS_TYPE                        BSSType;
 157   //
 158   // Specifies the SSID of the BSS.
 159   //
 160   EFI_80211_SSID                            SSId;
 161   //
 162   // Pointer to the AKM suites supported in the wireless network.
 163   //
 164   EFI_80211_AKM_SUITE_SELECTOR              *AKMSuite;
 165   //
 166   // Pointer to the cipher suites supported in the wireless network.
 167   //
 168   EFI_80211_CIPHER_SUITE_SELECTOR           *CipherSuite;
 169 } EFI_80211_NETWORK;
 170
 171 ///
 172 /// EFI_80211_NETWORK_DESCRIPTION
 173 ///
 174 typedef struct {
 175   //
 176   // Specifies the found wireless network.
 177   //
 178   EFI_80211_NETWORK                         Network;
 179   //
 180   // Indicates the network quality as a value between 0 to 100, where 100
 181   // indicates the highest network quality.
 182   //
 183   UINT8                                     NetworkQuality;
 184 } EFI_80211_NETWORK_DESCRIPTION;
 185
 186 ///
 187 /// EFI_80211_GET_NETWORKS_RESULT
 188 ///
 189 typedef struct {
 190   //
 191   // The number of EFI_80211_NETWORK_DESCRIPTION in NetworkDesc. If zero,
 192   // NetworkDesc should be ignored.
 193   //
 194   UINT8                                     NumOfNetworkDesc;
 195   //
 196   // The NetworkDesc is a pointer to an array of EFI_80211_NETWORK_DESCRIPTION
 197   // instances. It is caller's responsibility to free this buffer.
 198   //
 199   EFI_80211_NETWORK_DESCRIPTION             NetworkDesc[1];
 200 } EFI_80211_GET_NETWORKS_RESULT;
 201
 202 ///
 203 /// EFI_80211_GET_NETWORKS_TOKEN
 204 ///
 205 typedef struct {
 206   //
 207   // If the status code returned by GetNetworks() is EFI_SUCCESS, then this
 208   // Event will be signaled after the Status field is updated by the EFI
 209   // Wireless MAC Connection Protocol II driver. The type of Event must be
 210   // EFI_NOTIFY_SIGNAL.
 211   //
 212   EFI_EVENT                                 Event;
 213   //
 214   // Will be set to one of the following values:
 215   // EFI_SUCCESS: The operation completed successfully.
 216   // EFI_NOT_FOUND: Failed to find available wireless networks.
 217   // EFI_DEVICE_ERROR: An unexpected network or system error occurred.
 218   // EFI_ACCESS_DENIED: The operation is not completed due to some underlying
 219   // hardware or software state.
 220   // EFI_NOT_READY: The operation is started but not yet completed.
 221   //
 222   EFI_STATUS                                Status;
 223   //
 224   // Pointer to the input data for getting networks.
 225   //
 226   EFI_80211_GET_NETWORKS_DATA               *Data;
 227   //
 228   // Indicates the scan result. It is caller's responsibility to free this
 229   // buffer.
 230   //
 231   EFI_80211_GET_NETWORKS_RESULT             *Result;
 232 } EFI_80211_GET_NETWORKS_TOKEN;
 233
 234 ///
 235 /// EFI_80211_CONNECT_NETWORK_DATA
 236 ///
 237 typedef struct {
 238   //
 239   // Specifies the wireless network to connect to.
 240   //
 241   EFI_80211_NETWORK                         *Network;
 242   //
 243   // Specifies a time limit in seconds that is optionally present, after which
 244   // the connection establishment procedure is terminated by the UNDI driver.
 245   // This is an optional parameter and may be 0. Values of 5 seconds or higher
 246   // are recommended.
 247   //
 248   UINT32                                    FailureTimeout;
 249 } EFI_80211_CONNECT_NETWORK_DATA;
 250
 251 ///
 252 /// EFI_80211_CONNECT_NETWORK_TOKEN
 253 ///
 254 typedef struct {
 255   //
 256   // If the status code returned by ConnectNetwork() is EFI_SUCCESS, then this
 257   // Event will be signaled after the Status field is updated by the EFI
 258   // Wireless MAC Connection Protocol II driver. The type of Event must be
 259   // EFI_NOTIFY_SIGNAL.
 260   //
 261   EFI_EVENT                                 Event;
 262   //
 263   // Will be set to one of the following values:
 264   // EFI_SUCCESS: The operation completed successfully.
 265   // EFI_DEVICE_ERROR: An unexpected network or system error occurred.
 266   // EFI_ACCESS_DENIED: The operation is not completed due to some underlying
 267   // hardware or software state.
 268   // EFI_NOT_READY: The operation is started but not yet completed.
 269   //
 270   EFI_STATUS                                Status;
 271   //
 272   // Pointer to the connection data.
 273   //
 274   EFI_80211_CONNECT_NETWORK_DATA            *Data;
 275   //
 276   // Indicates the connection state.
 277   //
 278   EFI_80211_CONNECT_NETWORK_RESULT_CODE     ResultCode;
 279 } EFI_80211_CONNECT_NETWORK_TOKEN;
 280
 281 ///
 282 /// EFI_80211_DISCONNECT_NETWORK_TOKEN
 283 ///
 284 typedef struct {
 285   //
 286   // If the status code returned by DisconnectNetwork() is EFI_SUCCESS, then
 287   // this Event will be signaled after the Status field is updated by the EFI
 288   // Wireless MAC Connection Protocol II driver. The type of Event must be
 289   // EFI_NOTIFY_SIGNAL.
 290   //
 291   EFI_EVENT                                 Event;
 292   //
 293   // Will be set to one of the following values:
 294   // EFI_SUCCESS: The operation completed successfully
 295   // EFI_DEVICE_ERROR: An unexpected network or system error occurred.
 296   // EFI_ACCESS_DENIED: The operation is not completed due to some underlying
 297   // hardware or software state.
 298   //
 299   EFI_STATUS                                Status;
 300 } EFI_80211_DISCONNECT_NETWORK_TOKEN;
 301
 302 /**
 303   Request a survey of potential wireless networks that administrator can later
 304   elect to try to join.
 305
 306   @param[in]  This                Pointer to the
 307                                   EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL
 308                                   instance.
 309   @param[in]  Token               Pointer to the token for getting wireless
 310                                   network.
 311
 312   @retval EFI_SUCCESS             The operation started, and an event will
 313                                   eventually be raised for the caller.
 314   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is
 315                                   TRUE:
 316                                   This is NULL.
 317                                   Token is NULL.
 318   @retval EFI_UNSUPPORTED         One or more of the input parameters is not
 319                                   supported by this implementation.
 320   @retval EFI_ALREADY_STARTED     The operation of getting wireless network is
 321                                   already started.
 322   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be
 323                                   allocated.
 324
 325 **/
 326 typedef
 327 EFI_STATUS
 328 (EFIAPI *EFI_WIRELESS_MAC_CONNECTION_II_GET_NETWORKS) (
 329   IN EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL          *This,
 330   IN EFI_80211_GET_NETWORKS_TOKEN                     *Token
 331   );
 332
 333 /**
 334   Connect a wireless network specified by a particular SSID, BSS type and
 335   Security type.
 336
 337   @param[in]  This                Pointer to the
 338                                   EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL
 339                                   instance.
 340   @param[in]  Token               Pointer to the token for connecting wireless
 341                                   network.
 342
 343   @retval EFI_SUCCESS             The operation started successfully. Results
 344                                   will be notified eventually.
 345   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is
 346                                   TRUE:
 347                                   This is NULL.
 348                                   Token is NULL.
 349   @retval EFI_UNSUPPORTED         One or more of the input parameters are not
 350                                   supported by this implementation.
 351   @retval EFI_ALREADY_STARTED     The connection process is already started.
 352   @retval EFI_NOT_FOUND           The specified wireless network is not found.
 353   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be
 354                                   allocated.
 355
 356 **/
 357 typedef
 358 EFI_STATUS
 359 (EFIAPI *EFI_WIRELESS_MAC_CONNECTION_II_CONNECT_NETWORK) (
 360   IN EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL          *This,
 361   IN EFI_80211_CONNECT_NETWORK_TOKEN                  *Token
 362   );
 363
 364 /**
 365   Request a disconnection with current connected wireless network.
 366
 367   @param[in]  This                Pointer to the
 368                                   EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL
 369                                   instance.
 370   @param[in]  Token               Pointer to the token for disconnecting
 371                                   wireless network.
 372
 373   @retval EFI_SUCCESS             The operation started successfully. Results
 374                                   will be notified eventually.
 375   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is
 376                                   TRUE:
 377                                   This is NULL.
 378                                   Token is NULL.
 379   @retval EFI_UNSUPPORTED         One or more of the input parameters are not
 380                                   supported by this implementation.
 381   @retval EFI_NOT_FOUND           Not connected to a wireless network.
 382   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be
 383                                   allocated.
 384
 385 **/
 386 typedef
 387 EFI_STATUS
 388 (EFIAPI *EFI_WIRELESS_MAC_CONNECTION_II_DISCONNECT_NETWORK) (
 389   IN EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL          *This,
 390   IN EFI_80211_DISCONNECT_NETWORK_TOKEN               *Token
 391   );
 392
 393 ///
 394 /// The EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL provides network management
 395 /// service interfaces for 802.11 network stack. It is used by network
 396 /// applications (and drivers) to establish wireless connection with a wireless
 397 /// network.
 398 ///
 399 struct _EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL {
 400   EFI_WIRELESS_MAC_CONNECTION_II_GET_NETWORKS         GetNetworks;
 401   EFI_WIRELESS_MAC_CONNECTION_II_CONNECT_NETWORK      ConnectNetwork;
 402   EFI_WIRELESS_MAC_CONNECTION_II_DISCONNECT_NETWORK   DisconnectNetwork;
 403 };
 404
 405 extern EFI_GUID gEfiWiFi2ProtocolGuid;
 406
 407 #endif