frameworks/base/telephony/java/com/android/internal/telephony/Connection.java

   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         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 CDMA CNAP name associated with connection.
  88      * @return cnap name or null if unavailable
  89      */
  90     public String getCnapName() {
  91         return null;
  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 CDMA CNAP presentation associated with connection.
 104      * @return cnap name or null if unavailable
 105      */
 106
 107     public int getCnapNamePresentation() {
 108        return 0;
 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 (Log.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 }