API iOS English 150721

CONFIDENTIAL
FreePP Mobile SDK on iOS

API Document
version 1.0
www.browan.com
BROWAN COMMUNICATIONS
INCORPORTATION
April 22, 2016
0
Public
Table of Contents
Table of Contents..................................................................................................1
Chapter 1: Introduction...............................................................................................3
1.1 Purpose........................................................................................................3
1.2 Scope...........................................................................................................3
1.3 Overview......................................................................................................3
1.4 Definitions and Acronyms..............................................................................4
Chapter 2: Design Considerations................................................................................5
Chapter 3: Architecture................................................................................................8
3.1 Overview......................................................................................................8
3.2 Modules.....................................................................................................10
3.2.1 Basic Function Modules.....................................................................10
3.2.2 Audio and Video Module....................................................................11
3.3 SDK Package..............................................................................................12

Chapter 4: SDK API..................................................................................................16
4.1 Message API Interface.................................................................................16
4.1.1 APP/User Management......................................................................16
4.1.2 Message Sending and Receiving...........................................................18
4.1.3 File Sending and Receiving.................................................................22
4.1.4 Group Management...........................................................................23
4.2 Call API Interface.......................................................................................24

4.2.1 Call Control Interface........................................................................24
4.2.2 State Notification Interface..................................................................26
4.2.3 Media I/O Interface...........................................................................27
4.2.4 Call Information Query Interface.........................................................28
4.2.5 Video Conference Control Interface.......................................................29
4.2.6 Video Call Control Interface................................................................29
4.3 Basic Flow of Message Interface..................................................................30

4.3.1 Startup Flow....................................................................................30
4.3.2 One-to-one message communication flow...............................................30
4.3.2 Communication Flow of Group Message................................................31
4.4 Basic Flow of Call Interface.........................................................................31

4.4.2 Overall Call Flow.............................................................................32
4.4.3 Basic Flow-Caller Initiates Call............................................................32
4.4.4 Basic Flow-Callee Answers the Call......................................................33
4.4.5 Basic Flow-Answer and Hang Up.........................................................33
4.4.6 Callee Rejects The Call......................................................................34
4.4.7 Call Hold and Resume.......................................................................34
4.4.8 Initiate Multi-party Call......................................................................35
4.4.9 Finish Multi-Party Call.......................................................................35
4.4.10 Video Conference Control Mode.........................................................36
FreePP Mobile SDK on iOS API Document- 1 -
Public
4.4.11 Video Conference Subscription...........................................................36
4.4.12 One-way Video Control Mode............................................................38
4.5 Error Code Table.........................................................................................38

4.6 Definition of enumeration related to message SDK........................................39
4.7 Definition of enumeration related to call SDK...............................................39
4.8 Multi-language KEY filed related to Push notification...................................39
Public
Introduction
1.1 Purpose
It mainly introduces the architecture and basic design considerations of FreePP Mobile
SDK, and describes functions, call method and workflow of SDK API interface in details.
1.2 Scope
It is suitable for FreePP Mobile SDK developers and software testing engineer to read
and discuss.
1.3 Overview
FreePP Mobile SDK (iOS version) is developed with Objective-C language and iOS
SDK 7.1 class library under XCode 5.1 version, and is compatible with iOS 5.0/6.0/7.0
system and higher.
Through FreePP Mobile SDK, third-party application programmer (APP for short) can
realize authentication, communication number allocation and query, instant message, A/V
(audio and video) communication, and other functions, including:
Binding and query of APP account with the unified communication number inside
instant communication system (communication no. for short)
One-to-one instant message, including text or file message
Instant group message
Group member control, including: invite, mute, join and leave
One-to-one audio/video call
Audio/video conference (including: client or server audio mixing)
Real-time push to talk
Besides, for different operating systems and CPU processors, SDK adopts hardware
acceleration optimization algorithm in modules with high computational complexity, like
A/V compression codec, and compiles the algorithm for armv7 and arm64 processors
respectively to ensure smooth user experience.
The content of this document mainly includes: SDK architecture, SDK internal function
Public
modules, SDK design considerations, SDK package, API interface design and workflow.
1.4 Definitions and Acronyms

