API-iOS-English-150721.doc

8/18/2019 API-iOS-English-150721.doc

http://slidepdf.com/reader/full/api-ios-english-150721doc 1/41

CONFIDENTIAL

0

BROWAN COMMUNICATIONSINCORPORTATION

April 22, 2016

www.browan.com

FreePP Mobile SDK on iOS

API Document

version 1.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 ideo Module....................................................................11

3.3 SD! Pac"a#e..............................................................................................12

Chapter 4: SDK API..................................................................................................16

4.1 Messa#e AP$ $nterface.................................................................................16

%.1.1 APP&'ser Mana#ement......................................................................16

%.1.2 Messa#e Sendin# and (eceivin#...........................................................18

%.1.3 File Sendin# and (eceivin#.................................................................22

%.1.% )roup Mana#ement...........................................................................23

4.2 *all AP$ $nterface.......................................................................................24

%.2.1 *all *ontrol $nterface........................................................................24

%.2.2 State +otification $nterface..................................................................26

%.2.3 Media $&O $nterface...........................................................................27

%.2.% *all $nformation ,uery $nterface.........................................................28

%.2.- ideo *onference *ontrol $nterface.......................................................29

%.2. ideo *all *ontrol $nterface................................................................29

4.3 Basic Flow of Messa#e $nterface..................................................................30

%.3.1 Startup Flow....................................................................................30

%.3.2 One/to/one messa#e communication flow...............................................30%.3.2 *ommunication Flow of )roup Messa#e................................................31

4.4 Basic Flow of *all $nterface.........................................................................31

%.%.2 Overall Call Flow.............................................................................32

