Merge branch 'master' of git.sv.gnu.org:/srv/git/linphone

java/common/org/linphone/core/LinphoneAddress.java

@@ -17,7 +17,16 @@ along with this program; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 package org.linphone.core;
-
+/**
+ * Object that represents a SIP address.
+ * The LinphoneAddress is an opaque object to represents SIP addresses, ie the content of SIP's 'from' and 'to' headers. 
+ * A SIP address is made of display name, username, domain name, port, and various uri headers (such as tags). 
+ * It looks like 'Alice <sip:alice@example.net>'. The LinphoneAddress has methods to extract and manipulate all parts of the address. 
+ * When some part of the address (for example the username) is empty, the accessor methods return null.
+ * <br> Can be instanciated using both  {@link LinphoneCoreFactory#createLinphoneAddress(String, String, String)} or {@link LinphoneCoreFactory#createLinphoneAddress(String)} 
+ * @author jehanmonnier
+ *
+ */
 public interface LinphoneAddress {
 	/**
 	 * Human display name
@@ -58,6 +67,9 @@ public interface LinphoneAddress {
 	 */
 	public String asStringUriOnly();
 	
-	/*must return the same thing as asString()*/
+	/**
+	 * same as {@link #asString()}
+	 * 
+	 * */
 	public String toString();
 }

java/common/org/linphone/core/LinphoneAuthInfo.java