NS
CS
FXS
FXO
APNS
FPS
MEC
Notification Server
Configuration Server
Foreign Exchange Subscriber
Foreign Exchange Office
Apple Push Notification Service
FreePP Push Notification Service
Message Exchange Center
Public
Design Considerations
To ensure the interoperability, compatibility and openness of SDK, support third-party
accounts in various forms (e.g. nickname, Email address, phone no. or APP account, etc.),
hide the implementation details of underlying communication system, and reduce APP
development complexity, SDK follows the basic principles below in design:
Unified User Identifier
Within the system, SDK identifies each user uniquely with its communication no., APP
can associate a specific APP account with the allocated communication no. by binding
method. In this way, for different forms of APP accounts, a unified user identification
management and control mechanism inside communication system can be realized by
communication no., to ensure interconnection and interoperability among different APPs.
Besides, when APP calls SDK API interface, communication no. should be used as target
parameter, but for end-user, it is transparent and invisible, APP can get corresponding
communication no. of each APP account, through SDK query account interface.
The relation between APP account and communication no. is shown below,
Note: SDK can support intercommunication between different forms of APP accounts
through unified user identification, i.e., communication no.
Unified Message Format
In SDK system, MIME coding format is unified to define various types of instant
message, the basic format is type/subtype, e.g.:
Message type
MIME code
Text string
text/plain
Public
Image file
image/{png,jpeg...}
Audio file
audio/{amr,3gp,mp3}
Video file
video/{mpeg ,mp4,avi,asf,mov}
Other types of file
application/{pdf ,msword,octet-stream...}
JSON string
application/json
Note: types of instant message are not limited to the definition mentioned above, APP
can expand new MIME type and corresponding function to suit its own needs, while SDK
can ensure transparent transmission of MIME type when transmitting message.
Unified Character Coding Format
To be compatible with strings in different languages and avoid messy code between
different languages or platforms, SDK only adopts UTF-8 code inside the system.
Both input parameters and return values of SDK API interface adopt UTF-8 coding
format, SDK developer needs to complete conversion of related string coding formats in
upper layer. Meanwhile, SDK also provides auxiliary interface function for interconversion
between UNICODE string and UTF-8 string.
Asynchronous Operations of Interface
To reduce the operation coupling between APP and SDK, and improve program
efficiency and responsiveness, all interfaces involving message and conversation functions
(usually need to assess network and take a long time) handle APPs call requests with nonblocking mode, i.e. APP can return and continue to run immediately after calling SDK API
interface, while SDK keeps processing in background without blocking the APP, and return
results to APP asynchronously by corresponding callback function, therefore, APP doesnt
need to wait, otherwise may cause main thread blocking, making App become unresponsive.
Besides, message/call request ID is adopted between APP and SDK to match
asynchronous request and response. E.g.:
When APP sends message, SDK interface will return the message ID to APP
immediately, meanwhile transmitting message in background with multithread technology;
After sending message successfully, SDK will notify APP by callback function, and
Public
specify the successfully sent message ID in callback function;

APP can identify specific message content through message ID and update message
transmission state
Each asynchronous operation interface has corresponding callback function. APP should
implement these functions, and transmit their entries through SDK interface to SDK for call.
Note: APP cant perform long running task in callback function interface,
otherwise may block SDK to perform other callback task. Therefore, APP can execute
asynchronous processing notified by SDK, according to mechanism of operating system
itself, when designing callback functions.
Suggestions:
1) In iOS system, it can transfer the processing of SDKs notification to other nonmain thread in callback function with GCD technology, to perform asynchronously.
In Android system, it can broadcast the content of SDKs notification to
corresponding Activity to process in callback function, with Broadcast technology.
Simplify Communication Service
For A/V communication, SDK provides complete call control functions with call state
machine as the core for upper-layer APP, including: initiate, answer/reject, hang up, etc. and
hide the implementation details of transmission path of underlying network, session control
signal, call setup flow and A/V information processing etc, to reduce complexity of upperlayer APP software development.
Public
Architecture
3.1 Overview
FreePP Mobile SDK has two main functions: user identity authentication/instant
message and A/V call, of which the former one is SDKs basic function, as well as the
infrastructure for client to access the instant communication system.
Basic architecture of user identity authentication/instant message function is shown
below,
In the above figure, there are following layers in SDK, by call relations between function
blocks:
Interface layer: mask the implementation details inside middleware, and provide
easy-to-use services of user identity authentication and instant message for App.
Service layer: provide user identity management and control, and workflow of
various instant communication services.
Communication layer: provide interactive operation between client and server, and
ensure that client can be notified in time.
Public
Protocol layer: responsible for encapsulation and parsing of protocol message.
Based on the above functions, A/V communication also provides one-to-one video call
and multi-party A/V conference functions.
Basic architecture of SDKs A/V function is shown below,
In the above figure, there are following layers inside SDK, by call relations between
function blocks:
Interface layer: hide the implementation details inside middleware, and provide
easy-to-use A/V communication services for APP.
Call control and information processing layer: provide workflow of call setup,
maintenance, and release, and A/V stream processing and network adaptive
function.
Transport protocol layer: responsible for encapsulation and parsing of

communication protocol message.
Moreover, call state machine is the core of A/V call module, mainly responsible for
recording and managing the current state of each call, and makes corresponding processing
action according to user operation or request. SDK call state machine implements call state
control according to following state transition diagram (Figure 3)
Public
In the above figure, IDLE refers to call standby, i.e. SDK returns to this state before
initiating or finishing a call; INITIATE refers to call initiating state, i.e. both parties of a
call are in this state after initiating call and before answering; HANGUP refers to call
finishing state, i.e. both parties of a call are in this state if either party hangs up first. Besides,
once in HANGUP state, SDK will transfer to IDLE state automatically.
When using call modules, APP needs to display corresponding user interface
according to current call state or SDK call state notification, and perform
corresponding call control operations.
3.2 Modules
3.2.1 Basic Function Modules
Basic function modules include user identity authentication/instant message function.
Layer
Module
Service layer
Authentication APP authentication and SDK initialization

and authorization FreePP ID application, login and assigning server
APP account query
Instant
Description
Message transfer state machine
Public
Communication
layer
Protocol layer
message
Message sending and receiving workflow
File transfer
File transfer state machine

File sending and receiving workflow
Local storage
Related information on user identity

