Skip to main content

1-to-1 call

This page describes the current public 1-to-1 calling capabilities in Nexconn Call SDK for iOS.

Key types​

TypeDescription
NCCallEngineCall entry point. Starts, accepts, and ends calls, controls devices, and queries call logs.
NCCallSessionCurrent call session object. Includes callId, callerUserId, inviterUserId, callType, mediaType, remoteParticipants, callState, and related fields.
NCCallUserParticipant state object. Includes userId, userState, isCameraEnabled, and isMicrophoneEnabled.
NCCallParams.hParameter objects for initialize:, startCall:, acceptCall:, endCall:, and other engine APIs (NCCallInitParams, NCCallStartCallParams, …).
NCCallEventHandlerHandler for incoming calls, connected calls, ended calls, participant state changes, server start time, and call logs. Callbacks receive NCCall*Event objects (see NCCallEventModels.h).
NCCallAPIResultHandlerAsynchronous API results. Each callback receives a NCCall*Result object whose code is an NCCallCode (see NCCallAPIResultModels.h).

Add handlers​

Objective C
NCCallEngine *engine = [NCCallEngine getInstance];
[engine setCallEventHandler:self];
[engine setAPIResultHandler:self];

If you need quality metrics, also set:

Objective C
[engine setConnectionQualityHandler:self];

Read the current session​

Use getCurrentCallSession to fetch the active session snapshot. The method returns nil when no call is active.

Objective C
NCCallSession *session = [[NCCallEngine getInstance] getCurrentCallSession];

Set video views​

Use NCCallLocalVideoView for the local preview and NCCallRemoteVideoView for the remote stream:

Objective C
NCCallLocalVideoView *localView = [NCCallLocalVideoView new];
localView.userId = self.currentUserId;
localView.renderMode = NCCallRenderModeAspectFit;

NCCallRemoteVideoView *remoteView = [NCCallRemoteVideoView new];
remoteView.userId = self.remoteUserId;
remoteView.renderMode = NCCallRenderModeAspectFit;
remoteView.enableLowResolutionStream = NO;

NCCallEngine *engine = [NCCallEngine getInstance];
[engine setLocalVideoView:localView];
[engine setRemoteVideoView:@[ remoteView ]];

If you no longer need to show one or more remote users' video, pass their user IDs in an array (empty array or nil does nothing):

Objective C
[[NCCallEngine getInstance] removeVideoView:@[ self.remoteUserId ]];

Start a 1-to-1 call​

For a 1-to-1 call, callType must be NCCallTypeSingle, and calleeIds must contain exactly one remote user.

Objective C
NCCallStartCallParams *params =
    [[NCCallStartCallParams alloc] initWithCalleeIds:@[ self.remoteUserId ]
                                            callType:NCCallTypeSingle
                                           mediaType:NCCallMediaTypeAudioVideo];
[[NCCallEngine getInstance] startCall:params];

If you need to pass push fields or business extra, set properties on NCCallStartCallParams after initialization:

Objective C
NCCallPushConfig *pushConfig = [NCCallPushConfig new];
pushConfig.pushTitle = @"New call invitation";
pushConfig.pushContent = @"Please answer";

NCCallStartCallParams *params =
    [[NCCallStartCallParams alloc] initWithCalleeIds:@[ self.remoteUserId ]
                                            callType:NCCallTypeSingle
                                           mediaType:NCCallMediaTypeAudioVideo];
params.pushConfig = pushConfig;
params.extra = @"business-extra";

[[NCCallEngine getInstance] startCall:params];

Async completion is reported on NCCallAPIResultHandler via onStartCall: with an NCCallStartCallResult (result.code, result.callId, result.busyLineUserList).

Receive and accept an incoming call​

The callee receives the incoming call through onCallReceived::

Objective C
- (void)onCallReceived:(NCCallReceivedEvent *)event {
    NCCallAcceptCallParams *accept =
        [[NCCallAcceptCallParams alloc] initWithCallId:event.session.callId];
    [[NCCallEngine getInstance] acceptCall:accept];
}

Use event.extra for the caller’s opaque payload. Configure push on the caller side via NCCallStartCallParams.pushConfig when starting the call.

End the call​

Objective C
NCCallSession *session = [[NCCallEngine getInstance] getCurrentCallSession];
if (session == nil) {
    return;
}

NCCallEndCallParams *params = [[NCCallEndCallParams alloc] initWithCallId:session.callId];
params.pushConfig = nil;
[[NCCallEngine getInstance] endCall:params];

The asynchronous result is returned through onEndCall: (NCCallEndCallResult). The call end event is onCallEnded: (NCCallEndedEvent with event.session and event.reason).

Control devices during the call​

Microphone and speaker​

Objective C
NCCallEngine *engine = [NCCallEngine getInstance];

engine.enableMicrophone = YES;
engine.enableSpeaker = YES;

Camera​

