|
Liblinphone
5.3.0
|
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 (https://www.gnu.org/licenses/gpl-3.0.html). 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 (https://www.linphone.org/contact).
Liblinphone has support for a variety of languages, each one has its own reference documentation:
Tutorials (code examples) are available on our gitlab repository (https://gitlab.linphone.org/BC/public/tutorials) for Swift, Java/Kotlin, and C#.
Liblinphone's has a consistent object-oriented design. All objects are sharing a common base structure, with ref-counting. Most objects must be constructed from the LinphoneFactory object. By convention, all functions that are called 'create' return a new object that needs to be later destroy by the application using the 'unref' function of the object. 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.
A typical liblinphone application has to first instanciate a LinphoneCore object using the LinphoneFactory. 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 linphone_core_iterate() at regular interval, typically from a 20ms timer. 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 LinphoneAccount object. A LinphoneAccount can be created using linphone_core_create_account(), based on LinphoneAccountParams representing parameters created with linphone_core_create_account_params(). Then, account can be added to the core for usage using linphone_core_add_account().
Application usually need to get informed of events occuring in the lifetime of the engine, which is done through callbacks '*Cbs' objects that application can use to set their own callbacks functions. An important callback object is the LinphoneCoreCbs. Once filled with its own function pointers, the callback structure can be assigned to the LinphoneCore using linphone_core_add_callbacks(). For example, application usually need to at least fill the LinphoneCoreCbsCallCreatedCb callback using linphone_core_cbs_set_call_created() in order to get informed when a new incoming call is created.
Applications can place outgoing calls using linphone_core_invite() or linphone_core_invite_address_with_params(). The LinphoneCallParams object represents parameters for the calls, such as enabling video, requiring a specific LinphoneMediaEncryption. The LinphoneCallCbs object provides application way to get inform of the progress of the call, represented by the LinphoneCallState enum. Incoming calls are notified through the LinphoneCoreCbs callback interface, and can later be accepted using linphone_call_accept(). Calls can be terminated or aborted at any time using linphone_call_terminate().
The LinphoneChatRoom object represents a text conversation. The LinphoneCore object provides persistancy for all conversations, ie it stores all received and sent messages. The list of conversations can be retrieved using linphone_core_get_chat_rooms() To create a new conversation, use linphone_core_create_chat_room_2(). 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 LinphoneChatMessage with linphone_chat_room_create_message_from_utf8(), then send it with linphone_chat_message_send(). A LinphoneChatMessage reports its progress through the LinphoneChatMessageCbs callback interface. #LinphoneChatRooms are automatically created by the LinphoneCore when receiving a message that starts a new conversation, and notified through the LinphoneCoreCbs interface.
Applications can submit presence information through linphone_core_set_presence_model(). The LinphonePresenceModel object 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 LinphoneFriendList and LinphoneFriend object.
1.8.13