MdePkg/Include/Protocol/WiFi2.h

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