Objective C
[[NCCallEngine getInstance] enableCamera:YES];
[[NCCallEngine getInstance] switchCamera];

The current header comments indicate that the camera is enabled by default after a video call is connected.

Camera and switch results are reported on NCCallAPIResultHandler via onEnableCamera: (NCCallEnableCameraResult) and onSwitchCamera: (NCCallSwitchCameraResult).

Video configuration​

Before the call is connected, configure capture parameters through setVideoConfig::

Objective C
NCCallVideoConfig *videoConfig = [NCCallVideoConfig new];
videoConfig.resolution = NCCallVideoResolution640X480;
videoConfig.frameRate = NCCallVideoFrameRate15;
videoConfig.minBitrate = 200;
videoConfig.maxBitrate = 900;

[[NCCallEngine getInstance] setVideoConfig:videoConfig];

The public umbrella header does not expose a separate setAudioConfig: API.

Switch media type​

1-to-1 calls support switching between audio and audio-video modes.

Send a change request​

Objective C
NCCallRequestChangeMediaTypeParams *req =
    [[NCCallRequestChangeMediaTypeParams alloc] initWithMediaType:NCCallMediaTypeAudioVideo];
[[NCCallEngine getInstance] requestChangeMediaType:req];

The async API result is onRequestChangeMediaType: (NCCallRequestChangeMediaTypeResult).

Receive and respond to a request​

Objective C
- (void)onMediaTypeChangeRequestReceived:(NCCallMediaTypeChangeRequestReceivedEvent *)event {
    NCCallReplyChangeMediaTypeParams *reply =
        [[NCCallReplyChangeMediaTypeParams alloc] initWithTransactionId:event.transactionId
                                                                isAgreed:YES];
    [[NCCallEngine getInstance] replyChangeMediaType:reply];
}

The async API results for the response flow are onReplyChangeMediaType: (NCCallReplyChangeMediaTypeResult) and onCancelChangeMediaType: (NCCallCancelChangeMediaTypeResult). The final outcome event is onMediaTypeChangeResultReceived: (NCCallMediaTypeChangeResultReceivedEvent).

To cancel a pending request:

Objective C
NCCallCancelChangeMediaTypeParams *cancel =
    [[NCCallCancelChangeMediaTypeParams alloc] initWithTransactionId:transactionId];
[[NCCallEngine getInstance] cancelChangeMediaType:cancel];

Call logs​

Call log callbacks after the call ends​

  • onLocalCallLogReceived: — parameter type NCCallLocalCallLogReceivedEvent (event.callLog).
  • onServerCallLogReceived: — parameter type NCCallServerCallLogReceivedEvent (event.callLog).
  • onStartTimeReceived: — parameter type NCCallStartTimeReceivedEvent. Server-synchronized call start time for billing or UI; read event.startTime (milliseconds, same semantics as the underlying server callback).

Query history with pagination​

Objective C
NCCallGetHistoryCallLogsParams *query =
    [[NCCallGetHistoryCallLogsParams alloc] initWithStartTime:-1
                                                        count:20
                                                        order:NCCallLogOrderDescending];
[[NCCallEngine getInstance] getHistoryCallLogs:query];

The result is onGetHistoryCallLogs: (NCCallGetHistoryCallLogsResult). Read pagination from result.callLogInfo: callLogs, hasMore, and syncTime. When hasMore is YES, pass result.callLogInfo.syncTime as the startTime argument of the next NCCallGetHistoryCallLogsParams.

Sort order uses NCCallLogOrder:

  • NCCallLogOrderAscending: older records first
  • NCCallLogOrderDescending: newer records first

Delete logs​

Objective C
NCCallDeleteCallLogsForMeParams *del =
    [[NCCallDeleteCallLogsForMeParams alloc] initWithCallIds:@[ callId ]];
[[NCCallEngine getInstance] deleteCallLogsForMe:del];

[[NCCallEngine getInstance] deleteAllCallLogsForMe];

Results are delivered through onDeleteCallLogsForMe: (NCCallDeleteCallLogsForMeResult) and onDeleteAllCallLogsForMe: (NCCallDeleteAllCallLogsForMeResult).

Ongoing calls​

Objective C
[[NCCallEngine getInstance] getOngoingCallLogs];

Results are delivered through onGetOngoingCallLogs: (NCCallGetOngoingCallLogsResult).

Quality metrics and capture handlers​

If you need volume or network quality metrics, set NCCallConnectionQualityHandler. The protocol currently exposes:

  • onAudioVolumeChanged: — NSDictionary<NSString *, NSNumber *> * keyed by user ID, volume range 0 to 10
  • onReceiveQualityChanged: — NSDictionary<NSString *, NCCallQualityStats *> * keyed by remote user ID
  • onSendQualityChanged: — local NCCallQualityStats

If you need local captured audio and video frames, set:

  • setVideoFrameCaptureHandler:
  • setAudioFrameCaptureHandler:
Last updated on