%.%.3 Basic Flow/*aller $nitiates *all............................................................32

%.%.% Basic Flow/*allee Answers t0e *all......................................................33

%.%.- Basic Flow/Answer and an# 'p.........................................................33

%.%. *allee (eects 0e *all......................................................................34

%.%.4 *all old and (esume.......................................................................34

%.%.5 $nitiate Multi/party *all......................................................................35

%.%.6 Finis0 Multi/Party *all.......................................................................35%.%.17 ideo *onference *ontrol Mode.........................................................36

FreePP Mobile SDK on iOS API Document- 1 -



Public

%.%.11 ideo *onference Su8scription...........................................................36

%.%.12 One/way ideo *ontrol Mode............................................................38

4.5 9rror *ode a8le.........................................................................................38

4.6 Definition of enumeration related to messa#e SD! ........................................39

4.7 Definition of enumeration related to call SD! ...............................................394.8 Multi/lan#ua#e !9: filed related to Pus0 notification...................................39




Public

Χηαπτερ :

Introduction

1.1 Purpose

$t mainly introduces t0e arc0itecture and 8asic desi#n considerations of FreePP Mo8ile

SD!; and descri8es functions; call met0od and wor"flow of SD! AP$ interface in details.

1.2 Scope

$t is suita8le for FreePP Mo8ile SD! developers and software testin# en#ineer to read

and discuss.

1. Overview

FreePP Mo8ile SD! <iOS version= is developed wit0 O8ective/* lan#ua#e and iOS

SD! 4.1 class li8rary under >*ode -.1 version; and is compati8le wit0 iOS -.7&.7&4.7

system and 0i#0er.

0rou#0 FreePP Mo8ile SD!; t0ird/party application pro#rammer <APP for s0ort= can

reali?e aut0entication; communication num8er allocation and @uery; instant messa#e; A&<audio and video= communication; and ot0er functions; includin#

Bindin# and @uery of APP account wit0 t0e unified communication num8er inside

instant communication system <communication no. for s0ort=

One/to/one instant messa#e; includin# tet or file messa#e

$nstant #roup messa#e

)roup mem8er control; includin# invite; mute; oin and leave

One/to/one audio&video call

Audio&video conference <includin# client or server audio miin#=

(eal/time pus0 to tal"

Besides; for different operatin# systems and *P' processors; SD! adopts 0ardware

acceleration optimi?ation al#orit0m in modules wit0 0i#0 computational compleity; li"e

A& compression codec; and compiles t0e al#orit0m for armv4 and arm% processors

respectively to ensure smoot0 user eperience.

0e content of t0is document mainly includes SD! arc0itecture; SD! internal function




Public

modules; SD! desi#n considerations; SD! pac"a#e; AP$ interface desi#n and wor"flow.

1.! Definitions and Acronyms

+S +otification Server

*S *onfi#uration Server

F>S Forei#n 9c0an#e Su8scri8er

F>O Forei#n 9c0an#e Office

AP+S Apple Pus0 +otification Service

FPS FreePP Pus0 +otification Service

M9* Messa#e 9c0an#e *enter




Public

Χηαπτερ 2:

Design Considerations

o ensure t0e interopera8ility; compati8ility and openness of SD!; support t0ird/party

accounts in various forms <e.#. nic"name; 9mail address; p0one no. or APP account; etc.=;

0ide t0e implementation details of underlyin# communication system; and reduce APP

development compleity; SD! follows t0e 8asic principles 8elow in desi#n

Unified User Identifier

Cit0in t0e system; SD! identifies eac0 user uni@uely wit0 its communication no.; APP

can associate a specific APP account wit0 t0e allocated communication no. 8y 8indin#

met0od. $n t0is way; for different forms of APP accounts; a unified user identification

mana#ement and control mec0anism inside communication system can 8e reali?ed 8y

communication no.; to ensure interconnection and interopera8ility amon# different APPs.

Besides; w0en APP calls SD! AP$ interface; communication no. s0ould 8e used as tar#et

parameter; 8ut for end/user; it is transparent and invisi8le; APP can #et correspondin#

communication no. of eac0 APP account; t0rou#0 SD! @uery account interface.

0e relation 8etween APP account and communication no. is s0own 8elow;

Note: SDK can support intercommunication between different forms of APP accounts

through unified user identification, i.e., communication no.

Unified Message Format

$n SD! system; M$M9 codin# format is unified to define various types of instant

messa#e; t0e 8asic format is type/subtypeE; e.#.

Message type MIME codeet strin# tet&plain




Public

$ma#e file ima#e& pn#;pe#...G

Audio file audio&amr;3#p;mp3G

ideo file video&mpe# ;mp%;avi;asf;movG

Ot0er types of file application& pdf ;msword;octet/stream...G

HSO+ strin# application&son

+ote types of instant messa#e are not limited to t0e definition mentioned a8ove; APP

can epand new M$M9 type and correspondin# function to suit its own needs; w0ile SD!

can ensure transparent transmission of M$M9 type w0en transmittin# messa#e.

Unified Character Coding Format

o 8e compati8le wit0 strin#s in different lan#ua#es and avoid messy code 8etween

different lan#ua#es or platforms; SD! only adopts 'F/5 code inside t0e system.

Bot0 input parameters and return values of SD! AP$ interface adopt 'F/5 codin#

format; SD! developer needs to complete conversion of related strin# codin# formats in

upper layer. Meanw0ile; SD! also provides auiliary interface function for interconversion

8etween '+$*OD9 strin# and 'F/5 strin#.

Asynchronous perations of Interface

o reduce t0e operation couplin# 8etween APP and SD!; and improve pro#ram

efficiency and responsiveness; all interfaces involvin# messa#e and conversation functions

<usually need to assess networ" and ta"e a lon# time= 0andle APPIs call re@uests wit0 non/

8loc"in# mode; i.e. APP can return and continue to run immediately after callin# SD! AP$

interface; w0ile SD! "eeps processin# in 8ac"#round wit0out 8loc"in# t0e APP; and return

results to APP async0ronously 8y correspondin# call8ac" function; t0erefore; APP doesnIt

need to wait; ot0erwise may cause main t0read 8loc"in#; ma"in# App 8ecome unresponsive.

Besides; messa#e&call re@uest $D is adopted 8etween APP and SD! to matc0

async0ronous re@uest and response. 9.#.

①C0en APP sends messa#e; SD! interface will return t0e messa#e $D to APP

immediately; meanw0ile transmittin# messa#e in 8ac"#round wit0 multit0read tec0nolo#yJ

②After sendin# messa#e successfully; SD! will notify APP 8y call8ac" function; and






Public

Χηαπτερ 3:

Architecture

.1 Overview

FreePP Mo8ile SD! 0as two main functions user identity aut0entication&instant

messa#e and A& call; of w0ic0 t0e former one is SD!Is 8asic function; as well as t0e

infrastructure for client to access t0e instant communication system.

Basic arc0itecture of user identity aut0entication&instant messa#e function is s0own

8elow;

$n t0e a8ove fi#ure; t0ere are followin# layers in SD!; 8y call relations 8etween function

8loc"s

$nterface layer mas" t0e implementation details inside middleware; and provide

easy/to/use services of user identity aut0entication and instant messa#e for App.

Service layer provide user identity mana#ement and control; and wor"flow of

various instant communication services.

*ommunication layer provide interactive operation 8etween client and server; and

ensure t0at client can 8e notified in time.




Public

Protocol layer responsi8le for encapsulation and parsin# of protocol messa#e.

Based on t0e a8ove functions; A& communication also provides one/to/one video call

and multi/party A& conference functions.

Basic arc0itecture of SD!Is A& function is s0own 8elow;

$n t0e a8ove fi#ure; t0ere are followin# layers inside SD!; 8y call relations 8etween

function 8loc"s

$nterface layer 0ide t0e implementation details inside middleware; and provide

easy/to/use A& communication services for APP.

*all control and information processin# layer provide wor"flow of call setup;

maintenance; and release; and A& stream processin# and networ" adaptive

function.

ransport protocol layer responsi8le for encapsulation and parsin# of

communication protocol messa#e.

Moreover; call state mac0ine is t0e core of A& call module; mainly responsi8le for

recordin# and mana#in# t0e current state of eac0 call; and ma"es correspondin# processin#

action accordin# to user operation or re@uest. SD! call state mac0ine implements call state

control accordin# to followin# state transition dia#ram <Fi#ure 3=




Public

$n t0e a8ove fi#ure; $DK9E refers to call stand8y; i.e. SD! returns to t0is state 8efore

initiatin# or finis0in# a callJ $+$$A9E refers to call initiatin# state; i.e. 8ot0 parties of a

call are in t0is state after initiatin# call and 8efore answerin#J A+)'PE refers to call

finis0in# state; i.e. 8ot0 parties of a call are in t0is state if eit0er party 0an#s up first. Besides;

once in A+)'P state; SD! will transfer to $DK9 state automatically.

,hen using ca$$ modu$es& APP needs to disp$ay corresponding user interface

according to current ca$$ state or SDK ca$$ state notification& and perform

corresponding ca$$ contro$ operations(

.2 *odu%es

-(.( 0asic Function Modu$es

Basic function modules include user identity aut0entication&instant messa#e function.

1ayer Modu$e Description

Service layer Aut0entication

and aut0ori?ation

• APP aut0entication and SD! initiali?ation

• FreePP $D application; lo#in and assi#nin# server

• APP account @uery

$nstant • Messa#e transfer state mac0ine




Public

messa#e • Messa#e sendin# and receivin# wor"flow

File transfer • File transfer state mac0ine

• File sendin# and receivin# wor"flow

Kocal stora#e • (elated information on user identity

• Server settin#s

• Messa#e lo##in# to 8e processed

)roup

mana#ement

• *reate; oin or leave #roup

• ,uery #roup information

*ommunication

layer

Kon#

connection

• eart8eat service

• (eceivin# of pus0 notification

Ce8 service • P re@uest and response

• Async0ronous operation re@uest @ueue

Protocol layer M,&AP+S • Pu8lis0in#&su8scription service

• Pus0 notification

P • Ce8 Service

-(.(. Audio and 2ideo Modu$e

1ayer Modu$e Description

*all control

and

information

processin#

layer

*all state mac0ine • (ecord call state

• *ontrol call processin#

Pus0 notification • Bac"ward call si#nal transmission

• *all reect si#nal transmission

*all capacity

ne#otiation and

@uality monitorin#

• (eal/time monitorin# of circuit transmission

@uality; adaptive control of A& encoder

• +e#otiate call capacities and parameters; e.#. video

capacity; encryption capacity and AD capacity

ideo en#ine • ideo capture and compression encodin#

• Adaptive control of video codin# rate

Audio en#ine • Audio capture and compression encodin#

• Audio conference mier

Protocol layer M,&AP+S Kon# connection and Pus0 notification




Public

P

$A>2&'DP Session control and streamin# media transmission

. SDK Pac&age

FreePP Mo8ile SD! li8raries can 8e divided into followin# versions 8y functions

com8ination

0asic +ersion" 8asic functions and instant messa#e functionJ

Ca$$ +ersion" 8asic version L A& call functionJ

Enhanced +ersion call version L audio pus0/to/tal" functionJ

(elations 8etween a8ove SD! li8raries and AP$ interfaces are s0own in followin# ta8le

<c0aracters in 8lue are for Android; and t0at in 8lac" are for iOS and cross platform=

SDK

+ersion

3eference re$ation

Inc$ude/Import

Dependency re$ation

4(a/(so5

Function

Basic

version

FreePPSD!.0& ar li8FreePPSD!Basic.a&so 1=Basic functions

<initiali?ation and user

mana#ement=J

2=$nstant messa#eJ

*all

version

FreePPSD!.0& ar

FreePPSD!Stream.

0& ar

li8FreePPSD!Std.a&so

or

li8FreePPSD!Std.a&so

1=Basic functions


mana#ement=J

2=$nstant messa#eJ

3=One/to/one video

callJ

%=Multi/party A&

conferenceJ9n0anced

version

FreePPSD!.0& ar

FreePPSD!Stream.

0& ar

FreePPSD!P.0& a

r

li8FreePPSD!Pro.a&so

or

li8FreePPSD!Pro.a&so

1=Basic functions


mana#ement=J

2=$nstant messa#eJ

3=One/to/one video

callJ

%=A& conferenceJ

-=Audio intercomJ

!ote" ca$$ +ersion and enhanced +ersion can generate t'o $ibrary fi$es& respecti+e$y




Public

corresponding to t'o so$utions66c$ient audio mi*ing and ser+er audio mi*ing 4the

one 'ith 7*8 behind is ser+er audio mi*ing5( ,hen using SDK& de+e$oper can

choose either of the t'o $ibrary fi$es as re9uired by ser+ice(

C0en t0e t0ird/party APP uses SD!; t0e followin# Framewor" and Ki8rary need to 8e

lin"ed to APP proect

$f only use 8asic version SD!; add framewor" and Ki8rary as s0own 8elow to

proect;

$f use call version SD!; 8e sure to add Ki8rary <as s0own 8elow= to proect;

*all version SD! needs specific compilation options; w0ic0 are s0own 8elow;




Public

C0en t0ird party references call SD! li8rary files; 8e sure to add macro definition

F(99PPSD!S(9AMAP$E to use AP$ met0od in SD!; as s0own 8elow;




Public

C0en t0e t0ird/party references call version SD! li8rary file for conference

function; 8e sure to add macro definition F(99PPSD!S(9AM*O+FAP$E

to use t0e relevant conference AP$ met0od in SD!; as s0own 8elow




Public

Χηαπτερ 4:

SDK API

FreePP Mo8ile SD! mainly 0as two types of AP$ interfaces messa#e AP$ and call AP$.

$n #eneral; AP$ interfaces in SD! are all sync0ronous <8loc"in#= interfacesJ async0ronous

<non/8loc"in#= interfaces will 8e specified in special description.

Moreover; any interface mar"ed wit0 CALLBACK is call8ac" interface; and APP needs

to reali?e suc0 interface function in dele#ate class; meanw0ile avoid performin# t0e lon#

runnin# tas"s; to prevent 8loc"in# t0e wor"er t0read of SD!.

!.1 *essage AP" "nterface

:(( APP/User Management

Interface name Parameters 3eturn +a$ues !otice

; 4015initia$i<e appKey：

Strin#; AppIs aut0ori?ation code;

to identify t0ird/party App.

de$egate：

Any pointer type; t0ird/party

APPIs dele#ate.

Boolean/client

initiali?ation result; if

succeed; return :9S;

if fail; return +O.

$nitiali?e and start SD!

client module.

;4!SString

=5bindAppAccount

appUserAccount：

Strin#; App account <may use

p0one no.; 9mail or ot0er forms

of accounts=.

mustAuth：

Boolean value; if it is :9S; SD!

s0ould connect to server to

perform remote identification;

ot0erwise verify app account only

in local data8ase. $n t0is way; APP

decides on its own w0et0er to

"ic" out eac0 ot0er; or lo# in

@uic"ly.

ca$$er!ame：

Strin#/FreePP $D

8ound wit0 t0is APP

account

$f return value is

+'KK; App!ey is

ille#itimate; or

8indin# fails. For

details; refer to error

code ta8le.

erify t0e le#itimacy of

App; and allocate or 8ind

FreePP $D; and lo# in

FreePP system.

$f caller+ame and

caller+um8er eist; t0ey

will 8e stored in SD!;

and carried out in

out8ound call.




Public

Strin#; userIs local nic"name;

mainly used to set callerIs name

in out8ound call.

ca$$er!umber：

Strin#; userIs p0one no.; mainly

used to set callerIs p0one no. in

out8ound call; standard 9.1%

format.

; 4!SDictionary

=59ueryFreePPID0

yAppAccount

appAccountArray：

Strin# array; App account list of

tar#et user.

Strin# dictionary/list of

FreePP $D and

correspondin# App

account <as0 ta8le

"eyNvalue=. $f error

occurs; return +'KKJ if

multiple accounts

repeat; only one "ey

eists in as0 ta8le.

,uery t0e FreePP $D of

specific user wit0 APP

account.

; 4!SDictionary

=59ueryAppAccou

nt0yFreePPID

freePPIDArray：

Strin# array; FreePP $D list of

tar#et user.

Strin# dictionary/list of

FreePP $D and

correspondin# App

account <as0 ta8le

"eyNvalue=. $f error

occurs or peer/party

doesnIt install FreePP;

return +'KKJ if

multiple accounts

repeat; only one "ey

eists in as0 ta8le.

,uery t0e FreePP $D of

specific user wit0 APP

account.

;

4int5setParameter

name：

Strin#; parameter name.

+a$ue：

Strin#; parameter value.

$nte#er; return 7/setup

succeeds; for error;

refer to error code

ta8le.

Set SD!Is internal

wor"in# parameters.

+ote for currently

supported parameters;

please refer to

Parameter

Configuration Table.

; 4!SString

=5getParameter

name：

String& parameter name(

Strin#/parameter

value. $f it doesnIt

eist; return +'KK.

)et SD!Is internal

parameters.

;

4int5get1astErrorC

ode

!o $nte#er; if no error

eists; return 7. <for

error code; refer to

)et t0e error code of t0e

Kast failed interface

invocation.




Public

section %.% error code

ta8le=

+ote t0is interface is

t0read /safe i.e. SD!

ensure separate stora#e

of last errors in different

t0reads; Once call t0is

interface; SD! will clear

error code of current

t0read.

;

4int5$ogoutAppAcc

ount

!o $nte#er; if no error

occurs; return 7.

9rror code /1-

FreePP SD!;

uninitiali?ed.

Ko# out and reset current

account.

+ote SD! temporarily

donIt delete local

data8ase; for possi8le

follow/up lo#in 8y

reusin# account 8indin#.

;

4+oid5onSystemE+e

nt

e+ent)ype" inte#er; event type;

includin#

1Ncurrent user is "ic"ed outJ

correspondin# data is +'KKJ

data>bect" correspondin# data

o8ect. $t varies wit0 different

event type; can 8e +'KK.

+o (eport event information

correspondin# to current

account.

1N current user is "ic"ed

out

+ote1. Parameter confi#uration ta8le of name in #etParameter and setParameter interface

Parameter name peration 3ea$i<ation

re9uirement

!otice

ersion #et +o FreePP SD! version +o.

(ootcs #et&set :es FreePP SD! (oot*S address; used

for server portal address

ma#roupmem8er #et +o Ma. num8er of #roup mem8ers

videoorientation #et&set +o ideo display orientation 1

<vertical= or 7 <0ori?ontal=; default

1/vertical

calltimeout #et&set +o *all timeout <s=; default %-s; ran#e

1%-s

:((. Message Sending and 3ecei+ing

Interface name Parameter 3eturn +a$ue !otice

; 4!SString =5sendMessage dstFreePPID：

Strin#; FreePP $D of tar#et user.Strin#/messa#e $D.

Send one/to/one multimediamessa#e to specific user.




Public

mime)ype：

Strin#; type of multimedia

messa#e; e.#. tet&plainE

te*tContent：

Strin#; content of tet messa#e;

format distin#uis0es 8y

mimeype. $f in tet&plain; it is

plain strin#J if in

application&son; it is HSO+

strin#.

fi$ePath：

Strin#; local file pat0 of 8inary

file.

Strin#; messa#e $D for

retransmission

$f error

occurs; return

+'KK.

!ote"

message ID

format"

FreePP ID6

Uni*

timestamp

4s56t'o

random

digits8

+ote if messa#e$D

parameter 0as value; it will

8e ud#ed w0et0er valid.

$f t0is Messa#e$D

#enerates 8efore FreePP

SD!; consider it valid.

$f valid; re/send its

correspondin# messa#e;

and return t0is Messa#e $DJ

$f invalid; directly return

+'KK.

+ote t0is is async0ronous

interface; its runnin# results

will 8e returned to APP

t0rou#0 correspondin#

call8ac" interface.

; 4!SString

=5send?roupMessage

dst?roupID：

Strin#; uni@ue identifier of

tar#et #roup.

mime)ype：

Strin#; type of multimedia

messa#e

te*tContent：Strin#; content of tet messa#e;

format distin#uis0es 8y

mimeype.

fi$ePath：

Strin#; local file pat0 of 8inary

file.

Strin#; messa#e $D for

retransmission.

。

Strin#/

messa#e $D.

$f error

occurs; return

+'KK.

!ote"

message ID

format"

FreePP ID6

Uni*

timestamp

4s56t'o

random

digits8

Send one/to/many

multimedia messa#e to

specific #roup.

+ote if messa#e$D

parameter 0as value; it will

8e ud#ed w0et0er valid. $f

valid; resend correspondin#

messa#e of t0is messa#e $D.




t0rou#0 correspondin#

call8ac" interface.

(A++)A(K

;

4+oid5onSendMessageE+ent

messageID：Strin#; uni@ue messa#e send $D.

send3esu$t：

$nte#er; results of messa#e send.

7Nsucceed; if fail; refer to error

code ta8le.

+o *all8ac" response interfaceof one/to/one and #roup

messa#e send state; it is

dele#ate met0od interface.

App updates messa#e send

state t0rou#0 t0is interface.

For 8ot0 tet and file

messa#es; t0is call8ac" is

used to s0ow send result. For

file messa#e;








Public

3<messa#e

receivin# state

notification=

+SStrin# messa#e$D

int messa#eStatus

int createime

Messa#eStatus

Description of eac0 attri8ute is s0own 8elow

mime)ype" strin#; multimedia messa#e formatJ

srcFreePPID" strin#; FreePP $D of senderJ

dstFreePPID" strin#; FreePP $D of receiver; for #roup c0at; it is )roup $DJ

te*tContent" strin#; content of contet messa#eJ

messageID" strin#; uni@ue $D of messa#eJ

fi$ePath" strin#; used inside SD!; file pat0 w0en sendin# file; invalid w0en receivin#

messa#eJ

session)ype" inte#er; session type of messa#e <7 sin#le c0at; 1 #roup c0at=J

create)ime" inte#er; time of messa#e #eneration; 'ni timestamp; unit sJ

freepp?roup" )roup$nfo o8ect pointer; #roup messa#e o8ect; valid for #roup c0atJ

groupID" strin#; uni@ue $D of #roupJ

group!ame" strin#; name of #roupJ

in+itorFreePPID" strin#; FreePP $D of inviterJ

array@oinFreePPID" strin# array; FreePP $D list of inviteeJ

array1ea+eFreePPID" strin# array; FreePP $D list of leavin# #roup c0atJ

$ea+e3eason" inte#er; reason for leavin# #roup <N7 "ic"ed outJ N1 leave=.

messageStatus" inte#er; messa#e send notification type; includin# 1Ndelivered;

2Nread.

:((- Fi$e Sending and 3ecei+ing


;

4int5do'n$oadMess

ageAttachment

messageID：

Strin#; uni@ue $D of messa#e

re@uired to 8e downloaded.

is)humbnai$：

$nte#er; w0et0er to download

t0um8nail; 7/download ori#inal

$nte#er/7 added to

download @ueue;

for ot0er error

code; refer to error

code ta8le.

Download attac0ment

<multimedia file= of specific

messa#e.

+ote First; App #ets messa#e

notification from

On(eceivedMessa#eevent




Public

ima#e< +ote invalid for non/

ima#e type=.

fi$ePath：

Strin#; local file pat0 of

downloaded file; includin# file

name.

interface; t0en calls

downloadMessa#eAttac0ment

interface to download

attac0ment of t0e messa#e.




t0rou#0 correspondin# call8ac"

response interface.

;

4+oid5onDo'n$oad

MessageAttachme

ntProgressE+ent

messageID：

Strin#; uni@ue $D of messa#eJ

do'n$oadProgress：

$nte#er; percenta#e of current

fileIs download pro#ress

+o *all8ac" interface of file

download pro#ress; it is

dele#ate met0od interface.

App can update fileIs pro#ress

indication 8y t0is call8ac"

function.

;

4+oid5onUp$oadMe

ssageAttachmentP

rogressE+ent

messageID" strin#; uni@ue $D of

messa#eJ

up$oadProgress：

$nte#er; percenta#e of current

fileIs upload pro#ress.

+o *all8ac" interface of file

upload pro#ress; it is dele#ate

met0od interface.

App can update fileIs pro#ress

indication 8y t0is call8ac"

function.

+ote file upload initiates from

sendMessa#e or

send)roupMessa#e interface.

:((: ?roup Management


; 4!SString

=5create?roupChat

group!ame：

Strin#; topic of creatin#

t0e #roup.

memberArray：

Strin# array; FreePP $D

list of #roup mem8er.

Strin#/#roup $D allocated 8y server.

$f error occurs; return +'KK.

*reate a new

#roup.

; 4int5>oin?roupChat groupID：

Strin#; #roup $D returned

w0en creatin# #roup.

memberArray：


array of invited #roup

$nte#er/result of oin #roup. $nvite user to

oin specific

#roup.

0e invited

client will

receive




Public

mem8er. notification 8y

messa#e.

;

4int5$ea+e?roupChat

groupID：


w0en creatin# #roup.

memberArray：


array of leaved #roup

mem8er.

$nte#er/result of leavin# #roup. Keave specific

#roup; or "ic"

out specific user

of #roup.

0e "ic"ed out

client will

receive

notification 8y

messa#e.

;

4FreePP?roupb>ect

=5get?roupChatInfo

groupID：


w0en creatin# #roup; or

#ot w0en receivin# #roup

messa#e.

)roup o8ect/defined 8y platform.

+ote #roup o8ect < )roup$nfo=

contains followin# attri8utes

groupID" strin#; uni@ue $D of

#roupJ

o'nerFreePPID" strin#; FreePP

$D of #roup creatorJ

arrayMemberFreePPID" strin#

array; FreePP $D of #roup

mem8erJ

create)ime" inte#er; time w0en

creatin# #roupJ

group!ame" strin#; #roup name

or topicJ

)et information

of specific

#roup

!.2 (a%% AP" "nterface

:(.( Ca$$ Contro$ Interface


; 4!SString

=5ma%eCa$$

dstID" strin#; FreePP $D of t0e

called user.

media" inte#er; media type of

call.

1N Audio call

2N ideo call

-NFull duple audio c0annel for

pus0/to/tal"

Strin#/callIs

session identifier

<call/id=.

$nitiate a free FreePP

audio or video call.

; 4!SString phone" strin#; p0one no. of t0e Strin#/callIs $nitiate savin# out8ound




Public

=5ma&eOutbound

(a%%

callee.

+ia：Out8ound

+ia Out8ound route code.

session identifier

<call/id=.

audio call.

; 4!SString

=5 oin(onference

dstIDs" FreePP $D of

participants.

media" inte#er; conferenceIs

media type.

ser+er" strin#; room $D of

server audio miin# conference

Phones" strin# array; p0one no.

of participants.

+ia Out8ound route code.

Strin#/session

identifier of

conference

<conference/id=.

$nitiate a conference call.

0e met0od can 8e called

repeatedly; for invitin#

various participants to t0e

same conference.

+ote server is valid only

w0en media type e@ual to

3N Audio conference callJ

Or %Nvideo conference

call.

; 4int5

getNetwor&-ua%it

y

4reser+e5

ca$$Id" strin#; session identifier

of specific call.

$nte#er/networ"

@uality score value

R7; .

)et score of networ"

transmission @uality of

call.

;

4int5hangupCa$$

ca$$Id" strin#; callIs session

identifier <returned 8y makeCall

or onReceiveCallEvent)

$nte#er/w0et0er

operate

successfully.

Finis0 specific call <8ot0

caller and t0e called can

call t0is function to 0an#

up t0emselves=.

;4int5

hangupConferen

ce

conferenceId" strin#; session

identifier of conference call

<returned 8y oin*onference or

onReceiveCallEvent =

$nte#er/w0et0er

operate

successfully.

Finis0 specific conference

call <0an# up everyone in

conference room=

; 4int5ans'erCa$$ ca$$Id" strin#; callIs session

identifier <returned 8y

on(eceived*all=

$nte#er/w0et0er

operate

successfully.

0e called user answers

specific incomin# call.

; 4int5ho$dCa$$ ca$$Id" string& ca$$#s session

identifier(

ho$d" inte#er; 0old <1= or resume

<7= call.

$nte#er/w0et0er

operate

successfully.

One/way call 0old or

resume call.

; 4int5muteCa$$ ca$$Id" strin#; callIs session

identifier or conferenceIs room

identifier.

mute"inte#er; microp0one mute

<1= or unmute <7=.

$nte#er/w0et0er

operate

successfully.

One/way call mute or

unmute microp0one.

; 4int5sendD)MF ca$$ID" strin#; callIs session

identifier

digit" strin#; secondary dial

num8er to 8e sent.

$nte#er/w0et0er

operate

successfully.

Send DMF dial tone to

t0e peer user of an

answered call to complete

secondary dialin#.




Public

time" inte#er; interval for

sendin# multiple "ey di#its;

unit ms <+ote if send a

di#it only; it can 8e set as 7=.

mode" inte#er; DMF si#nal

transmission mode

7 in/8and dialin# mode

1 out/8and dialin# mode

:(.(. State !otification Interface


(A++)A(K

6

4+oid5on3ecei+eCa

$$E+ent

ca$$Id" strin#; session

identifier of call or

conference.

ca$$erId" strin#; FreePP $D

of caller.

ca$$er!ame" strin#;

nic"name or p0one no. of

caller.

media" inte#er; media type

of call re@uest.

1N Audio callJ

2N视ideo callJ

3NAudio conference callJ

%Nideo conference call.

ca$$)ype" inte#er; call type

of received notification.

1N $ncomin# call

2N Missed call

!o +otify APP of receivin# call

re@uest from remote user.

+ote

1） $f APP is in loc" screen

state; SD! will pop up

P'S notification

automaticallyJ

2）$f APP is in runnin# state;

APP will decide to display

incomin# notification

interface on its own.

(A++)A(K

6

4+oid5onCa$$StateE

+ent

ca$$Id" strin#; session

identifier of call or

conference.

state" inte#er; current call

state; can ta"e followin#

values

7 / $DK9；

1 / $+$$A9；

2 / A+SC9( ；

3 / OKD；

+o +otify APP of call state

c0an#ed.

$n different call state; APP

s0ould display different

prompts

1= $DK9－ +o

2= +$$A9－ *allin# <for

caller= or connectin# <for

callee=




Public

% / A+)'P。

reason" inte#er.

C0en state is A+)'P;

identify reason for finis0in#

a call; includin# user offline;

networ" connection

unavaila8le; 8usyin#; etcJ

C0en state is A+SC9(;

identify way to #o into

answer state; includes 7/

answerJ

1 / (esume call.

3= A+SC9(/ al"in#

%= OKD

-= A+)'P

(A++)A(K

6

4+oid5onConferenc

eStateE+ent

conferenceId" strin#;

conferenceIs session

identifier.

ca$$Id" strin#; callIs session

identifier of participants.

ca$$eeId" strin#; FreePP $D

of participants.

state" inte#er; current call


values

1 / $+$$A9； 2 / A+SC9( ；

3 / A+)'P。

C0en state is A+)'P;

identify reason for finis0in#

a call; includin# user offline;

networ" connection

unavaila8le; 8usyin#; etcJ

C0en state is A+SC9(;

identify way to #o intoanswer state includes 7/

answerJ

1 / (esume call.

无

+o

+otify APP of certain

participantIs state c0an#e in

conference.



prompts

1= $+$$A9－*allin# <for

caller= or connectin# <for

callee=

2= A+SC9(

3= A+)'P

(A++)A(K

6 4+oid5

on3emote2ideoSta

teE+ent

ca$$eeId" strin#; FreePP $D

of participant.

state" inte#er; remote video


values

7 / SOP；

无

+o

+otify APP of remote video

state c0an#e.



prompts

1= SA(－ Start remote




Public

1 / SA(； video sendin#

2= SOP － Stop remote

video sendin#

:(.(- Media I/ Interface


; 4int5setCamera de+ice" inte#er; device

identifier; e.#.

7 / (ear camera

1 / Front camera

/1 T*lose preview

$nte#er/w0et0er

operate

successfully.

Set camera for current video call.

;

4int5setAudioutp

ut

de+ice" inte#er; spea"er

device identifier; e.#.

7 / (eceiver

1 / Spea"er

2 /Bluetoot0 0eadset

connected currently

$nte#er/w0et0er

operate

successfully.

Set spea"er device for call.

;

4int5set2ideoDisp$a

y

disp$ay3emote" iew

o8ect; window o8ect to

display remote video <peer

userIs ima#e; select o8ect

type 8y operatin# system=.

disp$ayPre+ie'" iew

o8ect; window o8ect to

display near/end video <own

ima#e=.

$nte#er/w0et0er

operate

successfully.

Set window o8ect to display video

in video call.

;

4int5set3ingbac%)o

ne

ringbac%Fi$ePath" strin#;

audio pat0 in Bundle of App

layer or local file.

$nte#er/w0et0er

operate

successfully.

Set rin#8ac" tone of out8ound call.

Supported file format

pcm<1!=、wav<pcm5";1";32";11

72-;227-7;%%177";%5"JpcmaJpcmu=

:(.(: Ca$$ Information uery Interface


; 4!SArray +o Array/ strin# list of )et t0e list of call$D for all calls currently




Public

=5getA$$Ca$$ID1ist all call$Ds. on#oin# ;includes call/in and call/out.

; 4FreePPCa$$Info

=5getCa$$Info

ca$$Id"

strin#;

session

identifier of

call or

conference.

FreePP*all$nfo

o8ect pointer/call

information o8ect.

)et correspondin# call o8ect 8y *all$D.

FreePPCa$$Info ob>ect contains fo$$o'ing

attributes"

ca$$Id" strin#; session identifier of call or

conference.

ca$$eeId" strin#; FreePP $D of peer user.

ca$$ee!ame" strin#; nic"name or p0one no. of

peer user.

media)ype" inte#er; media type of call re@uest

<audio; video or conference=.

ca$$State" inte#er; current call state can ta"e

followin# values

7 / $DK9；

1 / $+$$A9；

2 / A+SC9( ；

3 / OKD；

% / A+)'P。

:(.(B 2ideo Conference Contro$ Interface

$nterface name Parameter (eturn

value

+otice

; 4int5

subConference2ideo

pubID" strin#; FreePP $D

of video pu8lis0er

$nte#er/

w0et0er

operate

successfully

.

Su8scri8e conference video for

conference participants <0ost and

attendee=

+ote anyone can call t0is function;

8ut only 0ost can complete actual

su8scription function.;4int5$istConference conferenceID" strin#;

conference room $D

$nte#er/

w0et0er

operate

successfully

(e@uest for updatin# participants

list of conference room

+ote once call t0is function; SD!

will report participant state

information to APP automatically

t0rou#0 on*onferenceState9vent

L 4int5

ctr$Conference

conferenceID" strin#;

conference room $D

action" integer& controlaction to 8e performed

$nte#er/

w0et0er

operatesuccessfully

Perform specific conference control

action to participant <currently only

support "ic"out function=






Public

call8ac" functionJ

Step . For file messa#e; receiver calls do'n$oadMessageAttachment function to download

attac0ment of t0e messa#eJ

Step4. (eceiver #ets file download pro#ress t0rou#0

onDo'n$oadMessageAttachmentE+ent call8ac" function; and #ets state value of

downloaded messa#e file t0rou#0 onDo'n$oadMessageE+ent call8ac" function.

:(-(. Communication F$o' of ?roup Message

Step 1. )et #roup $D 8y callin# create?roupChat funciton to create #roup; or receive #roup

invitation t0rou#0 on3ecei+edMessageE+ent call8ac" functionJ

Step 2. *all send?roupMessage function to send #roup messa#eJ

Step 3. )et #roup messa#e send state t0rou#0 onSendMessageE+ent call8ac" functionJ

Step%. For file messa#e; #et file upload pro#ress t0rou#0

onUp$oadMessageAttachmentE+ent call8ac" functionJ

Step -. (eceiver will receive messa#e or notification t0rou#0 on3ecei+edMessageE+ent

call8ac" functionJ

Step . For file messa#e; receiver calls do'n$oadMessageAttachment function to download

attac0ment of t0e messa#eJ

Step4. (eceiver #ets file download pro#ress t0rou#0

onDo'n$oadMessageAttachmentE+ent call8ac" function; and #ets state value of

downloaded messa#e file t0rou#0 onDo'n$oadMessageE+ent call8ac" function.

!.! )asic %ow of (a%% "nterface

+ote w0en performin# call 0old function; APP is responsi8le for playin# call 0old music.




Public

:(:(. Overa%% (a%% %ow

:(:(- 0asic F$o'6Ca$$er Initiates Ca$$




Public

:(:(: 0asic F$o'6Ca$$ee Ans'ers the Ca$$

:(:(B 0asic F$o'6Ans'er and ang Up




Public

:(:( Ca$$ee 3e>ects )he Ca$$

:(:( Ca$$ o$d and 3esume




Public

:(:( Initiate Mu$ti6party Ca$$

:(:(G Finish Mu$ti6Party Ca$$




Public

:(:(H 2ideo Conference Contro$ Mode

:(:( 2ideo Conference Subscription

Processin# flow of conferee end is s0own 8elow;






Public

:(:(. ne6'ay 2ideo Contro$ Mode

!." /rror (ode 0ab%e

For iOS and Android AP$ interfaces; if t0e error codeIs unified definition of return

value is 7; operation succeeds. *orrespondin# error codes of ot0er values are s0own 8elow

Error code Meaning

(elated to networ" and device

/1 +o networ" connection

/2 imeout or error of AP$ re@uest

(elated to user

/17 $lle#itimate App!ey

/11 Parameter error

/12 (epeat lo#in; current user is "ic"ed out; or already lo#s in on ot0er device

/13 Banned user; current user is for8idden

/1% 0is FreePP $D doesnIt eist

/1- FreePP SD! isnIt initiali?ed or 8inds successfully

/1 FreePP SD! setParameter interface parameter 0as no correspondin# value

/14 rootcs is not set <must 8e set t0rou#0 setParameter interface=

(elated to messa#e

/27 Failed to send messa#e/uploaded attac0ment is 8eyond maimum limit

/21 Failed to download file




Public

/22 Downloaded file doesnIt eist

(elated to multi/people session&#roup c0at

/37 Failed to create multi/people session #roup

/31 Failed to invite friends to multi/people session #roup

/32 Failed to leave #roup c0at

9rror code related to call

/%7 $ncorrect call$D of current call

/%1 (eal call doesnIt eist

/%2 *urrently eisted out8ound callin#

/%3 Failed to set output device

/%% Microp0one permission doesnIt start t0e error code

/%- *anIt call oneIs own error code

9rror code related to conference

/-7 $ncorrect conferenceid of current conference

/-1 +o current conference

/-2 0is operation is not supported in conference

!.6 Definition of enumeration re%ated to message SDK

!.# Definition of enumeration re%ated to ca%% SDK

!.$ *u%ti$%anguage K/1 fi%ed re%ated to Push notification

$f APP needs to develop Pus0 notification in multi/lan#ue; t0e followin# fields need to

8e added to multi/lan#ua#e file

UAU N UAnswerUJ

UU N UiewUJ

U*U N UQV *allin# :ouUJ

UMU N U:ou 0ave QV missed call<s=.UJ

U+U N U:ou 0ave QV unread messa#e<s=.UJ

UOU N U:ou 0ave QV missed call<s=; and QV unread messa#e<s=.UJ

APP can ta"e custom value for eac0 filed.




Public

)his page is intentiona$$y $eft b$an%(

API-iOS-English-150721.doc

Documents