android/bluetooth/BluetoothSinkAudioPolicy.java

/*
 * Copyright 2022 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.bluetooth;

import android.annotation.IntDef;
import android.annotation.NonNull;
import android.annotation.Nullable;
import android.annotation.SystemApi;
import android.os.Parcel;
import android.os.Parcelable;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.util.Objects;

/**
 * Represents Bluetooth Audio Policies of a Handsfree (HF) device (if HFP is used)
 * and Call Terminal (CT) device (if BLE Audio is used), which describes the
 * preferences of allowing or disallowing audio based on the use cases. The HF/CT
 * devices shall send objects of this class to send its preference to the AG/CG
 * devices.
 *
 * <p>HF/CT side applications on can use {@link BluetoothDevice#requestAudioPolicyAsSink}
 * API to set and send a {@link BluetoothSinkAudioPolicy} object containing the
 * preference/policy values. This object will be stored in the memory of HF/CT
 * side, will be send to the AG/CG side using Android Specific AT Commands and will
 * be stored in the AG side memory and database.
 *
 * <p>HF/CT side API {@link BluetoothDevice#getRequestedAudioPolicyAsSink} can be used to retrieve
 * the stored audio policies currently.
 *
 * <p>Note that the setter APIs of this class will only set the values of the
 * object. To actually set the policies, API {@link BluetoothDevice#requestAudioPolicyAsSink}
 * must need to be invoked with the {@link BluetoothSinkAudioPolicy} object.
 *
 * <p>Note that any API related to this feature should be used after configuring
 * the support of the AG device and after checking whether the AG device supports
 * this feature or not by invoking {@link BluetoothDevice#isRequestAudioPolicyAsSinkSupported}.
 * Only after getting a {@link BluetoothStatusCodes#FEATURE_SUPPORTED} response
 * from the API should the APIs related to this feature be used.
 *
 *
 * @hide
 */
@SystemApi
public final class BluetoothSinkAudioPolicy implements Parcelable {

    /**
     * @hide
    */
    @Retention(RetentionPolicy.SOURCE)
    @IntDef(
        prefix = {"POLICY_"},
        value = {
            POLICY_UNCONFIGURED,
            POLICY_ALLOWED,
            POLICY_NOT_ALLOWED,
        }
    )
    public @interface AudioPolicyValues{}

    /**
     * Audio behavior not configured for the policy.
     *
     * If a policy is set with this value, it means that the policy is not
     * configured with a value yet and should not be used to make any decision.
     * @hide
     */
    @SystemApi
    public static final int POLICY_UNCONFIGURED = 0;

    /**
     * Audio is preferred by HF device for the policy.
     *
     * If a policy is set with this value, then the HF device will prefer the
     * audio for the policy use case. For example, if the Call Establish audio
     * policy is set with this value, then the HF will prefer the audio
     * during making or picking up a call.
     * @hide
     */
    @SystemApi
    public static final int POLICY_ALLOWED = 1;

    /**
     * Audio is not preferred by HF device for the policy.
     *
     * If a policy is set with this value, then the HF device will not prefer the
     * audio for the policy use case. For example, if the Call Establish audio
     * policy is set with this value, then the HF will not prefer the audio
     * during making or picking up a call.
     * @hide
     */
    @SystemApi
    public static final int POLICY_NOT_ALLOWED = 2;

    /**
     * The feature ID used in the HFP AT command.
     * @hide
     */
    public static final String HFP_SET_SINK_AUDIO_POLICY_ID = "SINKAUDIOPOLICY";

    @AudioPolicyValues private final int mCallEstablishPolicy;
    @AudioPolicyValues private final int mConnectingTimePolicy;
    @AudioPolicyValues private final int mInBandRingtonePolicy;

