blob: afd34fc74e4301bdd839f9ccdda5dc2aa709acc1 [file] [log] [blame]
/*
* 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.FlaggedApi;
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 com.android.server.telecom.flags.Flags;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
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";
/** @hide **/
public static final String DISPLAY_NAME_KEY = "DisplayName";
/** @hide **/
public static final String CALLER_PID_KEY = "CallerPid";
/** @hide **/
public static final String CALLER_UID_KEY = "CallerUid";
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})
@Retention(RetentionPolicy.SOURCE)
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})
@Retention(RetentionPolicy.SOURCE)
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,
SUPPORTS_VIDEO_CALLING}, flag = true)
@Retention(RetentionPolicy.SOURCE)
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;
/**
* The call supports video calling. This allows clients to gate video calling on a per call
* basis as opposed to re-registering the phone account.
*/
@FlaggedApi(Flags.FLAG_TRANSACTIONAL_VIDEO_STATE)
public static final int SUPPORTS_VIDEO_CALLING = 1 << 4;
/**
* Build an instance of {@link CallAttributes}. In order to build a valid instance, a
* {@link PhoneAccountHandle}, call 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;
}
/**
* Sets the type of call; uses to indicate if a call is a video call or audio call.
* @param callType The call type.
* @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;
}
/**
* Sets the capabilities of this call. Use this to indicate whether your app supports
* holding, streaming and call transfers.
* @param callCapabilities Bitmask of call capabilities.
* @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);
}
}