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
diff --git a/telecomm/java/android/telecom/Call.java b/telecomm/java/android/telecom/Call.java
index 432af3a..9c1e8dd 100644
--- a/telecomm/java/android/telecom/Call.java
+++ b/telecomm/java/android/telecom/Call.java
@@ -1839,8 +1839,15 @@
/**
* 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.
+ * <p>
+ * Tones are both played locally for the user to hear and sent to the network to be relayed
+ * to the remote device.
+ * <p>
+ * 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 '#'}.