DTMF dialing support in frameworks/base

Change-Id: I86695161fab9c4fbd4a021ba69cc61ec5e585adc

5 files changed, 232 insertions, 2 deletions

diff --git a/telecomm/java/android/telecomm/CallService.java b/telecomm/java/android/telecomm/CallService.java
index 3b88be1..c34395b 100644
--- a/telecomm/java/android/telecomm/CallService.java
+++ b/telecomm/java/android/telecomm/CallService.java
@@ -57,6 +57,8 @@ public abstract class CallService extends Service {
     private static final int MSG_HOLD = 9;
     private static final int MSG_UNHOLD = 10;
     private static final int MSG_ON_AUDIO_STATE_CHANGED = 11;
+    private static final int MSG_PLAY_DTMF_TONE = 12;
+    private static final int MSG_STOP_DTMF_TONE = 13;
 
     /**
      * Default Handler used to consolidate binder method calls onto a single thread.
@@ -116,6 +118,12 @@ public abstract class CallService extends Service {
                     }
                     break;
                 }
+                case MSG_PLAY_DTMF_TONE:
+                    playDtmfTone((String) msg.obj, (char) msg.arg1);
+                    break;
+                case MSG_STOP_DTMF_TONE:
+                    stopDtmfTone((String) msg.obj);
+                    break;
                 default:
                     break;
             }
@@ -181,6 +189,16 @@ public abstract class CallService extends Service {
         }
 
         @Override
+        public void playDtmfTone(String callId, char digit) {
+            mMessageHandler.obtainMessage(MSG_PLAY_DTMF_TONE, digit, 0, callId).sendToTarget();
+        }
+
+        @Override
+        public void stopDtmfTone(String callId) {
+            mMessageHandler.obtainMessage(MSG_STOP_DTMF_TONE, callId).sendToTarget();
+        }
+
+        @Override
         public void onAudioStateChanged(String callId, CallAudioState audioState) {
             SomeArgs args = SomeArgs.obtain();
             args.arg1 = callId;
@@ -307,6 +325,25 @@ public abstract class CallService extends Service {
     public abstract void unhold(String callId);
 
     /**
+     * Plays a dual-tone multi-frequency signaling (DTMF) tone in a call.
+     *
+     * @param callId The unique ID of the call in which the tone will be played.
+     * @param digit A character representing the DTMF digit for which to play the tone. This
+     *         value must be one of {@code '0'} through {@code '9'}, {@code '*'} or {@code '#'}.
+     */
+    public abstract void playDtmfTone(String callId, char digit);
+
+    /**
+     * Stops any dual-tone multi-frequency sinaling (DTMF) tone currently playing.
+     *
+     * DTMF tones are played by calling {@link #playDtmfTone(String,char)}. If no DTMF tone is
+     * currently playing, this method will do nothing.
+     *
+     * @param callId The unique ID of the call in which any currently playing tone will be stopped.
+     */
+    public abstract void stopDtmfTone(String callId);
+
+    /**
      * Called when the audio state changes.
      *
      * @param activeCallId The identifier of the call that was active during the state change.
diff --git a/telecomm/java/android/telecomm/CallState.java b/telecomm/java/android/telecomm/CallState.java
index 3937b08..fd611cc 100644
--- a/telecomm/java/android/telecomm/CallState.java
+++ b/telecomm/java/android/telecomm/CallState.java
@@ -49,6 +49,22 @@ public enum CallState {
     RINGING,
 
     /**
+     * Indicates that the call is active but in a "post-dial" state where Telecomm is now sending
+     * some dual-tone multi-frequency signaling (DTMF) tones appended to the dialed number. Normal
+     * transitions are to {@link #POST_DIAL_WAIT} when the post-dial string requires user
+     * confirmation to proceed, {@link #ACTIVE} when the post-dial tones are completed, or
+     * {@link #DISCONNECTED}.
+     */
+    POST_DIAL,
+
+    /**
+     * Indicates that the call was in the {@link #POST_DIAL} state but is now waiting for user
+     * confirmation before the remaining digits can be sent. Normal transitions are to
+     * {@link #POST_DIAL} when the user asks Telecomm to proceed with the post-dial sequence.
+     */
+    POST_DIAL_WAIT,
+
+    /**
      * Indicates that a call is currently connected to another party and a communication channel is
      * open between them. The normal transition to this state is by the user answering a
      * {@link #DIALING} call or a {@link #RINGING} call being answered by the other party.
diff --git a/telecomm/java/android/telecomm/InCallAdapter.java b/telecomm/java/android/telecomm/InCallAdapter.java
index 0a8571a..4f32458 100644
--- a/telecomm/java/android/telecomm/InCallAdapter.java
+++ b/telecomm/java/android/telecomm/InCallAdapter.java
@@ -126,4 +126,62 @@ public final class InCallAdapter {
         } catch (RemoteException e) {
         }
     }
+
+    /**
+     * Instructs Telecomm to play a dual-tone multi-frequency signaling (DTMF) tone in a call.
+     *
+     * Any other currently playing DTMF tone in the specified call is immediately stopped.
+     *
+     * @param callId The unique ID of the call in which the tone will be played.
+     * @param digit A character representing the DTMF digit for which to play the tone. This
+     *         value must be one of {@code '0'} through {@code '9'}, {@code '*'} or {@code '#'}.
+     */
+    public void playDtmfTone(String callId, char digit) {
+        try {
+            mAdapter.playDtmfTone(callId, digit);
+        } catch (RemoteException e) {
+        }
+    }
+
+    /**
+     * Instructs Telecomm to stop any dual-tone multi-frequency signaling (DTMF) tone currently
+     * playing.
+     *
+     * DTMF tones are played by calling {@link #playDtmfTone(String,char)}. If no DTMF tone is
+     * currently playing, this method will do nothing.
+     *
+     * @param callId The unique ID of the call in which any currently playing tone will be stopped.
+     */
+    public void stopDtmfTone(String callId) {
+        try {
+            mAdapter.stopDtmfTone(callId);
+        } catch (RemoteException e) {
+        }
+    }
+
+    /**
+     * Instructs Telecomm to continue playing a post-dial DTMF string.
+     *
+     * A post-dial DTMF string is a string of digits entered after a phone number, when dialed,
+     * that are immediately sent as DTMF tones to the recipient as soon as the connection is made.
+     * While these tones are playing, Telecomm will notify the {@link InCallService} that the call
+     * is in the {@link InCallService#setPostDial(String)} state.
+     *
+     * If the DTMF string contains a {@link #DTMF_CHARACTER_PAUSE} symbol, Telecomm will temporarily
+     * pause playing the tones for a pre-defined period of time.
+     *
+     * If the DTMF string contains a {@link #DTMF_CHARACTER_WAIT} symbol, Telecomm will pause
+     * playing the tones and notify the {@link InCallService} that the call is in the
+     * {@link InCallService#setPostDialWait(String)} state. When the user decides to continue the
+     * postdial sequence, the {@link InCallService} should invoke the
+     * {@link #postDialContinue(String)} method.
+     *
+     * @param callId The unique ID of the call for which postdial string playing should continue.
+     */
+    public void postDialContinue(String callId) {
+        try {
+            mAdapter.postDialContinue(callId);
+        } catch (RemoteException e) {
+        }
+    }
 }
