# Class CallSession

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

public final class CallSession extends Object

One call, from the system's point of view.

Obtained from `Calls.reportIncoming(String, CallHandle, String, boolean)` or `Calls.reportOutgoing(String, CallHandle, String, boolean)`, or handed over already ringing by `com.codename1.call.voip.PushedCall#getSession()`. A session is a handle on a call the operating system knows about; it does not carry audio.

Every method here is a request to the system, and every one of them is asynchronous because the system can refuse. Acting on a call that has already ended fails with `CallError.INVALID_ID` rather than doing nothing, so a bug in the app's own bookkeeping shows up instead of hiding.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `AsyncResource<Boolean>`
  `end(CallEndReason reason)`
  Hangs up, and writes `reason` into the system call log.
  `String`
  `getCallId()`
  The identifier naming this call everywhere -- here, in the system, and in whatever signalling the app uses.
  `CallDirection`
  `getDirection()`
  Which way the call was placed.
  `String`
  `getDisplayName()`
  The name shown for the far end, or null.
  `CallHandle`
  `getHandle()`
  Who is on the other end.
  `CallState`
  `getState()`
  Where the call is in its life.
  `AsyncResource<Boolean>`
  `groupWith(CallSession other)`
  Puts this call in a conference with `other`, or takes it out of one when `other` is null.
  `boolean`
  `isMuted()`
  Whether the call is muted, as far as the system is concerned.
  `void`
  `reportConnected()`
  Tells the system the call is connected.
  `void`
  `reportEndedRemotely(CallEndReason reason)`
  Tells the system the far end ended the call.
  `void`
  `reportStartedConnecting()`
  Tells the system the outgoing call has begun connecting -- the far end is being rung.
  `AsyncResource<Boolean>`
  `sendDigits(String digits)`
  Sends DTMF digits through the system.
  `AsyncResource<Boolean>`
  `setHeld(boolean held)`
  Holds or resumes the call.
  `AsyncResource<Boolean>`
  `setMuted(boolean value)`
  Mutes or unmutes the call in the system UI.
  `void`
  `update(CallHandle newHandle, String newDisplayName)`
  Changes what the system shows for this call.

  ### Methods inherited from class Object

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

- ## Method Details

  - ### getCallId

    public String getCallId()
    The identifier naming this call everywhere -- here, in the system, and in whatever signalling the app uses.

  - ### getDirection

    public CallDirection getDirection()
    Which way the call was placed.

  - ### getHandle

    public CallHandle getHandle()
    Who is on the other end.

  - ### getDisplayName

    public String getDisplayName()
    The name shown for the far end, or null.

  - ### getState

    public CallState getState()
    Where the call is in its life.

  - ### isMuted

    public boolean isMuted()
    Whether the call is muted, as far as the system is concerned.

  - ### reportStartedConnecting

    public void reportStartedConnecting()
    Tells the system the outgoing call has begun connecting -- the far end is being rung. Ignored for an incoming call, and ignored once the call has connected.

  - ### reportConnected

    public void reportConnected()
    Tells the system the call is connected. Call this when media is actually flowing, because it starts the duration the user sees.

  - ### update

    public void update(CallHandle newHandle, String newDisplayName)

    Changes what the system shows for this call. Arguments left null are left alone.

    The two fields are written under the session monitor, like the state and the mute flag: a signalling worker calls this while the EDT reads the same session to refresh the in-app call UI, and plain writes gave that reader no reason ever to see them -- so the system UI could show the new identity while Java went on displaying the old one, or a mixed pair of the two.

  - ### end

    public AsyncResource<Boolean> end(CallEndReason reason)

    Hangs up, and writes `reason` into the system call log.

    Do not call this from `CallActionListener.providerReset()` -- by then the call no longer exists.

  - ### reportEndedRemotely

    public void reportEndedRemotely(CallEndReason reason)
    Tells the system the far end ended the call. Use this rather than `end(CallEndReason)` when the hang-up came down the app's own signalling, so the call log says what happened.

  - ### setHeld

    public AsyncResource<Boolean> setHeld(boolean held)
    Holds or resumes the call.

  - ### setMuted

    public AsyncResource<Boolean> setMuted(boolean value)

    Mutes or unmutes the call in the system UI.

    This tells the operating system what the mute button should look like. It does not stop the app sending audio -- nothing here touches media -- so an app that only calls this is still transmitting.

    Gated by `CallBridge.CAPABILITY_MUTE`, which Android does not offer: a self-managed call there cannot tell Telecom its mute state, so this answers `NOT_SUPPORTED` and `isMuted()` stays where the system left it. Hearing what the user does with the system's own mute control is a separate thing and works everywhere; see `CallActionListener.muteRequested(String, boolean, CallAction)`.

  - ### sendDigits

    public AsyncResource<Boolean> sendDigits(String digits)
    Sends DTMF digits through the system.

  - ### groupWith

    public AsyncResource<Boolean> groupWith(CallSession other)

    Puts this call in a conference with `other`, or takes it out of one when `other` is null.

    Answers NOT_SUPPORTED on every platform today, which is why `CallBridge.CAPABILITY_GROUPING` is set by no port: CallKit's group action travels system to app with no app-initiated counterpart, and Telecom conferences self-managed calls only through a `ConnectionService` conference this framework does not build. It stays here because the system may still ask an app to group calls, and because a conference an app mixes itself needs no permission from either platform.