com.zoiper.zdk.EventHandlers

Interface CallEventsHandler

public interface CallEventsHandler

Method Summary

Modifier and Type	Method and Description
default void	onCallDTMFReceived(Call call, DTMFCodes dtmf) Notify upon reception of DTMF from the remote peer The event notify upon DTMF (Dual-Tone Multi-Frequency) reception from the remote peer
default void	onCallDTMFResult(Call call, Result result) Notify upon DTMF call result The event notify upon DTMF (Dual-Tone Multi-Frequency) result for the call is returned
default void	onCallExtendedError(Call call, ExtendedError error) Notify upon call extended error occurs Event fired when extended error in call occurs, providing detailed information for the error in the ExtendedError object.
default void	onCallNetworkQualityLevel(Call call, int callChannel, NetworkQualityLevel qualityLevel) Notify upon network quality level change The event notify when network quality level changes
default void	onCallNetworkStatistics(Call call, NetworkStatistics networkStatistics) Event for network statistics update The event provides call's network statistic information
default void	onCallSecurityLevelChanged(Call call, CallMediaChannel callChannel, CallSecurityLevel qualityLevel) Notify upon network quality level change The event notify when network quality level changes
default void	onCallSipHeaderFields(Call call, java.util.List<HeaderField> headerFields) SIP header dump for a SIP call Dumps the header of a SIP message from a SIP call.
default void	onCallStatusChanged(Call call, CallStatus status) Notify upon Call's status change Notify upon call's related status information is changed
default void	onCallTransferFailure(Call call, ExtendedError error) Failed call transfer event The event notify that the call transfer failed, it also provides the reason for the failure
default void	onCallTransferStarted(Call call, java.lang.String name, java.lang.String number, java.lang.String uri) Notify that call transfer is initiated The event notify that the call transfer is initiated.The number to transfer to (and display name and optionally an URI, depending on the protocol) is given for informational purposes (or to help make the decision to accept or reject the transfer).
default void	onCallTransferSucceeded(Call call) Succesuful call transfer event The event notify upon the call transfer has succeeded
default void	onCallZrtpFailed(Call call, ExtendedError error) ZRTP negotiation failed for a call The ZRTP negotiation for a call has failed.
default void	onCallZrtpSecondaryError(Call call, int callChannel, ExtendedError error) Secondary stream failed to negotiate ZRTP Multistream ZRTP negotiation has failed for a secondary stream in a call.
default void	onCallZrtpSuccess(Call call, java.lang.String zidHex, int knownPeer, int cacheMismatch, int peerKnowsUs, ZRTPSASEncoding sasEncoding, java.lang.String sas, ZRTPHashAlgorithm hash, ZRTPCipherAlgorithm cipher, ZRTPAuthTag authTag, ZRTPKeyAgreement keyAgreement) ZRTP negotiation succeeded for a call The ZRTP negotiation for a call has succeeded.
default void	onVideoCameraChanged(Call call) Video camera changed The Video cameras changed.
default void	onVideoFormatSelected(Call call, OriginType dir, int width, int height, float fps) Video format selected
default void	onVideoOffered(Call call) Video offered for audio calls The remote party has offered us video during a normal (audio) call.
default void	onVideoStarted(Call call, OriginType origin) Video started The video has started.The call is ready to encode and send frames over the network.
default void	onVideoStopped(Call call, OriginType origin) Video stopped The Video has stopped.

Method Detail

onCallStatusChanged

default void onCallStatusChanged(Call call,
                                 CallStatus status)

Notify upon Call's status change Notify upon call's related status information is changed

Parameters:

call - The call which status is changed

status - What status the account is changed to

See Also:

CallStatus

onCallExtendedError

default void onCallExtendedError(Call call,
                                 ExtendedError error)

Notify upon call extended error occurs Event fired when extended error in call occurs, providing detailed information for the error in the ExtendedError object.

Parameters:

call - The call that received the error

error - The error object that provides full information regarding the error

See Also:

ExtendedError

onCallNetworkStatistics

default void onCallNetworkStatistics(Call call,
                                     NetworkStatistics networkStatistics)

Event for network statistics update The event provides call's network statistic information

Parameters:

call - The call which network statics is provided

networkStatistics - The network statistics object with full statistic information

See Also:

NetworkStatistics

onCallNetworkQualityLevel

default void onCallNetworkQualityLevel(Call call,
                                       int callChannel,
                                       NetworkQualityLevel qualityLevel)

Notify upon network quality level change The event notify when network quality level changes

Parameters:

call - The call which network quality level is changed

callChannel - The call's channel

qualityLevel - The quality level value

See Also:

NetworkQualityLevelType

onCallSecurityLevelChanged