    /**
     * @hide
     */
    public BluetoothSinkAudioPolicy(int callEstablishPolicy,
            int connectingTimePolicy, int inBandRingtonePolicy) {
        mCallEstablishPolicy = callEstablishPolicy;
        mConnectingTimePolicy = connectingTimePolicy;
        mInBandRingtonePolicy = inBandRingtonePolicy;
    }

    /**
     * Get Call establishment policy audio policy.
     * <p>This policy is used to determine the audio preference when the
     * HF device makes or answers a call. That is, if this device
     * makes or answers a call, is the audio preferred by HF.
     *
     * @return the call pick up audio policy value
     *
     * @hide
     */
    @SystemApi
    public @AudioPolicyValues int getCallEstablishPolicy() {
        return mCallEstablishPolicy;
    }

    /**
     * Get during connection audio up policy.
     * <p>This policy is used to determine the audio preference when the
     * HF device connects with the AG device. That is, when the
     * HF device gets connected, should the HF become active and get audio
     * is decided by this policy. This also covers the case of during a call.
     * If the HF connects with the AG during an ongoing call, should the call
     * audio be routed to the HF will be decided by this policy.
     *
     * @return the during connection audio policy value
     *
     * @hide
     */
    @SystemApi
    public @AudioPolicyValues int getActiveDevicePolicyAfterConnection() {
        return mConnectingTimePolicy;
    }

    /**
     * Get In band ringtone audio up policy.
     * <p>This policy is used to determine the audio preference of the
     * in band ringtone. That is, if there is an incoming call, should the
     * inband ringtone audio be routed to the HF will be decided by this policy.
     *
     * @return the in band ringtone audio policy value
     *
     * @hide
     */
    @SystemApi
    public @AudioPolicyValues int getInBandRingtonePolicy() {
        return mInBandRingtonePolicy;
    }

    @Override
    public String toString() {
        StringBuilder builder = new StringBuilder("BluetoothSinkAudioPolicy{");
        builder.append("mCallEstablishPolicy: ");
        builder.append(mCallEstablishPolicy);
        builder.append(", mConnectingTimePolicy: ");
        builder.append(mConnectingTimePolicy);
        builder.append(", mInBandRingtonePolicy: ");
        builder.append(mInBandRingtonePolicy);
        builder.append("}");
        return builder.toString();
    }

    /**
     * {@link Parcelable.Creator} interface implementation.
     */
    public static final @android.annotation.NonNull Parcelable.Creator<BluetoothSinkAudioPolicy>
            CREATOR = new Parcelable.Creator<BluetoothSinkAudioPolicy>() {
                @Override
                public BluetoothSinkAudioPolicy createFromParcel(@NonNull Parcel in) {
                    return new BluetoothSinkAudioPolicy(
                            in.readInt(), in.readInt(), in.readInt());
                }

                @Override
                public BluetoothSinkAudioPolicy[] newArray(int size) {
                    return new BluetoothSinkAudioPolicy[size];
                }
            };

    @Override
    public void writeToParcel(@NonNull Parcel out, int flags) {
        out.writeInt(mCallEstablishPolicy);
        out.writeInt(mConnectingTimePolicy);
        out.writeInt(mInBandRingtonePolicy);
    }

    /**
     * @hide
     */
    @Override
    public int describeContents() {
        return 0;
    }

    @Override
    public boolean equals(@Nullable Object o) {
        if (o instanceof BluetoothSinkAudioPolicy) {
            BluetoothSinkAudioPolicy other = (BluetoothSinkAudioPolicy) o;
            return (other.mCallEstablishPolicy == mCallEstablishPolicy
                    && other.mConnectingTimePolicy == mConnectingTimePolicy
                    && other.mInBandRingtonePolicy == mInBandRingtonePolicy);
        }
        return false;
    }

    /**
     * Returns a hash representation of this BluetoothCodecConfig
     * based on all the config values.
     *
     * @hide
     */
    @Override
    public int hashCode() {
        return Objects.hash(mCallEstablishPolicy, mConnectingTimePolicy, mInBandRingtonePolicy);
    }

