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 19 import android.util.Log; 20 21 /** 22 * {@hide} 23 */ 24 public 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
