From 92b5747b7cfcff39dd64bffae481d3c00dcee75a Mon Sep 17 00:00:00 2001 From: Simon Morlat Date: Mon, 1 Nov 2010 11:32:24 +0100 Subject: [PATCH 1/2] propose video window interface --- java/common/org/linphone/core/LinphoneCore.java | 3 +++ java/common/org/linphone/core/VideoWindow.java | 5 +++++ 2 files changed, 8 insertions(+) create mode 100644 java/common/org/linphone/core/VideoWindow.java diff --git a/java/common/org/linphone/core/LinphoneCore.java b/java/common/org/linphone/core/LinphoneCore.java index d74997d52..b001f0a6f 100644 --- a/java/common/org/linphone/core/LinphoneCore.java +++ b/java/common/org/linphone/core/LinphoneCore.java @@ -275,4 +275,7 @@ public interface LinphoneCore { * @return {@link LinphoneChatRoom} where messaging can take place. */ LinphoneChatRoom createChatRoom(String to); + + public void setVideoWindow(VideoWindow w); + public void setPreviewWindow(VideoWindow w); } diff --git a/java/common/org/linphone/core/VideoWindow.java b/java/common/org/linphone/core/VideoWindow.java new file mode 100644 index 000000000..d4a46b931 --- /dev/null +++ b/java/common/org/linphone/core/VideoWindow.java @@ -0,0 +1,5 @@ +package org.linphone.core; + +public interface VideoWindow { + +} From 95bd9f46bf7373e018b58c4c7e914b07a52be8f1 Mon Sep 17 00:00:00 2001 From: Jehan Monnier Date: Thu, 4 Nov 2010 16:44:25 +0100 Subject: [PATCH 2/2] javadoc enhancements --- .../org/linphone/core/LinphoneAddress.java | 16 ++- .../org/linphone/core/LinphoneAuthInfo.java | 9 +- .../org/linphone/core/LinphoneCall.java | 62 +++++++- .../org/linphone/core/LinphoneCallLog.java | 20 ++- .../org/linphone/core/LinphoneCore.java | 132 +++++++++++++++--- .../linphone/core/LinphoneCoreFactory.java | 14 +- .../linphone/core/LinphoneCoreListener.java | 8 +- .../org/linphone/core/LinphoneLogHandler.java | 14 +- 8 files changed, 236 insertions(+), 39 deletions(-) diff --git a/java/common/org/linphone/core/LinphoneAddress.java b/java/common/org/linphone/core/LinphoneAddress.java index 16c688470..b2a2c9380 100644 --- a/java/common/org/linphone/core/LinphoneAddress.java +++ b/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 '. 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. + *
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(); } diff --git a/java/common/org/linphone/core/LinphoneAuthInfo.java b/java/common/org/linphone/core/LinphoneAuthInfo.java index f679307c5..6590dafeb 100644 --- a/java/common/org/linphone/core/LinphoneAuthInfo.java +++ b/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. + *
This object is instanciated using {@link LinphoneCoreFactory#createAuthInfo(String, String, String)}. *
*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(); /** diff --git a/java/common/org/linphone/core/LinphoneCall.java b/java/common/org/linphone/core/LinphoneCall.java index 03baca9df..65923706c 100644 --- a/java/common/org/linphone/core/LinphoneCall.java +++ b/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(); diff --git a/java/common/org/linphone/core/LinphoneCallLog.java b/java/common/org/linphone/core/LinphoneCallLog.java index 08cdb8034..6c4923872 100644 --- a/java/common/org/linphone/core/LinphoneCallLog.java +++ b/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(); } diff --git a/java/common/org/linphone/core/LinphoneCore.java b/java/common/org/linphone/core/LinphoneCore.java index d74997d52..46a631a7a 100644 --- a/java/common/org/linphone/core/LinphoneCore.java +++ b/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. + *
+ * 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. + *
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 + *
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: + *
  • receiving of SIP messages + *
  • handles timers and timeout + *
  • performs registration to proxies + *
  • authentication retries The application MUST call this function from periodically, in its main loop. + *
    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. diff --git a/java/common/org/linphone/core/LinphoneCoreFactory.java b/java/common/org/linphone/core/LinphoneCoreFactory.java index c0d09b0a6..4089ca1fb 100644 --- a/java/common/org/linphone/core/LinphoneCoreFactory.java +++ b/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; diff --git a/java/common/org/linphone/core/LinphoneCoreListener.java b/java/common/org/linphone/core/LinphoneCoreListener.java index 6cb038cdd..daf256662 100644 --- a/java/common/org/linphone/core/LinphoneCoreListener.java +++ b/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); diff --git a/java/common/org/linphone/core/LinphoneLogHandler.java b/java/common/org/linphone/core/LinphoneLogHandler.java index d1330a400..9465dccc7 100644 --- a/java/common/org/linphone/core/LinphoneLogHandler.java +++ b/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. + *
    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); }