wifi/supplicant/aidl/android/hardware/wifi/supplicant/ISupplicantStaIfaceCallback.aidl

/*
 * Copyright (C) 2021 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;

import android.hardware.wifi.supplicant.AnqpData;
import android.hardware.wifi.supplicant.AssociationRejectionData;
import android.hardware.wifi.supplicant.AuxiliarySupplicantEventCode;
import android.hardware.wifi.supplicant.BssTmData;
import android.hardware.wifi.supplicant.BssidChangeReason;
import android.hardware.wifi.supplicant.DppAkm;
import android.hardware.wifi.supplicant.DppConfigurationData;
import android.hardware.wifi.supplicant.DppConnectionKeys;
import android.hardware.wifi.supplicant.DppEventType;
import android.hardware.wifi.supplicant.DppFailureCode;
import android.hardware.wifi.supplicant.DppProgressCode;
import android.hardware.wifi.supplicant.DppStatusErrorCode;
import android.hardware.wifi.supplicant.Hs20AnqpData;
import android.hardware.wifi.supplicant.OsuMethod;
import android.hardware.wifi.supplicant.PmkSaCacheData;
import android.hardware.wifi.supplicant.QosPolicyData;
import android.hardware.wifi.supplicant.QosPolicyScsResponseStatus;
import android.hardware.wifi.supplicant.StaIfaceCallbackState;
import android.hardware.wifi.supplicant.StaIfaceReasonCode;
import android.hardware.wifi.supplicant.SupplicantStateChangeData;
import android.hardware.wifi.supplicant.UsdMessageInfo;
import android.hardware.wifi.supplicant.UsdReasonCode;
import android.hardware.wifi.supplicant.UsdServiceDiscoveryInfo;
import android.hardware.wifi.supplicant.WpsConfigError;
import android.hardware.wifi.supplicant.WpsErrorIndication;

/**
 * Callback Interface exposed by the supplicant service
 * for each station mode interface (ISupplicantStaIface).
 *
 * Clients need to host an instance of this AIDL interface object and
 * pass a reference of the object to the supplicant via the
 * corresponding |ISupplicantStaIface.registerCallback| method.
 */
