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