wifi/supplicant/1.0/ISupplicantStaIfaceCallback.hal

/*
 * Copyright 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.hardware.wifi.supplicant@1.0;

/**
 * Callback Interface exposed by the supplicant service
 * for each station mode interface (ISupplicantStaIface).
 *
 * Clients need to host an instance of this HIDL interface object and
 * pass a reference of the object to the supplicant via the
 * corresponding |ISupplicantStaIface.registerCallback| method.
 */
interface ISupplicantStaIfaceCallback {
  /** Various states of the interface reported by |onStateChanged|.*/
  enum State : uint32_t {
    /**
     * This state indicates that client is not associated, but is likely to
     * start looking for an access point. This state is entered when a
     * connection is lost.
     */
    DISCONNECTED = 0,
    /**
     * This state is entered if the network interface is disabled, e.g.,
     * due to rfkill. the supplicant refuses any new operations that would
     * use the radio until the interface has been enabled.
     */
    IFACE_DISABLED = 1,
    /**
     * This state is entered if there are no enabled networks in the
     * configuration. the supplicant is not trying to associate with a new
     * network and external interaction (e.g., ctrl_iface call to add or
     * enable a network) is needed to start association.
     */
    INACTIVE = 2,
    /**
     * This state is entered when the supplicant starts scanning for a
     * network.
     */
    SCANNING = 3,
    /**
     * This state is entered when the supplicant has found a suitable BSS
     * to authenticate with and the driver is configured to try to
     * authenticate with this BSS. This state is used only with drivers
     * that use the supplicant as the SME.
     */
    AUTHENTICATING = 4,
    /**
     * This state is entered when the supplicant has found a suitable BSS
     * to associate with and the driver is configured to try to associate
     * with this BSS in ap_scan=1 mode. When using ap_scan=2 mode, this
     * state is entered when the driver is configured to try to associate
     * with a network using the configured SSID and security policy.
     */
    ASSOCIATING = 5,
    /**
     * This state is entered when the driver reports that association has
     * been successfully completed with an AP. If IEEE 802.1X is used
     * (with or without WPA/WPA2), the supplicant remains in this state
     * until the IEEE 802.1X/EAPOL authentication has been completed.
     */
    ASSOCIATED = 6,
    /**
     * This state is entered when WPA/WPA2 4-Way Handshake is started. In
     * case of WPA-PSK, this happens when receiving the first EAPOL-Key
     * frame after association. In case of WPA-EAP, this state is entered
     * when the IEEE 802.1X/EAPOL authentication has been completed.
     */
    FOURWAY_HANDSHAKE = 7,
    /**
     * This state is entered when 4-Way Key Handshake has been completed
     * (i.e., when the supplicant sends out message 4/4) and when Group
     * Key rekeying is started by the AP (i.e., when supplicant receives
     * message 1/2).
     */
    GROUP_HANDSHAKE = 8,
    /**
     * This state is entered when the full authentication process is
     * completed. In case of WPA2, this happens when the 4-Way Handshake is
     * successfully completed. With WPA, this state is entered after the
     * Group Key Handshake; with IEEE 802.1X (non-WPA) connection is
     * completed after dynamic keys are received (or if not used, after
     * the EAP authentication has been completed). With static WEP keys and
     * plaintext connections, this state is entered when an association
     * has been completed.
     *
     * This state indicates that the supplicant has completed its
     * processing for the association phase and that data connection is
     * fully configured.
     */
    COMPLETED = 9
  };

  /**
   * OSU Method. Refer to section 4.8.1.3 of the Hotspot 2.0 spec.
   */
  enum OsuMethod : uint8_t {
    OMA_DM = 0,
    SOAP_XML_SPP = 1
  };

  /**
   * ANQP data for IEEE Std 802.11u-2011.
   * The format of the data within these elements follows the IEEE
   * Std 802.11u-2011 standard.
   */
  struct AnqpData {
    vec<uint8_t> venueName;
    vec<uint8_t> roamingConsortium;
    vec<uint8_t> ipAddrTypeAvailability;
    vec<uint8_t> naiRealm;
    vec<uint8_t> anqp3gppCellularNetwork;
    vec<uint8_t> domainName;
  };

