linphonec (console interface)
Liblinphone is GPL (see COPYING file). Please understand the licencing details before using it!
For any use of this library beyond the rights granted to you by the GPL license, please contact Belledonne Communications (contact@belledonne-communications.com)
Package Specification
LibLinphone package is organized in submodules.
Related Documentation
For overviews, tutorials, examples, guides, and tool documentation, please see:
User registration is controled by {@link org.linphone.core.LinphoneProxyConfig } settings.
Each {@link org.linphone.core.LinphoneProxyConfig } object can be configured with registration informations
like {@link org.linphone.core.LinphoneProxyConfig#setProxy proxy address } , {@link org.linphone.core.LinphoneProxyConfig#setIdentity user id}, and so on.
A created proxy config using {@link org.linphone.core.LinphoneCoreFactory#createProxyConfig }, once configured, must be added to {@link org.linphone.core.LinphoneCore} using function {@link org.linphone.core.LinphoneCore#addProxyConfig }.
It is recommended to set a default {@link org.linphone.core.LinphoneProxyConfig proxy config } using function {@link org.linphone.core.LinphoneCore#setDefaultProxyConfig }. Once done, if {@link org.linphone.core.LinphoneProxyConfig a proxy config } has been configured with attribute {@link org.linphone.core.LinphoneProxyConfig#enableRegister enable register } , next call to {@link org.linphone.core.LinphoneCore#iterate } triggers a SIP register.
Registration status is reported by {@link org.linphone.core.LinphoneCoreListener#registrationState registration listener}.
This pseudo code demonstrates basic registration operations:
LinphoneProxyConfig proxy_cfg;
/*create proxy config*/
proxy_cfg = LinphoneCoreFactory.instance().createProxyConfig();
/*parse identity*/
LinphoneAddress from = LinphoneCoreFactory.instance().createAddress("sip:toto@sip.titi.com");
LinphoneAuthInfo info;
if (password!=NULL){
info=LinphoneCoreFactory.instance().createAuthInfo(from.getUsername(),null,"secret",null,null); /*create authentication structure from identity*/
lc.addAuthInfo(info); /*add authentication info to LinphoneCore*/
}
// configure proxy entries
proxy_cfg.setIdenty(identity); /*set identity with user name and domain*/
String server_addr = from.getDomain(); /*extract domain address from identity*/
proxy_cfg.setProxy(server_addr); /* we assume domain = proxy server address*/
proxy_cfg.enableRegister(true); /*activate registration for this proxy config*/
lc.addProxyConfig(proxy_cfg); /*add proxy config to linphone core*/
lc.setDefaultProxyconfig(proxy_cfg); /*set to default proxy*/
{@link org.linphone.core.LinphoneCoreListener#registrationState Registration state listener} :
void registrationState(LinphoneCore lc, LinphoneProxyConfig cfg, LinphoneCore.RegistrationState cstate, String message){
System.out.println(New registration state ["+cstate+"] for user id ["+cfg.getUserName()+"] at proxy ["+cfg.getProxy()+"]";
}
Authentication:
Most of the time, registration requires {@link org.linphone.core.LinphoneAuthInfo authentication } to succed. {@link org.linphone.core.LinphoneAuthInfo} info must be either added to {@link org.linphone.core.LinphoneCore } using method {@link org.linphone.core.LinphoneCore#addAuthInfo } before {@link org.linphone.core.LinphoneProxyConfig} is added to Linphone core, or on demand from listener {@link org.linphone.core.LinphoneCoreListener#authInfoRequested(LinphoneCore, String, String)} .
Unregistration:
Unregistration or any changes to {@link org.linphone.core.LinphoneProxyConfig} must be first started by a call to function {@link org.linphone.core.LinphoneProxyConfig#edit } and validated by function {@link org.linphone.core.LinphoneProxyConfig#done }
This pseudo code shows how to unregister a user associated to a{@link org.linphone.core.LinphoneProxyConfig}
LinphoneProxyConfig proxy_cfg;
lc.setDefaultProxyConfig(proxy_cfg); /* get default proxy config*/
proxy_cfg.edit(); /*start editing proxy configuration*/
proxy_cfg.enableRegister(false); /*de-activate registration for this proxy config*/
proxy_cfg.done(); /*initiate REGISTER with expire = 0*/
Buddies and buddy list
Each buddy is represented by a {@link org.linphone.core.LinphoneFriend } object created by function {@link org.linphone.core.LinphoneCoreFactory#createLinphoneFriend()}.
Buddy configuration parameters like {@link org.linphone.core.LinphoneFriend#setAddress(LinphoneAddress) sip uri} or {@link org.linphone.core.LinphoneFriend#setIncSubscribePolicy(LinphoneFriend.SubscribePolicy) status publication} are configurable for each buddy.
Here under a typical buddy creation:
LinphoneFriend my_friend=LinphoneFactory.instance().createFriend("sip:joe@sip.linphone.org"); /*creates friend object for buddy joe*/
my_friend.enableSubscribes(true); /*configure this friend to emit SUBSCRIBE message after being added to LinphoneCore*/
my_friend.setIncSubscribePolicy(LinphoneFriend.SubscribePolicy.Accept); /* accept Incoming subscription request for this friend*/
{@link LinphoneFriend friends } status changes are reported by {@link org.linphone.core.LinphoneCoreListener#notifyPresenceReceived(LinphoneCore lc, LinphoneFriend lf)} .
void notifyPresenceReceived(LinphoneCore lc, LinphoneFriend lf){
LinphoneAddress friend_address = lf.getAddress();
System.out.println("New state ["+lf.getStatus()+"] for user id ["+friend_address+"] ");
}
Once created a buddy can be added to the buddy list using function {@link org.linphone.core.LinphoneCore#addFriend(LinphoneFriend lf) } . Added friends will be notified about {@link org.linphone.core.LinphoneCore#setPresenceInfo(int minute_away,String alternative_contact, OnlineStatus status) local status changes }
Any subsequente modifications to {@link org.linphone.core.LinphoneFriend} must be first started by a call to function to {@link org.linphone.core.LinphoneFriend#edit()} and validated by function {@link org.linphone.core.LinphoneFriend#done()}
my_friend.edit(); /* start editing friend */
my_friend.enableSubscribes(true); /*disable subscription for this friend*/
my_friend.done(); /*commit changes triggering an UNSUBSCRIBE message*/
Publishing presence status
Local presence status can be changed using function {@link org.linphone.core.LinphoneCore#setPresenceInfo }.New status is propagated to all friends {@link org.linphone.core.LinphoneCore#addFriend(LinphoneFriend lf) previously added } to LinphoneCore.
Handling incoming subscription request
New incoming subscription requests are process according to{@link org.linphone.core.LinphoneFriend#setIncSubscribePolicy(LinphoneFriend.SubscribePolicy) the incoming subscription policy state} for subscription initiated by {@link org.linphone.core.LinphoneCore#addFriend(LinphoneFriend lf) members of the buddy list. }
For incoming request coming from an unknown buddy, the call back {@link org.linphone.core.LinphoneCoreListener#newSubscriptionRequest(LinphoneCore lc, LinphoneFriend lf, String url)}
Exchanging text messages
Messages are sent using {@link org.linphone.core.LinphoneChatRoom} object. First step is to create a {@link org.linphone.core.LinphoneCore#createChatRoom chat room }
from a peer sip uri.
LinphoneChatRoom chat_room = lc.createChatRoom("sip:joe@sip.linphone.org");
Once created, messages are sent using function {@link org.linphone.core.LinphoneChatRoom#sendMessage } .
chat_room.sendMessage("Hello world"); /*sending message*/
Incoming message are received from {@link org.linphone.core.LinphoneCoreListener#textReceived a listener }
void textReceived(LinphoneCore lc, LinphoneChatRoom cr,LinphoneAddress from,String message) {
System.out.println("Message ["+message+"] received from ["+from+"] ");
}