default void onCallSecurityLevelChanged(Call call,
                                        CallMediaChannel callChannel,
                                        CallSecurityLevel qualityLevel)

Notify upon network quality level change The event notify when network quality level changes

Parameters:

call - The call which network quality level is changed

callChannel - The call's channel

qualityLevel - The quality level value

See Also:

Call

onCallDTMFResult

default void onCallDTMFResult(Call call,
                              Result result)

Notify upon DTMF call result The event notify upon DTMF (Dual-Tone Multi-Frequency) result for the call is returned

Parameters:

call - The call for which DTMF response is returned

result - The result

See Also:

Call

onCallDTMFReceived

default void onCallDTMFReceived(Call call,
                                DTMFCodes dtmf)

Notify upon reception of DTMF from the remote peer The event notify upon DTMF (Dual-Tone Multi-Frequency) reception from the remote peer

Parameters:

call - The call for which received a DTMF

dtmf - The received DTMF

See Also:

DTMFCodes

onCallTransferSucceeded

default void onCallTransferSucceeded(Call call)

Succesuful call transfer event The event notify upon the call transfer has succeeded

Parameters:

call - The call which was transfered

See Also:

onCallTransferStarted onCallTransferSucceeded

onCallTransferFailure

default void onCallTransferFailure(Call call,
                                   ExtendedError error)

Failed call transfer event The event notify that the call transfer failed, it also provides the reason for the failure

Parameters:

call - The call which was transfered failed

error - The reason why it failed

See Also:

onCallTransferStarted onCallTransferSucceeded

onCallTransferStarted

default void onCallTransferStarted(Call call,
                                   java.lang.String name,
                                   java.lang.String number,
                                   java.lang.String uri)

Notify that call transfer is initiated The event notify that the call transfer is initiated.The number to transfer to (and display name and optionally an URI, depending on the protocol) is given for informational purposes (or to help make the decision to accept or reject the transfer).

Parameters:

call - The call on which the transfer request came

name - The name of the transfer target

number - The number of the transfer target

uri - Optionally, protocol dependant URI of the transfer target

See Also:

onCallTransferStarted onCallTransferSucceeded

onCallZrtpFailed

default void onCallZrtpFailed(Call call,
                              ExtendedError error)

ZRTP negotiation failed for a call The ZRTP negotiation for a call has failed. Information about the failure can be found in the error parameter.

Parameters:

call - The call on which ZRTP failed

error - Information on why the ZRTP failed

See Also:

ExtendedError

onCallZrtpSuccess

default void onCallZrtpSuccess(Call call,
                               java.lang.String zidHex,
                               int knownPeer,
                               int cacheMismatch,
                               int peerKnowsUs,
                               ZRTPSASEncoding sasEncoding,
                               java.lang.String sas,
                               ZRTPHashAlgorithm hash,
                               ZRTPCipherAlgorithm cipher,
                               ZRTPAuthTag authTag,
                               ZRTPKeyAgreement keyAgreement)

ZRTP negotiation succeeded for a call The ZRTP negotiation for a call has succeeded. This does not always mean full security yet, due to the nature of ZRTP. Even though at this stage there is an active SRTP encryption, the keys used might be compromised. To make sure the keys were safe the participants will need to do verbal comparison of a short string derived from the same calculations. In case the identify of the participants was confirmed by using secret data from previous calls SAS verification is not required. If the peer in this call was known (found in the cache) the @p knownPeer parameter will be set to 1. If we meet this peer for the first time, the parameter will be set to 0. If the peer knows us, the @p peerKnowsUs parameter will be set to 1. If the peer sees us for the first time, or they see some other problem with our identity, this flag will be set to 0. Note that this information comes over the encrypted channel protected by ZRTP but there is a small chance the encryption was compromised (i.e. do not completely trust this flag). If the peer is known and we agree on the retained secrets in our caches (both us and them), the cacheMismatch will be set to 0. If the peer was known but we disagree on the retained secret there might be a security problem or one of us might have a corrupted cache file. In this case the cacheMismatch will be set to 1. If the peer is not known, the @p cacheMismatch value is set to 1 to make it easier to check if we need SAS comparison by only looking at one parameter instead of making complex logic checks. If the peer sent us an indication that they do not know us from previous calls (@p peerKnowsUs set to 0), @p cacheMismatch will also be set to 1 to force SAS verification. The string that needs to be compared is called the Short Authentication String. It is returned in the @p sas parameter. Although @p sas is based on a binary hash, it is encoded in a human-readable form. The encoding type is returned in the @p sasEncoding paramter. The ZRTP RFC recommends using the following warning text if SAS comparison is required for a known peer (i.e. when @p knownPeer is 1 but @p cacheMismatch is also set to 1): Long version: We expected the other party to have a shared secret cached from a previous call, but they don't have it. This may mean your peer simply lost their cache of shared secrets, but it could also mean someone is trying to wiretap you. To resolve this question you must check the authentication string with your peer. If it doesn't match, it indicates the presence of a wiretapper. Short version: Something's wrong. You must check the authentication string with your peer. If it doesn't match, it indicates the presence of a wiretapper. Even if @p knownPeer is 1 and @p cacheMismatch is 0 and @p peerKnowsUs is 1, the SAS should be made available on demand from the user. If the user demands SAS verification and it fails,the call will be treated as insecure and the user will be alerted. More information about the ZRTP negotiation is returned in the rest of the parameters. "cipher" and "authTag" are of interest as they'll be employed by the SRTP encryption and it might be useful to display them somewhere. "hash" and "keyAgreement" are the hash algorithm and the key agreement method used in this call.