@@ -19,9 +19,8 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 package org.linphone.core;
 /**
  * Object holding authentication information.
- * Note:
- * The object's fields should not be accessed directly. Prefer using the accessor methods.
  * In most case, authentication information consists of a username and password. Sometimes, a userid is required by proxy, and realm can be useful to discriminate different SIP domains.
+ *<br>This object is instanciated using {@link LinphoneCoreFactory#createAuthInfo(String, String, String)}.
  *<br>
  *Once created and filled, a LinphoneAuthInfo must be added to the LinphoneCore in order to become known and used automatically when needed. 
  *Use {@link LinphoneCore#addAuthInfo(LinphoneAuthInfo)} for that purpose.
@@ -35,7 +34,7 @@ package org.linphone.core;
  */
 public interface LinphoneAuthInfo {
 	/**
-	 * 
+	 * get user name
 	 * @return username
 	 */
 	String getUsername();
@@ -45,8 +44,8 @@ public interface LinphoneAuthInfo {
 	 */
 	void setUsername(String username);
 	/**
-	 * 
-	 * @return paasword
+	 * get password
+	 * @return password
 	 */
 	String getPassword();
 	/**

java/common/org/linphone/core/LinphoneCall.java

@@ -20,26 +20,78 @@ package org.linphone.core;
 
 import java.util.Vector;
 
-
+/**
+ * Object representing a Call. calls are created using {@link LinphoneCore#invite(LinphoneAddress)} or paased to the application by listener {@link LinphoneCoreListener#callState(LinphoneCore, LinphoneCall, State, String)}
+ * 
+ */
 public interface LinphoneCall {
+	/**
+	 * Linphone call states
+	 *
+	 */
 	static class State {
 		static private Vector values = new Vector();
 		private final int mValue;
 		private final String mStringValue;
+		/**
+		 * Idle
+		 */
 		public final static State Idle = new State(0,"Idle");
+		/**
+		 * Incoming call received.
+		 */
 		public final static State IncomingReceived = new State(1,"IncomingReceived");
+		/**
+		 * Outgoing call initialiazed.
+		 */
 		public final static State OutgoingInit = new State(2,"OutgoingInit");
+		/**
+		 * Outgoing call in progress. 
+		 */
 		public final static State OutgoingProgress = new State(3,"OutgoingProgress");
+		/**
+		 * Outgoing call ringing.
+		 */
 		public final static State OutgoingRinging = new State(4,"OutgoingRinging");
+		/**
+		 * Outgoing call early media
+		 */
 		public final static State OutgoingEarlyMedia = new State(5,"OutgoingEarlyMedia");
+		/**
+		 * Connected
+		 */
 		public final static State Connected = new State(6,"Connected");
+		/**
+		 * Streams running
+		 */
 		public final static State StreamsRunning = new State(7,"StreamsRunning");
+		/**
+		 * Paussing
+		 */
 		public final static State Pausing = new State(8,"Pausing");
+		/**
+		 * Paused
+		 */
 		public final static State Paused = new State(9,"Paused");
+		/**
+		 * Resuming
+		 */
 		public final static State Resuming = new State(10,"Resuming");
+		/**
+		 * Refered
+		 */
 		public final static State Refered = new State(11,"Refered");
+		/**
+		 * Error
+		 */
 		public final static State Error = new State(12,"Error");
+		/**
+		 * Call end
+		 */
 		public final static State CallEnd = new State(13,"CallEnd");
+		/**
+		 * Paused by remote
+		 */
 		public final static State PausedByRemote = new State(14,"PausedByRemote");
 		private State(int value,String stringValue) {
 			mValue = value;
@@ -69,10 +121,14 @@ public interface LinphoneCall {
 	 *
 	**/
 	public LinphoneAddress  getRemoteAddress();
-	
+	/**
+	 * get direction of the call (incoming or outgoing).
+	 * @return CallDirection 
+	 */
 	public CallDirection getDirection();
 	/**
-	 * Returns the call log associated to this call.
+	 * get the call log associated to this call.
+	 * @Return LinphoneCallLog
 	**/
 	public LinphoneCallLog getCallLog();
 

java/common/org/linphone/core/LinphoneCallLog.java

@@ -17,13 +17,25 @@ along with this program; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 package org.linphone.core;
-
+/**
+ * Call data records object 
+ *
+ */
 public interface LinphoneCallLog {
 
-	
+	/**
+	 * Originator of the call as a LinphoneAddress object.
+	 * @return LinphoneAddress
+	 */
 	public LinphoneAddress getFrom();
-	
+	/**
+	 * Destination of the call as a LinphoneAddress object.
+	 * @return
+	 */
 	public LinphoneAddress getTo ();
-	
+	/**
+	 * The direction of the call
+	 * @return CallDirection
+	 */
 	public CallDirection getDirection();
 }

java/common/org/linphone/core/LinphoneCore.java

@@ -21,17 +21,31 @@ package org.linphone.core;
 
 import java.util.Vector;
 
-	
+/**
+ * Linphone core main object created by method {@link LinphoneCoreFactory#createLinphoneCore(LinphoneCoreListener, String, String, Object)}.	
+ *
+ */
 public interface LinphoneCore {
 	/**
 	 * linphone core states
 	 */
 	static public class 	GlobalState {
 		static private Vector values = new Vector();
-
+		/**
+		 * Off
+		 */
 		static public GlobalState GlobalOff = new GlobalState(0,"GlobalOff");       
+		/**
+		 * Startup
+		 */
 		static public GlobalState GlobalStartup = new GlobalState(1,"GlobalStartup");
+		/**
+		 * On
+		 */
 		static public GlobalState GlobalOn = new GlobalState(2,"GlobalOn");
+		/**
+		 * Shutdown
+		 */
 		static public GlobalState GlobalShutdown = new GlobalState(3,"GlobalShutdown");
 
 		private final int mValue;
@@ -54,12 +68,31 @@ public interface LinphoneCore {
 			return mStringValue;
 		}
 	}
+	/**
+	 * Describes proxy registration states.
+	 *
+	 */
 	static public class 	RegistrationState {
 		static private Vector values = new Vector();
+		/**
+		 * None
+		 */
 		static public RegistrationState RegistrationNone = new RegistrationState(0,"RegistrationNone");       
+		/**
+		 * In Progress
+		 */
 		static public RegistrationState RegistrationProgress  = new RegistrationState(1,"RegistrationProgress");
+		/**
+		 * Ok
+		 */
 		static public RegistrationState RegistrationOk = new RegistrationState(2,"RegistrationOk");
+		/**
+		 * Cleared
+		 */
 		static public RegistrationState RegistrationCleared = new RegistrationState(3,"RegistrationCleared");
+		/**
+		 * Failed
+		 */
 		static public RegistrationState RegistrationFailed = new RegistrationState(4,"RegistrationFailed");
 		private final int mValue;
 		private final String mStringValue;
@@ -81,8 +114,18 @@ public interface LinphoneCore {
 			return mStringValue;
 		}
 	}
+	/**
+	 * Signaling transports 
+	 *
+	 */
 	static public class Transport {
+		/**
+		 * UDP transport
+		 */
 		public final static Transport udp =new Transport("udp");
+		/**
+		 * TCP transport
+		 */
 		public final static Transport tcp =new Transport("tcp");
 		private final String mStringValue;
 
@@ -94,15 +137,26 @@ public interface LinphoneCore {
 		}		
 	}
 	/**
-	 * clear all added proxy config
+	 * clear all added proxy configs
 	 */
 	public void clearProxyConfigs();
-	
+	/**
+	 * Add a proxy configuration. This will start registration on the proxy, if registration is enabled.
+	 * @param proxyCfg
+	 * @throws LinphoneCoreException
+	 */
 	public void addProxyConfig(LinphoneProxyConfig proxyCfg) throws LinphoneCoreException;
-
+	/**
+	 * Sets the default proxy.
+	 *<br>
+	 * This default proxy must be part of the list of already entered {@link LinphoneProxyConfig}. 
+	 * Toggling it as default will make LinphoneCore use the identity associated with the proxy configuration in all incoming and outgoing calls.
+	 * @param proxyCfg 
+	 */
 	public void setDefaultProxyConfig(LinphoneProxyConfig proxyCfg);
 	
 	/**
+	 * get he default proxy configuration, that is the one used to determine the current identity.
 	 * @return null if no default proxy config 
 	 */
 	public LinphoneProxyConfig getDefaultProxyConfig() ;
@@ -111,7 +165,11 @@ public interface LinphoneCore {
 	 * clear all the added auth info
 	 */
 	void clearAuthInfos();
-	
+	/**
+	 * Adds authentication information to the LinphoneCore.
+	 * <br>This information will be used during all SIP transacations that require authentication.
+	 * @param info
+	 */
 	void addAuthInfo(LinphoneAuthInfo info);
 	
 	/**
@@ -123,13 +181,22 @@ public interface LinphoneCore {
 	public LinphoneAddress interpretUrl(String destination) throws LinphoneCoreException;
 	
 	/**
-	 * Starts a call given a destination. Internally calls interpretUrl() then invite(LinphoneAddress).
+	 * Starts a call given a destination. Internally calls {@link #interpretUrl(String)} then {@link #invite(LinphoneAddress)}.
 	 * @param uri
 	 */
 	public LinphoneCall invite(String destination)throws LinphoneCoreException;
-	
+	/**
+	 * Initiates an outgoing call given a destination LinphoneAddress
+	 *<br>The LinphoneAddress can be constructed directly using linphone_address_new(), or created by linphone_core_interpret_url(). The application doesn't own a reference to the returned LinphoneCall object. Use linphone_call_ref() to safely keep the LinphoneCall pointer valid within your application.
+	 * @param to the destination of the call (sip address).
+	 * @return LinphoneCall
+	 * @throws LinphoneCoreException
+	 */
 	public LinphoneCall invite(LinphoneAddress to)throws LinphoneCoreException;
-	
+	/**
+	 * Terminates a call.
+	 * @param aCall to be terminated
+	 */
 	public void terminateCall(LinphoneCall aCall);
 	/**
 	 * Returns The LinphoneCall the current call if one is in call
@@ -152,6 +219,17 @@ public interface LinphoneCore {
 	 * @return Returns true if in incoming call is pending, ie waiting for being answered or declined.
 	 */
 	public boolean isInComingInvitePending();
+	/**
+	 * Main loop function. It is crucial that your application call it periodically.
+	 *
+	 *	#iterate() performs various backgrounds tasks:
+	 * <li>receiving of SIP messages
+	 * <li> handles timers and timeout
+	 * <li> performs registration to proxies
+	 * <li> authentication retries The application MUST call this function from periodically, in its main loop. 
+	 * <br> Be careful that this function must be call from the same thread as other liblinphone methods. In not the case make sure all liblinphone calls are serialized with a mutex.
+
+	 */
 	public void iterate();
 	/**
 	 * Accept an incoming call.
@@ -232,28 +310,46 @@ public interface LinphoneCore {
 	public void stopDtmf();
 	
 	/**
-	 * 
+	 * remove all call logs
 	 */
 	public void clearCallLogs();
-	
-	
 	/***
 	 * get payload type  from mime type an clock rate
 	 * 
 	 * return null if not found
 	 */
 	public PayloadType findPayloadType(String mime,int clockRate); 
-	
+	/**
+	 * not implemented yet
+	 * @param pt
+	 * @param enable
+	 * @throws LinphoneCoreException
+	 */
 	public void enablePayloadType(PayloadType pt, boolean enable) throws LinphoneCoreException;
-	
+	/**
+	 * Enables or disable echo cancellation.
+	 * @param enable
+	 */
 	public void enableEchoCancellation(boolean enable);
-	
+	/**
+	 * get EC status 
+	 * @return true if echo cancellation is enabled.
+	 */
 	public boolean isEchoCancellationEnabled();
-	
+	/**
+	 * not implemented yet
+	 * @param aTransport
+	 */
 	public void setSignalingTransport(Transport aTransport);
-	
+	/**
+	 * not implemented
+	 * @param value
+	 */
 	public void enableSpeaker(boolean value);
-	
+	/**
+	 * not implemented
+	 * @return
+	 */
 	public boolean isSpeakerEnabled();
 	/**
 	 * add a friend to the current buddy list, if subscription attribute is set, a SIP SUBSCRIBE message is sent.

java/common/org/linphone/core/LinphoneCoreFactory.java

@@ -49,9 +49,19 @@ abstract public class LinphoneCoreFactory {
 	abstract public LinphoneAuthInfo createAuthInfo(String username,String password, String realm);
 	
 	abstract public LinphoneCore createLinphoneCore(LinphoneCoreListener listener, String userConfig,String factoryConfig,Object  userdata) throws LinphoneCoreException;
-	
+	/**
+	 * Constructs a LinphoneAddress object
+	 * @param username 
+	 * @param domain
+	 * @param displayName
+	 * @return 
+	 */
 	abstract public LinphoneAddress createLinphoneAddress(String username,String domain,String displayName);
-	
+	/**
+	 * Constructs a LinphoneAddress object by parsing the user supplied address, given as a string.
+	 * @param address should be like sip:joe@sip.linphone.org
+	 * @return
+	 */
 	abstract public LinphoneAddress createLinphoneAddress(String address);
 	
 	abstract public  LinphoneProxyConfig createProxyConfig(String identity, String proxy,String route,boolean enableRegister) throws LinphoneCoreException;

java/common/org/linphone/core/LinphoneCoreListener.java

@@ -19,15 +19,15 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 package org.linphone.core;
 
 
-
+/**
+ * 
+ *This interface holds all callbacks that the application should implement. None is mandatory.
+ */
 public interface LinphoneCoreListener {
 
 	/**< Notifies the application that it should show up
 	 * @return */
 		public void show(LinphoneCore lc);
-		 /**< Notify calls terminated by far end
-		 * @return */
-		public void byeReceived(LinphoneCore lc,String from);
 		/**< Ask the application some authentication information 
 		 * @return */
 		public void authInfoRequested(LinphoneCore lc,String realm,String username); 

java/common/org/linphone/core/LinphoneLogHandler.java

@@ -17,7 +17,11 @@ along with this program; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
 package org.linphone.core;
-
+/**
+ * Interface to implement for handling liblinphone log.
+ * <br> use {@link LinphoneCoreFactory#setLogHandler(LinphoneLogHandler)}
+ *
+ */
 public interface LinphoneLogHandler {
 	public static final int Fatal=1<<4;
 	public static final int Error=1<<3|Fatal;
@@ -25,5 +29,13 @@ public interface LinphoneLogHandler {
 	public static final int Info=1<<1|Warn;
 	public static final int Debug=1|Info;
 	
+	/**
+	 * Method invoked for each traces
+	 * @param loggerName
+	 * @param level
+	 * @param levelString
+	 * @param msg
+	 * @param e
+	 */
 	public void log(String loggerName, int level, String levelString, String msg, Throwable e);
 }