# Class Calls

java.lang.Object
com.codename1.call.session.Calls

public final class Calls extends Object

System call integration: the entry point for reporting calls to the operating system and hearing what the user does with them.

    if (!Calls.isSupported()) {
        return;                      // fall back to an in-app call screen
    }
    Calls.configure(new CallConfiguration().displayName("Acme Talk"));
    Calls.addActionListener(new CallActionAdapter() {
        public void answerRequested(String callId, CallAction action) {
            signalling.accept(callId);
        }
        public void audioSessionActivated(CallAudioSession session) {
            media.start();           // here, not in answerRequested
        }
        public void providerReset() {
            media.stopEverything();
        }
    });

Everything here is static because there is one operating system and one call provider per app.

##### Order matters

`configure(CallConfiguration)` must run before any call is reported. On Android an unconfigured provider makes `TelecomManager` ignore reported calls silently.

##### Every callback arrives on the EDT

Unlike some other families in this framework, that is true here without exception: an action from the system is a user-interface event and there is nothing to gain by delivering it anywhere else.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `addActionListener(CallActionListener l)`
  Adds a listener.
  `static AsyncResource<Boolean>`
  `configure(CallConfiguration config)`
  Installs the calling identity.
  `static void`
  `deliverCallEnded(String callId, int reasonOrdinal)`
  `static CallAudioRoute`
  `getAudioRoute()`
  Where call audio is going right now.
  `static CallAvailability`
  `getAvailability()`
  Whether a call could be rung right now.
  `static int`
  `getCapabilities()`
  The `CallBridge.CAPABILITY_*` mask this platform supports.
  `static int`
  `getGrantedPermissions()`
  The `CallBridge.PERMISSION_*` mask currently granted.
  `static CallSession`
  `getSession(String callId)`
  The session for a call id, or null when this app has none.
  `static CallSession[]`
  `getSessions()`
  Every call this app currently has.
  `static boolean`
  `isSupported()`
  Whether this platform can show a call in its own call UI.
  `static void`
  `removeActionListener(CallActionListener l)`
  Removes a listener.
  `static AsyncResource<CallSession>`
  `reportIncoming(String callId, CallHandle handle, String displayName, boolean video)`
  Rings an incoming call.
  `static AsyncResource<CallSession>`
  `reportOutgoing(String callId, CallHandle handle, String displayName, boolean video)`
  Places an outgoing call in the system UI.
  `static AsyncResource<Integer>`
  `requestPermissions(int permissions)`
  Asks for the `CallBridge.PERMISSION_*` bits in `permissions`, resolving with the mask actually granted.
  `static AsyncResource<Boolean>`
  `setAudioRoute(CallAudioRoute r)`
  Asks for a particular audio route.
  `static AsyncResource<Boolean>`
  `showAudioRoutePicker(String callId)`
  Shows the system's audio route picker for a call.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### isSupported

    public static boolean isSupported()

    Whether this platform can show a call in its own call UI.

    False on the ports that have no such concept, and on Android below API 26. An app must have a fallback; there is no way to make a desktop show a lock-screen call.

  - ### getCapabilities

    public static int getCapabilities()
    The `CallBridge.CAPABILITY_*` mask this platform supports. Branch on this rather than on the platform.

  - ### getAvailability

    public static CallAvailability getAvailability()

    Whether a call could be rung right now.

    Different from `isSupported()`: an emergency call, or another app's call, makes this refuse on a platform that supports calling perfectly. Check it before telling a caller their call is ringing.

  - ### getGrantedPermissions

    public static int getGrantedPermissions()
    The `CallBridge.PERMISSION_*` mask currently granted.

  - ### requestPermissions

    public static AsyncResource<Integer> requestPermissions(int permissions)
    Asks for the `CallBridge.PERMISSION_*` bits in `permissions`, resolving with the mask actually granted.

  - ### configure

    public static AsyncResource<Boolean> configure(CallConfiguration config)
    Installs the calling identity. Must precede any reported call.

  - ### reportIncoming

    public static AsyncResource<CallSession> reportIncoming(String callId, CallHandle handle, String displayName, boolean video)

    Rings an incoming call.

    `callId` must be a canonical `CallId` and must be the same identifier the far end uses. Allocate one with `CallId.random()` for a call learned over the app's own connection; a call that arrived as a VoIP push already has one and must not be re-reported here -- see `com.codename1.call.voip.VoipPush`.

  - ### reportOutgoing

    public static AsyncResource<CallSession> reportOutgoing(String callId, CallHandle handle, String displayName, boolean video)
    Places an outgoing call in the system UI.

  - ### getSession

    public static CallSession getSession(String callId)
    The session for a call id, or null when this app has none.

  - ### getSessions

    public static CallSession[] getSessions()
    Every call this app currently has.

  - ### getAudioRoute

    public static CallAudioRoute getAudioRoute()
    Where call audio is going right now.

  - ### setAudioRoute

    public static AsyncResource<Boolean> setAudioRoute(CallAudioRoute r)
    Asks for a particular audio route.

  - ### showAudioRoutePicker

    public static AsyncResource<Boolean> showAudioRoutePicker(String callId)
    Shows the system's audio route picker for a call.

  - ### addActionListener

    public static void addActionListener(CallActionListener l)
    Adds a listener. Every method arrives on the EDT.

  - ### removeActionListener

    public static void removeActionListener(CallActionListener l)
    Removes a listener.

  - ### deliverCallEnded

    public static void deliverCallEnded(String callId, int reasonOrdinal)