- * The difference between this API call and {@link TelecomManager#placeCall(Uri, Bundle)} or - * {@link TelecomManager#addNewIncomingCall(PhoneAccountHandle, Bundle)} is that this API - * will asynchronously provide an update on whether the new call was added successfully via - * an {@link OutcomeReceiver}. Additionally, callbacks will run on the executor thread that was - * passed in. - * *
- * Note: Only packages that register with + *
+ * Call Lifecycle: Your app is given foreground execution priority as long as you have a + * valid call and are posting a {@link android.app.Notification.CallStyle} notification. + * When your application is given foreground execution priority, your app is treated as a + * foreground service. Foreground execution priority will prevent the + * {@link android.app.ActivityManager} from killing your application when it is placed the + * background. Foreground execution priority is removed from your app when all of your app's + * calls terminate or your app no longer posts a valid notification. + *
+ *
+ *
+ * Note: Only packages that register with * {@link PhoneAccount#CAPABILITY_SUPPORTS_TRANSACTIONAL_OPERATIONS} * can utilize this API. {@link PhoneAccount}s that set the capabilities * {@link PhoneAccount#CAPABILITY_SIM_SUBSCRIPTION}, * {@link PhoneAccount#CAPABILITY_CALL_PROVIDER}, * {@link PhoneAccount#CAPABILITY_CONNECTION_MANAGER} * are not supported and will cause an exception to be thrown. - * *
- * Usage example: + *
+ *
+ * Usage example: *
- *
- * // An app should first define their own construct of a Call that overrides all the
- * // {@link CallControlCallback}s and {@link CallEventCallback}s
- * private class MyVoipCall {
- * public String callId = "";
- *
- * public CallControlCallEventCallback handshakes = new
- * CallControlCallEventCallback() {
- * // override/ implement all {@link CallControlCallback}s
+ * // Its up to your app on how you want to wrap the objects. One such implementation can be:
+ * class MyVoipCall {
+ * ...
+ * public CallControlCallEventCallback handshakes = new CallControlCallback() {
+ * ...
* }
- * public CallEventCallback events = new
- * CallEventCallback() {
- * // override/ implement all {@link CallEventCallback}s
+ *
+ * public CallEventCallback events = new CallEventCallback() {
+ * ...
* }
- * public MyVoipCall(String id){
- * callId = id;
+ *
+ * public MyVoipCall(String id){
+ * ...
+ * }
* }
*
- * PhoneAccountHandle handle = new PhoneAccountHandle(
- * new ComponentName("com.example.voip.app",
- * "com.example.voip.app.NewCallActivity"), "123");
- *
- * CallAttributes callAttributes = new CallAttributes.Builder(handle,
- * CallAttributes.DIRECTION_OUTGOING,
- * "John Smith", Uri.fromParts("tel", "123", null))
- * .build();
- *
* MyVoipCall myFirstOutgoingCall = new MyVoipCall("1");
*
- * telecomManager.addCall(callAttributes, Runnable::run, new OutcomeReceiver() {
+ * telecomManager.addCall(callAttributes,
+ * Runnable::run,
+ * new OutcomeReceiver() {
* public void onResult(CallControl callControl) {
- * // The call has been added successfully
+ * // The call has been added successfully. For demonstration
+ * // purposes, the call is disconnected immediately ...
+ * callControl.disconnect(
+ * new DisconnectCause(DisconnectCause.LOCAL) )
* }
- * }, myFirstOutgoingCall.handshakes, myFirstOutgoingCall.events);
+ * },
+ * myFirstOutgoingCall.handshakes,
+ * myFirstOutgoingCall.events);
*
*
- * @param callAttributes attributes of the new call (incoming or outgoing, address, etc. )
- * @param executor thread to run background CallEventCallback updates on
- * @param pendingControl OutcomeReceiver that receives the result of addCall transaction
- * @param handshakes object that overrides {@link CallControlCallback}s
- * @param events object that overrides {@link CallEventCallback}s
+ * @param callAttributes attributes of the new call (incoming or outgoing, address, etc.)
+ * @param executor execution context to run {@link CallControlCallback} updates on
+ * @param pendingControl Receives the result of addCall transaction. Upon success, a
+ * CallControl object is provided which can be used to do things like
+ * disconnect the call that was added.
+ * @param handshakes callback that receives actionable updates that originate from
+ * Telecom.
+ * @param events callback that receives non-actionable updates that originate
+ * from Telecom.
*/
@RequiresPermission(android.Manifest.permission.MANAGE_OWN_CALLS)
@SuppressLint("SamShouldBeLast")