Commit d995f3f0 authored by Sylvain Berfini's avatar Sylvain Berfini 🎩

Added comments to Cpp API

parent 876b116d
......@@ -10,17 +10,14 @@ namespace Linphone
{
ref class Globals;
// A method that is called back when the incoming call dialog has been dismissed.
// This callback is used to complete the incoming call agent.
public delegate void IncomingCallViewDismissedCallback();
// A class that provides methods and properties related to VoIP calls.
// It wraps Windows.Phone.Networking.Voip.VoipCallCoordinator, and provides app-specific call functionality.
/// <summary>
/// Provides methods and properties related to Windows.Phone.Networking.Voip.VoipPhoneCall calls.
/// </summary>
public ref class CallController sealed
{
public:
// Start processing an incoming call. Called by managed code in this process (the VoIP agent host process).
// Returns true if the incoming call processing was started, false otherwise.
bool OnIncomingCallReceived(Platform::String^ contactName, Platform::String^ contactNumber, IncomingCallViewDismissedCallback^ incomingCallViewDismissedCallback);
void EndCall(Windows::Phone::Networking::Voip::VoipPhoneCall^ call);
......@@ -37,7 +34,6 @@ namespace Linphone
Platform::String^ callerNumber;
// The relative URI to the call-in-progress page
Platform::String^ callInProgressPageUri;
// The URI to the contact image, jpg or png, 1mb max !
......@@ -52,10 +48,8 @@ namespace Linphone
IncomingCallViewDismissedCallback^ onIncomingCallViewDismissed;
// Called by the VoipCallCoordinator when the user accepts an incoming call.
void OnAcceptCallRequested(Windows::Phone::Networking::Voip::VoipPhoneCall^ sender, Windows::Phone::Networking::Voip::CallAnswerEventArgs^ args);
// Called by the VoipCallCoordinator when the user rejects an incoming call.
void OnRejectCallRequested(Windows::Phone::Networking::Voip::VoipPhoneCall^ sender, Windows::Phone::Networking::Voip::CallRejectEventArgs^ args);
Windows::Foundation::TypedEventHandler<Windows::Phone::Networking::Voip::VoipPhoneCall^, Windows::Phone::Networking::Voip::CallAnswerEventArgs^>^ acceptCallRequestedHandler;
......
......@@ -6,8 +6,14 @@ namespace Linphone
{
public interface class CallControllerListener
{
/// <summary>
/// Called when a call is started (incoming or outgoing), after the creation of the VoipPhoneCall.
/// </summary>
void NewCallStarted(Platform::String^ callerNumber);
/// <summary>
/// Called when a call is terminated, after the VoipPhoneCall->NotifyCallEnded();
/// </summary>
void CallEnded();
};
}
......
......@@ -71,6 +71,7 @@
<AdditionalUsingDirectories>$(WindowsSDK_WindowsMetadata);$(AdditionalUsingDirectories)</AdditionalUsingDirectories>
<CompileAsWinRT Condition="'$(Configuration)|$(Platform)'=='Debug|ARM'">true</CompileAsWinRT>
<CompileAsWinRT Condition="'$(Configuration)|$(Platform)'=='Release|ARM'">true</CompileAsWinRT>
<GenerateXMLDocumentationFiles Condition="'$(Configuration)|$(Platform)'=='Debug|ARM'">true</GenerateXMLDocumentationFiles>
</ClCompile>
<Link>
<SubSystem>Console</SubSystem>
......
......@@ -10,21 +10,22 @@ namespace Linphone
ref class LinphoneCoreFactory;
ref class LinphoneCore;
// A singleton container that is used to hold other global singletons and background process-wide static state.
// Another purpose of this class is to start the out-of-process WinRT server, so that the UI process
// managed code can instantiate WinRT objects in this process.
/// <summary>
/// Singleton container used to hold global singletons and background process-wide objects.
/// Also used to start out of process server, allowing the UI process managed code to instantiate WinRT objects in this process.
/// </summary>
public ref class Globals sealed
{
public:
// Start the out-of-process WinRT server, so that the UI process can instantiate WinRT objects in this process.
/// <summary>
/// Starts the out of process server, allowing the UI process to instantiate WinRT objects in this process.
/// </summary>
void StartServer(const Platform::Array<Platform::String^>^ outOfProcServerClassNames);
static unsigned int GetCurrentProcessId();
// Get the name of the event that indicates if the UI is connected to the background process or not
static Platform::String^ GetUiDisconnectedEventName(unsigned int backgroundProcessId);
// Get the name of the event that indicates if the background process is ready or not
static Platform::String^ GetBackgroundProcessReadyEventName(unsigned int backgroundProcessId);
static property Globals^ Instance
......@@ -51,13 +52,10 @@ namespace Linphone
Globals();
~Globals();
// Name of the event that indicates if another instance of the VoIP background process exists or not
static const LPCWSTR noOtherBackgroundProcessEventName;
// Name of the event that indicates if the UI is connected to the background process or not
static const LPCWSTR uiDisconnectedEventName;
// Name of the event that indicates if the background process is ready or not
static const LPCWSTR backgroundProcessReadyEventName;
static Globals^ singleton;
......@@ -67,10 +65,8 @@ namespace Linphone
// A cookie that is used to unregister remotely activatable objects in this process
RO_REGISTRATION_COOKIE serverRegistrationCookie;
// An event that indicates if another instance of the background process exists or not
HANDLE noOtherBackgroundProcessEvent;
// An event that indicates that the background process is ready
HANDLE backgroundReadyEvent;
Linphone::Core::CallController^ callController;
......
......@@ -4,12 +4,44 @@ namespace Linphone
{
namespace Core
{
/// <summary>
/// Object that represents a SIP address.
/// It's an opaque object that represents a SIP address, i.e. the content of SIP's "from" and "to" headers.
/// A SIP address is made of a display name, username, domain, port and various URI headers(such as tags).
/// It looks like "Alice &lt;sip:alice@example.net&gt;". 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 method return null.
/// </summary>
/// <example>
/// Can be instancied using
/// <code>
/// LinphoneAddress addr = LinphoneCoreFactory.CreateLinphoneAddress("sip:alice@example.net");
/// </code>
/// or
/// <code>
/// LinphoneAddress addr = LinphoneCoreFactory.CreateLinphoneAddress("alice", "example.net", "Alice B.");
/// </code>
/// </example>
public ref class LinphoneAddress sealed
{
public:
/// <summary>
/// Human display name
/// </summary>
/// <returns>
/// null if not set
/// </returns>
Platform::String^ GetDisplayName();
/// <returns>
/// null if not set
/// </returns>
Platform::String^ GetUserName();
/// <returns>
/// null if not set
/// </returns>
Platform::String^ GetDomain();
int GetPort();
void SetDisplayName(Platform::String^ name);
......@@ -18,8 +50,20 @@ namespace Linphone
void SetPort(int port);
void Clean();
/// <returns>
/// the address as a string
/// </returns>
Platform::String^ AsString();
/// <returns>
/// the address without display name as a string
/// </returns>
Platform::String^ AsStringUriOnly();
/// <summary>
/// Same as AsString.
/// </summary>
Platform::String^ ToString();
};
}
......
......@@ -4,14 +4,29 @@ namespace Linphone
{
namespace Core
{
/// <summary>
/// Object holding authentication information.
/// In most cases, authentication information consists in an username and a password.
/// Sometimes, a userid is required by the proxy, and realm can be useful to discriminate different SIP domains.
/// This object is instanciated using LinphoneCoreFactory::CreateAuthInfo.
/// Once created and filled, a LinphoneAuthInfo must be added to the LinphoneCore in order to become known and used automatically when needed.
/// The LinphoneCore object can take the initiative to request authentication information when needed in the application through the LinphoneCoreListener::AuthInfoRequested listener.
/// The application can respond to this information request later using LinphoneCore::AddAuthInfo.
/// This will unblock all pending authentication transactions and retry them with authentication headers.
/// </summary>
public ref class LinphoneAuthInfo sealed
{
public:
Platform::String^ GetUsername();
void SetUsername(Platform::String^ username);
Platform::String^ GetPassword();
void SetPassword(Platform::String^ password);
Platform::String^ GetRealm();
void SetRealm(Platform::String^ realm);
};
}
......
......@@ -63,7 +63,7 @@ Platform::Boolean LinphoneCall::IsEchoLimiterEnabled()
return false;
}
int LinphoneCall::GetDuraction()
int LinphoneCall::GetDuration()
{
return -1;
}
......
......@@ -11,6 +11,9 @@ namespace Linphone
ref class LinphoneCallStats;
ref class LinphoneCallParams;
/// <summary>
/// Linphone call states
/// </summary>
public enum class LinphoneCallState : int
{
Idle = 0,
......@@ -34,6 +37,10 @@ namespace Linphone
Released = 18
};
/// <summary>
/// Object representing a call.
/// Calls are create using LinphoneCore::Invite or passed to the application by the listener LinphoneCoreListener::CallState.
/// </summary>
public ref class LinphoneCall sealed
{
public:
......@@ -42,6 +49,10 @@ namespace Linphone
CallDirection GetDirection();
LinphoneCallLog^ GetCallLog();
LinphoneCallStats^ GetAudioStats();
/// <summary>
/// This is usefull for example to know if far end supports video or encryption.
/// </summary>
LinphoneCallParams^ GetRemoteParams();
LinphoneCallParams^ GetCurrentParamsCopy();
......@@ -49,12 +60,52 @@ namespace Linphone
Platform::Boolean IsEchoCancellationEnabled();
void EnableEchoLimiter(Platform::Boolean enable);
Platform::Boolean IsEchoLimiterEnabled();
int GetDuraction();
int GetDuration();
/// <summary>
/// Obtain real time quality rating of the call.
/// Based on local RTP statistics and RTCP feedback, a quality rating is computed and updated during all the duration of the call.
/// This function returns its value at the time of the function call.
/// It is expected that the rating is updated at least every 5 seconds or so.
/// The rating is a floating point number comprised between 0 and 5.
/// 4-5 = good quality
/// 3-4 = average quality
/// 2-3 = poor quality
/// 1-2 = very poor quality
/// 0-1 = can't be worse, mostly unusable
/// </summary>
/// <returns>
/// -1 if no quality mesurement is available, for example if no active audio stream exists. Otherwise returns the quality rating.
/// </returns>
float GetCurrentQuality();
/// <summary>
/// Returns call quality averaged over all the duration of the call.
/// See GetCurrentQuality for more details about quality mesurement.
/// </summary>
float GetAverageQuality();
/// <summary>
/// Used by ZRTP encryption mechanism.
/// </summary>
/// <returns>
/// SAS associated to the main stream [voice].
/// </returns>
Platform::String^ GetAuthenticationToken();
/// <summary>
/// Used by ZRTP mechanism.
/// SAS can verified manually by the user or automatically using a previously shared secret.
/// </summary>
/// <returns>
/// true if the main stream [voice] SAS was verified.
/// </returns>
Platform::Boolean IsAuthenticationTokenVerified();
/// <summary>
/// Used by ZRTP mechanism.
/// </summary>
/// <param name="verified">true when displayed SAS is correct</param>
void SetAuthenticationTokenVerified(Platform::Boolean verified);
Platform::Boolean IsInConference();
......
......@@ -8,6 +8,9 @@ namespace Linphone
{
ref class LinphoneAddress;
/// <summary>
/// Represents a call status
/// </summary>
public enum class LinphoneCallStatus : int
{
Success = 0,
......@@ -16,6 +19,9 @@ namespace Linphone
Declined = 3
};
/// <summary>
/// Call data records object
/// </summary>
public ref class LinphoneCallLog sealed
{
public:
......@@ -23,9 +29,25 @@ namespace Linphone
LinphoneAddress^ GetTo();
CallDirection GetDirection();
LinphoneCallStatus GetStatus();
/// <summary>
/// Returns a human readable string with the start date/time of the call.
/// </summary>
Platform::String^ GetStartDate();
/// <summary>
/// Returns a timestamp of the start date/time of the call in milliseconds elapsed since Januart 1st 1970.
/// </summary>
int64 GetTimestamp();
/// <summary>
/// Returns the call duration in seconds.
/// </summary>
int GetCallDuration();
/// <summary>
/// Returns the call id from signaling.
/// </summary>
int GetCallId();
};
}
......
......@@ -5,7 +5,7 @@
using namespace Linphone::Core;
void LinphoneCallParams::SetAudioBandwidth()
void LinphoneCallParams::SetAudioBandwidth(int value)
{
}
......
......@@ -8,13 +8,28 @@ namespace Linphone
{
ref class PayloadType;
/// <summary>
/// This object contains various call related parameters.
/// It can be used to retrieve parameters from a currently running call or modify the call's caracteristics dynamically.
/// </summary>
public ref class LinphoneCallParams sealed
{
public:
void SetAudioBandwidth();
/// <summary>
/// Sets the audio bandwidth in kbits/s.
/// </summary>
/// <param name="value">0 to disable limitation</param>
void SetAudioBandwidth(int value);
MediaEncryption GetMediaEncryption();
void SetMediaEncryption(MediaEncryption menc);
PayloadType^ GetUsedAudioCodec();
/// <summary>
/// Indicates low bandwidth mode.
/// Configuring a call to low bandwidth mode will result in the core to activate several settings for the call in order to ensure that bitrate usage is lowered to the minimum possible.
/// Tyically, ptime (packetization time) will be increased, audio codecs's output bitrate will be targetted to 20kbits/s provided that it is achievable by the codec selected after SDP handshake.
/// Video is automatically disabled.
/// </summary>
void EnableLowBandwidth(Platform::Boolean enable);
Platform::Boolean IsLowBandwidthEnabled();
};
......
......@@ -25,14 +25,33 @@ namespace Linphone
public:
MediaType GetMediaType();
IceState GetIceState();
/// <summary>
/// Gets the download bandwidth in kbits/s.
/// </summary>
float GetDownloadBandwidth();
/// <summary>
/// Gets the upload bandwidth in kbits/s.
/// </summary>
float GetUploadBandwidth();
float GetSenderLossRate();
float GetReceiverLossRate();
float GetSenderInterarrivalJitter();
float GetReceiverInterarrivalJitter();
/// <summary>
/// Gets the round trip delay in seconds.
/// </summary>
/// <returns>
/// -1 if the information is not available.
/// </returns>
float GetRoundTripDelay();
int64 GetLatePacketsCumulativeNumber();
/// <summary>
/// Gets the jitter buffer size in milliseconds.
/// </summary>
float GetJitterBufferSize();
};
}
......
......@@ -46,6 +46,11 @@ Platform::String^ Transports::ToString()
return "udp[" + udp + "] tcp[" + tcp + "] tls[" + tls + "]";
}
void LinphoneCore::SetContext(Platform::Object^ object)
{
}
void LinphoneCore::ClearProxyConfigs()
{
......
This diff is collapsed.
......@@ -28,6 +28,11 @@ namespace Linphone
LinphoneAuthInfo^ CreateAuthInfo(Platform::String^ username, Platform::String^ password, Platform::String^ realm);
LinphoneAddress^ CreateLinphoneAddress(Platform::String^ username, Platform::String^ domain, Platform::String^ displayName);
/// <summary>
/// Constructs a LinphoneAddress object by parsing the user supplied address, given as a string.
/// </summary>
/// <param name="address">address, should be like "sip:joe@sip.linphone.org"</param>
LinphoneAddress^ CreateLinphoneAddress(Platform::String^ address);
private:
......
......@@ -9,6 +9,8 @@ namespace Linphone
{
public interface class LinphoneCoreListener
{
void AuthInfoRequested(Platform::String^ realm, Platform::String^ username);
void GlobalState(GlobalState state, Platform::String^ message);
void CallState(LinphoneCall^ call, LinphoneCallState state);
......
......@@ -6,29 +6,113 @@ namespace Linphone
{
namespace Core
{
/// <summary>
/// This object represents a proxy configuration to be used by the LinphoneCore object.
/// Its fields mustn't be used directly in favour of the accessors methods.
/// Once created and filled properly, the LinphoneProxyConfig can be given to LinphoneCore using LinphoneCore::AddProxyConfig.
/// This will automatically triggers the registration if enabled.
/// The proxy configuration are persistent to restarts because they are saved in the configuration file.
/// As a consequence, after LinphoneCoreFactory::CreateLinphoneCore there might already be a default proxy that can be examined with LinphoneCore::GetDefaultProxyConfig.
/// </summary>
public ref class LinphoneProxyConfig sealed
{
public:
/// <summary>
/// Starts editing a proxy config.
/// Because proxy config must be consistent, app MUST call Edit before doing any attempts to modify proxy config (such as identity, address and so on).
/// Once modifications are done, then the app MUST call Done to commit the changes.
/// </summary>
void Edit();
/// <summary>
/// Commits changes made to the proxy config.
/// </summary>
void Done();
/// <param name="identity">
/// identity is normally formed with display name, username and domain, such as: Alice &lt;sip:alice@example.net&gt;.
/// The REGISTER messages will have from and to set to this identity.
/// </param>
void SetIdentity(Platform::String^ identity);
Platform::String^ GetIdentity();
/// <summary>
/// Sets the proxy address.
/// <example>
/// Examples of valid sip proxy are:
/// <list type="bullet">
/// <item>
/// <term>sip:87.98.157.38</term>
/// <description>IP address</description>
/// </item>
/// <item>
/// <term>sip:87.98.157.38:5062</term>
/// <description>IP address with port</description>
/// </item>
/// <item>
/// <term>sip:sip.example.net</term>
/// <description>Hostname</description>
/// </item>
/// </list>
/// </example>
/// </summary>
void SetProxy(Platform::String^ proxyUri);
/// <summary>
/// Enables register for this proxy config.
/// Register message is issued after call to Done.
/// </summary>
void EnableRegister(Platform::Boolean enable);
Platform::Boolean IsRegisterEnabled();
/// <summary>
/// Normalizes a human readable phone number into a basic string.
/// <example>
/// 888-444-222 becomes 888444222
/// </example>
/// </summary>
Platform::String^ NormalizePhoneNumber(Platform::String^ phoneNumber);
/// <summary>
/// Automatically add international prefix to e164 phone numbers
/// </summary>
void SetDialPrefix(Platform::String^ prefix);
/// <summary>
/// Sets whether Linphone should replace "+" by "00" in dialed numbers passed to LinphoneCore::Invite.
/// </summary>
void SetDialEscapePlus(Platform::Boolean value);
Platform::String^ GetDomain();
Platform::Boolean IsRegistered();
/// <summary>
/// Sets a SIP route.
/// When a route is set, all outgoing calls will go the the route's destination if this proxy is the default one (see LinphoneCore::GetDefaultProxyConfig).
/// </summary>
void SetRoute(Platform::String^ routeUri);
Platform::String^ GetRoute();
/// <summary>
/// Indicates either or not PUBLISH must be issued for this LinphoneProxyConfig.
/// </summary>
void EnablePublish(Platform::Boolean enable);
Platform::Boolean IsPublishEnabled();
RegistrationState GetState();
/// <summary>
/// Sets the registration expiration time in seconds.
/// </summary>
void SetExpires(int delay);
void SetContactParameters(Platform::String^ params);
/// <summary>
/// Returns the international prefix for the given country.
/// </summary>
int LookupCCCFromIso(Platform::String^ iso);
/// <summary>
/// Returns the international prefix for the given country.
/// </summary>
int LookupCCCFromE164(Platform::String^ e164);
};
}
......
......@@ -4,9 +4,26 @@ namespace Linphone
{
namespace Core
{
/// <summary>
/// Object used to manipulate a configuration file.
/// The format of the configuration file is a .ini like format:
/// - sections are defined in []
/// - each section contains a sequence of key=value pairs.
/// <example>
/// [sound]
/// echocanceler=1
/// playback_dev=ALSA: Default device
///
/// [video]
/// enabled=1
/// </example>
/// </summary>
public ref class LpConfig sealed
{
public:
/// <summary>
/// Sets an integer configuration item.
/// </summary>
void SetInt(Platform::String^ section, Platform::String^ key, int value);
};
}
......
No preview for this file type
......@@ -78,6 +78,7 @@
<NoConfig>true</NoConfig>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
<DocumentationFile>Bin\ARM\Debug\Linphone.XML</DocumentationFile>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|ARM' ">
<DebugType>pdbonly</DebugType>
......
......@@ -298,6 +298,11 @@ namespace Linphone.Model
#endregion
#region LinphoneCoreListener Callbacks
public void AuthInfoRequested(string realm, string username)
{
}
public void GlobalState(GlobalState state, string message)
{
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment