Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 9bfb2434 authored by Thomas Stuart's avatar Thomas Stuart
Browse files

Platform Telecom Transactional APIs 

Telecom Transactional APIs are defined as APIs that leverage
android.os.OutcomeReceivers.  The receivers are to be completed by
Telecom for CallControl opertaions and the Client for CallEventCallback
operations.  Doing so ensures the client and telecom are in sync with
call states.  Also, these APIs are more lightweight than the
ConnectionService way of starting a self-managed call.

bug: 249779561
Test: atest android.telecom.cts.TransactionalApisTest

Change-Id: Icb09b2874d599a40afca8b7e960b14ca1bca606d
parent 765accac

core/api/current.txt

+61 −0
Original line number Original line Diff line number Diff line
@@ -41004,6 +41004,32 @@ package android.telecom { 
    field public static final int RTT_MODE_VCO = 3; // 0x3

    field public static final int RTT_MODE_VCO = 3; // 0x3

  }

  }




















  public final class CallAttributes implements android.os.Parcelable {














    method public int describeContents();














    method @NonNull public android.net.Uri getAddress();














    method public int getCallCapabilities();














    method public int getCallType();














    method public int getDirection();














    method @NonNull public CharSequence getDisplayName();














    method @NonNull public android.telecom.PhoneAccountHandle getPhoneAccountHandle();














    method public void writeToParcel(@Nullable android.os.Parcel, int);














    field public static final int AUDIO_CALL = 1; // 0x1














    field @NonNull public static final android.os.Parcelable.Creator<android.telecom.CallAttributes> CREATOR;














    field public static final int DIRECTION_INCOMING = 1; // 0x1














    field public static final int DIRECTION_OUTGOING = 2; // 0x2














    field public static final int SUPPORTS_SET_INACTIVE = 2; // 0x2














    field public static final int SUPPORTS_STREAM = 4; // 0x4














    field public static final int SUPPORTS_TRANSFER = 8; // 0x8














    field public static final int VIDEO_CALL = 2; // 0x2














  }



























  public static final class CallAttributes.Builder {














    ctor public CallAttributes.Builder(@NonNull android.telecom.PhoneAccountHandle, int, @NonNull CharSequence, @NonNull android.net.Uri);














    method @NonNull public android.telecom.CallAttributes build();














    method @NonNull public android.telecom.CallAttributes.Builder setCallCapabilities(int);














    method @NonNull public android.telecom.CallAttributes.Builder setCallType(int);














  }
























  public final class CallAudioState implements android.os.Parcelable {







  public final class CallAudioState implements android.os.Parcelable {











    ctor public CallAudioState(boolean, int, int);







    ctor public CallAudioState(boolean, int, int);











    method public static String audioRouteToString(int);







    method public static String audioRouteToString(int);









@@ -41022,6 +41048,15 @@ package android.telecom {









    field public static final int ROUTE_WIRED_OR_EARPIECE = 5; // 0x5







    field public static final int ROUTE_WIRED_OR_EARPIECE = 5; // 0x5











  }







  }






























  public final class CallControl implements java.lang.AutoCloseable {














    method public void close();














    method public void disconnect(@NonNull android.telecom.DisconnectCause, @NonNull java.util.concurrent.Executor, @NonNull android.os.OutcomeReceiver<java.lang.Void,android.telecom.CallException>);














    method @NonNull public android.os.ParcelUuid getCallId();














    method public void rejectCall(@NonNull java.util.concurrent.Executor, @NonNull android.os.OutcomeReceiver<java.lang.Void,android.telecom.CallException>);














    method public void setActive(@NonNull java.util.concurrent.Executor, @NonNull android.os.OutcomeReceiver<java.lang.Void,android.telecom.CallException>);














    method public void setInactive(@NonNull java.util.concurrent.Executor, @NonNull android.os.OutcomeReceiver<java.lang.Void,android.telecom.CallException>);














  }
























  public final class CallEndpoint implements android.os.Parcelable {







  public final class CallEndpoint implements android.os.Parcelable {











    ctor public CallEndpoint(@NonNull CharSequence, int, @NonNull android.os.ParcelUuid);







    ctor public CallEndpoint(@NonNull CharSequence, int, @NonNull android.os.ParcelUuid);











    method public int describeContents();







    method public int describeContents();










@@ -41052,6 +41087,30 @@ package android.telecom {









    field public static final int ERROR_UNSPECIFIED = 4; // 0x4







    field public static final int ERROR_UNSPECIFIED = 4; // 0x4











  }







  }






























  public interface CallEventCallback {














    method public void onAnswer(int, @NonNull java.util.function.Consumer<java.lang.Boolean>);














    method public void onCallAudioStateChanged(@NonNull android.telecom.CallAudioState);














    method public void onDisconnect(@NonNull java.util.function.Consumer<java.lang.Boolean>);














    method public void onReject(@NonNull java.util.function.Consumer<java.lang.Boolean>);














    method public void onSetActive(@NonNull java.util.function.Consumer<java.lang.Boolean>);














    method public void onSetInactive(@NonNull java.util.function.Consumer<java.lang.Boolean>);














  }



























  public final class CallException extends java.lang.RuntimeException implements android.os.Parcelable {














    ctor public CallException(@Nullable String);














    ctor public CallException(@Nullable String, int);














    method public int describeContents();














    method public int getCode();














    method public void writeToParcel(@NonNull android.os.Parcel, int);














    field public static final int CODE_CALL_CANNOT_BE_SET_TO_ACTIVE = 4; // 0x4














    field public static final int CODE_CALL_IS_NOT_BEING_TRACKED = 3; // 0x3














    field public static final int CODE_CALL_NOT_PERMITTED_AT_PRESENT_TIME = 5; // 0x5














    field public static final int CODE_CANNOT_HOLD_CURRENT_ACTIVE_CALL = 2; // 0x2














    field public static final int CODE_ERROR_UNKNOWN = 1; // 0x1














    field public static final int CODE_OPERATION_TIMED_OUT = 6; // 0x6














    field @NonNull public static final android.os.Parcelable.Creator<android.telecom.CallException> CREATOR;














  }
























  public abstract class CallRedirectionService extends android.app.Service {







  public abstract class CallRedirectionService extends android.app.Service {











    ctor public CallRedirectionService();







    ctor public CallRedirectionService();











    method public final void cancelCall();







    method public final void cancelCall();










@@ -41561,6 +41620,7 @@ package android.telecom {









    field public static final int CAPABILITY_RTT = 4096; // 0x1000







    field public static final int CAPABILITY_RTT = 4096; // 0x1000











    field public static final int CAPABILITY_SELF_MANAGED = 2048; // 0x800







    field public static final int CAPABILITY_SELF_MANAGED = 2048; // 0x800











    field public static final int CAPABILITY_SIM_SUBSCRIPTION = 4; // 0x4







    field public static final int CAPABILITY_SIM_SUBSCRIPTION = 4; // 0x4














    field public static final int CAPABILITY_SUPPORTS_TRANSACTIONAL_OPERATIONS = 262144; // 0x40000











    field public static final int CAPABILITY_SUPPORTS_VIDEO_CALLING = 1024; // 0x400







    field public static final int CAPABILITY_SUPPORTS_VIDEO_CALLING = 1024; // 0x400











    field public static final int CAPABILITY_SUPPORTS_VOICE_CALLING_INDICATIONS = 65536; // 0x10000







    field public static final int CAPABILITY_SUPPORTS_VOICE_CALLING_INDICATIONS = 65536; // 0x10000











    field public static final int CAPABILITY_VIDEO_CALLING = 8; // 0x8







    field public static final int CAPABILITY_VIDEO_CALLING = 8; // 0x8










@@ -41753,6 +41813,7 @@ package android.telecom {









    method public void acceptHandover(android.net.Uri, int, android.telecom.PhoneAccountHandle);







    method public void acceptHandover(android.net.Uri, int, android.telecom.PhoneAccountHandle);











    method @Deprecated @RequiresPermission(anyOf={android.Manifest.permission.ANSWER_PHONE_CALLS, android.Manifest.permission.MODIFY_PHONE_STATE}) public void acceptRingingCall();







    method @Deprecated @RequiresPermission(anyOf={android.Manifest.permission.ANSWER_PHONE_CALLS, android.Manifest.permission.MODIFY_PHONE_STATE}) public void acceptRingingCall();











    method @Deprecated @RequiresPermission(anyOf={android.Manifest.permission.ANSWER_PHONE_CALLS, android.Manifest.permission.MODIFY_PHONE_STATE}) public void acceptRingingCall(int);







    method @Deprecated @RequiresPermission(anyOf={android.Manifest.permission.ANSWER_PHONE_CALLS, android.Manifest.permission.MODIFY_PHONE_STATE}) public void acceptRingingCall(int);














    method @RequiresPermission(android.Manifest.permission.MANAGE_OWN_CALLS) public void addCall(@NonNull android.telecom.CallAttributes, @NonNull java.util.concurrent.Executor, @NonNull android.os.OutcomeReceiver<android.telecom.CallControl,android.telecom.CallException>, @NonNull android.telecom.CallEventCallback);











    method public void addNewIncomingCall(android.telecom.PhoneAccountHandle, android.os.Bundle);







    method public void addNewIncomingCall(android.telecom.PhoneAccountHandle, android.os.Bundle);











    method public void addNewIncomingConference(@NonNull android.telecom.PhoneAccountHandle, @NonNull android.os.Bundle);







    method public void addNewIncomingConference(@NonNull android.telecom.PhoneAccountHandle, @NonNull android.os.Bundle);











    method @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE) public void cancelMissedCallsNotification();







    method @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE) public void cancelMissedCallsNotification();

























telecomm/java/android/telecom/CallAttributes.aidl
0 → 100644



+22
−0




























Original line number
Original line
Diff line number
Diff line














/*














 * 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.telecom;





























/**














 * {@hide}














 */














parcelable CallAttributes;











 No newline at end of file
























telecomm/java/android/telecom/CallAttributes.java
0 → 100644



+344
−0




























Original line number
Original line
Diff line number
Diff line














/*














 * Copyright (C) 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.telecom;





























import android.annotation.IntDef;














import android.annotation.NonNull;














import android.annotation.Nullable;














import android.net.Uri;














import android.os.Parcel;














import android.os.Parcelable;














import android.text.TextUtils;





























import java.util.Objects;





























/**














 * CallAttributes represents a set of properties that define a new Call.  Apps should build an














 * instance of this class and use {@link TelecomManager#addCall} to start a new call with Telecom.














 *














 * <p>














 * Apps should first register a {@link PhoneAccount} via {@link TelecomManager#registerPhoneAccount}














 * and use the same {@link PhoneAccountHandle} registered with Telecom when creating an














 * instance of CallAttributes.














 */














public final class CallAttributes implements Parcelable {





























    /** PhoneAccountHandle associated with the App managing calls **/














    private final PhoneAccountHandle mPhoneAccountHandle;





























    /** Display name of the person on the other end of the call **/














    private final CharSequence mDisplayName;





























    /** Address of the call. Note, this can be extended to a meeting link **/














    private final Uri mAddress;





























    /** The direction (Outgoing/Incoming) of the new Call **/














    @Direction private final int mDirection;





























    /** Information related to data being transmitted (voice, video, etc. ) **/














    @CallType private final int mCallType;





























    /** Allows a package to opt into capabilities on the telecom side, on a per-call basis **/














    @CallCapability private final int mCallCapabilities;





























    /** @hide **/














    public static final String CALL_CAPABILITIES_KEY = "TelecomCapabilities";





























    private CallAttributes(@NonNull PhoneAccountHandle phoneAccountHandle,














            @NonNull CharSequence displayName,














            @NonNull Uri address,














            int direction,














            int callType,














            int callCapabilities) {














        mPhoneAccountHandle = phoneAccountHandle;














        mDisplayName = displayName;














        mAddress = address;














        mDirection = direction;














        mCallType = callType;














        mCallCapabilities = callCapabilities;














    }





























    /** @hide */














    @IntDef(value = {DIRECTION_INCOMING, DIRECTION_OUTGOING})














    public @interface Direction {














    }














    /**














     * Indicates that the call is an incoming call.














     */














    public static final int DIRECTION_INCOMING = 1;














    /**














     * Indicates that the call is an outgoing call.














     */














    public static final int DIRECTION_OUTGOING = 2;





























    /** @hide */














    @IntDef(value = {AUDIO_CALL, VIDEO_CALL})














    public @interface CallType {














    }














    /**














     * Used when answering or dialing a call to indicate that the call does not have a video














     * component














     */














    public static final int AUDIO_CALL = 1;














    /**














     * Indicates video transmission is supported














     */














    public static final int VIDEO_CALL = 2;





























    /** @hide */














    @IntDef(value = {SUPPORTS_SET_INACTIVE, SUPPORTS_STREAM, SUPPORTS_TRANSFER}, flag = true)














    public @interface CallCapability {














    }














    /**














     * The call being created can be set to inactive (traditionally referred to as hold).  This














     * means that once a new call goes active, if the active call needs to be held in order to














     * place or receive an incoming call, the active call will be placed on hold.  otherwise, the














     * active call may be disconnected.














     */














    public static final int SUPPORTS_SET_INACTIVE = 1 << 1;














    /**














     * The call can be streamed from a root device to another device to continue the call without














     * completely transferring it.














     */














    public static final int SUPPORTS_STREAM = 1 << 2;














    /**














     * The call can be completely transferred from one endpoint to another














     */














    public static final int SUPPORTS_TRANSFER = 1 << 3;





























    /**














     * Build an instance of {@link CallAttributes}. In order to build a valid instance, a














     * {@link PhoneAccountHandle}, call {@link Direction}, display name, and {@link Uri} address














     * are required.














     *














     * <p>














     * Note: Pass in the same {@link PhoneAccountHandle} that was used to register a














     * {@link PhoneAccount} with Telecom. see {@link TelecomManager#registerPhoneAccount}














     */














    public static final class Builder {














        // required and final fields














        private final PhoneAccountHandle mPhoneAccountHandle;














        @Direction private final int mDirection;














        private final CharSequence mDisplayName;














        private final Uri mAddress;














        // optional fields














        @CallType private int mCallType = CallAttributes.AUDIO_CALL;














        @CallCapability private int mCallCapabilities = SUPPORTS_SET_INACTIVE;





























        /**














         * Constructor for the CallAttributes.Builder class














         *














         * @param phoneAccountHandle that belongs to package registered with Telecom














         * @param callDirection of the new call that will be added to Telecom














         * @param displayName of the caller for incoming calls or initiating user for outgoing calls














         * @param address of the caller for incoming calls or destination for outgoing calls














         */














        public Builder(@NonNull PhoneAccountHandle phoneAccountHandle,














                @Direction int callDirection, @NonNull CharSequence displayName,














                @NonNull Uri address) {














            if (!isInRange(DIRECTION_INCOMING, DIRECTION_OUTGOING, callDirection)) {














                throw new IllegalArgumentException(TextUtils.formatSimple("CallDirection=[%d] is"














                                + " invalid. CallDirections value should be within [%d, %d]",














                        callDirection, DIRECTION_INCOMING, DIRECTION_OUTGOING));














            }














            Objects.requireNonNull(phoneAccountHandle);














            Objects.requireNonNull(displayName);














            Objects.requireNonNull(address);














            mPhoneAccountHandle = phoneAccountHandle;














            mDirection = callDirection;














            mDisplayName = displayName;














            mAddress = address;














        }





























        /**














         * @param callType see {@link CallType} for valid arguments














         * @return Builder














         */














        @NonNull














        public Builder setCallType(@CallType int callType) {














            if (!isInRange(AUDIO_CALL, VIDEO_CALL, callType)) {














                throw new IllegalArgumentException(TextUtils.formatSimple("CallType=[%d] is"














                                + " invalid. CallTypes value should be within [%d, %d]",














                        callType, AUDIO_CALL, VIDEO_CALL));














            }














            mCallType = callType;














            return this;














        }





























        /**














         * @param callCapabilities see {@link CallCapability} for valid arguments














         * @return Builder














         */














        @NonNull














        public Builder setCallCapabilities(@CallCapability int callCapabilities) {














            mCallCapabilities = callCapabilities;














            return this;














        }





























        /**














         * Build an instance of {@link CallAttributes} based on the last values passed to the














         * setters or default values.














         *














         * @return an instance of {@link CallAttributes}














         */














        @NonNull














        public CallAttributes build() {














            return new CallAttributes(mPhoneAccountHandle, mDisplayName, mAddress, mDirection,














                    mCallType, mCallCapabilities);














        }





























        /** @hide */














        private boolean isInRange(int floor, int ceiling, int value) {














            return value >= floor && value <= ceiling;














        }














    }





























    /**














     * The {@link PhoneAccountHandle} that should be registered to Telecom to allow calls.  The














     * {@link PhoneAccountHandle} should be registered before creating a CallAttributes instance.














     *














     * @return the {@link PhoneAccountHandle} for this package that allows this call to be created














     */














    @NonNull public PhoneAccountHandle getPhoneAccountHandle() {














        return mPhoneAccountHandle;














    }





























    /**














     * @return display name of the incoming caller or the person being called for an outgoing call














     */














    @NonNull public CharSequence getDisplayName() {














        return mDisplayName;














    }





























    /**














     * @return address of the incoming caller














     *           or the address of the person being called for an outgoing call














     */














    @NonNull public Uri getAddress() {














        return mAddress;














    }





























    /**














     * @return the direction of the new call.














     */














    public @Direction int getDirection() {














        return mDirection;














    }





























    /**














     * @return Information related to data being transmitted (voice, video, etc. )














     */














    public @CallType int getCallType() {














        return mCallType;














    }





























    /**














     * @return The allowed capabilities of the new call














     */














    public @CallCapability int getCallCapabilities() {














        return mCallCapabilities;














    }





























    @Override














    public int describeContents() {














        return 0;














    }





























    @Override














    public void writeToParcel(@Nullable Parcel dest, int flags) {














        dest.writeParcelable(mPhoneAccountHandle, flags);














        dest.writeCharSequence(mDisplayName);














        dest.writeParcelable(mAddress, flags);














        dest.writeInt(mDirection);














        dest.writeInt(mCallType);














        dest.writeInt(mCallCapabilities);














    }





























    /**














     * Responsible for creating CallAttribute objects for deserialized Parcels.














     */














    public static final @android.annotation.NonNull














            Parcelable.Creator<CallAttributes> CREATOR =














            new Parcelable.Creator<>() {














                @Override














                public CallAttributes createFromParcel(Parcel source) {














                    return new CallAttributes(source.readParcelable(getClass().getClassLoader(),














                            android.telecom.PhoneAccountHandle.class),














                            source.readCharSequence(),














                            source.readParcelable(getClass().getClassLoader(),














                                    android.net.Uri.class),














                            source.readInt(),














                            source.readInt(),














                            source.readInt());














                }





























                @Override














                public CallAttributes[] newArray(int size) {














                    return new CallAttributes[size];














                }














            };





























    /**














     * {@inheritDoc}














     */














    @Override














    public String toString() {














        StringBuilder sb = new StringBuilder();





























        sb.append("{ CallAttributes: [phoneAccountHandle: ")














                .append(mPhoneAccountHandle)  /* PhoneAccountHandle#toString handles PII */














                .append("], [contactName: ")














                .append(Log.pii(mDisplayName))














                .append("], [address=")














                .append(Log.pii(mAddress))














                .append("], [direction=")














                .append(mDirection)














                .append("], [callType=")














                .append(mCallType)














                .append("], [mCallCapabilities=")














                .append(mCallCapabilities)














                .append("]  }");





























        return sb.toString();














    }





























    /**














     * {@inheritDoc}














     */














    @Override














    public boolean equals(Object obj) {














        if (obj == null || obj.getClass() != this.getClass()) {














            return false;














        }














        CallAttributes that = (CallAttributes) obj;














        return this.mDirection == that.mDirection














                && this.mCallType == that.mCallType














                && this.mCallCapabilities == that.mCallCapabilities














                && Objects.equals(this.mPhoneAccountHandle, that.mPhoneAccountHandle)














                && Objects.equals(this.mAddress, that.mAddress)














                && Objects.equals(this.mDisplayName, that.mDisplayName);














    }





























    /**














     * {@inheritDoc}














     */














    @Override














    public int hashCode() {














        return Objects.hash(mPhoneAccountHandle, mAddress, mDisplayName,














                mDirection, mCallType, mCallCapabilities);














    }














}
























telecomm/java/android/telecom/CallControl.aidl
0 → 100644



+22
−0




























Original line number
Original line
Diff line number
Diff line














/*














 * 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.telecom;





























/**














 * {@hide}














 */














parcelable CallControl;
























telecomm/java/android/telecom/CallControl.java
0 → 100644



+250
−0


























File added.
Preview size limit exceeded, changes collapsed.