Welcome to liblinphone's Java API reference documentation.
Liblinphone is a high-level open source library that integrates all the SIP voice/video and instant messaging features into a single easy-to-use API.
This is the VoIP SDK engine on which Linphone applications are based.
Liblinphone combines our media processing and streaming toolkit (Mediastreamer2) with our user-agent library for SIP signaling (belle-sip).
Liblinphone is distributed under
GPLv3. Please understand the licencing details before using it!
For any use of this library beyond the rights granted to you by the GPLv3 license, please
contact Belledonne Communications.
Other languages
Liblinphone has support for a variety of languages, each one has its own reference documentation:
Tutorials are available on our
gitlab repository.
See also
http://www.linphone.org
Quick tour of liblinphone's features
Introduction
Liblinphone's has a consistent object-oriented design.
All objects are sharing a common base class, with ref-counting.
Root objects must be constructed by the
Factory class.
No 'new' operator invocation is permitted.
Liblinphone is using SIP as signaling protocol, which actually comprises a huge set of RFCs to cover various aspects of communications.
Some terminology of the API is directly inherited from SIP specifications, that's why having some knowledge of the protocol is recommended for a better understanding of this documentation.
Initializing the engine
A typical liblinphone application has to first instanciate a
Core object using the
Factory.
The core object represents the liblinphone engine, from which call, conferences, instant messages can be sent or received.
For events to be reported and engine to schedule its tasks, the application must call
Core.iterate() at regular interval, typically from a 20ms timer.
On Android, it is done automatically by the Java wrapper using a
Timer and a
TimerTask, but you can disable that behavior using
Core.setAutoIterateEnabled().
In most case, a SIP account has to be provisionned so that SIP registration can take place onto a SIP server.
This task is designated to the
Account class.
An
Account can be created using
Core.createAccount(), based on parameters created with
Core.createAccountParams().
Then, account can be added to the core for usage using
Core.addAccount().
Application usually need to get informed of events occuring in the lifetime of the engine, which is done through listeners that the applications can override.
An important listener interface is the
CoreListener, that application should override and and create, and then insert into their
Core object with
Core.addListener().
Making calls
Applications can place outgoing calls using
Core.invite() or
Core.inviteAddressWithParams().
The
CallParams class represents parameters for the calls, such as enabling video, requiring a specific MediaEncryption.
The
CallListener interface provides application way to get inform of the progress of the call, represented by the
Call.State enum.
Incoming calls are notified through the
CoreListener interface, and can later be accepted using
Call.accept().
Calls can be terminated or aborted at any time using
Call.terminate().
Instant messaging
The
ChatRoom class represents a text conversation.
The
Core object provides persistancy for all conversations, ie it stores all received and sent messages.
The list of conversation can be retrieved using
Core.getChatRooms().
To create a new conversation, use
Core.createChatRoom().
ChatRoomParams provide a way to specify which kind of chatroom is to be created: for group, for one-ton-one conversation, with end-to end encryption for example.
To send a message, first create the
ChatMessage with
ChatRoom.createMessageFromUtf8(), then send it with
ChatMessage.send().
A
ChatMessage reports its progress through the
ChatMessageListener interface.
ChatRooms are automatically created by the
Core when receiving a message that starts a new conversation, and notified through the
CoreListener interface.
Presence
Applications can submit presence information through
Core.setPresenceModel().
The
PresenceModel class represents the presence information, which is submitted to a presence server.
Symmetrically, applications can subscribe to the presence server to get notified of the presence status of a contact list.
This is to be done thanks to the
FriendList and
Friend classes.