zdk.objc
Instance Methods | List of all members
<ZDKCallEventsHandler> Protocol Reference
Inheritance diagram for <ZDKCallEventsHandler>:
<ZDKEventHandle>

Instance Methods

(void) - onCall:statuschanged:
 Notify upon Call's status change. More...
 
(void) - onCall:extendedError:
 Notify upon call extended error occurs. More...
 
(void) - onCall:networkStatistics:
 Event for network statistics update. More...
 
(void) - onCall:networkQualityLevel:qualityLevel:
 Notify upon network quality level change. More...
 
(void) - onCall:securityLevelChanged:qualityLevel:
 Notify upon network quality level change. More...
 
(void) - onCall:dtmfResult:
 Notify upon DTMF call result. More...
 
(void) - onCall:dtmfReceived:
 Notify upon reception of DTMF from the remote peer. More...
 
(void) - onCalltransferSucceeded:
 Succesuful call transfer event. More...
 
(void) - onCall:transferFailure:
 Failed call transfer event. More...
 
(void) - onCall:transferStarted:number:uri:
 Notify that call transfer is initiated. More...
 
(void) - onCall:zrtpFailed:
 ZRTP negotiation failed for a call. More...
 
(void) - onCall:zrtpSuccess:knownPeer:cacheMismatch:peerKnowsUs:sasEncoding:sas:hash:cipher:authTag:keyAgreement:
 ZRTP negotiation succeeded for a call. More...
 
(void) - onCall:zrtpSecondaryError:error:
 Secondary stream failed to negotiate ZRTP. More...
 
(void) - onCall:sipHeaderFields:
 SIP header dump for a SIP call. More...
 
(void) - onVideoOffered:
 Video offered for audio calls. More...
 
(void) - onVideoStarted:origin:
 Video started. More...
 
(void) - onVideoStopped:origin:
 Video stopped. More...
 
(void) - onVideoCameraChanged:
 Video camera changed. More...
 
(void) - onVideoFormatSelected:dir:width:height:fps:
 Video format selected. More...
 
(NSString *) - handlesDescription
 
- Instance Methods inherited from <ZDKEventHandle>
(long int) - eventHandle
 
(NSString *) - handlesDescription
 

Method Documentation

◆ handlesDescription

- (NSString *) handlesDescription
optional

Reimplemented from <ZDKEventHandle>.

◆ onCall:dtmfReceived:

- (void) onCall: (id< ZDKCall >)  call
dtmfReceived: (ZDKDTMFCodes)  dtmf 
optional

Notify upon reception of DTMF from the remote peer.

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

Parameters
[in]callThe call for which received a DTMF
[in]dtmfThe received DTMF
See also
ZDKCall, DTMFCodes

◆ onCall:dtmfResult:

- (void) onCall: (id< ZDKCall >)  call
dtmfResult: (id< ZDKResult >)  result 
optional

Notify upon DTMF call result.

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

Parameters
[in]callThe call for which DTMF response is returned
[in]resultThe result
See also
ZDKCall

◆ onCall:extendedError:

- (void) onCall: (id< ZDKCall >)  call
extendedError: (id< ZDKExtendedError >)  error 
optional

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
[in]callThe call that received the error
[in]errorThe error object that provides full information regarding the error
See also
ZDKCall, ZDKExtendedError

◆ onCall:networkQualityLevel:qualityLevel:

- (void) onCall: (id< ZDKCall >)  call
networkQualityLevel: (int)  callChannel
qualityLevel: (ZDKNetworkQualityLevel)  qualityLevel 
optional

Notify upon network quality level change.

The event notify when network quality level changes

Parameters
[in]callThe call which network quality level is changed
[in]callChannelThe call's channel
[in]qualityLevelThe quality level value
See also
ZDKCall, NetworkQualityLevelType

◆ onCall:networkStatistics:

- (void) onCall: (id< ZDKCall >)  call
networkStatistics: (id< ZDKNetworkStatistics >)  networkStatistics 
optional

Event for network statistics update.

The event provides call's network statistic information

Parameters
[in]callThe call which network statics is provided
[in]networkStatisticsThe network statistics object with full statistic information
See also
ZDKCall, ZDKNetworkStatistics

◆ onCall:securityLevelChanged:qualityLevel:

- (void) onCall: (id< ZDKCall >)  call
securityLevelChanged: (ZDKCallMediaChannel)  callChannel
qualityLevel: (ZDKCallSecurityLevel)  qualityLevel 
optional

Notify upon network quality level change.

The event notify when network quality level changes

Parameters
[in]callThe call which network quality level is changed
[in]callChannelThe call's channel
[in]qualityLevelThe quality level value
See also
ZDKCall

◆ onCall:sipHeaderFields:

- (void) onCall: (id< ZDKCall >)  call
sipHeaderFields: (NSArray *)  headerFields 
optional

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

Each header field can have one or more values associated with it in the Values array.

The header field Name and the Values are UTF-8 strings.

The structure is valid only for the duration of this callback.

To enable this callback, use zdksipConfig::HeaderDump().

Parameters
[in]callThe call
[in]headerFieldsThe header fields array
See also
ZDKCall, ZDKHeaderFields

◆ onCall:statuschanged:

- (void) onCall: (id< ZDKCall >)  call
statuschanged: (id< ZDKCallStatus >)  status 
optional

Notify upon Call's status change.

Notify upon call's related status information is changed

Parameters
[in]callThe call which status is changed
[in]statusWhat status the account is changed to
See also
ZDKCall, ZDKCallStatus

