1/*
2 * Copyright (C) 2006 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
17package com.android.internal.telephony;
18
19import android.util.Log;
20
21/**
22 * {@hide}
23 */
24public abstract class Connection {
25
26    //Caller Name Display
27    protected String cnapName;
28    protected int cnapNamePresentation  = PhoneConstants.PRESENTATION_ALLOWED;
29
30    private static String LOG_TAG = "TelephonyConnection";
31
32    public enum DisconnectCause {
33        NOT_DISCONNECTED,               /* has not yet disconnected */
34        INCOMING_MISSED,                /* an incoming call that was missed and never answered */
35        NORMAL,                         /* normal; remote */
36        LOCAL,                          /* normal; local hangup */
37        BUSY,                           /* outgoing call to busy line */
38        CONGESTION,                     /* outgoing call to congested network */
39        MMI,                            /* not presently used; dial() returns null */
40        INVALID_NUMBER,                 /* invalid dial string */
41        NUMBER_UNREACHABLE,             /* cannot reach the peer */
42        SERVER_UNREACHABLE,             /* cannot reach the server */
43        INVALID_CREDENTIALS,            /* invalid credentials */
44        OUT_OF_NETWORK,                 /* calling from out of network is not allowed */
45        SERVER_ERROR,                   /* server error */
46        TIMED_OUT,                      /* client timed out */
47        LOST_SIGNAL,
48        LIMIT_EXCEEDED,                 /* eg GSM ACM limit exceeded */
49        INCOMING_REJECTED,              /* an incoming call that was rejected */
50        POWER_OFF,                      /* radio is turned off explicitly */
51        OUT_OF_SERVICE,                 /* out of service */
52        ICC_ERROR,                      /* No ICC, ICC locked, or other ICC error */
53        CALL_BARRED,                    /* call was blocked by call barring */
54        FDN_BLOCKED,                    /* call was blocked by fixed dial number */
55        CS_RESTRICTED,                  /* call was blocked by restricted all voice access */
56        CS_RESTRICTED_NORMAL,           /* call was blocked by restricted normal voice access */
57        CS_RESTRICTED_EMERGENCY,        /* call was blocked by restricted emergency voice access */
58        UNOBTAINABLE_NUMBER,            /* Unassigned number (3GPP TS 24.008 table 10.5.123) */
59        CDMA_LOCKED_UNTIL_POWER_CYCLE,  /* MS is locked until next power cycle */
60        CDMA_DROP,
61        CDMA_INTERCEPT,                 /* INTERCEPT order received, MS state idle entered */
62        CDMA_REORDER,                   /* MS has been redirected, call is cancelled */
63        CDMA_SO_REJECT,                 /* service option rejection */
64        CDMA_RETRY_ORDER,               /* requested service is rejected, retry delay is set */
65        CDMA_ACCESS_FAILURE,
66        CDMA_PREEMPTED,
67        CDMA_NOT_EMERGENCY,              /* not an emergency call */
68        CDMA_ACCESS_BLOCKED,            /* Access Blocked by CDMA network */
69        ERROR_UNSPECIFIED
70    }
71
72    Object userData;
73
74    /* Instance Methods */
75
76    /**
77     * Gets address (e.g. phone number) associated with connection.
78     * TODO: distinguish reasons for unavailability
79     *
80     * @return address or null if unavailable
81     */
82
83    public abstract String getAddress();
84
85    /**
86     * Gets CNAP name associated with connection.
87     * @return cnap name or null if unavailable
88     */
89    public String getCnapName() {
90        return cnapName;
91    }
92
93    /**
94     * Get original dial string.
95     * @return original dial string or null if unavailable
96     */
97    public String getOrigDialString(){
98        return null;
99    }
100
101    /**
102     * Gets CNAP presentation associated with connection.
103     * @return cnap name or null if unavailable
104     */
105
106    public int getCnapNamePresentation() {
107       return cnapNamePresentation;
108    };
109
110    /**
111     * @return Call that owns this Connection, or null if none
112     */
113    public abstract Call getCall();
114
115    /**
116     * Connection create time in currentTimeMillis() format
117     * Basically, set when object is created.
118     * Effectively, when an incoming call starts ringing or an
119     * outgoing call starts dialing
120     */
121    public abstract long getCreateTime();
122
123    /**
124     * Connection connect time in currentTimeMillis() format.
125     * For outgoing calls: Begins at (DIALING|ALERTING) -> ACTIVE transition.
126     * For incoming calls: Begins at (INCOMING|WAITING) -> ACTIVE transition.
127     * Returns 0 before then.
128     */
129    public abstract long getConnectTime();
130
131    /**
132     * Disconnect time in currentTimeMillis() format.
133     * The time when this Connection makes a transition into ENDED or FAIL.
134     * Returns 0 before then.
135     */
136    public abstract long getDisconnectTime();
137
138    /**
139     * Returns the number of milliseconds the call has been connected,
140     * or 0 if the call has never connected.
141     * If the call is still connected, then returns the elapsed
142     * time since connect.
143     */
144    public abstract long getDurationMillis();
145
146    /**
147     * If this connection is HOLDING, return the number of milliseconds
148     * that it has been on hold for (approximately).
149     * If this connection is in any other state, return 0.
150     */
151
152    public abstract long getHoldDurationMillis();
153
154    /**
155     * Returns "NOT_DISCONNECTED" if not yet disconnected.
156     */
157    public abstract DisconnectCause getDisconnectCause();
158
159    /**
160     * Returns true of this connection originated elsewhere
161     * ("MT" or mobile terminated; another party called this terminal)
162     * or false if this call originated here (MO or mobile originated).
163     */
164    public abstract boolean isIncoming();
165
166    /**
167     * If this Connection is connected, then it is associated with
168     * a Call.
169     *
170     * Returns getCall().getState() or Call.State.IDLE if not
171     * connected
172     */
173    public Call.State getState() {
174        Call c;
175
176        c = getCall();
177
178        if (c == null) {
179            return Call.State.IDLE;
180        } else {
181            return c.getState();
182        }
183    }
184
185    /**
186     * isAlive()
187     *
188     * @return true if the connection isn't disconnected
189     * (could be active, holding, ringing, dialing, etc)
190     */
191    public boolean
192    isAlive() {
193        return getState().isAlive();
194    }
195
196    /**
197     * Returns true if Connection is connected and is INCOMING or WAITING
198     */
199    public boolean
200    isRinging() {
201        return getState().isRinging();
202    }
203
204    /**
205     *
206     * @return the userdata set in setUserData()
207     */
208    public Object getUserData() {
209        return userData;
210    }
211
212    /**
213     *
214     * @param userdata user can store an any userdata in the Connection object.
215     */
216    public void setUserData(Object userdata) {
217        this.userData = userdata;
218    }
219
220    /**
221     * Hangup individual Connection
222     */
223    public abstract void hangup() throws CallStateException;
224
225    /**
226     * Separate this call from its owner Call and assigns it to a new Call
227     * (eg if it is currently part of a Conference call
228     * TODO: Throw exception? Does GSM require error display on failure here?
229     */
230    public abstract void separate() throws CallStateException;
231
232    public enum PostDialState {
233        NOT_STARTED,    /* The post dial string playback hasn't
234                           been started, or this call is not yet
235                           connected, or this is an incoming call */
236        STARTED,        /* The post dial string playback has begun */
237        WAIT,           /* The post dial string playback is waiting for a
238                           call to proceedAfterWaitChar() */
239        WILD,           /* The post dial string playback is waiting for a
240                           call to proceedAfterWildChar() */
241        COMPLETE,       /* The post dial string playback is complete */
242        CANCELLED,       /* The post dial string playback was cancelled
243                           with cancelPostDial() */
244        PAUSE           /* The post dial string playback is pausing for a
245                           call to processNextPostDialChar*/
246    }
247
248    public void clearUserData(){
249        userData = null;
250    }
251
252    public abstract PostDialState getPostDialState();
253
254    /**
255     * Returns the portion of the post dial string that has not
256     * yet been dialed, or "" if none
257     */
258    public abstract String getRemainingPostDialString();
259
260    /**
261     * See Phone.setOnPostDialWaitCharacter()
262     */
263
264    public abstract void proceedAfterWaitChar();
265
266    /**
267     * See Phone.setOnPostDialWildCharacter()
268     */
269    public abstract void proceedAfterWildChar(String str);
270    /**
271     * Cancel any post
272     */
273    public abstract void cancelPostDial();
274
275    /**
276     * Returns the caller id presentation type for incoming and waiting calls
277     * @return one of PRESENTATION_*
278     */
279    public abstract int getNumberPresentation();
280
281    /**
282     * Returns the User to User Signaling (UUS) information associated with
283     * incoming and waiting calls
284     * @return UUSInfo containing the UUS userdata.
285     */
286    public abstract UUSInfo getUUSInfo();
287
288    /**
289     * Build a human representation of a connection instance, suitable for debugging.
290     * Don't log personal stuff unless in debug mode.
291     * @return a string representing the internal state of this connection.
292     */
293    public String toString() {
294        StringBuilder str = new StringBuilder(128);
295
296        if (Log.isLoggable(LOG_TAG, Log.DEBUG)) {
297            str.append("addr: " + getAddress())
298                    .append(" pres.: " + getNumberPresentation())
299                    .append(" dial: " + getOrigDialString())
300                    .append(" postdial: " + getRemainingPostDialString())
301                    .append(" cnap name: " + getCnapName())
302                    .append("(" + getCnapNamePresentation() + ")");
303        }
304        str.append(" incoming: " + isIncoming())
305                .append(" state: " + getState())
306                .append(" post dial state: " + getPostDialState());
307        return str.toString();
308    }
309}
310