Package com.avaya.clientservices.call

## Interface CallListener

-     public interface CallListener

  Interface that can be used to retrieve status updates from a Call object. One or more listeners can be registered with a Call object to retrieve status updates. All of the callback methods defined in CallListener interface have the Call object instance as an argument, to identify the call session.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `onCallAllowedVideoDirectionChanged​(Call call, AllowedVideoDirection allowedVideoDirection)` | Called to report allowed video direction has changed.
    `void` | `onCallAudioMuteStatusChanged​(Call call, boolean muted)` | Called when the call's audio is muted or unmuted.
    `void` | `onCallCapabilitiesChanged​(Call call)` | Called to report a change in call's capabilities.
    `void` | `onCallConferenceStatusChanged​(Call call, boolean isConference)` | Called to report a change in conference status of the call.
    `void` | `onCallDenied​(Call call)` | Called when an incoming call is locally denied.
    `void` | `onCallDigitCollectionCompleted​(Call call)` | For a call in the off-hook dialing state, indicates that digit collection has completed and the call will now be initiated using the collected digits.
    `void` | `onCallDigitCollectionPlayDialTone​(Call call)` | For a call in the off-hook dialing state, indicates that the dial plan data has specified that the application should resume playing dial tone until another digit is entered.
    `void` | `onCallEnded​(Call call, CallEndReason endReason)` | Called when a call is ended.
    `void` | `onCallEstablished​(Call call)` | Called when an outgoing call has been established.
    `void` | `onCallExtraPropertiesChanged​(Call call, java.util.Map<java.lang.String,​java.lang.String> extraProperties)` | Called to inform application about extra properties associated with the call has changed.
    `void` | `onCallFailed​(Call call, CallException exception)` | Called when a call fails.
    `void` | `onCallHeld​(Call call)` | Called when an existing call is locally held.
    `void` | `onCallHeldRemotely​(Call call)` | Called when an existing call is remotely held.
    `void` | `onCallIgnored​(Call call)` | Called when an incoming call is locally ignored, as a result of a prior Call.ignore() call by the client application.
    `void` | `onCallIncomingVideoAddRequestAccepted​(Call call, VideoChannel videoChannel)` | Called to report that the incoming video add request has been accepted by the client application.
    `void` | `onCallIncomingVideoAddRequestDenied​(Call call)` | Called to report that the incoming video add request by the far-end has been denied by local user calling call.denyVideo().
    `void` | `onCallIncomingVideoAddRequestReceived​(Call call)` | Called to report that the far-end has requested adding a new video channel, e.g., when the far-end wants to add video to an existing audio-only call.
    `void` | `onCallIncomingVideoAddRequestTimedOut​(Call call)` | Called to report that the incoming video add request has not been accepted or denied by the client application in a timely manner to allow the successful setup of the video channel.
    `void` | `onCallJoined​(Call call)` | Called when a previously remote call becomes a local call as a result of the local application calling Call.Join() on the Call object.
    `void` | `onCallLongHoldTimeExpired​(Call call)` | Sent when the call was kept on hold for longer than the hold recall timeout administered on Avaya Communication Manager (CM).
    `void` | `onCallParticipantMatchedContactsChanged​(Call call)` | Called to report that the participant's matched contacts changed.
    `void` | `onCallPrecedenceLevelChanged​(Call call, CallPrecedenceLevel newPrecedenceLevel)` | This is called to inform application about change in precedence level of call.
    `void` | `onCallPreempted​(Call call, CallPreemptionReason preemptionReason, boolean isPreemptionCompletionRequiredByClient)` | This is called to inform application about call being preempted.
    `void` | `onCallQueued​(Call call)` | Called when an outgoing call is queued by a network server.
    `void` | `onCallRecordingStateChanged​(Call call, CallRecordingState recordingState)` | Called to inform application about call recording state.
    `void` | `onCallRedirected​(Call call)` | Called when an outgoing call is redirected by the network servers to a different destination (e.g., when EC500 forking takes place or call is covered to voice mail).
    `void` | `onCallRemoteAddressChanged​(Call call, java.lang.String newAddress, java.lang.String newDisplayName)` | Called when remote party address of the call changes.
    `void` | `onCallRemoteAlerting​(Call call, boolean hasEarlyMedia)` | Called an when outgoing call has received ring back information from the signaling network.
    `void` | `onCallRemoteControlVideoModeRequested​(Call call, VideoMode videoMode)` | This is called to inform the application about video mode change request received from the user's other endpoint, which is controlling this application instance in Shared Control mode (see `SIPUserConfiguration.setControlledEndpointEnabled(boolean)`).
    `void` | `onCallSecureIndicationChanged​(Call call, boolean isSecure)` | Called to inform the application about a change in the end to end security status of the call from/to secured/unsecured.
    `void` | `onCallServiceAvailable​(Call call)` | Called to report that the call has a healthy signaling path.
    `void` | `onCallServiceUnavailable​(Call call)` | Called to report that the call's signaling path has failed.
    `void` | `onCallSpeakerSilenceStatusChanged​(Call call, boolean silenced)` | Called when speaker is silenced or unsilenced for the call.
    `void` | `onCallStarted​(Call call)` | Called to report that call has started.
    `void` | `onCallUnheld​(Call call)` | Called when an existing call is unheld.
    `void` | `onCallUnheldRemotely​(Call call)` | Called when an existing call is remotely unheld.
    `void` | `onCallVerificationStatusChanged​(Call call, VerificationStatus verificationStatus)` | This is called to inform application about change in verification status of call.
    `void` | `onCallVideoChannelsUpdated​(Call call, java.util.List<VideoChannel> videoChannels)` | Called when an the video channels have been updated.

- - ### Method Detail

    - #### onCallStarted

          void onCallStarted​(Call call)

      Called to report that call has started. In SIP, this corresponds to when Initial INVITE is sent.
      Parameters:
        `call` - current call object.

    - #### onCallRemoteAlerting

          void onCallRemoteAlerting​(Call call,
                                    boolean hasEarlyMedia)

      Called an when outgoing call has received ring back information from the signaling network. In SIP, this corresponds to when the call receives 180 or 183 response from the network. It should be noted that there may be one or more callbacks as a result of initiating an outgoing call. For example, a call may start out not having early media, in which case onCallRemoteAlerting(false) is called. This may be followed by onCallRemoteAlerting(true), possibly followed by onCallRedirected(), followed by onCallRemoteAlerting(false). Application developers should not make an assumption in exact ordering of these provisional responses, as the sequence depends on different call routing features and the call topology.
      Parameters:
        `call` - The call that the callback is associated with.
        `hasEarlyMedia` - Flag indicating whether there is an early dialog media call associated with the call or not.

    - #### onCallRedirected

          void onCallRedirected​(Call call)

      Called when an outgoing call is redirected by the network servers to a different destination (e.g., when EC500 forking takes place or call is covered to voice mail). For example, in SIP, this callback happens when 181 provisional response is received. It should be noted that this notice depends on the capabilities of the network servers, and some servers may redirect a call without providing a specific redirection notice.
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallQueued

          void onCallQueued​(Call call)

      Called when an outgoing call is queued by a network server. For example, this callback happens as a result of receiving SIP 182 provisional response. In Avaya's SIP solution, this response is received in contact center environment, when the call is placed in a VDN queue, waiting to be connected to a live agent.
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallEstablished

          void onCallEstablished​(Call call)

      Called when an outgoing call has been established. In SIP, this corresponds to when the call receives 200 OK response from the called party.
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallRemoteAddressChanged

          void onCallRemoteAddressChanged​(Call call,
                                          java.lang.String newAddress,
                                          java.lang.String newDisplayName)

      Called when remote party address of the call changes. The new address information is provided as part of the callback. For additional information that is updated, e.g., network-provided display name, the client may query the Call object.
      Parameters:
        `call` - The call that the callback is associated with.
        `newAddress` - New remote address
        `newDisplayName` - New name associate with the newAddress

    - #### onCallHeld

          void onCallHeld​(Call call)

      Called when an existing call is locally held. In SIP, this corresponds to when the call receives a 200 OK response to a previous hold request (re-INVITE).
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallUnheld

          void onCallUnheld​(Call call)

      Called when an existing call is unheld. In SIP, this corresponds to when the call receives a 200 OK response to a previous unhold request (re-INVITE).
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallHeldRemotely

          void onCallHeldRemotely​(Call call)

      Called when an existing call is remotely held. In SIP, this is based on receiving a re-INVITE with a SIP Reason header that has Avaya cause "Hold".
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallUnheldRemotely

          void onCallUnheldRemotely​(Call call)

      Called when an existing call is remotely unheld. In SIP, this is based on receiving a re-INVITE with a SIP Reason header that has Avaya cause "Unhold".
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallLongHoldTimeExpired

          void onCallLongHoldTimeExpired​(Call call)

      Sent when the call was kept on hold for longer than the hold recall timeout administered on Avaya Communication Manager (CM). Upon receipt of this event, the SDK's client application is responsible for presenting (alerting) the event to the user.
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallJoined

          void onCallJoined​(Call call)

      Called when a previously remote call becomes a local call as a result of the local application calling Call.Join() on the Call object. In Avaya Aura environment, this is done by sending INVITE with Join to join a remote call that is identified by the call information that was received in a dialog state notification.
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallEnded

          void onCallEnded​(Call call,
                           CallEndReason endReason)

      Called when a call is ended. This callback method is called when the call is either locally or remotely ended.
      Parameters:
        `call` - The call that the callback is associated with.
        `endReason` - Reason of a call end.

    - #### onCallFailed

          void onCallFailed​(Call call,
                            CallException exception)

      Called when a call fails. This callback method is called when the call has failed either by a local error or by an error feedback received over the signaling network (e.g., when a call attempt to an unreachable address is made). The specific reason for failure is identified by the 'exception' argument. It should be noted that a call that has failed is not automatically ended by the signaling engine (i.e. this toolkit). The application needs to call Call.end() to end the failed call. This is done so that a client application implementation that is line oriented can keep the line appearance occupied while the call is in failed state.
      Parameters:
        `call` - The call that the callback is associated with.
        `exception` - Call failure details.

    - #### onCallDenied

          void onCallDenied​(Call call)

      Called when an incoming call is locally denied.
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallIgnored

          void onCallIgnored​(Call call)

      Called when an incoming call is locally ignored, as a result of a prior Call.ignore() call by the client application.
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallAudioMuteStatusChanged

          void onCallAudioMuteStatusChanged​(Call call,
                                            boolean muted)

      Called when the call's audio is muted or unmuted.
      Parameters:
        `call` - The call associated with the callback.
        `muted` - The new mute state.

    - #### onCallSpeakerSilenceStatusChanged

          void onCallSpeakerSilenceStatusChanged​(Call call,
                                                 boolean silenced)

      Called when speaker is silenced or unsilenced for the call.
      Parameters:
        `call` - The call associated with the callback.
        `silenced` - The new silence state.

    - #### onCallVideoChannelsUpdated

          void onCallVideoChannelsUpdated​(Call call,
                                          java.util.List<VideoChannel> videoChannels)

      Called when an the video channels have been updated. The update may be related to one or more characteristics of the video channel, and may be used to report: - One or more channels added. - One or more channels removed. - One or more channels updated. Such as video direction change (e.g., changing from receive-only to send-receive) or video resolution change.
      Parameters:
        `call` - The call that the callback is associated with.
        `videoChannels` - Updated video channels

    - #### onCallIncomingVideoAddRequestReceived

          void onCallIncomingVideoAddRequestReceived​(Call call)

      Called to report that the far-end has requested adding a new video channel, e.g., when the far-end wants to add video to an existing audio-only call. In SDP, this is reported as a new video m-line, and in SIP is carried in an in-dialog INVITE request sent by the far-end. The application can either accept or reject the request by calling Call.acceptVideo() or Call.denyVideo(), respectively. When the video channel add request is successfully accepted, CallListener.onCallIncomingVideoAddRequestAccepted() is called. When the request is denied, CallListener.onCallIncomingVideoAddRequestDenied() is called.
      Parameters:
        `call` - The call that the callback is associated with.
      See Also:
        `Call`, `VideoChannel`

    - #### onCallIncomingVideoAddRequestAccepted

          void onCallIncomingVideoAddRequestAccepted​(Call call,
                                                     VideoChannel videoChannel)

      Called to report that the incoming video add request has been accepted by the client application.
      Parameters:
        `call` - The call that the callback is associated with.
        `videoChannel` - The video channel used to accept the incoming video request.

    - #### onCallIncomingVideoAddRequestDenied

          void onCallIncomingVideoAddRequestDenied​(Call call)

      Called to report that the incoming video add request by the far-end has been denied by local user calling call.denyVideo(). When an incoming video add request is reported to the application using onCallVideoAddRequestedRemotely(), an internal timer is started for the client application to either accept or deny the request. This is done to ensure that the incoming video add transaction does not timeout at the network level. If the client is unable to accept or deny the video add request, the internal timer fires up and the video add request is denied at the signaling protocol level, and onCallIncomingVideoAddRequestTimedOut() is called.
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallIncomingVideoAddRequestTimedOut

          void onCallIncomingVideoAddRequestTimedOut​(Call call)

      Called to report that the incoming video add request has not been accepted or denied by the client application in a timely manner to allow the successful setup of the video channel. This can happen if, for example, the client application decides to prompt user for either accepting or denying the request and the user takes an excessively long time to handle the prompt.
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallRemoteControlVideoModeRequested

          void onCallRemoteControlVideoModeRequested​(Call call,
                                                     VideoMode videoMode)

      This is called to inform the application about video mode change request received from the user's other endpoint, which is controlling this application instance in Shared Control mode (see `SIPUserConfiguration.setControlledEndpointEnabled(boolean)`).

      It should be noted that video mode change requests cannot be automatically handled by Client SDK, because video rendering surface and camera device are directly under the client application's control.

      Upon receiving this request, the application should initialize or cleanup video resources as required (e.g., video rendering surface, camera, etc.) and call `Call.setVideoMode(VideoMode, CallCompletionHandler)` on the call object with the requested video mode.

      If the video mode request is for enabling bidirectional video on the audio-only call, but local camera device cannot be initialized, the client application should enable receive-only video for the call by calling call.setVideoMode(VideoMode.RECEIVE_ONLY). If, for some reason, the client application is unable to even receive and render video, it may ignore this request and keep the call as audio-only.

      If the video mode request is for enabling bidirectional video on the receive-only video call, but local camera device cannot be initialized, the client application should ignore this request and keep the call with receive-only video.

      Parameters:
        `call` - The call that the callback is associated with.
        `videoMode` - Requested video mode.
      See Also:
        `VideoMode`

    - #### onCallConferenceStatusChanged

          void onCallConferenceStatusChanged​(Call call,
                                             boolean isConference)

      Called to report a change in conference status of the call.
      Parameters:
        `call` - The call that the callback is associated with.
        `isConference` - True if the call has become a conference call; false, if the call is no longer a conference call.

    - #### onCallCapabilitiesChanged

          void onCallCapabilitiesChanged​(Call call)

      Called to report a change in call's capabilities. The listener can query the Call object to find out about the capability that changed.
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallServiceAvailable

          void onCallServiceAvailable​(Call call)

      Called to report that the call has a healthy signaling path.
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallServiceUnavailable

          void onCallServiceUnavailable​(Call call)

      Called to report that the call's signaling path has failed.
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallParticipantMatchedContactsChanged

          void onCallParticipantMatchedContactsChanged​(Call call)

      Called to report that the participant's matched contacts changed.
      Parameters:
        `call` - The call that the callback is associated with.

    - #### onCallDigitCollectionPlayDialTone

          void onCallDigitCollectionPlayDialTone​(Call call)

      For a call in the off-hook dialing state, indicates that the dial plan data has specified that the application should resume playing dial tone until another digit is entered.
      Parameters:
        `call` - a call in the off-hook dialing state.

    - #### onCallDigitCollectionCompleted

          void onCallDigitCollectionCompleted​(Call call)

      For a call in the off-hook dialing state, indicates that digit collection has completed and the call will now be initiated using the collected digits.
      Parameters:
        `call` - a call in the off-hook dialing state.

    - #### onCallPrecedenceLevelChanged

          void onCallPrecedenceLevelChanged​(Call call,
                                            CallPrecedenceLevel newPrecedenceLevel)

      This is called to inform application about change in precedence level of call.
      Parameters:
        `call` - Call object that the callback is associated with.
        `newPrecedenceLevel` - the new precedence level of call.
      See Also:
        `CallPrecedenceLevel`

    - #### onCallPreempted

          void onCallPreempted​(Call call,
                               CallPreemptionReason preemptionReason,
                               boolean isPreemptionCompletionRequiredByClient)

      This is called to inform application about call being preempted. This would trigger application to start either continuous preemption tone OR three seconds preemption tone based on flag isPreemptionCompletionRequiredByClient and call state. Call preemption occurs when a precedence call is sent to a preemptable endpoint that is busy with a call of lower precedence and has no idle appearances. This causes the lower precedence call to be preempted, regardless of whether the lower precedence call and the new higher precedence call are of the same media type. When preemption occurs, the active busy user receive a continuous preemption tone until user acknowledges the preemption by invoking complete preemption method and the other party receives a preemption tone for a minimum of 3 seconds. After acknowledging the preemption, the extension to which the precedence call is directed will be provided with precedence ringing and the calling party will receive an audible ringback precedence tone. Application must start playing preemption tone upon receipt of event onCallPreempted and stop preemption tone before calling `CallFeatureService.completeCallPreemption(Call, com.avaya.clientservices.call.feature.FeatureCompletionHandler)` when user acknowledges the preemption. However when other end receives preemption application must stop tone after 3 seconds and `CallFeatureService.completeCallPreemption(Call, com.avaya.clientservices.call.feature.FeatureCompletionHandler)` is NOT needed since there is no precedence call is directed at this end, other end is free and ready to receive any other new call while tone is being played.
      Parameters:
        `call` - Call object that the callback is associated with, the same call object should be used for completing the preemption.
        `preemptionReason` - the reason why this call was preempted.
        `isPreemptionCompletionRequiredByClient` - indicates if application needs complete call preemption. When isPreemptionCompletionRequiredByClient is true, Application must inform system when user acknowledges the preemption after continuous preemption tone is being played because active busy user's call is preempted. This is done by calling method `CallFeatureService.completeCallPreemption(Call, com.avaya.clientservices.call.feature.FeatureCompletionHandler)` after user acknowledges the preemption, that also means application would stop preemption tone. When isPreemptionCompletionRequiredByClient is false, Application needs to play three seconds preemption tone after active or outgoing alerting call is preempted.
      See Also:
        `CallFeatureService.completeCallPreemption(Call, com.avaya.clientservices.call.feature.FeatureCompletionHandler)`, `CallPreemptionReason`

    - #### onCallAllowedVideoDirectionChanged

          void onCallAllowedVideoDirectionChanged​(Call call,
                                                  AllowedVideoDirection allowedVideoDirection)

      Called to report allowed video direction has changed. The listener can query the Call object to find out about the allowed direction.
      Parameters:
        `call` - The call that the callback is associated with.
        `allowedVideoDirection` - New allowed video direction.

    - #### onCallExtraPropertiesChanged

          void onCallExtraPropertiesChanged​(Call call,
                                            java.util.Map<java.lang.String,​java.lang.String> extraProperties)

      Called to inform application about extra properties associated with the call has changed. The application can invoke getExtraProperties() at any time to see the contents, and that the parameter passed as part of this call is the map as it exists at that point in time.
      Parameters:
        `call` - The call sending the message.
        `extraProperties` - Complete list of extra properties associated with the call. `getExtraProperties`

    - #### onCallRecordingStateChanged

          void onCallRecordingStateChanged​(Call call,
                                           CallRecordingState recordingState)

      Called to inform application about call recording state.
      Parameters:
        `call` - The call that the callback is associated with.
        `recordingState` - New recording state of the call.

    - #### onCallSecureIndicationChanged

          void onCallSecureIndicationChanged​(Call call,
                                             boolean isSecure)

      Called to inform the application about a change in the end to end security status of the call from/to secured/unsecured.
      Parameters:
        `call` - The call that the callback is associated with.
        `isSecure` - Flag indicating whether the call is secure or not.

    - #### onCallVerificationStatusChanged

          void onCallVerificationStatusChanged​(Call call,
                                               VerificationStatus verificationStatus)

      This is called to inform application about change in verification status of call.
      Parameters:
        `call` - Call object that the callback is associated with.
        `verificationStatus` - the verification status of call.
      See Also:
        `VerificationStatus`