Server settings
Message logging to be processed
Group
management
Create, join or leave group

Query group information
Long
connection
Heartbeat service
Receiving of push notification
Web service
HTTP request and response

Asynchronous operation request queue
MQTT/APNS Publishing/subscription service

Push notification
HTTP
Web Service
3.2.2 Audio and Video Module

Layer
Module
Call control Call state machine

and
information
Push notification
processing
layer
Call
capacity
negotiation
and
quality monitoring
Description
Record call state

Control call processing
Backward call signal transmission

Call reject signal transmission
Real-time monitoring of circuit transmission

quality, adaptive control of A/V encoder
Negotiate call capacities and parameters, e.g.: video
capacity, encryption capacity and VAD capacity
Video engine
Video capture and compression encoding

Adaptive control of video coding rate
Audio engine
Audio capture and compression encoding

Audio conference mixer
Protocol layer MQTT/APNS
Long connection and Push notification
Public
HTTP
IAX2/UDP
Session control and streaming media transmission
3.3 SDK Package

FreePP Mobile SDK libraries can be divided into following versions by functions
combination:
Basic version: basic functions and instant message function;
Call version: basic version + A/V call function;
Enhanced version: call version + audio push-to-talk function;
Relations between above SDK libraries and API interfaces are shown in following table
(characters in blue are for Android, and that in black are for iOS and cross platform):
SDK
version
Basic
version
Reference relation
Dependency relation
Include/Import (.a/.so)
FreePPSDK.h/jar
libFreePPSDKBasic.a/so
Function
1)Basic
functions
(initialization and user
management);
2)Instant message;
Call
FreePPSDK.h/jar
libFreePPSDKStd.a/so
1)Basic
functions
version
FreePPSDKStream. or
h/jar
libFreePPSDKStdx.a/so
management);
2)Instant message;
3)One-to-one
video
call;
4)Multi-party
A/V
conference;
Enhanced FreePPSDK.h/jar
libFreePPSDKPro.a/so
1)Basic
functions
version
FreePPSDKStream. or
h/jar
libFreePPSDKProx.a/so
management);
FreePPSDKPTT.h/ja
2)Instant message;
r
3)One-to-one
video
call;
4)A/V conference;
5)Audio intercom;
Note: call version and enhanced version can generate two library files, respectively
Public
corresponding to two solutions--client audio mixing and server audio mixing (the
one with x behind is server audio mixing). When using SDK, developer can
choose either of the two library files as required by service.
When the third-party APP uses SDK, the following Framework and Library need to be
linked to APP project:
If only use basic version SDK, add framework and Library as shown below to
project,
If use call version SDK, be sure to add Library (as shown below) to project,
Call version SDK needs specific compilation options, which are shown below,
Public
When third party references call SDK library files, be sure to add macro definition
FREEPP_SDK_STREAM_API to use API method in SDK, as shown below,
Public
When the third-party references call version SDK library file for conference
function, be sure to add macro definition FREEPP_SDK_STREAM_CONF_API
to use the relevant conference API method in SDK, as shown below:
Public
SDK API
FreePP Mobile SDK mainly has two types of API interfaces: message API and call API.
In general, API interfaces in SDK are all synchronous (blocking) interfaces; asynchronous
(non-blocking) interfaces will be specified in special description.
Moreover, any interface marked with CALLBACK is callback interface, and APP needs
to realize such interface function in delegate class, meanwhile avoid performing the long
running tasks, to prevent blocking the worker thread of SDK.
4.1 Message API Interface

4.1.1 APP/User Management
Interface name
Parameters
Return values
Notice
+ (BOOL)initialize
appKey
Boolean-client
Initialize and start SDK
String, Apps authorization code,
initialization result, if
client module.
to identify third-party App.
succeed, return YES,
delegate
if fail, return NO.
Any pointer
type,
third-party
APPs delegate.
+(NSString
appUserAccount
String-FreePP
ID
Verify the legitimacy of
*)bindAppAccount
String, App account (may use
bound with this APP
App, and allocate or bind
phone no., Email or other forms
account
FreePP ID, and log in
of accounts).
If
mustAuth
NULL,
Boolean value, if it is YES, SDK
illegitimate,
should
binding
perform
connect
remote
to
server
to
identification,
otherwise verify app account only

in local database. In this way, APP
decides on its own whether to
kick out each other, or log in
quickly.
callerName
return
value
is
FreePP system.
AppKey
is
If
or
callerNumber exist, they
For
will be stored in SDK,
fails.
callerName
details, refer to error
and
carried
code table.
outbound call.
out
and
in
Public
String, users local nickname,
mainly used to set callers name
in outbound call.
callerNumber
String, users phone no., mainly
used to set callers phone no. in
outbound call, standard E.164
format.
+
(NSDictionary
appAccountArray
String dictionary-list of
*)queryFreePPIDB
String array, App account list of FreePP
yAppAccount
target user.
ID
corresponding
account
(Hash
key=value).
If
Query the FreePP ID of
and
specific user with APP
App
account.
table:
error
occurs, return NULL; if

multiple
accounts
repeat, only one key

