1 /*
2  * Copyright 2014, The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *     http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package com.android.server.telecom;
18 
19 import android.telecom.TelecomProtoEnums;
20 
21 /**
22  * Defines call-state constants of the different states in which a call can exist. Although states
23  * have the notion of normal transitions, due to the volatile nature of telephony systems, code
24  * that uses these states should be resilient to unexpected state changes outside of what is
25  * considered traditional.
26  */
27 public final class CallState {
28 
CallState()29     private CallState() {}
30 
31     /**
32      * Indicates that a call is new and not connected. This is used as the default state internally
33      * within Telecom and should not be used between Telecom and call services. Call services are
34      * not expected to ever interact with NEW calls, but {@link android.telecom.InCallService}s will
35      * see calls in this state.
36      */
37     public static final int NEW = TelecomProtoEnums.NEW; // = 0
38 
39     /**
40      * The initial state of an outgoing {@code Call}.
41      * Common transitions are to {@link #DIALING} state for a successful call or
42      * {@link #DISCONNECTED} if it failed.
43      */
44     public static final int CONNECTING = TelecomProtoEnums.CONNECTING; // = 1
45 
46     /**
47      * The state of an outgoing {@code Call} when waiting on user to select a
48      * {@link android.telecom.PhoneAccount} through which to place the call.
49      */
50     public static final int SELECT_PHONE_ACCOUNT = TelecomProtoEnums.SELECT_PHONE_ACCOUNT; // = 2
51 
52     /**
53      * Indicates that a call is outgoing and in the dialing state. A call transitions to this state
54      * once an outgoing call has begun (e.g., user presses the dial button in Dialer). Calls in this
55      * state usually transition to {@link #ACTIVE} if the call was answered or {@link #DISCONNECTED}
56      * if the call was disconnected somehow (e.g., failure or cancellation of the call by the user).
57      */
58     public static final int DIALING = TelecomProtoEnums.DIALING; // = 3
59 
60     /**
61      * Indicates that a call is incoming and the user still has the option of answering, rejecting,
62      * or doing nothing with the call. This state is usually associated with some type of audible
63      * ringtone. Normal transitions are to {@link #ACTIVE} if answered or {@link #DISCONNECTED}
64      * otherwise.
65      */
66     public static final int RINGING = TelecomProtoEnums.RINGING; // = 4
67 
68     /**
69      * Indicates that a call is currently connected to another party and a communication channel is
70      * open between them. The normal transition to this state is by the user answering a
71      * {@link #DIALING} call or a {@link #RINGING} call being answered by the other party.
72      */
73     public static final int ACTIVE = TelecomProtoEnums.ACTIVE; // = 5
74 
75     /**
76      * Indicates that the call is currently on hold. In this state, the call is not terminated
77      * but no communication is allowed until the call is no longer on hold. The typical transition
78      * to this state is by the user putting an {@link #ACTIVE} call on hold by explicitly performing
79      * an action, such as clicking the hold button.
80      */
81     public static final int ON_HOLD = TelecomProtoEnums.ON_HOLD; // = 6
82 
83     /**
84      * Indicates that a call is currently disconnected. All states can transition to this state
85      * by the call service giving notice that the connection has been severed. When the user
86      * explicitly ends a call, it will not transition to this state until the call service confirms
87      * the disconnection or communication was lost to the call service currently responsible for
88      * this call (e.g., call service crashes).
89      */
90     public static final int DISCONNECTED = TelecomProtoEnums.DISCONNECTED; // = 7
91 
92     /**
93      * Indicates that the call was attempted (mostly in the context of outgoing, at least at the
94      * time of writing) but cancelled before it was successfully connected.
95      */
96     public static final int ABORTED = TelecomProtoEnums.ABORTED; // = 8
97 
98     /**
99      * Indicates that the call is in the process of being disconnected and will transition next
100      * to a {@link #DISCONNECTED} state.
101      * <p>
102      * This state is not expected to be communicated from the Telephony layer, but will be reported
103      * to the InCall UI for calls where disconnection has been initiated by the user but the
104      * ConnectionService has confirmed the call as disconnected.
105      */
106     public static final int DISCONNECTING = TelecomProtoEnums.DISCONNECTING; // = 9
107 
108     /**
109      * Indicates that the call is in the process of being pulled to the local device.
110      * <p>
111      * This state should only be set on a call with
112      * {@link android.telecom.Connection#PROPERTY_IS_EXTERNAL_CALL} and
113      * {@link android.telecom.Connection#CAPABILITY_CAN_PULL_CALL}.
114      */
115     public static final int PULLING = TelecomProtoEnums.PULLING; // = 10
116 
117     /**
118      * Indicates that an incoming call has been answered by the in-call UI, but Telephony hasn't yet
119      * set the call to active.
120      */
121     public static final int ANSWERED = TelecomProtoEnums.ANSWERED; // = 11
122 
123     /**
124      * Indicates that the call is undergoing audio processing by a different app in the background.
125      * @see android.telecom.Call#STATE_AUDIO_PROCESSING
126      */
127     public static final int AUDIO_PROCESSING = TelecomProtoEnums.AUDIO_PROCESSING; // = 12
128 
129     /**
130      * Indicates that the call is in a fake ringing state.
131      * @see android.telecom.Call#STATE_SIMULATED_RINGING
132      */
133     public static final int SIMULATED_RINGING = TelecomProtoEnums.SIMULATED_RINGING; // = 13
134 
toString(int callState)135     public static String toString(int callState) {
136         switch (callState) {
137             case NEW:
138                 return "NEW";
139             case CONNECTING:
140                 return "CONNECTING";
141             case SELECT_PHONE_ACCOUNT:
142                 return "SELECT_PHONE_ACCOUNT";
143             case DIALING:
144                 return "DIALING";
145             case RINGING:
146                 return "RINGING";
147             case ACTIVE:
148                 return "ACTIVE";
149             case ON_HOLD:
150                 return "ON_HOLD";
151             case DISCONNECTED:
152                 return "DISCONNECTED";
153             case ABORTED:
154                 return "ABORTED";
155             case DISCONNECTING:
156                 return "DISCONNECTING";
157             case PULLING:
158                 return "PULLING";
159             case ANSWERED:
160                 return "ANSWERED";
161             case AUDIO_PROCESSING:
162                 return "AUDIO_PROCESSING";
163             case SIMULATED_RINGING:
164                 return "SIMULATED_RINGING";
165             default:
166                 return "UNKNOWN";
167         }
168     }
169 }
170