Skip to content

GitLab

Commit 08b6f466 authored by jehan's avatar jehan
Browse files

javadoc enhancements

parent 63117d28
Hide whitespace changes
Inline Side-by-side
Showing with 385 additions and 75 deletions
coreapi/linphonecore.h
View file @ 08b6f466
......@@ -47,12 +47,29 @@ typedef struct _LinphoneCore LinphoneCore;
struct _LpConfig;
struct _LCSipTransports{
/**
* Linphone core SIP transport ports.
* Use with #linphone_core_set_sip_transports
* @ingroup initializing
*/
typedef struct _LCSipTransports{
/**
* udp port to listening on, negative value if not set
* */
int udp_port;
/**
* tcp port to listening on, negative value if not set
* */
int tcp_port;
/**
* dtls port to listening on, negative value if not set
* */
int dtls_port;
/**
* tls port to listening on, negative value if not set
* */
int tls_port;
};
} LCSipTransports;
typedef struct _LCSipTransports LCSipTransports;
......@@ -934,7 +951,12 @@ int linphone_core_update_call(LinphoneCore *lc, LinphoneCall *call, const Linpho
int linphone_core_defer_call_update(LinphoneCore *lc, LinphoneCall *call);
int linphone_core_accept_call_update(LinphoneCore *lc, LinphoneCall *call, const LinphoneCallParams *params);
/**
* @ingroup media_parameters
* Get default call parameters reflecting current linphone core configuration
* @param LinphoneCore object
* @return LinphoneCallParams
*/
LinphoneCallParams *linphone_core_create_default_call_parameters(LinphoneCore *lc);
LinphoneCall *linphone_core_get_call_by_remote_address(LinphoneCore *lc, const char *remote_address);
......@@ -982,16 +1004,23 @@ const MSList *linphone_core_get_video_codecs(const LinphoneCore *lc);
int linphone_core_set_video_codecs(LinphoneCore *lc, MSList *codecs);
bool_t linphone_core_payload_type_enabled(LinphoneCore *lc, const PayloadType *pt);
/**
* Enable payload type
* @param linphone core
* @param pt payload type to enable, can be retrieve from #linphone_core_find_payload_type
* @param TRUE if enabled
* @return 0 if succed
*
*/
int linphone_core_enable_payload_type(LinphoneCore *lc, PayloadType *pt, bool_t enable);
/**
* Wildcard value used by #linphone_core_find_payload_type to ignore rate in search algirithm
* Wildcard value used by #linphone_core_find_payload_type to ignore rate in search algorithm
* @ingroup media_parameters
*/
#define LINPHONE_FIND_PAYLOAD_IGNORE_RATE -1
/**
* Wildcard value used by #linphone_core_find_payload_type to ignore channel in search algirithm
* Wildcard value used by #linphone_core_find_payload_type to ignore channel in search algorithm
* @ingroup media_parameters
*/
#define LINPHONE_FIND_PAYLOAD_IGNORE_CHANNELS -1
......@@ -1370,7 +1399,13 @@ void linphone_core_refresh_registers(LinphoneCore* lc);
/* Path to the file storing secrets cache */
void linphone_core_set_zrtp_secrets_file(LinphoneCore *lc, const char* file);
const char *linphone_core_get_zrtp_secrets_file(LinphoneCore *lc);
/**
* Search from the list of current calls if a remote address match uri
* @ingroup call_control
* @param lc
* @param uri which should match call remote uri
* @return LinphoneCall or NULL is no match is found
*/
const LinphoneCall* linphone_core_find_call_from_uri(LinphoneCore *lc, const char *uri);
int linphone_core_add_to_conference(LinphoneCore *lc, LinphoneCall *call);
......@@ -1385,8 +1420,19 @@ int linphone_core_terminate_conference(LinphoneCore *lc);
int linphone_core_get_conference_size(LinphoneCore *lc);
int linphone_core_start_conference_recording(LinphoneCore *lc, const char *path);
int linphone_core_stop_conference_recording(LinphoneCore *lc);
/**
* Get the maximum number of simultaneous calls Linphone core can manage at a time. All new call above this limit are declined with a busy answer
* @ingroup initializing
* @param lc core
* @return max number of simultaneous calls
*/
int linphone_core_get_max_calls(LinphoneCore *lc);
/**
* Set the maximum number of simultaneous calls Linphone core can manage at a time. All new call above this limit are declined with a busy answer
* @ingroup initializing
* @param lc core
* @param max number of simultaneous calls
*/
void linphone_core_set_max_calls(LinphoneCore *lc, int max);
bool_t linphone_core_sound_resources_locked(LinphoneCore *lc);
......
java/common/org/linphone/core/CallDirection.java
View file @ 08b6f466
......@@ -18,9 +18,17 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
package org.linphone.core;
/**
* Enum representing the direction of a call.
**/
public class CallDirection {
/**
* outgoing calls*
* */
public static CallDirection Outgoing = new CallDirection("CallOutgoing");
/**
* incoming calls
*/
public static CallDirection Incoming = new CallDirection("Callincoming");
private String mStringValue;
private CallDirection(String aStringValue) {
......
java/common/org/linphone/core/LinphoneAddress.java
View file @ 08b6f466
......@@ -39,21 +39,48 @@ public interface LinphoneAddress {
*/
public String getUserName();
/**
*
* Domain name
* @return null if not set
*/
public String getDomain();
/**
* Port as String
* @return null if not set
*/
public String getPort();
/**
* Port as integer value.
* @return negative value if not set if not set
*/
public int getPortInt();
/**
* set display name
* @param name
*/
public void setDisplayName(String name);
/**
* set user name
* @param username
*/
public void setUserName(String username);
/**
* set domain name
* @param domain
*/
public void setDomain(String domain);
/**
* set port as String
* @param port, null if not set
*/
public void setPort(String port);
/**
* set port as int
* @param port, negative value if not set
*/
public void setPortInt(int port);
/**
* Removes address's tags and uri headers so that it is displayable to the user.
**/
public void clean();
/**
......
java/common/org/linphone/core/LinphoneAuthInfo.java
View file @ 08b6f466
......@@ -20,7 +20,7 @@ package org.linphone.core;
/**
* Object holding authentication information.
* 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>This object is instantiated using either {@link LinphoneCoreFactory#createAuthInfo(String, String, String)} or {@link LinphoneCoreFactory#createAuthInfo(String, String, 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.
......
java/common/org/linphone/core/LinphoneCallLog.java
View file @ 08b6f466
......@@ -24,7 +24,11 @@ package org.linphone.core;
import java.util.Vector;
/**
* Object representing a call log.
*
*
**/
public interface LinphoneCallLog {
/**
* Represents call status
......@@ -91,26 +95,30 @@ public interface LinphoneCallLog {
public CallDirection getDirection();
/**
* get status of this call
* @return
* @return CallStatus
*/
public CallStatus getStatus();
/**
* @return a human readble String with the start date/time of the call
* A human readable String with the start date/time of the call
* @return String
*/
public String getStartDate();
/**
* @return a timestamp of the start date/time of the call in milliseconds since January 1st 1970
* A timestamp of the start date/time of the call in milliseconds since January 1st 1970
* @return long
*/
public long getTimestamp();
/**
* @return the call duration, in seconds
* The call duration, in seconds
* @return int
*/
public int getCallDuration();
/**
* @return the call id from signaling
* Call id from signaling
* @return int
*/
public int getCallId();
}
java/common/org/linphone/core/LinphoneCore.java
View file @ 08b6f466
......@@ -20,6 +20,9 @@ package org.linphone.core;
import java.util.Vector;
import org.linphone.core.LinphoneCall.State;
import org.linphone.mediastream.video.capture.hwconf.AndroidCameraConfiguration;
/**
* Linphone core main object created by method {@link LinphoneCoreFactory#createLinphoneCore(LinphoneCoreListener, String, String, Object)}.
*
......@@ -172,11 +175,22 @@ public interface LinphoneCore {
}
/**
* Signaling transports ports.
* Linphone core SIP transport ports.
* Use with {@link LinphoneCore#setSignalingTransportPorts(Transports)}
* @ingroup initializing
*/
static public class Transports {
/**
* udp port to listening on, negative value if not set
* */
public int udp;
/**
* tcp port to listening on, negative value if not set
* */
public int tcp;
/**
* tls port to listening on, negative value if not set
* */
public int tls;
public Transports() {};
......@@ -389,10 +403,10 @@ public interface LinphoneCore {
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.
*<br>The LinphoneAddress can be constructed directly using {@link LinphoneCoreFactory#createLinphoneAddress} , or created {@link LinphoneCore#interpretUrl(String)}. .
* @param to the destination of the call (sip address).
* @return LinphoneCall
* @throws LinphoneCoreException
* @return linphone call
* @throws LinphoneCoreException if linphone call cannot be created
*/
public LinphoneCall invite(LinphoneAddress to)throws LinphoneCoreException;
/**
......@@ -402,6 +416,8 @@ public interface LinphoneCore {
public void terminateCall(LinphoneCall aCall);
/**
* Declines an incoming call, providing a reason for declining it.
* @param call the LinphoneCall, must be in the {@link LinphoneCall.State#IncomingReceived} state.
* @param reason the reason for rejecting the call: {@link Reason#Declined} or {@link Reason#Busy}
*/
public void declineCall(LinphoneCall aCall, Reason reason);
/**
......@@ -417,7 +433,7 @@ public interface LinphoneCore {
public LinphoneAddress getRemoteAddress();
/**
*
* @return TRUE if there is a call running or pending.
* @return true if there is a call running or pending.
*/
public boolean isIncall();
/**
......@@ -482,8 +498,6 @@ public interface LinphoneCore {
*/
public void deferCallUpdate(LinphoneCall aCall) throws LinphoneCoreException;
public void startRinging();
/**
* @return a list of LinphoneCallLog
*/
......@@ -499,7 +513,7 @@ public interface LinphoneCore {
*/
public void setNetworkReachable(boolean isReachable);
/**
*
* Get network state has known by {@link LinphoneCore}
* @return if false, there is no network connection.
*/
public boolean isNetworkReachable();
......@@ -541,16 +555,16 @@ public interface LinphoneCore {
/**
* Initiate a dtmf signal if in call
* @param number
* @param send dtmf ['0'..'9'] | '#', '*'
*/
void sendDtmf(char number);
/**
* Initiate a dtmf signal to the speaker if not in call.
* Sending of the DTMF is done in another function.
* @param number
* @param dtmf ['0'..'9'] | '#', '*'
* @param duration in ms , -1 for unlimited
*/
void playDtmf(char number,int duration);
void playDtmf(char dtmf,int duration);
/**
* stop current dtmf
*/
......@@ -560,23 +574,43 @@ public interface LinphoneCore {
* remove all call logs
*/
void clearCallLogs();
/***
* get payload type from mime type, clock rate, and number of channels.-
*
* return null if not found
*/
/**
* Get payload type from mime type and clock rate
*
* This function searches in audio and video codecs for the given payload type name and clockrate.
* @param mime payload mime type (I.E SPEEX, PCMU, VP8)
* @param clockRate (I.E 8000, 16000, 90000, ...)
* @param channels number of channels
* @return Returns null if not found.
*/
PayloadType findPayloadType(String mime, int clockRate, int channels);
/***
* get payload type from mime type and clock rate..
*
* return null if not found
* Same as @{link {@link #findPayloadType(String, int, int)} but ignoring channels params
* @param mime payload mime type (I.E SPEEX, PCMU, VP8)
* @param clockRate (I.E 8000, 16000, 90000, ...)
* @return null if not found
*/
PayloadType findPayloadType(String mime, int clockRate);
/***
* get payload type from mime type
* Same as @{link {@link #findPayloadType(String, int, int)} but ignoring channels and clock rate params
* @param mime payload mime type (I.E SPEEX, PCMU, VP8)
* @return null if not found
*/
PayloadType findPayloadType(String mime);
/**
* not implemented yet
* @param pt
* @param enable
* @throws LinphoneCoreException
* Enable payload type
* @param pt payload type to enable, can be retrieve from {@link #findPayloadType}
* @param true if enabled
* @exception LinphoneCoreException
*
*/
void enablePayloadType(PayloadType pt, boolean enable) throws LinphoneCoreException;
/**
......@@ -595,10 +629,11 @@ public interface LinphoneCore {
*/
boolean isEchoLimiterEnabled();
/**
* @param transports used for signaling (TCP, UDP and TLS)
* Set transport ports linphone core will listen on
* @param local transports ports used for signaling (TCP, UDP and TLS)
*/
void setSignalingTransportPorts(Transports transports);
/**
/**Get
* @return transports used for signaling (TCP, UDP, TLS)
*/
Transports getSignalingTransportPorts();
......@@ -632,12 +667,36 @@ public interface LinphoneCore {
* @return {@link LinphoneChatRoom} where messaging can take place.
*/
LinphoneChatRoom createChatRoom(String to);
/**
* Set the native video window id where the video is to be displayed.
* On Android, it must be of type {@link AndroidVideoWindowImpl}
* @param video window of type {@link AndroidVideoWindowImpl}
**/
void setVideoWindow(Object w);
/**
* Set the native video window id where the video preview is to be displayed.
* On Android, it must of type {@link SurfaceView}
* @param video window of type {@link SurfaceView}
**/
void setPreviewWindow(Object w);
/**
* Tells the core the device current orientation. This can be used by capture filters
* on mobile devices to select between portrait/landscape mode and to produce properly
* oriented images. The exact meaning of the value in rotation if left to each device
* specific implementations.
*@param rotation . Android supported values are 0, 90, 180 and 270.
*
**/
void setDeviceRotation(int rotation);
/**
* Sets the active video device.
*
* @param id of the video device as returned by {@link AndroidCameraConfiguration#retrieveCameras}
**/
void setVideoDevice(int id);
/**
* Returns the id of the currently active video device as found in {@link AndroidCameraConfiguration#retrieveCameras}.
**/
int getVideoDevice();
/**
......@@ -665,6 +724,7 @@ public interface LinphoneCore {
*/
void setStunServer(String stun_server);
/**
* Get STUN server
* @return stun server address if previously set.
*/
String getStunServer();
......@@ -678,11 +738,35 @@ public interface LinphoneCore {
* @return previously set firewall policy.
*/
FirewallPolicy getFirewallPolicy();
/**
* Initiates an outgoing call given a destination LinphoneAddress
*
* @param addr the destination of the call {@link #LinphoneAddress }.
* @param params call parameters {@link #LinphoneCallParams }
*
*<br>The LinphoneAddress can be constructed directly using {@link LinphoneCoreFactory#createLinphoneAddress} , or created {@link LinphoneCore#interpretUrl(String)}. .
*
* @return a {@link #LinphoneCall LinphoneCall} object
* @throws LinphoneCoreException in case of failure
**/
LinphoneCall inviteAddressWithParams(LinphoneAddress destination, LinphoneCallParams params) throws LinphoneCoreException ;
/**
* Updates a running call according to supplied call parameters or parameters changed in the LinphoneCore.
*
* In this version this is limited to the following use cases:
* - setting up/down the video stream according to the video parameter of the {@link LinphoneCallParams} (see {@link LinphoneCallParams#enableVideo} ).
* - changing the size of the transmitted video after calling {@link LinphoneCore#setPreferredVideoSize(VideoSize)}
*
* In case no changes are requested through the {@link LinphoneCallParams} argument, then this argument can be omitted and set to null.
* @param call the {@link LinphoneCall} to be updated
* @param params the new {@link LinphoneCallParams call parameters} to use. (may be NULL)
* @return 0 if successful, -1 otherwise.
**/
int updateCall(LinphoneCall call, LinphoneCallParams params);
/**
* Get default call parameters reflecting current linphone core configuration
* @return LinphoneCallParams
*/
LinphoneCallParams createDefaultCallParameters();
/**
......@@ -694,7 +778,7 @@ public interface LinphoneCore {
/**
* gets the path to a wav file used for ringing.
*
* @param null if not set
* @return null if not set
*/
String getRing();
......@@ -706,7 +790,18 @@ public interface LinphoneCore {
void setRootCA(String path);
void setUploadBandwidth(int bw);
/**
* Sets maximum available download bandwidth
*
*
* This is IP bandwidth, in kbit/s.
* This information is used signaled to other parties during
* calls (within SDP messages) so that the remote end can have
* sufficient knowledge to properly configure its audio & video
* codec output bitrate to not overflow available bandwidth.
*
* @param bw the bandwidth in kbits/s, 0 for infinite
*/
void setDownloadBandwidth(int bw);
/**
......@@ -720,9 +815,20 @@ public interface LinphoneCore {
* @param ptime packetization interval in milliseconds
*/
void setUploadPtime(int ptime);
/**
* Sets the preferred video size.
*
* This applies only to the stream that is captured and sent to the remote party,
* since we accept all standard video size on the receive path.
* @param vSize
*
**/
void setPreferredVideoSize(VideoSize vSize);
/**
* get current preferred video size for sending.
* @return video size
*
**/
VideoSize getPreferredVideoSize();
/**
......@@ -766,13 +872,18 @@ public interface LinphoneCore {
void adjustSoftwareVolume(int i);
/**
* Pause a call.
* Pauses a call. If a music file has been setup using {@link LinphoneCore#setPlayFile(String)},
* this file will be played to the remote user.
*
**/
boolean pauseCall(LinphoneCall call);
/**
* Resume a call.
**/
boolean resumeCall(LinphoneCall call);
/**
* Pause all currently running calls.
**/
boolean pauseAllCalls();
void setZrtpSecretsCache(String file);
......@@ -783,33 +894,75 @@ public interface LinphoneCore {
**/
boolean isInConference();
/**
* Connect the local user to the conference.
* Moves the local participant inside the conference.
*
* Makes the local participant to join the conference.
* Typically, the local participant is by default always part of the conference when joining an active call into a conference.
* However, by calling {@link #leaveConference()} and {@link #enterConference()} the application can decide to temporarily
* move out and in the local participant from the conference.
*
* @returns true if successful
**/
boolean enterConference();
/**
* Disconnect the local user from the conference.
* Moves the local participant out of the conference.
* When the local participant is out of the conference, the remote participants can continue to talk normally.
**/
void leaveConference();
/**
* Add an established call to the conference. The LinphoneCore is able to manage one client based conference.
* Merge a call into a conference.
*
* If this is the first call that enters the conference, the virtual conference will be created automatically.
* If the local user was actively part of the call (ie not in paused state), then the local user is automatically entered into the conference.
* If the call was in paused state, then it is automatically resumed when entering into the conference.
* @param call an established call, either in {@link LinphoneCall.State#StreamsRunning} or {@link LinphoneCall.State#Paused} state.
*
**/
void addToConference(LinphoneCall call);
/**
* Remove an established call from the conference.
**/
* Remove a call from the conference.
* @param call a call that has been previously merged into the conference.
*
* After removing the remote participant belonging to the supplied call, the call becomes a normal call in paused state.
* If one single remote participant is left alone together with the local user in the conference after the removal, then the conference is
* automatically transformed into a simple call in StreamsRunning state.
* The conference's resources are then automatically destroyed.
*
* In other words, unless {@link #leaveConference()} is explicitely called, the last remote participant of a conference is automatically
* put in a simple call in running state.
*
**/
void removeFromConference(LinphoneCall call);
/**
* Add all calls into a conference.
*
* Merge all established calls (either in {@link LinphoneCall.State#StreamsRunning} or {@link LinphoneCall.State#Paused}) into a conference.
*
**/
void addAllToConference();
/**
* Terminate the conference, all users are disconnected.
* Terminates the conference and the calls associated with it.