Parameters:

call - The call

zidHex - The peer's ZRTP ID (ZID) in HEX representation

knownPeer - 1 if the peer is known, 0 if we see them for the first time

cacheMismatch - 1 if the peer needs to be confirmed, 0 if the cache agrees

peerKnowsUs - 1 if the peer knows us, 0 if they see us for the first time or if they have encountered a cache mismatch of their own

sasEncoding - The SAS encoding

sas - The Short Authentication String to be confirmed if needed. The string is in human readable form in the encoding @p sasEncoding

hash - The chosen Hash Algorithm

cipher - The chosen Cipher Algorithm (used in SRTP)

authTag - The chosen Authentication Tag type (used in SRTP)

keyAgreement - The key agreement method used for the negotiation

See Also:

ZRTPSASEncoding ZRTPHashAlgorithm ZRTPCipherAlgorithm ZRTPAuthTag ZRTPKeyAgreement

onCallZrtpSecondaryError

default void onCallZrtpSecondaryError(Call call,
                                      int callChannel,
                                      ExtendedError error)

Secondary stream failed to negotiate ZRTP Multistream ZRTP negotiation has failed for a secondary stream in a call. ZRTP requires only the first RTP stream in a SIP call to be negotiated with a full Diffie-Hellman key exchange. Due to the nature of ZRTP the primary RTP stream is an audio stream (to allow for voice confirmation of the SAS). Subsequent streams in a call, like the video stream for example, will use a shorter version of ZRTP called "Multistream ZRTP" to negotiate the keys. In case a SIP call is configured with both ZRTP and Video, after the ZRTP finishes securing the audio channel, the SIP call will automatically try to secure the video channel. If this secondary negotiation fails this event will be fired. This error does NOT mean that the primary channel is suddenly broken. There are no side effects from this failure. The remote end might have a different opinion on the matter and might decide to close the call.

Parameters:

call - The call Id on which the secondary ZRTP negotiation failed

callChannel - The type of the secondary RTP stream (usually video)

error - Detailed error information about the failure

See Also:

ExtendedError

onCallSipHeaderFields

default void onCallSipHeaderFields(Call call,
                                   java.util.List<HeaderField> headerFields)

SIP header dump for a SIP call Dumps the header of a SIP message from a SIP call. For incoming calls, this is the header of the NVITE message. For outgoing calls, this is the header of the 200 response. Each header field from the SIP header is represented as an entry in @p headerFields. Each header field can have one or more values associated with it in the @p Values array. The header field @p Name and the @p Values are UTF-8 strings. The structure is valid only for the duration of this callback. To enable this callback, use sipConfig::HeaderDump.

Parameters:

call - The call

headerFields - The header fields array

See Also:

HeaderFields

onVideoOffered

default void onVideoOffered(Call call)

Video offered for audio calls The remote party has offered us video during a normal (audio) call. Use acceptVideo to accept or decline the video

Parameters:

call - The call

See Also:

Call

onVideoStarted

default void onVideoStarted(Call call,
                            OriginType origin)

Video started The video has started.The call is ready to encode and send frames over the network. Use the sendVideoFrame function to send frames.

Parameters:

call - The video call

origin - The call initiator type (incoming, outgoing)

See Also:

OriginType

onVideoStopped

default void onVideoStopped(Call call,
                            OriginType origin)

Video stopped The Video has stopped.

Parameters:

call - The video call

origin - The call initiator type (incoming, outgoing)

See Also:

OriginType

onVideoCameraChanged

default void onVideoCameraChanged(Call call)

Video camera changed The Video cameras changed.

Parameters:

call - The video call

See Also:

Call

onVideoFormatSelected

default void onVideoFormatSelected(Call call,
                                   OriginType dir,
                                   int width,
                                   int height,
                                   float fps)

Video format selected

Parameters:

call - The call for which the video format was selected

dir - The direction

width - Width in pixels

height - Height in pixels

fps - Frames per seconds

See Also:

OriginType