    /**
     * Builder for {@link BluetoothSinkAudioPolicy}.
     * <p> By default, the audio policy values will be set to
     * {@link BluetoothSinkAudioPolicy#POLICY_UNCONFIGURED}.
     */
    public static final class Builder {
        private int mCallEstablishPolicy = POLICY_UNCONFIGURED;
        private int mConnectingTimePolicy = POLICY_UNCONFIGURED;
        private int mInBandRingtonePolicy = POLICY_UNCONFIGURED;

        public Builder() {

        }

        public Builder(@NonNull BluetoothSinkAudioPolicy policies) {
            mCallEstablishPolicy = policies.mCallEstablishPolicy;
            mConnectingTimePolicy = policies.mConnectingTimePolicy;
            mInBandRingtonePolicy = policies.mInBandRingtonePolicy;
        }

        /**
         * Set Call Establish (pick up and answer) policy.
         * <p>This policy is used to determine the audio preference when the
         * HF device makes or answers a call. That is, if this device
         * makes or answers a call, is the audio preferred by HF.
         * <p>If set to {@link BluetoothSinkAudioPolicy#POLICY_ALLOWED}, answering or making
         * a call from the HF device will route the call audio to it.
         * If set to {@link BluetoothSinkAudioPolicy#POLICY_NOT_ALLOWED}, answering or making
         * a call from the HF device will NOT route the call audio to it.
         *
         * @return reference to the current object
         *
         * @hide
         */
        @SystemApi public @NonNull Builder setCallEstablishPolicy(
                @AudioPolicyValues int callEstablishPolicy) {
            mCallEstablishPolicy = callEstablishPolicy;
            return this;
        }

        /**
         * Set during connection audio up policy.
         * <p>This policy is used to determine the audio preference when the
         * HF device connects with the AG device. That is, when the
         * HF device gets connected, should the HF become active and get audio
         * is decided by this policy. This also covers the case of during a call.
         * If the HF connects with the AG during an ongoing call, should the call
         * audio be routed to the HF will be decided by this policy.
         * <p>If set to {@link BluetoothSinkAudioPolicy#POLICY_ALLOWED}, connecting HF
         * during a call will route the call audio to it.
         * If set to {@link BluetoothSinkAudioPolicy#POLICY_NOT_ALLOWED}, connecting HF
         * during a call will NOT route the call audio to it.
         *
         * @return reference to the current object
         *
         * @hide
         */
        @SystemApi public @NonNull Builder setActiveDevicePolicyAfterConnection(
                @AudioPolicyValues int connectingTimePolicy) {
            mConnectingTimePolicy = connectingTimePolicy;
            return this;
        }

        /**
         * Set In band ringtone audio up policy.
         * <p>This policy is used to determine the audio preference of the
         * in band ringtone. That is, if there is an incoming call, should the
         * inband ringtone audio be routed to the HF will be decided by this policy.
         * <p>If set to {@link BluetoothSinkAudioPolicy#POLICY_ALLOWED}, there will be
         * in band ringtone in the HF device during an incoming call.
         * If set to {@link BluetoothSinkAudioPolicy#POLICY_NOT_ALLOWED}, there will NOT
         * be in band ringtone in the HF device during an incoming call.
         *
         * @return reference to the current object
         *
         * @hide
         */
        @SystemApi public @NonNull Builder setInBandRingtonePolicy(
                @AudioPolicyValues int inBandRingtonePolicy) {
            mInBandRingtonePolicy = inBandRingtonePolicy;
            return this;
        }

        /**
         * Build {@link BluetoothSinkAudioPolicy}.
         * @return new BluetoothSinkAudioPolicy object
         *
         * @hide
         */
        @SystemApi public @NonNull BluetoothSinkAudioPolicy build() {
            return new BluetoothSinkAudioPolicy(
                    mCallEstablishPolicy, mConnectingTimePolicy, mInBandRingtonePolicy);
        }
    }
}