Connection.java revision b7b7a62112b79571adf74372c5f5366fd62d0031 
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 mCnapName;
29    protected int mCnapNamePresentation  = PhoneConstants.PRESENTATION_ALLOWED;
30
31    private static String LOG_TAG = "Connection";
32
33    Object mUserData;
34
35    /* Instance Methods */
36
37    /**
38     * Gets address (e.g. phone number) associated with connection.
39     * TODO: distinguish reasons for unavailability
40     *
41     * @return address or null if unavailable
42     */
43
44    public abstract String getAddress();
45
46    /**
47     * Gets CNAP name associated with connection.
48     * @return cnap name or null if unavailable
49     */
50    public String getCnapName() {
51        return mCnapName;
52    }
53
54    /**
55     * Get original dial string.
56     * @return original dial string or null if unavailable
57     */
58    public String getOrigDialString(){
59        return null;
60    }
61
62    /**
63     * Gets CNAP presentation associated with connection.
64     * @return cnap name or null if unavailable
65     */
66
67    public int getCnapNamePresentation() {
68       return mCnapNamePresentation;
69    }
70
71    /**
72     * @return Call that owns this Connection, or null if none
73     */
74    public abstract Call getCall();
75
76    /**
77     * Connection create time in currentTimeMillis() format
78     * Basically, set when object is created.
79     * Effectively, when an incoming call starts ringing or an
80     * outgoing call starts dialing
81     */
82    public abstract long getCreateTime();
83
84    /**
85     * Connection connect time in currentTimeMillis() format.
86     * For outgoing calls: Begins at (DIALING|ALERTING) -> ACTIVE transition.
87     * For incoming calls: Begins at (INCOMING|WAITING) -> ACTIVE transition.
88     * Returns 0 before then.
89     */
90    public abstract long getConnectTime();
91
92    /**
93     * Disconnect time in currentTimeMillis() format.
94     * The time when this Connection makes a transition into ENDED or FAIL.
95     * Returns 0 before then.
96     */
97    public abstract long getDisconnectTime();
98
99    /**
100     * Returns the number of milliseconds the call has been connected,
101     * or 0 if the call has never connected.
102     * If the call is still connected, then returns the elapsed
103     * time since connect.
104     */
105    public abstract long getDurationMillis();
106
107    /**
108     * If this connection is HOLDING, return the number of milliseconds
109     * that it has been on hold for (approximately).
110     * If this connection is in any other state, return 0.
111     */
112
113    public abstract long getHoldDurationMillis();
114
115    /**
116     * Returns call disconnect cause. Values are defined in
117     * {@link android.telephony.DisconnectCause}. If the call is not yet
118     * disconnected, NOT_DISCONNECTED is returned.
119     */
120    public abstract int getDisconnectCause();
121
122    /**
123     * Returns true of this connection originated elsewhere
124     * ("MT" or mobile terminated; another party called this terminal)
125     * or false if this call originated here (MO or mobile originated).
126     */
127    public abstract boolean isIncoming();
128
129    /**
130     * If this Connection is connected, then it is associated with
131     * a Call.
132     *
133     * Returns getCall().getState() or Call.State.IDLE if not
134     * connected
135     */
136    public Call.State getState() {
137        Call c;
138
139        c = getCall();
140
141        if (c == null) {
142            return Call.State.IDLE;
143        } else {
144            return c.getState();
145        }
146    }
147
148    /**
149     * isAlive()
150     *
151     * @return true if the connection isn't disconnected
152     * (could be active, holding, ringing, dialing, etc)
153     */
154    public boolean
155    isAlive() {
156        return getState().isAlive();
157    }
158
159    /**
160     * Returns true if Connection is connected and is INCOMING or WAITING
161     */
162    public boolean
163    isRinging() {
164        return getState().isRinging();
165    }
166
167    /**
168     *
169     * @return the userdata set in setUserData()
170     */
171    public Object getUserData() {
172        return mUserData;
173    }
174
175    /**
176     *
177     * @param userdata user can store an any userdata in the Connection object.
178     */
179    public void setUserData(Object userdata) {
180        mUserData = userdata;
181    }
182
183    /**
184     * Hangup individual Connection
185     */
186    public abstract void hangup() throws CallStateException;
187
188    /**
189     * Separate this call from its owner Call and assigns it to a new Call
190     * (eg if it is currently part of a Conference call
191     * TODO: Throw exception? Does GSM require error display on failure here?
192     */
193    public abstract void separate() throws CallStateException;
194
195    public enum PostDialState {
196        NOT_STARTED,    /* The post dial string playback hasn't
197                           been started, or this call is not yet
198                           connected, or this is an incoming call */
199        STARTED,        /* The post dial string playback has begun */
200        WAIT,           /* The post dial string playback is waiting for a
201                           call to proceedAfterWaitChar() */
202        WILD,           /* The post dial string playback is waiting for a
203                           call to proceedAfterWildChar() */
204        COMPLETE,       /* The post dial string playback is complete */
205        CANCELLED,       /* The post dial string playback was cancelled
206                           with cancelPostDial() */
207        PAUSE           /* The post dial string playback is pausing for a
208                           call to processNextPostDialChar*/
209    }
210
211    public void clearUserData(){
212        mUserData = null;
213    }
214
215    public abstract PostDialState getPostDialState();
216
217    /**
218     * Returns the portion of the post dial string that has not
219     * yet been dialed, or "" if none
220     */
221    public abstract String getRemainingPostDialString();
222
223    /**
224     * See Phone.setOnPostDialWaitCharacter()
225     */
226
227    public abstract void proceedAfterWaitChar();
228
229    /**
230     * See Phone.setOnPostDialWildCharacter()
231     */
232    public abstract void proceedAfterWildChar(String str);
233    /**
234     * Cancel any post
235     */
236    public abstract void cancelPostDial();
237
238    /**
239     * Returns the caller id presentation type for incoming and waiting calls
240     * @return one of PRESENTATION_*
241     */
242    public abstract int getNumberPresentation();
243
244    /**
245     * Returns the User to User Signaling (UUS) information associated with
246     * incoming and waiting calls
247     * @return UUSInfo containing the UUS userdata.
248     */
249    public abstract UUSInfo getUUSInfo();
250
251    /**
252     * Returns the CallFail reason provided by the RIL with the result of
253     * RIL_REQUEST_LAST_CALL_FAIL_CAUSE
254     */
255    public abstract int getPreciseDisconnectCause();
256
257    /**
258     * Build a human representation of a connection instance, suitable for debugging.
259     * Don't log personal stuff unless in debug mode.
260     * @return a string representing the internal state of this connection.
261     */
262    public String toString() {
263        StringBuilder str = new StringBuilder(128);
264
265        if (Rlog.isLoggable(LOG_TAG, Log.DEBUG)) {
266            str.append("addr: " + getAddress())
267                    .append(" pres.: " + getNumberPresentation())
268                    .append(" dial: " + getOrigDialString())
269                    .append(" postdial: " + getRemainingPostDialString())
270                    .append(" cnap name: " + getCnapName())
271                    .append("(" + getCnapNamePresentation() + ")");
272        }
273        str.append(" incoming: " + isIncoming())
274                .append(" state: " + getState())
275                .append(" post dial state: " + getPostDialState());
276        return str.toString();
277    }
278}
279