@VintfStability
oneway interface ISupplicantStaIfaceCallback {
    /**
     * Used to indicate the result of ANQP (either for IEEE 802.11u Interworking
     * or Hotspot 2.0) query.
     *
     * @param bssid BSSID 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.
     */
    void onAnqpQueryDone(in byte[] bssid, in AnqpData data, in Hs20AnqpData hs20Data);

    /**
     * Used to indicate an association rejection received from the AP
     * to which the connection is being attempted.
     *
     * @param assocRejectData Association Rejection related information.
     */
    void onAssociationRejected(in AssociationRejectionData assocRejectData);

    /**
     * Used to indicate the timeout of authentication to an AP.
     *
     * @param bssid BSSID of the corresponding AP.
     */
    void onAuthenticationTimeout(in byte[] bssid);

    /**
     * Indicates that an auxiliary event was generated by the supplicant.
     *
     * @param eventCode |AuxiliarySupplicantEventCode| for the event that occurred.
     * @param bssid BSSID of the AP which caused the event.
     * @param reasonString Additional information about why the event occurred.
     */
    void onAuxiliarySupplicantEvent(
            in AuxiliarySupplicantEventCode eventCode, in byte[] bssid, in String reasonString);

    /**
     * Indicates BTM request frame handling status.
     *
     * @param tmData Data retrieved from received BSS transition management
     * request frame.
     */
    void onBssTmHandlingDone(in BssTmData tmData);

    /**
     * Used to indicate the change of active bssid.
     * This is useful to figure out when the driver/firmware roams to a bssid
     * on its own.
     *
     * @param reason Reason why the bssid changed.
     * @param bssid BSSID of the corresponding AP.
     */
    void onBssidChanged(in BssidChangeReason reason, in byte[] bssid);

    /**
     * Used to indicate the disconnection 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.
     */
    void onDisconnected(
            in byte[] bssid, in boolean locallyGenerated, in StaIfaceReasonCode reasonCode);

    /**
     * Indicates a DPP failure event.
     *
     * ssid: A string indicating the SSID for the AP that the Enrollee attempted to connect.
     * channelList: A string containing a list of operating channels and operating classes
     *     indicating the channels that the Enrollee scanned in attempting to discover the AP.
     *     The list conforms to the following ABNF syntax:
     *         channel-list2 = class-and-channels *(“,” class-and-channels)
     *         class-and-channels = class “/” channel *(“,” channel)
     *         class = 1*3DIGIT
     *         channel = 1*3DIGIT
     * bandList: A list of band parameters that are supported by the Enrollee expressed as the
     *     Operating Class.
     */
    void onDppFailure(
            in DppFailureCode code, in String ssid, in String channelList, in char[] bandList);

    /**
     * Indicates a DPP progress event.
     */
    void onDppProgress(in DppProgressCode code);

    /**
     * Indicates a DPP success event.
     */
    void onDppSuccess(in DppEventType event);

    /**
     * Indicates DPP configuration received success event in Enrolee mode.
     * This is also triggered when Configurator generates credentials for itself
     * using generateSelfDppConfiguration() API
     * <p>
     * @deprecated This callback is deprecated from AIDL v2, newer HAL should call
     * onDppConfigReceived.
     */
    void onDppSuccessConfigReceived(in byte[] ssid, in String password, in byte[] psk,
            in DppAkm securityAkm, in DppConnectionKeys dppConnectionKeys);

    /**
     * Indicates DPP configuration sent success event (Configurator mode).
     */
    void onDppSuccessConfigSent();

    /**
     * Indicates an EAP authentication failure.
     * @param bssid BSSID of the access point.
     * @param errorCode Error code for EAP authentication failure.
     *        Either standard error code (enum EapErrorCode) or
     *        private error code defined by network provider.
     */
    void onEapFailure(in byte[] bssid, in int errorCode);

    /**
     * Used to indicate that the external radio work can start now.
     *
     * @param id Identifier generated for the radio work request.
     */
    void onExtRadioWorkStart(in int id);

    /**
     * Used to indicate that the external radio work request has timed out.
     *
     * @param id Identifier generated for the radio work request.
     */
    void onExtRadioWorkTimeout(in int id);

    /**
     * Used to indicate a Hotspot 2.0 imminent deauth notice.
     *
     * @param bssid BSSID of the access point.
     * @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.
     */
    void onHs20DeauthImminentNotice(
            in byte[] bssid, in int reasonCode, in int reAuthDelayInSec, in String url);

    /**
     * Used to indicate the result of Hotspot 2.0 Icon query.
     *
     * @deprecated This callback is deprecated from AIDL v3.
     *
     * @param bssid BSSID 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.
     */
    void onHs20IconQueryDone(in byte[] bssid, in String fileName, in byte[] data);

    /**
     * Used to indicate a Hotspot 2.0 subscription remediation event.
     *
     * @param bssid BSSID of the access point.
     * @param osuMethod OSU method.
     * @param url URL of the server.
     */
    void onHs20SubscriptionRemediation(in byte[] bssid, in OsuMethod osuMethod, in String url);

    /**
     * Used to indicate a Hotspot 2.0 terms and conditions acceptance is requested from the user
     * before allowing the device to get internet access.
     *
     * @param bssid BSSID of the access point.
     * @param url URL of the T&C server.
     */
    void onHs20TermsAndConditionsAcceptanceRequestedNotification(in byte[] bssid, in String url);

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

    /**
     * Used to indicate that the supplicant failed to find a network in scan result
     * which matches with the network capabilities requested by upper layer
     * for connection.
     *
     * @param ssid network name supplicant tried to connect.
     */
    void onNetworkNotFound(in byte[] ssid);

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

    /**
     * Indicates pairwise master key (PMK) cache added event.
     *
     * @deprecated use onPmkSaCacheAdded() instead.
     *
     * @param expirationTimeInSec expiration time in seconds
     * @param serializedEntry is serialized PMK cache entry, the content is
     *              opaque for the framework and depends on the native implementation.
     */
    void onPmkCacheAdded(in long expirationTimeInSec, in byte[] serializedEntry);

    /**
     * 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 caused this state transition.
     * <p>
     * @deprecated This callback is deprecated from AIDL v2, newer HAL should call
     * onSupplicantStateChanged()
     *
     * @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.
     * @param filsHlpSent If FILS HLP IEs were included in this association.
     */
    void onStateChanged(in StaIfaceCallbackState newState, in byte[] bssid, in int id,
            in byte[] ssid, in boolean filsHlpSent);

    /**
     * Used to indicate the failure of a WPS connection attempt.
     *
     * @param bssid BSSID of the AP to which we initiated WPS
     *        connection.
     * @param configError Configuration error code.
     * @param errorInd Error indication code.
     */
    void onWpsEventFail(
            in byte[] bssid, in WpsConfigError configError, in WpsErrorIndication errorInd);

    /**
     * Used to indicate the overlap of a WPS PBC connection attempt.
     */
    void onWpsEventPbcOverlap();

    /**
     * Used to indicate the success of a WPS connection attempt.
     */
    void onWpsEventSuccess();

    /**
     * Used to indicate that the AP has cleared all DSCP requests
     * associated with this device.
     */
    void onQosPolicyReset();

    /**
     * Used to indicate a DSCP request was received from the AP.
     *
     * @param qosPolicyRequestId Dialog token to identify the request.
     * @param qosPolicyData QoS policies info requested by the AP.
     */
    void onQosPolicyRequest(in int qosPolicyRequestId, in QosPolicyData[] qosPolicyData);

    /**
     * Reason codes to be used with the callback |ISupplicantStaIfaceCallback.onMloLinksInfoChanged|
     */
    @VintfStability
    @Backing(type="int")
    enum MloLinkInfoChangeReason {
        /**
         * TID-to-link mapping has changed. Updated mappings will be set in
         * |MloLinksInfo.MloLink[].tids_downlink_map| and
         * |MloLinksInfo.MloLink[].tids_uplink_map| for each of the links.
         *
         * STA MLD will operate in default mode if a TID-to-link mapping is not
         * indicated by the callback. In default mode, all TIDs are mapped to
         * all setup links in downlink and uplink directions.
         */
        TID_TO_LINK_MAP = 0,
        /**
         * Multi-link reconfiguration - AP removal as described in the Wi-Fi 7 R1 MRD section
         * 6.3.2.18. This is a mandatory feature for station.
         *
         * Removed link will not be present in |ISupplicantStaIface.getConnectionMloLinksInfo|.
         */
        MULTI_LINK_RECONFIG_AP_REMOVAL = 1,
        /**
         * Multi-link reconfiguration add/delete links without re-association as described in
         * the Wi-Fi 7 R2 MRD section 6.4.2.4. This is an optional feature.
         *
         * This feature enables dynamic link reconfiguration operations (add link and/or delete
         * link) on the multi-link setup of a STA MLD, either triggered by the AP MLD or initiated
         * by the STA MLD itself. This avoids reassociation for any link reconfiguration operation.
         *
         * Added link will be present in |ISupplicantStaIface.getConnectionMloLinksInfo|.
         * Deleted link will not be present in |ISupplicantStaIface.getConnectionMloLinksInfo|.
         */
        MULTI_LINK_DYNAMIC_RECONFIG = 2,
    }

    /**
     * Used to indicate that Multi Link status has changed due to the provided
     * reason. Upadted MLO link status can be fetched using
     * |ISupplicantStaIface.getConnectionMloLinksInfo|
     *
     * |MloLink.linkId| and |MloLink.staLinkMacAddress| are not expected
     * to change.
     *
     * @param reason Reason as given in MloLinkInfoChangeReason.
     */
    void onMloLinksInfoChanged(in MloLinkInfoChangeReason reason);

    /**
     * Indicates DPP configuration received success event in Enrollee mode.
     * This is also triggered when Configurator generates credentials for itself
     * using generateSelfDppConfiguration() API
     */
    void onDppConfigReceived(in DppConfigurationData configData);

    /**
     * Indicates that DPP connection status result frame is sent.
     */
    void onDppConnectionStatusResultSent(in DppStatusErrorCode code);

    /**
     * Used to indicate that the operating frequency has changed for this BSS.
     * This event is triggered when STA switches the channel due to channel
     * switch announcement from the connected access point.
     *
     * @param frequencyMhz New operating frequency in MHz.
     */
    void onBssFrequencyChanged(in int frequencyMhz);

    /**
     * Used to indicate a state change event on this particular iface.
     *
     * @param stateChangeData Supplicant state change related information.
     */
    void onSupplicantStateChanged(in SupplicantStateChangeData stateChangeData);

    /**
     * Indicates an SCS response from the AP.
     *
     * If the AP does not send a response within the timeout period (1 sec),
     * supplicant will call this API with the TIMEOUT status for each policy.
     *
     * The AP can trigger an unsolicited scs response to indicate the removal of
     * previously requested policies.
     *
     * @param qosPolicyScsResponseStatus[] status for each SCS id.
     */
    void onQosPolicyResponseForScs(in QosPolicyScsResponseStatus[] qosPolicyScsResponseStatus);

    /**
     * Indicates pairwise master key (PMK) cache added event.
     *
     * @param pmkSaData PMKSA cache entry added details.
     *
     */
    void onPmkSaCacheAdded(in PmkSaCacheData pmkSaData);

    /**
     * Called in response to |ISupplicantStaIface.startUsdPublish| to indicate that the
     * publish session was started successfully.
     *
     * @param cmdId Identifier for the original request.
     * @param publishId Identifier for the publish session.
     */
    void onUsdPublishStarted(in int cmdId, in int publishId);

    /**
     * Called in response to |ISupplicantStaIface.startUsdSubscribe| to indicate that the
     * subscribe session was started successfully.
     *
     * @param cmdId Identifier for the original request.
     * @param subscribeId Identifier for the subscribe session.
     */
    void onUsdSubscribeStarted(in int cmdId, in int subscribeId);

    /**
     * Called in response to |ISupplicantStaIface.startUsdPublish| to indicate that the
     * publish session could not be configured.
     *
     * @param cmdId Identifier for the original request.
     */
    void onUsdPublishConfigFailed(in int cmdId);

    /**
     * Called in response to |ISupplicantStaIface.startUsdSubscribe| to indicate that the
     * subscribe session could not be configured.
     *
     * @param cmdId Identifier for the original request.
     */
    void onUsdSubscribeConfigFailed(in int cmdId);

    /**
     * Called in response to |ISupplicantStaIface.cancelUsdPublish| to indicate that the session
     * was cancelled successfully. May also be called unsolicited if the session terminated
     * by supplicant.
     *
     * @param publishId Identifier for the publish session.
     * @param reasonCode Code indicating the reason for the session cancellation.
     */
    void onUsdPublishTerminated(in int publishId, in UsdReasonCode reasonCode);

    /**
     * Called in response to |ISupplicantStaIface.cancelUsdSubscribe| to indicate that the session
     * was cancelled successfully. May also be called unsolicited if the session terminated
     * by supplicant.
     *
     * @param subscribeId Identifier for the subscribe session.
     * @param reasonCode Code indicating the reason for the session cancellation.
     */
    void onUsdSubscribeTerminated(in int subscribeId, in UsdReasonCode reasonCode);

    /**
     * Indicates that the publisher sent solicited publish message to the subscriber.
     *
     * @param info Instance of |UsdServiceDiscoveryInfo| containing information about the reply.
     */
    void onUsdPublishReplied(in UsdServiceDiscoveryInfo info);

    /**
     * Indicates that a publisher was discovered. Only called if this device is acting as a
     * subscriber.
     *
     * @param info Instance of |UsdServiceDiscoveryInfo| containing information about the service.
     */
    void onUsdServiceDiscovered(in UsdServiceDiscoveryInfo info);

    /**
     * Indicates that a message was received on an active USD link.
     *
     * @param messageInfo Information about the message that was received.
     */
    void onUsdMessageReceived(in UsdMessageInfo messageInfo);
}