◆ onCall:transferFailure:

- (void) onCall: (id< ZDKCall >)  call
transferFailure: (id< ZDKExtendedError >)  error 
optional

Failed call transfer event.

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

Parameters
[in]callThe call which was transfered failed
[in]errorThe reason why it failed
See also
ZDKCall, onCallTransferStarted(), onCallTransferSucceeded()

◆ onCall:transferStarted:number:uri:

- (void) onCall: (id< ZDKCall >)  call
transferStarted: (NSString *)  name
number: (NSString *)  number
uri: (NSString *)  uri 
optional

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
[in]callThe call on which the transfer request came
[in]nameThe name of the transfer target
[in]numberThe number of the transfer target
[in]uriOptionally, protocol dependant URI of the transfer target
See also
ZDKCall, onCallTransferStarted(), onCallTransferSucceeded()

◆ onCall:zrtpFailed:

- (void) onCall: (id< ZDKCall >)  call
zrtpFailed: (id< ZDKExtendedError >)  error 
optional

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
[in]callThe call on which ZRTP failed
[in]errorInformation on why the ZRTP failed
See also
ZDKCall, ZDKExtendedError

◆ onCall:zrtpSecondaryError:error:

- (void) onCall: (id< ZDKCall >)  call
zrtpSecondaryError: (int)  callChannel
error: (id< ZDKExtendedError >)  error 
optional

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
[in]callThe call Id on which the secondary ZRTP negotiation failed
[in]callChannelThe type of the secondary RTP stream (usually video)
[in]errorDetailed error information about the failure
See also
ZDKCall, ZDKExtendedError

◆ onCall:zrtpSuccess:knownPeer:cacheMismatch:peerKnowsUs:sasEncoding:sas:hash:cipher:authTag:keyAgreement:

- (void) onCall: (id< ZDKCall >)  call
zrtpSuccess: (NSString *)  zidHex
knownPeer: (int)  knownPeer
cacheMismatch: (int)  cacheMismatch
peerKnowsUs: (int)  peerKnowsUs
sasEncoding: (ZDKZRTPSASEncoding)  sasEncoding
sas: (NSString *)  sas
hash: (ZDKZRTPHashAlgorithm)  hash
cipher: (ZDKZRTPCipherAlgorithm)  cipher
authTag: (ZDKZRTPAuthTag)  authTag
keyAgreement: (ZDKZRTPKeyAgreement)  keyAgreement 
optional

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 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 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 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 (peerKnowsUs set to 0), 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 sas parameter. Although sas is based on a binary hash, it is encoded in a human-readable form. The encoding type is returned in the sasEncoding paramter.

The ZRTP RFC recommends using the following warning text if SAS comparison is required for a known peer (i.e. when knownPeer is 1 but 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 knownPeer is 1 and cacheMismatch is 0 and 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
[in]callThe call
[in]zidHexThe peer's ZRTP ID (ZID) in HEX representation
[in]knownPeer1 if the peer is known, 0 if we see them for the first time
[in]cacheMismatch1 if the peer needs to be confirmed, 0 if the cache agrees
[in]peerKnowsUs1 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
[in]sasEncodingThe SAS encoding
[in]sasThe Short Authentication String to be confirmed if needed. The string is in human readable form in the encoding sasEncoding
[in]hashThe chosen Hash Algorithm
[in]cipherThe chosen Cipher Algorithm (used in SRTP)
[in]authTagThe chosen Authentication Tag type (used in SRTP)
[in]keyAgreementThe key agreement method used for the negotiation
See also
ZDKCall, ZRTPSASEncoding, ZRTPHashAlgorithm, ZRTPCipherAlgorithm, ZRTPAuthTag, ZRTPKeyAgreement

◆ onCalltransferSucceeded:

- (void) onCalltransferSucceeded: (id< ZDKCall >)  call
optional

Succesuful call transfer event.

The event notify upon the call transfer has succeeded

Parameters
[in]callThe call which was transfered
See also
ZDKCall, onCallTransferStarted(), onCallTransferSucceeded()

◆ onVideoCameraChanged:

- (void) onVideoCameraChanged: (id< ZDKCall >)  call
optional

Video camera changed.

The Video cameras changed.

Parameters
[in]callThe video call
See also
ZDKCall

◆ onVideoFormatSelected:dir:width:height:fps:

- (void) onVideoFormatSelected: (id< ZDKCall >)  call
dir: (ZDKOriginType)  dir
width: (int)  width
height: (int)  height
fps: (float)  fps 
optional

Video format selected.

Parameters
[in]callThe call for which the video format was selected
[in]dirThe direction
[in]widthWidth in pixels
[in]heightHeight in pixels
[in]fpsFrames per seconds
See also
ZDKCall, OriginType

◆ onVideoOffered:

- (void) onVideoOffered: (id< ZDKCall >)  call
optional

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
[in]callThe call
See also
ZDKCall

◆ onVideoStarted:origin:

- (void) onVideoStarted: (id< ZDKCall >)  call
origin: (ZDKOriginType)  origin 
optional

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
[in]callThe video call
[in]originThe call initiator type (incoming, outgoing)
See also
ZDKCall, OriginType

◆ onVideoStopped:origin:

- (void) onVideoStopped: (id< ZDKCall >)  call
origin: (ZDKOriginType)  origin 
optional

Video stopped.

The Video has stopped.

Parameters
[in]callThe video call
[in]originThe call initiator type (incoming, outgoing)
See also
ZDKCall, OriginType

The documentation for this protocol was generated from the following file: