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