exists in Hash table.
+
(NSDictionary
freePPIDArray
String dictionary-list of
*)queryAppAccou
String array, FreePP ID list of FreePP
ntByFreePPID
target user.
ID
corresponding
account
(Hash
and
specific user with APP
App
account.
table:
key=value).
If
occurs
peer-party
or
Query the FreePP ID of
error
doesnt install FreePP,

return
multiple
NULL;
if
accounts
repeat, only one key

exists in Hash table.
+
name
Integer, return 0-setup
Set
SDKs
(int)setParameter
String, parameter name.
succeeds, for error,
working parameters.
value
refer to error code
Note:
String, parameter value.
table.
supported
for
please
internal
currently
parameters,
refer
to
Parameter
Configuration Table.
+
(NSString
*)getParameter
name
String-parameter
Get
SDKs
String, parameter name.
value. If it doesnt
parameters.
internal
exist, return NULL.

+
No
Integer, if no error
Get the error code of the
(int)getLastErrorC
exists, return 0. (for
Last
ode
error code, refer to
invocation.
failed
interface
Public
section 4.4 error code
Note: this interface is
table)
thread -safe i.e. SDK

ensure separate storage
of last errors in different
threads, Once call this
interface, SDK will clear
error code of current
thread.
No
Integer, if no error
Log out and reset current
(int)logoutAppAcc
occurs, return 0.
account.
ount
Error
code:
FreePP
-15:
SDK,
uninitialized.
Note: SDK temporarily

dont
delete
local
database, for possible

follow-up
login
by
reusing account binding.

+
eventType: integer, event type,
No
Report event information
(void)onSystemEve
including:
corresponding to current
nt
1=current user is kicked out;
account.
corresponding data is NULL;
1= current user is kicked
dataOjbect: corresponding data
out
object. It varies with different

event type, can be NULL.
Note1. Parameter configuration table of name in getParameter and setParameter interface:

Parameter name
Operation
Realization
Notice
requirement
Version
get
No
FreePP SDK version No.
Rootcs
get/set
Yes
FreePP SDK RootCS address, used

for server portal address
max_group_member
get
No
Max. number of group members
video_orientation
get/set
No
Video
display
orientation:
(vertical) or 0 (horizontal), default

1-vertical
call_timeout
get/set
No
Call timeout (s), default 45s, range:

1~45s
4.1.2 Message Sending and Receiving

Interface name
Parameter
Return value
Notice
+ (NSString *)sendMessage
dstFreePPID
String-
Send one-to-one multimedia
String, FreePP ID of target user.
message
ID.
message to specific user.
Public
mimeType
String,
type
If
of
multimedia
error
Note:
if
messageID
occurs, return
parameter has value, it will
message, e.g.: text/plain
NULL.
be judged whether valid.
textContent
Note:
String, content of text message,
message
format
by
format:
mimeType. If in text/plain, it is
FreePP
plain
Unix
corresponding
application/json, it is JSON
timestamp
and return this Message ID;
string.
(s)-two
filePath
random
String, local file path of binary
digits
distinguishes
string;
if
in
ID
this
MessageID
generates before FreePP

SDK, consider it valid.
ID-
If
valid,
re-send
its
message,
If invalid, directly return
NULL.
Note: this is asynchronous
file.
String,
If
interface, its running results

message
ID
for
will be returned to APP
retransmission
through
corresponding
callback interface.
+
(NSString
*)sendGroupMessage
dstGroupID
String,
unique
identifier
of
Send
String-
multimedia
target group.
message
mimeType
If
String,
type
of
multimedia
ID.
error
one-to-many
message
to
specific group.
Note:
if
messageID
occurs, return
parameter has value, it will
message
NULL.
be judged whether valid. If
textContent
Note:
valid, resend corresponding
String, content of text message,
message
format
format:
distinguishes
by
ID
message of this message ID.

Note: this is asynchronous
mimeType.
FreePP
filePath
Unix
will be returned to APP
String, local file path of binary
timestamp
through
file.
(s)-two
callback interface.
String,
message
ID
for
ID-

corresponding
random
retransmission.
digits
CALLBACK
messageID
No
String, unique message send ID.
of
(void)onSendMessageEvent
sendResult
message send state, it is
Integer, results of message send.
delegate method interface.
0=succeed, if fail, refer to error
App updates message send
code table.
state through this interface.
Callback response interface
For
one-to-one
both
text
and
and
group
file
messages, this callback is

used to show send result. For
file
message,
Public
onUploadMessageAttachmen
tProgressEvent will be sent
first for callback response.
CALLBACK
messageID
String, unique ID of message to
message download state, it is
(void)onDownloadMessage
be downloaded
AttachmentEvent
downloadResult
App
Integer,
No
message
download
Callback
interface
updates
of
message
download state through this
result. 0=succeed, if fail, refer
interface
to error code table.

CALLBACK
msgType
No
Integer,
(void)onReceiveMessageEv
including:
function
ent
One-to-one/group message
Join group notification
App
Leave group notification
message
type
Message
of
message,
receiving
One-to-one or group message

receiving delegate or callback
state
interface,
unifies
to
it
is
receive
through
this
callback function.
notification
msgObject
Message object, defined by
each platform, it varies with
different message type. (Note:
refer
to
message
object
comparison table.)
+ (void)clearMessage
messageIDArray
String
array,
No
identifier
of
Clear message logging stored

