sjero.net Git - linphone/blob - java/common/org/linphone/core/package.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <html>
   3 <head>
   4 <!--
   5
   6   @(#)package.html
   7
   8 Copyright (C) 2010  Belledonne Communications, Grenoble, France
   9
  10 This program is free software; you can redistribute it and/or
  11 modify it under the terms of the GNU General Public License
  12 as published by the Free Software Foundation; either version 2
  13 of the License, or (at your option) any later version.
  14
  15 This program is distributed in the hope that it will be useful,
  16 but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 GNU General Public License for more details.
  19
  20 You should have received a copy of the GNU General Public License
  21 along with this program; if not, write to the Free Software
  22 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  23
  24
  25 -->
  26 </head>
  27 <body bgcolor="white">
  28
  29 Liblinphone is a high level library for bringing SIP video call functionnality into an application. It aims at making easy the integration of the SIP video calls into any applications. All variants of linphone are directly based on it:
  30
  31         <li>linphone (GUI interface)
  32         <li>linphonec (console interface)
  33 <br> Liblinphone is GPL (see COPYING file). Please understand the licencing details before using it!
  34
  35 <br>For any use of this library beyond the rights granted to you by the GPL license, please contact Belledonne Communications (contact@belledonne-communications.com)
  36
  37
  38
  39
  40 <h2>Package Specification</h2>
  41
  42 LibLinphone package is organized in submodules.
  43 <ul>
  44   <li><a href="#proxy">Managing proxies</a>
  45 </ul>
  46 <ul>
  47   <li><a href="#buddy">Managing Buddies and buddy list and presence</a>
  48 </ul>
  49 <ul>
  50   <li><a href="#chat">Chat room and Messaging</a>
  51 </ul>
  52
  53 <h2>Related Documentation</h2>
  54
  55 For overviews, tutorials, examples, guides, and tool documentation, please see:
  56 <ul>
  57   <li><a href="http://www.linphone.org">linphone web site</a>
  58 </ul>
  59
  60 <!-- Put @see and @since tags down here. -->
  61 <h3>
  62 <a name="proxy">Managing proxies</a>
  63 </h3>
  64 User registration is controled by  {@link org.linphone.core.LinphoneProxyConfig } settings.
  65 <br> Each {@link org.linphone.core.LinphoneProxyConfig } object can be configured with registration informations
  66 like {@link org.linphone.core.LinphoneProxyConfig#setProxy proxy address } , {@link org.linphone.core.LinphoneProxyConfig#setIdentity user id}, and so on.
  67 <br> 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 }.
  68 <br> 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.
  69 <br> Registration status is reported by {@link org.linphone.core.LinphoneCoreListener#registrationState registration listener}.
  70 <br>
  71 <br> This pseudo code demonstrates basic registration operations:
  72 <br>
  73 <pre>
  74 <code>
  75
  76         LinphoneProxyConfig proxy_cfg;
  77         /*create proxy config*/
  78         proxy_cfg = LinphoneCoreFactory.instance().createProxyConfig();
  79         /*parse identity*/
  80         LinphoneAddress from = LinphoneCoreFactory.instance().createAddress("sip:toto@sip.titi.com");
  81         LinphoneAuthInfo info;
  82         if (password!=NULL){
  83                 info=LinphoneCoreFactory.instance().createAuthInfo(from.getUsername(),null,"secret",null,null); /*create authentication structure from identity*/
  84                 lc.addAuthInfo(info); /*add authentication info to LinphoneCore*/
  85         }
  86         // configure proxy entries
  87         proxy_cfg.setIdenty(identity); /*set identity with user name and domain*/
  88         String server_addr = from.getDomain(); /*extract domain address from identity*/
  89         proxy_cfg.setProxy(server_addr); /* we assume domain = proxy server address*/
  90         proxy_cfg.enableRegister(true); /*activate registration for this proxy config*/
  91
  92         lc.addProxyConfig(proxy_cfg); /*add proxy config to linphone core*/
  93         lc.setDefaultProxyconfig(proxy_cfg); /*set to default proxy*/
  94 </code>
  95 </pre>
  96 <br>
  97   {@link org.linphone.core.LinphoneCoreListener#registrationState Registration state listener} :
  98 <pre>
  99 <code>
 100  void registrationState(LinphoneCore lc, LinphoneProxyConfig cfg, LinphoneCore.RegistrationState cstate, String message){
 101                 System.out.println(New registration state ["+cstate+"] for user id ["+cfg.getUserName()+"] at proxy ["+cfg.getProxy()+"]";
 102 }
 103 </pre>
 104 </code>
 105
 106 <br><b>Authentication:</b>
 107 <br>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)}  .
 108 <br>
 109 <br><b>Unregistration:</b>
 110 <br> 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 }
 111 <br> This pseudo code shows how to unregister a user associated to a{@link org.linphone.core.LinphoneProxyConfig}
 112 <pre>
 113 <code>
 114         LinphoneProxyConfig proxy_cfg;
 115         lc.setDefaultProxyConfig(proxy_cfg); /* get default proxy config*/
 116         proxy_cfg.edit(); /*start editing proxy configuration*/
 117         proxy_cfg.enableRegister(false); /*de-activate registration for this proxy config*/
 118         proxy_cfg.done(); /*initiate REGISTER with expire = 0*/
 119 </pre>
 120 </code>
 121 <br>
 122 <br>
 123 <h3>
 124 <a name="buddy">Managing Buddies and buddy list and presence</a>
 125 </h3>
 126 <br>
 127 <b>Buddies and buddy list</b>
 128 <br>Each buddy is represented by a {@link org.linphone.core.LinphoneFriend } object created by function {@link org.linphone.core.LinphoneCoreFactory#createLinphoneFriend()}.
 129 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.
 130 <br>Here under a typical buddy creation:
 131 <br>
 132 <pre>
 133 <code>
 134         LinphoneFriend my_friend=LinphoneFactory.instance().createFriend("sip:joe@sip.linphone.org"); /*creates friend object for buddy joe*/
 135         my_friend.enableSubscribes(true); /*configure this friend to emit SUBSCRIBE message after being added to LinphoneCore*/
 136         my_friend.setIncSubscribePolicy(LinphoneFriend.SubscribePolicy.Accept); /* accept Incoming subscription request for this friend*/
 137 </code>
 138 </pre>
 139 {@link LinphoneFriend  friends } status changes are reported by  {@link org.linphone.core.LinphoneCoreListener#notifyPresenceReceived(LinphoneCore lc, LinphoneFriend lf)} .
 140 <pre>
 141 <code>
 142  void notifyPresenceReceived(LinphoneCore lc, LinphoneFriend lf){
 143         LinphoneAddress friend_address = lf.getAddress();
 144         System.out.println("New state ["+lf.getStatus()+"] for user id ["+friend_address+"] ");
 145 }
 146 </code>
 147 </pre>
 148
 149 <br>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 }
 150 <br>
 151 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()}
 152 <pre>
 153 <code>
 154         my_friend.edit(); /* start editing friend */
 155         my_friend.enableSubscribes(true); /*disable subscription for this friend*/
 156         my_friend.done(); /*commit changes triggering an UNSUBSCRIBE message*/
 157 </code>
 158 </pre>
 159
 160 <b> Publishing presence status </b>
 161 <br>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.
 162 <br>
 163 <br>
 164 <b>Handling incoming subscription request</b>
 165 <br> 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. }
 166 <br> For incoming request coming from an unknown buddy, the call back  {@link org.linphone.core.LinphoneCoreListener#newSubscriptionRequest(LinphoneCore lc, LinphoneFriend lf, String url)}
 167
 168 <h3>
 169 <a name="chat">Chat room and Messaging</a>
 170 </h3>
 171 <b> Exchanging text messages</b>
 172 <br> Messages are sent using {@link org.linphone.core.LinphoneChatRoom} object. First step is to create a {@link org.linphone.core.LinphoneCore#createChatRoom chat room }
 173 from a peer sip uri.
 174 <pre>
 175 <code>
 176         LinphoneChatRoom chat_room = lc.createChatRoom("sip:joe@sip.linphone.org");
 177 </pre>
 178 </code>
 179 <br>Once created, messages are sent using function {@link org.linphone.core.LinphoneChatRoom#sendMessage }  .
 180 <pre>
 181 <code>
 182         chat_room.sendMessage("Hello world"); /*sending message*/
 183 </pre>
 184 </code>
 185 <br>Incoming message are received from {@link org.linphone.core.LinphoneCoreListener#textReceived  a listener }
 186 <pre>
 187 <code>
 188         void textReceived(LinphoneCore lc, LinphoneChatRoom cr,LinphoneAddress from,String message) {
 189                 System.out.println("Message ["+message+"] received from ["+from+"] ");
 190         }
 191 </code>
 192 <pre>
 193 </body>
 194 </html>