Home | History | Annotate | Download | only in telephony
      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.telephony.Rlog;
     20 import android.util.Log;
     21 
     22 /**
     23  * {@hide}
     24  */
     25 public 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     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 mUserData;
     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 mCnapName;
     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 mCnapNamePresentation;
    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 mUserData;
    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         mUserData = 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         mUserData = 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