From 2517d03c19ce5f9792eccca4018a64de131108ba Mon Sep 17 00:00:00 2001 From: Tyler Gunn Date: Mon, 6 Feb 2023 16:34:54 +0000 Subject: [PATCH] Clarify start/stop DTMF tone API documentation. The API docs are not clear; they insinuate that a caller can issue any number of "play" DTMF requests followed by a single "stop" request and that the framework will interpret this as two digits in succession. In reality, the documentation is referring to the fact that the local tone will correctly stop if another tone is already playing. The API requests are sent directly to the modem as the InCallService sends them, and it is possible that some ConnectionService implementations (more specifically some vendor IMS implementations) will get confused if they receiver multiple starts and then a single stop. Test: Docs only change Bug: 262699364 Change-Id: I770008cc3b000f739d930ea899df5e98d1b17129 --- telecomm/java/android/telecom/Call.java | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/telecomm/java/android/telecom/Call.java b/telecomm/java/android/telecom/Call.java index 432af3aa1aa03..9c1e8dd25a0e7 100644 --- a/telecomm/java/android/telecom/Call.java +++ b/telecomm/java/android/telecom/Call.java @@ -1839,8 +1839,15 @@ public final class Call { /** * Instructs this {@code Call} to play a dual-tone multi-frequency signaling (DTMF) tone. - * - * Any other currently playing DTMF tone in the specified call is immediately stopped. + *

+ * Tones are both played locally for the user to hear and sent to the network to be relayed + * to the remote device. + *

+ * You must ensure that any call to {@link #playDtmfTone(char}) is followed by a matching + * call to {@link #stopDtmfTone()} and that each tone is stopped before a new one is started. + * The play and stop commands are relayed to the underlying + * {@link android.telecom.ConnectionService} as executed; implementations may not correctly + * handle out of order commands. * * @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 '#'}.