inside SDK.
released message. If it is null,
After App receives or sends
clear all caches by default.
message
successfully,
this
function should be called to

clear cached records in SDK.
+
userInfo
(void)receivedPushNotifica
Dictionary
tionInfo
system
No
type,
Push
received
notification,
Receive and process message

notified by APNS and FreePP
Push Service.
including userInfo value of
(void)application:
delegate method of remote and
(UIApplication *)application
local notifications.
didReceiveRemoteNotificatio
n:(NSDictionary
*)userInfo
NS_AVAILABLE_IOS(3_0);
-
(void)application:
(UIApplication *)application
didReceiveLocalNotification:
Public
(UILocalNotification
*)notification
NS_AVAILABLE_IOS(4_0);
Call in the above system
delegate method, and pass in
userInfo
or
notification.userInfo to this
interface as parameters.
+ (int)reportMessageStatus
dstFreePPID
Integer-
Send notification of message
String, FreePP ID of target user.
whether send
send state, including message
messageID
successfully.
delivered and read.
String, unique ID of message.
Note: cant ensure 100%
already success of this notification of

Integer, notification type of added
to message receiving state.
message
receiving
state, send queue
including:
and sent ;
status
0-
1 = Delivered
-1-no
2 = Read
network,
unable
to
send.
Note1: Message Objects Comparison Table is shown below,

Message
type
Attribute
Object name (class name)
(int)
0
NSString * mimeType
NSString * srcFreePPID
NSString * dstFreePPID
NSString * textContent
NSString * messageID
NSString * filePath
int createTime
int sessionType
GroupInfo * freeppGroup
NSString * groupID
NSString * groupName
NSString * invitorFreePPID
NSArray * arrayJoinFreePPID
int createTime
NSString * groupID
NSArray * arrayLeaveFreePPID
int leaveReason
int createTime
Message
JoinGroupMessage
LeaveGroupMessage
Public
3(message
receiving
state
notification)
NSString * messageID
int messageStatus
int createTime
MessageStatus
Description of each attribute is shown below:
mimeType: string, multimedia message format;
srcFreePPID: string, FreePP ID of sender;
dstFreePPID: string, FreePP ID of receiver, for group chat, it is Group ID;
textContent: string, content of context message;
messageID: string, unique ID of message;
filePath: string, used inside SDK, file path when sending file, invalid when receiving
message;
sessionType: integer, session type of message (0 single chat, 1 group chat);
createTime: integer, time of message generation, Unix timestamp, unit: s;
freeppGroup: GroupInfo object pointer, group message object, valid for group chat;
groupID: string, unique ID of group;
groupName: string, name of group;
invitorFreePPID: string, FreePP ID of inviter;
arrayJoinFreePPID: string array, FreePP ID list of invitee;
arrayLeaveFreePPID: string array, FreePP ID list of leaving group chat;
leaveReason: integer, reason for leaving group (=0 kicked out; =1 leave).
messageStatus: integer, message send notification type, including: 1=delivered,

2=read.
4.1.3 File Sending and Receiving

Interface name
Parameter
Return value
Notice
messageID
Integer-0: added to
Download
(int)downloadMess
String, unique ID of message
download
(multimedia file) of specific
ageAttachment
required to be downloaded.
for
isThumbnail
code, refer to error
Note: First, App gets message
Integer, whether to download
code table.
notification
thumbnail, 0-download original
other
queue,
error
attachment
message.
OnReceivedMessageevent
from
Public
image( Note: invalid for non-
interface,
image type).
downloadMessageAttachment
filePath
interface
String,
local
file
path
of
then
to
calls
download
attachment of the message.
downloaded file, including file
Note:
name.

will
this is asynchronous
be
returned
to
APP
through corresponding callback

response interface.
+
messageID
No
(void)onDownload
String, unique ID of message;
download
MessageAttachme
downloadProgress
ntProgressEvent
Integer,
App can update files progress
percentage of current
files download progress
Callback
interface
of
progress,
file
it
is
indication by this callback

function.
messageID: string, unique ID of
No
(void)onUploadMe
message;
upload progress, it is delegate
ssageAttachmentP
uploadProgress
method interface.
rogressEvent
Integer,
App can update files progress
percentage of current
files upload progress.
Callback
interface
of
file
indication by this callback

function.
Note: file upload initiates from
sendMessage
or
sendGroupMessage interface.
4.1.4 Group Management

Interface name
Parameter
Return value
Notice
groupName
String-group ID allocated by server.
Create
String, topic of creating
If error occurs, return NULL.
group.
Integer-result of join group.
Invite
(NSString
*)createGroupChat
new
the group.
memberArray
String array, FreePP ID
list of group member.
+ (int)joinGroupChat
groupID
String, group ID returned
join
when creating group.
group.
memberArray
The
client
array of invited group
receive
user to
specific
invited
will
Public
member.
notification
by
message.
+
groupID
Integer-result of leaving group.
Leave
specific
(int)leaveGroupChat
group, or kick
when creating group.
out specific user
memberArray
of group.
The kicked out
array of leaved group
client
member.
receive
will
notification
by
message.
+
groupID
Group object-defined by platform.
Get information
(FreePPGroupObject
Note: group object (
of
*)getGroupChatInfo
when creating group, or
contains following attributes:
got when receiving group
GroupInfo)
group
groupID: string, unique ID of
group;
message.
ownerFreePPID: string, FreePP