  /**
   * ANQP data for Hotspot 2.0.
   * The format of the data within these elements follows the Hotspot 2.0
   * standard.
   */
  struct Hs20AnqpData {
    vec<uint8_t> operatorFriendlyName;
    vec<uint8_t> wanMetrics;
    vec<uint8_t> connectionCapability;
    vec<uint8_t> osuProvidersList;
  };

  /**
   * Used to indicate that a new network has been added.
   *
   * @param id Network ID allocated to the corresponding network.
   */
  oneway onNetworkAdded(SupplicantNetworkId id);

  /**
   * Used to indicate that a network has been removed.
   *
   * @param id Network ID allocated to the corresponding network.
   */
  oneway onNetworkRemoved(SupplicantNetworkId id);

  /**
   * Used to indicate a state change event on this particular iface. If this
   * event is triggered by a particular network, the |SupplicantNetworkId|,
   * |ssid|, |bssid| parameters must indicate the parameters of the network/AP
   * which cased this state transition.
   *
   * @param newState New State of the interface. This must be one of the |State|
   *        values above.
   * @param bssid BSSID of the corresponding AP which caused this state
   *        change event. This must be zero'ed if this event is not
   *        specific to a particular network.
   * @param id ID of the corresponding network which caused this
   *        state change event. This must be invalid (UINT32_MAX) if this
   *        event is not specific to a particular network.
   * @param ssid SSID of the corresponding network which caused this state
   *        change event. This must be empty if this event is not specific
   *        to a particular network.
   */
  oneway onStateChanged(
      State newState, Bssid bssid, SupplicantNetworkId id, Ssid ssid);

  /**
   * Used to indicate the result of ANQP (either for IEEE 802.11u Interworking
   * or Hotspot 2.0) query.
   *
   * @param macAddress MAC address of the access point.
   * @param data ANQP data fetched from the access point.
   *        All the fields in this struct must be empty if the query failed.
   * @param hs20Data ANQP data fetched from the Hotspot 2.0 access point.
   *        All the fields in this struct must be empty if the query failed.
   */
  oneway onAnqpQueryDone(MacAddress macAddress,
                         AnqpData data,
                         Hs20AnqpData hs20Data);

  /**
   * Used to indicate the result of Hotspot 2.0 Icon query.
   *
   * @param macAddress MAC address of the access point.
   * @param fileName Name of the file that was requested.
   * @param data Icon data fetched from the access point.
   *        Must be empty if the query failed.
   */
  oneway onHs20IconQueryDone(MacAddress macAddress,
                             string fileName,
                             vec<uint8_t> data);

  /**
   * Used to indicate a Hotspot 2.0 subscription remediation event.
   *
   * @param osuMethod OSU method.
   * @param url URL of the server.
   */
  oneway onHs20SubscriptionRemediation(OsuMethod osuMethod, string url);

  /**
   * Used to indicate a Hotspot 2.0 imminent deauth notice.
   *
   * @param reasonCode Code to indicate the deauth reason.
   *        Refer to section 3.2.1.2 of the Hotspot 2.0 spec.
   * @param reAuthDelayInSec Delay before reauthenticating.
   * @param url URL of the server.
   */
  oneway onHs20DeauthImminentNotice(uint32_t reasonCode,
                                    uint32_t reAuthDelayInSec,
                                    string url);

  /**
   * Used to indicate a disconnect from the currently connected
   * network on this iface,.
   *
   * @param bssid BSSID of the AP from which we disconnected.
   * @param locallyGenerated If the disconnect was triggered by
   *        wpa_supplicant.
   * @param reasonCode 802.11 code to indicate the disconnect reason
   *        from access point. Refer to section 8.4.1.7 of IEEE802.11 spec.
   */
  oneway onDisconnected(
          Bssid bssid, bool locallyGenerated, uint32_t reasonCode);

  /**
   * Used to indicate an association rejection recieved from the AP
   * to which the connection is being attempted.
   *
   * @param bssid BSSID of the corresponding AP which sent this
   *        reject.
   * @param statusCode 802.11 code to indicate the reject reason.
   *        Refer to section 8.4.1.9 of IEEE 802.11 spec.
   */
  oneway onAssociationRejected(Bssid bssid, uint32_t statusCode);
};