diff --git a/telecomm/java/android/telecomm/InCallService.java b/telecomm/java/android/telecomm/InCallService.java
index 8f1add2..8131815 100644
--- a/telecomm/java/android/telecomm/InCallService.java
+++ b/telecomm/java/android/telecomm/InCallService.java
@@ -23,6 +23,7 @@ import android.os.IBinder;
 import android.os.Looper;
 import android.os.Message;
 
+import com.android.internal.os.SomeArgs;
 import com.android.internal.telecomm.IInCallAdapter;
 import com.android.internal.telecomm.IInCallService;
 
@@ -41,6 +42,10 @@ public abstract class InCallService extends Service {
     private static final int MSG_SET_DISCONNECTED = 4;
     private static final int MSG_SET_HOLD = 5;
     private static final int MSG_ON_AUDIO_STATE_CHANGED = 6;
+    private static final int MSG_SET_DIALING = 7;
+    private static final int MSG_SET_RINGING = 8;
+    private static final int MSG_SET_POST_DIAL = 9;
+    private static final int MSG_SET_POST_DIAL_WAIT = 10;
 
     /** Default Handler used to consolidate binder method calls onto a single thread. */
     private final Handler mHandler = new Handler(Looper.getMainLooper()) {
@@ -57,6 +62,34 @@ public abstract class InCallService extends Service {
                 case MSG_SET_ACTIVE:
                     setActive((String) msg.obj);
                     break;
+                case MSG_SET_DIALING:
+                    setDialing((String) msg.obj);
+                    break;
+                case MSG_SET_RINGING:
+                    setRinging((String) msg.obj);
+                    break;
+                case MSG_SET_POST_DIAL: {
+                    SomeArgs args = (SomeArgs) msg.obj;
+                    try {
+                        String callId = (String) args.arg1;
+                        String remaining = (String) args.arg2;
+                        setPostDial(callId, remaining);
+                    } finally {
+                        args.recycle();
+                    }
+                    break;
+                }
+                case MSG_SET_POST_DIAL_WAIT: {
+                    SomeArgs args = (SomeArgs) msg.obj;
+                    try {
+                        String callId = (String) args.arg1;
+                        String remaining = (String) args.arg2;
+                        setPostDialWait(callId, remaining);
+                    } finally {
+                        args.recycle();
+                    }
+                    break;
+                }
                 case MSG_SET_DISCONNECTED:
                     setDisconnected((String) msg.obj, msg.arg1);
                     break;
@@ -108,6 +141,32 @@ public abstract class InCallService extends Service {
         public void onAudioStateChanged(CallAudioState audioState) {
             mHandler.obtainMessage(MSG_ON_AUDIO_STATE_CHANGED, audioState).sendToTarget();
         }
+
+        @Override
+        public void setDialing(String callId) {
+            mHandler.obtainMessage(MSG_SET_DIALING, callId).sendToTarget();
+        }
+
+        @Override
+        public void setRinging(String callId) {
+            mHandler.obtainMessage(MSG_SET_RINGING, callId).sendToTarget();
+        }
+
+        @Override
+        public void setPostDial(String callId, String remaining) {
+            SomeArgs args = SomeArgs.obtain();
+            args.arg1 = callId;
+            args.arg2 = remaining;
+            mHandler.obtainMessage(MSG_SET_POST_DIAL, args).sendToTarget();
+        }
+
+        @Override
+        public void setPostDialWait(String callId, String remaining) {
+            SomeArgs args = SomeArgs.obtain();
+            args.arg1 = callId;
+            args.arg2 = remaining;
+            mHandler.obtainMessage(MSG_SET_POST_DIAL_WAIT, args).sendToTarget();
+        }
     }
 
     private final InCallServiceBinder mBinder;
@@ -140,13 +199,36 @@ public abstract class InCallService extends Service {
      protected abstract void addCall(CallInfo callInfo);
 
     /**
-     * Indicates to the in-call app that a call has moved to the {@link CallState#ACTIVE} state.
+     * Indicates to the in-call app that the specified call is currently connected to another party
+     * and a communication channel is open between them. Normal transitions are to
+     * {@link #setDisconnected(String)} when the call is complete.
      *
-     * @param callId The identifier of the call that became active.
+     * @param callId The identifier of the call changing state.
      */
     protected abstract void setActive(String callId);
 
     /**
+     * Indicates to the in-call app that the specified call is outgoing and in the dialing state.
+     * Normal transition are to {@link #setActive(String)} if the call was answered,
+     * {@link #setPostDial(String,String)} if the dialed number includes a post-dial DTMF string, or
+     * {@link #setDisconnected(String)} if the call was disconnected immediately.
+     *
+     * @param callId The identifier of the call changing state.
+     */
+    protected abstract void setDialing(String callId);
+
+    /**
+     * Indicates to the in-call app that the specified call is incoming and the user still has the
+     * option of answering, rejecting, or doing nothing with the call. This state is usually
+     * associated with some type of audible ringtone. Normal transitions are to
+     * {@link #setActive(String)} if the call is answered, or {@link #setDisconnected(String)} if
+     * the call is not answered or is otherwise disconnected for some reason.
+     *
+     * @param callId The identifier of the call changing state.
+     */
+    protected abstract void setRinging(String callId);
+
+    /**
      * Indicates to the in-call app that a call has been moved to the
      * {@link CallState#DISCONNECTED} and the user should be notified.
      *
@@ -170,4 +252,29 @@ public abstract class InCallService extends Service {
      * @param audioState The new {@link CallAudioState}.
      */
     protected abstract void onAudioStateChanged(CallAudioState audioState);
+
+    /**
+     * Indicates to the in-call app that the specified call is active but in a "post-dial" state
+     * where Telecomm is now sending some dual-tone multi-frequency signaling (DTMF) tones appended
+     * to the dialed number. Normal transitions are to {@link #setPostDialWait(String,String)} when
+     * the post-dial string requires user confirmation to proceed, {@link #setActive(String)} when
+     * the post-dial tones are completed, or {@link #setDisconnected(String)} if the call is
+     * disconnected.
+     *
+     * @param callId The identifier of the call changing state.
+     * @param remaining The remaining postdial string to be dialed.
+     */
+    protected abstract void setPostDial(String callId, String remaining);
+
+    /**
+     * Indicates to the in-call app that the specified call was in the
+     * {@link #setPostDial(String,String)} state but is now waiting for user confirmation before the
+     * remaining digits can be sent. Normal transitions are to {@link #setPostDial(String,String)}
+     * when the user asks Telecomm to proceed with the post-dial sequence and the in-call app
+     * informs Telecomm of this by invoking {@link IInCallAdapter#postDialContinue(String)}.
+     *
+     * @param callId The identifier of the call changing state.
+     * @param remaining The remaining postdial string to be dialed.
+     */
+    protected abstract void setPostDialWait(String callId, String remaining);
 }
diff --git a/telecomm/java/android/telecomm/TelecommConstants.java b/telecomm/java/android/telecomm/TelecommConstants.java
index 4269424..c2cccf1 100644
--- a/telecomm/java/android/telecomm/TelecommConstants.java
+++ b/telecomm/java/android/telecomm/TelecommConstants.java
@@ -74,4 +74,16 @@ public final class TelecommConstants {
      * ID of the call.
      */
     public static final String EXTRA_CALL_ID = "android.telecomm.extra.CALL_ID";
+
+    /**
+     * The dual tone multi-frequency signaling character sent to indicate the dialing system should
+     * pause for a predefined period.
+     */
+    public static final char DTMF_CHARACTER_PAUSE = ',';
+
+    /**
+     * The dual-tone multi-frequency signaling character sent to indicate the dialing system should
+     * wait for user confirmation before proceeding.
+     */
+    public static final char DTMF_CHARACTER_WAIT = ';';
 }