ID of group creator;
arrayMemberFreePPID: string
array,
FreePP
ID
of
group
member;
createTime: integer, time when

creating group;
groupName: string, group name

or topic;
4.2 Call API Interface

4.2.1 Call Control Interface
Interface name
Parameter
Return value
Notice
dstID: string, FreePP ID of the
String-calls
Initiate
called user.
session
audio or video call.
media: integer, media type of
(call-id).
(NSString
*)makeCall
identifier
free
FreePP
call.
1= Audio call
2= Video call
5=Full duplex audio channel for
push-to-talk
+
(NSString
phone: string, phone no. of the
String-calls
Initiate saving outbound
specific
Public
*)makeOutbound
callee.
session
Call
viaOutbound
(call-id).
identifier
audio call.
via: Outbound route code.

+
(NSString
*)joinConference
dstIDs:
FreePP
ID
of
participants.
media:
String-session
identifier
integer,
conferences
media type.
server: string,
Initiate a conference call.

of
The method can be called
conference
repeatedly,
(conference-id).
various participants to the
room ID of
for
inviting
same conference.
server audio mixing conference
Note: server is valid only
Phones: string array, phone no.
when media type equal to :
of participants.
3= Audio conference call;
via: Outbound route code.
Or
4=video
conference
call.
+
(int)
getNetworkQualit
callId: string, session identifier
Integer-network
Get
of specific call.
quality score value
transmission
[0, 6].
call.
Integer-whether
Finish specific call (both
score
of
network
quality
of
(reserve)
+
callId:
string, calls
session
(int)hangupCall
identifier (returned by makeCall
operate
caller and the called can
or onReceiveCallEvent)
successfully.
call this function to hang

up themselves).
+(int)
conferenceId:
hangupConferen
ce
string, session
Integer-whether
Finish specific conference
identifier of conference call
operate
call (hang up everyone in
(returned by joinConference or
successfully.
conference room)
Integer-whether
The called user answers
operate
specific incoming call.
onReceiveCallEvent)
+ (int)answerCall
callId:
string, calls session
identifier
+ (int)holdCall
(returned
by
onReceivedCall)
successfully.
callId:
Integer-whether
One-way call: hold or
identifier.
operate
resume call.
hold: integer, hold (1) or resume
successfully.
(0) call.
+ (int)muteCall
callId: string, calls session
Integer-whether
One-way call: mute or
identifier or conferences room
operate
unmute microphone.
identifier.
successfully.
mute:integer, microphone mute

(1) or unmute (0).
+ (int)sendDTMF
callID:
Integer-whether
Send DTMF dial tone to
identifier
operate
the
digit: string, secondary dial
successfully.
answered call to complete
number to be sent.
peer
user
secondary dialing.
of
an
Public
interval for
sending multiple key digits,
unit: ms (Note: if send a
digit only, it can be set as 0).
time: integer,
mode: integer, DTMF signal

transmission mode
0: in-band dialing mode
1: out-band dialing mode
4.2.2 State Notification Interface

Interface name
Parameter
CALLBACK
callId:
identifier
(void)onReceiveCa
conference.
llEvent
callerId: string, FreePP ID
string,
of
session
call
Return value
Notice
No
Notify APP of receiving call
or
request from remote user.

Note:
1 If APP is in lock screen
of caller.
callerName:
state, SDK will pop up
string,
PUSH
nickname or phone no. of
notification
caller.
automatically;
media: integer, media type
2If APP is in running state,
of call request.
APP will decide to display
1= Audio call;
incoming
2= Video call;
notification
interface on its own.
3=Audio conference call;

4=Video conference call.
callType: integer, call type
of received notification.
1= Incoming call
2= Missed call
CALLBACK
callId:
string,
identifier
(void)onCallStateE
conference.
vent
state: integer, current call
of
session
call
or
state, can take following

values:
0 - IDLE
No
Notify APP of call state

changed.
In different call state, APP
should
display
different
prompts:
1) IDLENo
1 - INITIATE
2) NITIATE Calling (for
2 - ANSWER
caller) or connecting (for
3 - HOLD
callee)
Public
4 - HANGUP
3) ANSWER- Talking
reason: integer.
4) HOLD
When state is HANGUP,
5) HANGUP
identify reason for finishing

a call, including: user offline,
network
connection
unavailable, busying, etc;

When state is ANSWER,
identify way to go into
answer state, includes: 0answer;
1 - Resume call.
CALLBACK
conferenceId:
string,
Notify
conferences
(void)onConferenc
identifier.
eStateEvent
callId: string, calls session
APP
of
certain
session
No
participants state change in

conference.
identifier of participants.
should
calleeId: string, FreePP ID
display
different
of participants.
prompts:
state: integer, current call
1) INITIATE Calling (for
caller) or connecting (for
values:
callee)
1 - INITIATE
2) ANSWER
2 - ANSWER
3) HANGUP
3 - HANGUP
When state is HANGUP,
identify reason for finishing
a call, including: user offline,
network
connection
unavailable, busying, etc;

