API cleanups per API review.
1. removing deprecation for setExtras on Connection/Conference as these
have legitimate use-cases going forward.
2. Expanded documentation on Call.Callback class to clarify how it is
expected to be used.
3. Updated Callback#onConnectionEvent callback docs to clarify its usage.
4. Expanded Call#sendCallEvent docs to clarify expected namespacing of
call event keys and extras keys, as well as clarification about backwards
compatibility and expectations of ConnectionServices.
5. Standardized the "invoked" vs "notifies" language in the Conference
docs.
6. Clarified how Connection callbacks from Telecom should be implemented.
7. Added Bundle parameter expectations for pre-defined connection events.
8. Documented capabilities and properties toString methods.
9. Documented expectations for onCallEvent method.
10. Expanded documentation for sendConnectionEvent method to clarify
namespacing, use cases, etc.
Bug: 29759275
Bug: 29759954
Bug: 29759773
Change-Id: Ib8c983af4dbbfee68edb60937b268e2c1a9b5e64
diff --git a/telecomm/java/android/telecom/Call.java b/telecomm/java/android/telecom/Call.java
index 3a6d1fd..62625bd 100644
--- a/telecomm/java/android/telecom/Call.java
+++ b/telecomm/java/android/telecom/Call.java
@@ -701,6 +701,24 @@
}
}
+ /**
+ * Defines callbacks which inform the {@link InCallService} of changes to a {@link Call}.
+ * These callbacks can originate from the Telecom framework, or a {@link ConnectionService}
+ * implementation.
+ * <p>
+ * You can handle these callbacks by extending the {@link Callback} class and overriding the
+ * callbacks that your {@link InCallService} is interested in. The callback methods include the
+ * {@link Call} for which the callback applies, allowing reuse of a single instance of your
+ * {@link Callback} implementation, if desired.
+ * <p>
+ * Use {@link Call#registerCallback(Callback)} to register your callback(s). Ensure
+ * {@link Call#unregisterCallback(Callback)} is called when you no longer require callbacks
+ * (typically in {@link InCallService#onCallRemoved(Call)}).
+ * Note: Callbacks which occur before you call {@link Call#registerCallback(Callback)} will not
+ * reach your implementation of {@link Callback}, so it is important to register your callback
+ * as soon as your {@link InCallService} is notified of a new call via
+ * {@link InCallService#onCallAdded(Call)}.
+ */
public static abstract class Callback {
/**
* Invoked when the state of this {@code Call} has changed. See {@link #getState()}.
@@ -785,7 +803,13 @@
public void onConferenceableCallsChanged(Call call, List<Call> conferenceableCalls) {}
/**
- * Invoked when a call receives an event from its associated {@link Connection}.
+ * Invoked when a {@link Call} receives an event from its associated {@link Connection}.
+ * <p>
+ * Where possible, the Call should make an attempt to handle {@link Connection} events which
+ * are part of the {@code android.telecom.*} namespace. The Call should ignore any events
+ * it does not wish to handle. Unexpected events should be handled gracefully, as it is
+ * possible that a {@link ConnectionService} has defined its own Connection events which a
+ * Call is not aware of.
* <p>
* See {@link Connection#sendConnectionEvent(String, Bundle)}.
*
@@ -984,11 +1008,32 @@
* Sends a {@code Call} event from this {@code Call} to the associated {@link Connection} in
* the {@link ConnectionService}.
* <p>
+ * Call events are used to communicate point in time information from an {@link InCallService}
+ * to a {@link ConnectionService}. A {@link ConnectionService} implementation could define
+ * events which enable the {@link InCallService}, for example, toggle a unique feature of the
+ * {@link ConnectionService}.
+ * <p>
+ * A {@link ConnectionService} can communicate to the {@link InCallService} using
+ * {@link Connection#sendConnectionEvent(String, Bundle)}.
+ * <p>
* Events are exposed to {@link ConnectionService} implementations via
* {@link android.telecom.Connection#onCallEvent(String, Bundle)}.
* <p>
* No assumptions should be made as to how a {@link ConnectionService} will handle these events.
- * Events should be fully qualified (e.g., com.example.event.MY_EVENT) to avoid conflicts.
+ * The {@link InCallService} must assume that the {@link ConnectionService} could chose to
+ * ignore some events altogether.
+ * <p>
+ * Events should be fully qualified (e.g., {@code com.example.event.MY_EVENT}) to avoid
+ * conflicts between {@link InCallService} implementations. Further, {@link InCallService}
+ * implementations shall not re-purpose events in the {@code android.*} namespace, nor shall
+ * they define their own event types in this namespace. When defining a custom event type,
+ * ensure the contents of the extras {@link Bundle} is clearly defined. Extra keys for this
+ * bundle should be named similar to the event type (e.g. {@code com.example.extra.MY_EXTRA}).
+ * <p>
+ * When defining events and the associated extras, it is important to keep their behavior
+ * consistent when the associated {@link InCallService} is updated. Support for deprecated
+ * events/extras should me maintained to ensure backwards compatibility with older
+ * {@link ConnectionService} implementations which were built to support the older behavior.
*
* @param event The connection event.
* @param extras Bundle containing extra information associated with the event.