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 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.