# 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:

- C (https://download.linphone.org/snapshots/docs/liblinphone/5.5/c)
- C++ (https://download.linphone.org/snapshots/docs/liblinphone/5.5/c++)
- Swift (https://download.linphone.org/snapshots/docs/liblinphone/5.5/swift)
- Java (https://download.linphone.org/snapshots/docs/liblinphone/5.5/java)
- C# (https://download.linphone.org/snapshots/docs/liblinphone/5.5/cs/)
- Python (https://download.linphone.org/snapshots/docs/liblinphone/5.5/python/)

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.

# Liblinphone Configuration Parameters

# Provisioning configuration keys

This document lists the supported sections and keys of the ini-style linphonerc configuration file.
This configuration can be served through https in order to remotely configure a linphone-sdk based application, see Core.SetProvisioningUri().
The Flexisip Account Manager has built-in support for remote provisioning Linphone or linphone-sdk based client applications.
warning this page is under construction, not all section and keys are yet referenced.

## SIP accounts - section [proxy_N]

The proxy_N sections represents SIP accounts. Their name inherits from the legacy object name Linphone.ProxyConfig in liblinphone, that is now superseeded by by the Linphone.Account and Linphone.AccountParams object, but the linphonerc section name was left unchanged to preserve configuration file compatibility.

SIP account parameters
Key | Value type | Possible values | Default value | Description
--- | --- | --- | --- | ---
reg_identity | string | SIP address | "" | The SIP address of the user, as to be sent in the From header of the REGISTER request
reg_proxy | string | SIP address | "" | The address of the SIP server
reg_route | string | SIP address | "" | An optional SIP address to include as a route
reg_sendregister | boolean | 0 or 1 | 1 | Whether to send a REGISTER request
reg_expires | integer | any strictly positive integer | 3600 | The expiry of the REGISTER, in seconds
realm | string | any string | "" | The authentication realm of the SIP service, used to match with authentication information

## Remote contact directories - section [remote_contact_directory_N]

Their role is not to present a permanent list of contacts to the user, but rather return, per a search request, a list of contacts that match the request.
The search request is transmitted through the protocol (LDAP or CardDav), and executed on the server. The server's response is analysed and search results are represented as a list of Linphone.Friend objects.
LDAP connection configuration has it is own password key, and it is not relying at all on the Linphone.AuthInfo objects, unlike all other liblinphone initiated connections.
The table below lists all remote contact directory parameters one may find under section [remote_contact_directory_N] of a Linphone RC file.

Remote Contact directory parameters
Key | Value type | Possible values | Default value | Description
--- | --- | --- | --- | ---
enabled | integer | 0 or 1 | 1 | Whether the remote contact directory is enabled
type | string | carddav or ldap | "" | The type (protocol) used by the remote contact directory
uri | string | a URI | "" | The server URI, typically ldap://example.org or https://carddav.example.org
min_characters | integer | any positive integer or 0 | 3 | The minimum number of characters needed to submit the request
results_limit | integer | any positive integer or 0 | 0 | Limit on the number of returned results. 0 means returns all results
timeout | integer | any positive integer or 0 | 5 | Request timeout in seconds
delay | integer | any positive integer or 0 | 500 | Delay in milliseconds before submitting the request
carddav_fields_for_user_input | string |  | "" | List of comma separated VCard fields to match with the user input
carddav_fields_for_domain | string |  | "" | List of comma separated VCard fields to match for SIP domain
carddav_use_exact_match_policy | integer | 0 or 1 | 0 | Whether the match must be exact or approximate (ignoring accents, case, ...)
ldap_bind_dn | string |  | "" | LDAP bind distinguished name
ldap_auth_method | integer | 0: anonymous | 1 | LDAP authentication method
1: simple
ldap_base_object | string |  | "" | LDAP base object
ldap_name_attribute | string |  | "sn" | LDAP attribute(s) to browse for contact names
ldap_sip_attribute | string |  | "mobile,telephonenumber,homephone,sn" | LDAP attribute(s) to use to create SIP URIs associated with this remote contact directory
ldap_sip_domain | string |  | "" | A SIP domain to filter results
ldap_filter | string |  | "(sn=%s)" | A LDAP search filter

## Authentication - section [auth_info_N]

The auth_info sections provide authentication information to use for SIP as well as http services (typically remote provisioning, cardDav requests). They need to be supplied in the form of a Linphone.AuthInfo object, whose configuration storage representation is of [auth_info_N] sections, numbered continuously from 0.
The table below lists all remote contact directory parameters one may find under section [auth_info_N] of a Linphone RC file.

Authentication information parameters
Key | Value type | Possible values | Default value | Description
--- | --- | --- | --- | ---
username | string | anything | "" | The username to use for authenticating
domain | string | anything | "" | A SIP domain to which the use of thie Linphone.AuthInfo is scoped to
passwd | string | anything | "" | The clear-text password
realm | string | anything | "" | The realm advertised by the server, it may be left empty if unknown
ha1 | string | anything | "" | A digest HA1 of the password
algorithm | string | MD5 | MD5 | The digest algorithm
SHA-256
authorization_server | string | any HTTP/HTTPS URI | "" | An OAUTH/OpenID connect authorization server URI to use to autheticate
token_endpoint | string | any HTTP/HTTPS URI | "" | URI of endpoint to refresh tokens
client_id | string | anything | "" | OAUTH client ID
client_secret | string | anything | "" | OAUTH client secret