When state is ANSWER,
identify way to go into
answer state includes: 0answer;
1 - Resume call.
CALLBACK
-
(void)
calleeId: string, FreePP ID
Notify APP of remote video
of participant.
No
state change.
onRemoteVideoSta
state: integer, remote video
teEvent
should
values:
prompts:
0 - STOP
display
different
1) START Start remote
Public
1 - START
video sending
2) STOP Stop remote
video sending
4.2.3 Media I/O Interface

Interface name
Parameter
+ (int)setCamera
device:
integer,
device
Return value
Notice
Integer-whether
Set camera for current video call.
identifier, e.g.:
operate
0 - Rear camera
successfully.
1 - Front camera
-1 Close preview
+
device:
integer,
speaker
Integer-whether
(int)setAudioOutp
device identifier, e.g.:
operate
ut
0 - Receiver
successfully.
Set speaker device for call.
1 - Speaker
2
-Bluetooth
headset
connected currently
+
displayRemote:
(int)setVideoDispla
y
View
Integer-whether
Set window object to display video
object, window object to
operate
in video call.
display remote video (peer
successfully.
users image, select object

type by operating system).
displayPreview:
View
object, window object to

display near-end video (own
image).
+
ringbackFilePath:
(int)setRingbackTo
ne
string,
Integer-whether
Set ringback tone of outbound call.
audio path in Bundle of App
operate
Supported
layer or local file.
successfully.
pcm(16K) wav(pcm:8k,16k,32k,11
file
format:
025,22050,44100k,48k;pcma;pcmu)
4.2.4 Call Information Query Interface

Interface name
Parameter
Return value
Notice
No
Array- string list of
Get the list of callID for all calls currently
(NSArray
Public
*)getAllCallIDList
+
(FreePPCallInfo
*)getCallInfo
all callIDs.
ongoing ,includes call-in and call-out.
callId:
FreePPCallInfo
Get corresponding call object by CallID.
string,
object
FreePPCallInfo object contains following
session
information object.
identifier of
call
pointer-call
attributes:
callId: string, session identifier of call or
or
conference.
conference.
calleeId: string, FreePP ID of peer user.

calleeName: string, nickname or phone no. of
peer user.
mediaType: integer, media type of call request
(audio, video or conference).
callState: integer, current call state can take
following values:
0 - IDLE
1 - INITIATE
2 - ANSWER
3 - HOLD
4 - HANGUP
4.2.5 Video Conference Control Interface

Interface name
Parameter
Return
Notice
value
+ (int)
pubID: string, FreePP ID
Integer-
Subscribe
conference video for
subConferenceVideo
of video publisher
whether
conference participants (host and
operate
attendee)
successfully
Note: anyone can call this function,
but only host can complete actual

subscription function.
+(int)listConference
conferenceID:
string,
conference room ID
Integer-
Request for updating participants
whether
list of conference room
operate
Note: once call this function, SDK
successfully
will
report
participant
state
information to APP automatically

through onConferenceStateEvent
+ (int)
conferenceID:
ctrlConference
string,
Integer-
Perform specific conference control
conference room ID
whether
action to participant (currently only
action: integer, control
operate
support kickout function)
action to be performed
successfully
Public
FreePPID:
string,
FreePP ID of participant
controlled
4.2.6 Video Call Control Interface

Interface name
Para
Return value
Notice
Integer-
Start video preview sending manually
mete
r
+ (int)
No
startVideoSend
whether
operate
Note:
successfully
Set video start mode through setParameter interface:

auto_send_video, 0 (manual), 1 (auto), default is 1
+(int)
No
Integer-
stopVideoSend
whether
operate
Stop video preview sending manually, and send

VIDEO_STOP signal to peer user to stop video call.
successfully
4.3 Basic Flow of Message Interface

4.3.1 Startup Flow
Step 1. Call initialize function to initialize SDK library and verify legitimacy of APP,
meanwhile install delegate callback function object of application layer;
Step 2. Call bindAppAccount function to bind APP account and log in FreePP system;
Step 3. Enter standby state.
4.3.2 One-to-one message communication flow

Step 1. Call queryFreePPIDByAppAccount function to get Free PP ID of target user;
Step 2. Call sendMessage function to send message;
Step 3. Get message send state through onSendMessageEvent callback function;
Step4.For
file
message,get
file
upload
progress
through
onUploadMessageAttachmentEvent callback function;

Step 5. Receiver will receive message or notification through onReceivedMessageEvent
Public
callback function;
Step 6. For file message, receiver calls downloadMessageAttachment function to download
attachment of the message;
Step7.
Receiver
gets
file
download
progress
through
onDownloadMessageAttachmentEvent callback function, and gets state value of

downloaded message file through onDownloadMessageEvent callback function.
4.3.2 Communication Flow of Group Message

Step 1. Get group ID by calling createGroupChat funciton to create group, or receive group
invitation through onReceivedMessageEvent callback function;
Step 2. Call sendGroupMessage function to send group message;
Step 3. Get group message send state through onSendMessageEvent callback function;
Step4.
For
file
message,
get
file
upload
progress
through
onUploadMessageAttachmentEventcallback function;
Step 5. Receiver will receive message or notification through onReceivedMessageEvent
callback function;
Step 6. For file message, receiver calls downloadMessageAttachment function to download
attachment of the message;
Step7.
Receiver
gets
file
download
progress
through
onDownloadMessageAttachmentEvent callback function, and gets state value of
downloaded message file through onDownloadMessageEvent callback function.
4.4 Basic Flow of Call Interface

Note: when performing call hold function, APP is responsible for playing call hold music.
Public
4.4.2 Overall Call Flow
4.4.3 Basic Flow-Caller Initiates Call
Public
4.4.4 Basic Flow-Callee Answers the Call
4.4.5 Basic Flow-Answer and Hang Up
Public
4.4.6 Callee Rejects The Call
4.4.7 Call Hold and Resume
Public
4.4.8 Initiate Multi-party Call
4.4.9 Finish Multi-Party Call
Public
4.4.10 Video Conference Control Mode
4.4.11 Video Conference Subscription

Processing flow of conferee end is shown below,
Public
Processing flow of host end is shown below,
Public
4.4.12 One-way Video Control Mode
4.5 Error Code Table

For iOS and Android API interfaces, if the error codes unified definition of return
value is 0, operation succeeds. Corresponding error codes of other values are shown below:
Error code
Meaning
Related to network and device

-1
No network connection
-2
Timeout or error of API request
Related to user
-10
Illegitimate AppKey
-11
Parameter error
-12
Repeat login, current user is kicked out, or already logs in on other device
-13
Banned user, current user is forbidden
-14
This FreePP ID doesnt exist
-15
FreePP SDK isnt initialized or binds successfully
-16
FreePP SDK setParameter interface parameter has no corresponding value
-17
rootcs is not set (must be set through setParameter interface)
Related to message
-20
Failed to send message-uploaded attachment is beyond maximum limit
-21
Failed to download file
Public
-22
Downloaded file doesnt exist
Related to multi-people session/group chat

-30
Failed to create multi-people session group
-31
Failed to invite friends to multi-people session group
-32
Failed to leave group chat
Error code related to call

-40
Incorrect callID of current call
-41
Real call doesnt exist
-42
Currently existed outbound calling
-43
Failed to set output device
-44
Microphone permission doesnt start the error code
-45
Cant call ones own error code
Error code related to conference

-50
Incorrect conferenceid of current conference
-51
No current conference
-52
This operation is not supported in conference
4.6 Definition of enumeration related to message SDK

4.7 Definition of enumeration related to call SDK
4.8 Multi-language KEY filed related to Push notification
If APP needs to develop Push notification in multi-langue, the following fields need to
be added to multi-language file:
"A" = "Answer";
"V" = "View";
"C" = "%@ Calling You";
"M" = "You have %@ missed call(s).";
"N" = "You have %@ unread message(s).";
"O" = "You have %@ missed call(s), and %@ unread message(s).";
APP can take custom value for each filed.
Public
This page is intentionally left blank.

API iOS English 150721

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

API iOS English 150721

Uploaded by

Copyright:

Available Formats

CONFIDENTIAL

FreePP Mobile SDK on iOS

3.3 SDK Package..............................................................................................12

4.2 Call API Interface.......................................................................................24

4.3 Basic Flow of Message Interface..................................................................30

4.4 Basic Flow of Call Interface.........................................................................31

4.5 Error Code Table.........................................................................................38

FreePP Mobile SDK on iOS API Document- 2 -

FreePP Mobile SDK on iOS API Document- 3 -

1.4 Definitions and Acronyms

FreePP Mobile SDK on iOS API Document- 4 -

FreePP Mobile SDK on iOS API Document- 5 -

Other types of file

FreePP Mobile SDK on iOS API Document- 6 -

specify the successfully sent message ID in callback function;

FreePP Mobile SDK on iOS API Document- 7 -

FreePP Mobile SDK on iOS API Document- 8 -

Protocol layer: responsible for encapsulation and parsing of protocol message.

Transport protocol layer: responsible for encapsulation and parsing of

Authentication APP authentication and SDK initialization

Message transfer state machine

FreePP Mobile SDK on iOS API Document- 10 -

Message sending and receiving workflow

File transfer state machine

Related information on user identity

Create, join or leave group

HTTP request and response

MQTT/APNS Publishing/subscription service

3.2.2 Audio and Video Module

Call control Call state machine

Record call state

Backward call signal transmission

Real-time monitoring of circuit transmission

Video capture and compression encoding

Audio capture and compression encoding

Protocol layer MQTT/APNS

Long connection and Push notification

FreePP Mobile SDK on iOS API Document- 11 -

Session control and streaming media transmission

3.3 SDK Package

Basic version: basic functions and instant message function;

Call version: basic version + A/V call function;

Enhanced version: call version + audio push-to-talk function;

FreePP Mobile SDK on iOS API Document- 12 -

FreePP Mobile SDK on iOS API Document- 13 -

FreePP Mobile SDK on iOS API Document- 14 -

FreePP Mobile SDK on iOS API Document- 15 -

4.1 Message API Interface

Initialize and start SDK

String, Apps authorization code,

to identify third-party App.

succeed, return YES,

if fail, return NO.

Verify the legitimacy of

String, App account (may use

bound with this APP

App, and allocate or bind

phone no., Email or other forms

FreePP ID, and log in

Boolean value, if it is YES, SDK

otherwise verify app account only

FreePP Mobile SDK on iOS API Document- 16 -

callerNumber exist, they