Liblinphone  3.12.0
Macros | Typedefs | Functions
Call misc

Obtaining information about a running call: sound volumes, quality indicators. More...

Macros

#define LINPHONE_CALL_STATS_AUDIO   ((int)LinphoneStreamTypeAudio)
 
#define LINPHONE_CALL_STATS_VIDEO   ((int)LinphoneStreamTypeVideo)
 
#define LINPHONE_CALL_STATS_TEXT   ((int)LinphoneStreamTypeText)
 
#define LINPHONE_CALL_STATS_RECEIVED_RTCP_UPDATE   (1 << 0)
 received_rtcp field of LinphoneCallStats object has been updated
 
#define LINPHONE_CALL_STATS_SENT_RTCP_UPDATE   (1 << 1)
 sent_rtcp field of LinphoneCallStats object has been updated
 
#define LINPHONE_CALL_STATS_PERIODICAL_UPDATE   (1 << 2)
 Every seconds LinphoneCallStats object has been updated.
 
#define LINPHONE_VOLUME_DB_LOWEST   (-120) /* WARNING: keep this in sync with mediastreamer2/msvolume.h */
 Lowest volume measurement that can be returned by linphone_call_get_play_volume() or linphone_call_get_record_volume(), corresponding to pure silence.
 

Typedefs

typedef struct _LinphoneCallStats LinphoneCallStats
 The LinphoneCallStats objects carries various statistic informations regarding quality of audio or video streams. More...
 

Functions

LinphoneChatRoomlinphone_call_get_chat_room (LinphoneCall *call)
 Create a new chat room for messaging from a call if not already existing, else return existing one. More...
 
float linphone_call_get_play_volume (LinphoneCall *call)
 Get the mesured playback volume level (received from remote) in dbm0. More...
 
float linphone_call_get_record_volume (LinphoneCall *call)
 Get the mesured record volume level (sent to remote) in dbm0. More...
 
float linphone_call_get_speaker_volume_gain (const LinphoneCall *call)
 Get speaker volume gain. More...
 
void linphone_call_set_speaker_volume_gain (LinphoneCall *call, float volume)
 Set speaker volume gain. More...
 
float linphone_call_get_microphone_volume_gain (const LinphoneCall *call)
 Get microphone volume gain. More...
 
void linphone_call_set_microphone_volume_gain (LinphoneCall *call, float volume)
 Set microphone volume gain. More...
 
float linphone_call_get_current_quality (LinphoneCall *call)
 Obtain real-time quality rating of the call. More...
 
float linphone_call_get_average_quality (LinphoneCall *call)
 Returns call quality averaged over all the duration of the call. More...
 
void linphone_call_start_recording (LinphoneCall *call)
 Start call recording. More...
 
void linphone_call_stop_recording (LinphoneCall *call)
 Stop call recording.
 
LinphonePlayerlinphone_call_get_player (LinphoneCall *call)
 Get a player associated with the call to play a local file and stream it to the remote peer. More...
 
bool_t linphone_call_media_in_progress (LinphoneCall *call)
 Indicates whether an operation is in progress at the media side. More...
 
void linphone_call_ogl_render (const LinphoneCall *call)
 Call generic OpenGL render for a given call. More...
 
LinphoneStatus linphone_call_send_info_message (LinphoneCall *call, const LinphoneInfoMessage *info)
 Send a LinphoneInfoMessage through an established call. More...
 
LinphoneCallStatslinphone_call_get_stats (LinphoneCall *call, LinphoneStreamType type)
 Return a copy of the call statistics for a particular stream type. More...
 
LinphoneCallStatslinphone_call_get_audio_stats (LinphoneCall *call)
 
LinphoneCallStatslinphone_call_get_video_stats (LinphoneCall *call)
 
LinphoneCallStatslinphone_call_get_text_stats (LinphoneCall *call)
 
void linphone_call_add_callbacks (LinphoneCall *call, LinphoneCallCbs *cbs)
 Add a listener in order to be notified of LinphoneCall events. More...
 
void linphone_call_remove_callbacks (LinphoneCall *call, LinphoneCallCbs *cbs)
 Remove a listener from a LinphoneCall. More...
 
LinphoneCallCbslinphone_call_get_current_callbacks (const LinphoneCall *call)
 Gets the current LinphoneCallCbs. More...
 
void linphone_call_set_params (LinphoneCall *call, const LinphoneCallParams *params)
 Set call parameters - advanced and not recommended feature - use with caution. More...
 
const LinphoneCallParamslinphone_call_get_params (LinphoneCall *call)
 Returns local parameters associated with the call. More...
 
LinphoneStreamType linphone_call_stats_get_type (const LinphoneCallStats *stats)
 Get the type of the stream the stats refer to. More...
 
float linphone_call_stats_get_sender_loss_rate (const LinphoneCallStats *stats)
 Get the local loss rate since last report. More...
 
float linphone_call_stats_get_receiver_loss_rate (const LinphoneCallStats *stats)
 Gets the remote reported loss rate since last report. More...
 
float linphone_call_stats_get_local_loss_rate (const LinphoneCallStats *stats)
 Get the local loss rate since last report. More...
 
float linphone_call_stats_get_local_late_rate (const LinphoneCallStats *stats)
 Gets the local late rate since last report. More...
 
float linphone_call_stats_get_sender_interarrival_jitter (const LinphoneCallStats *stats)
 Gets the local interarrival jitter. More...
 
float linphone_call_stats_get_receiver_interarrival_jitter (const LinphoneCallStats *stats)
 Gets the remote reported interarrival jitter. More...
 
const rtp_stats_t * linphone_call_stats_get_rtp_stats (const LinphoneCallStats *stats)
 
uint64_t linphone_call_stats_get_late_packets_cumulative_number (const LinphoneCallStats *stats)
 Gets the cumulative number of late packets. More...
 
float linphone_call_stats_get_download_bandwidth (const LinphoneCallStats *stats)
 Get the bandwidth measurement of the received stream, expressed in kbit/s, including IP/UDP/RTP headers. More...
 
float linphone_call_stats_get_upload_bandwidth (const LinphoneCallStats *stats)
 Get the bandwidth measurement of the sent stream, expressed in kbit/s, including IP/UDP/RTP headers. More...
 
LinphoneIceState linphone_call_stats_get_ice_state (const LinphoneCallStats *stats)
 Get the state of ICE processing. More...
 
LinphoneUpnpState linphone_call_stats_get_upnp_state (const LinphoneCallStats *stats)
 Get the state of uPnP processing. More...
 
LinphoneAddressFamily linphone_call_stats_get_ip_family_of_remote (const LinphoneCallStats *stats)
 Get the IP address family of the remote peer. More...
 
float linphone_call_stats_get_jitter_buffer_size_ms (const LinphoneCallStats *stats)
 Get the jitter buffer size in ms. More...
 
float linphone_call_stats_get_round_trip_delay (const LinphoneCallStats *stats)
 Get the round trip delay in s. More...
 

Detailed Description

Obtaining information about a running call: sound volumes, quality indicators.

When a call is running, it is possible to retrieve in real time current measured volumes and quality indicator.

Typedef Documentation

◆ LinphoneCallStats

typedef struct _LinphoneCallStats LinphoneCallStats

The LinphoneCallStats objects carries various statistic informations regarding quality of audio or video streams.

To receive these informations periodically and as soon as they are computed, the application is invited to place a LinphoneCoreCallStatsUpdatedCb callback in the LinphoneCoreVTable structure it passes for instanciating the LinphoneCore object (see linphone_core_new() ).

At any time, the application can access last computed statistics using linphone_call_get_audio_stats() or linphone_call_get_video_stats().

Function Documentation

◆ linphone_call_add_callbacks()

void linphone_call_add_callbacks ( LinphoneCall call,
LinphoneCallCbs cbs 
)

Add a listener in order to be notified of LinphoneCall events.

Once an event is received, registred LinphoneCallCbs are invoked sequencially.

Parameters
[in]callLinphoneCall object to monitor.
[in]cbsA LinphoneCallCbs object holding the callbacks you need. A reference is taken by the LinphoneCall until you invoke linphone_call_remove_callbacks().

◆ linphone_call_get_average_quality()

float linphone_call_get_average_quality ( LinphoneCall call)

Returns call quality averaged over all the duration of the call.

See linphone_call_get_current_quality() for more details about quality measurement.

◆ linphone_call_get_chat_room()

LinphoneChatRoom* linphone_call_get_chat_room ( LinphoneCall call)

Create a new chat room for messaging from a call if not already existing, else return existing one.

No reference is given to the caller: the chat room will be deleted when the call is ended.

Parameters
callLinphoneCall object
Returns
LinphoneChatRoom where messaging can take place.

◆ linphone_call_get_current_callbacks()

LinphoneCallCbs* linphone_call_get_current_callbacks ( const LinphoneCall call)

Gets the current LinphoneCallCbs.

This is meant only to be called from a callback to be able to get the user_data associated with the LinphoneCallCbs that is calling the callback.

Parameters
[in]callLinphoneCall object
Returns
The LinphoneCallCbs that has called the last callback

◆ linphone_call_get_current_quality()

float linphone_call_get_current_quality ( LinphoneCall call)

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

Returns
The function returns -1 if no quality measurement is available, for example if no active audio stream exist. Otherwise it returns the quality rating.

◆ linphone_call_get_microphone_volume_gain()

float linphone_call_get_microphone_volume_gain ( const LinphoneCall call)

Get microphone volume gain.

If the sound backend supports it, the returned gain is equal to the gain set with the system mixer.

Parameters
callThe call.
Returns
double Percenatge of the max supported volume gain. Valid values are in [ 0.0 : 1.0 ]. In case of failure, a negative value is returned

◆ linphone_call_get_params()

const LinphoneCallParams* linphone_call_get_params ( LinphoneCall call)

Returns local parameters associated with the call.

This is typically the parameters passed at call initiation to linphone_core_invite_address_with_params() or linphone_call_accept_with_params(), or some default parameters if no LinphoneCallParams was explicitely passed during call initiation.

Parameters
callthe LinphoneCall object
Returns
the call's local parameters.

◆ linphone_call_get_play_volume()

float linphone_call_get_play_volume ( LinphoneCall call)

Get the mesured playback volume level (received from remote) in dbm0.

Parameters
callThe call.
Returns
float Volume level in percentage.

◆ linphone_call_get_player()

LinphonePlayer* linphone_call_get_player ( LinphoneCall call)

Get a player associated with the call to play a local file and stream it to the remote peer.

Parameters
[in]callLinphoneCall object
Returns
A LinphonePlayer object

◆ linphone_call_get_record_volume()

float linphone_call_get_record_volume ( LinphoneCall call)

Get the mesured record volume level (sent to remote) in dbm0.

Parameters
callThe call.
Returns
float Volume level in percentage.

◆ linphone_call_get_speaker_volume_gain()

float linphone_call_get_speaker_volume_gain ( const LinphoneCall call)

Get speaker volume gain.

If the sound backend supports it, the returned gain is equal to the gain set with the system mixer.

Parameters
callThe call.
Returns
Percenatge of the max supported volume gain. Valid values are in [ 0.0 : 1.0 ]. In case of failure, a negative value is returned

◆ linphone_call_get_stats()

LinphoneCallStats* linphone_call_get_stats ( LinphoneCall call,
LinphoneStreamType  type 
)

Return a copy of the call statistics for a particular stream type.

Parameters
callthe call
typethe stream type

◆ linphone_call_media_in_progress()

bool_t linphone_call_media_in_progress ( LinphoneCall call)

Indicates whether an operation is in progress at the media side.

It can be a bad idea to initiate signaling operations (adding video, pausing the call, removing video, changing video parameters) while the media is busy in establishing the connection (typically ICE connectivity checks). It can result in failures generating loss of time in future operations in the call. Applications are invited to check this function after each call state change to decide whether certain operations are permitted or not.

Parameters
callthe call
Returns
TRUE if media is busy in establishing the connection, FALSE otherwise.

◆ linphone_call_ogl_render()

void linphone_call_ogl_render ( const LinphoneCall call)

Call generic OpenGL render for a given call.

Parameters
callThe call.

◆ linphone_call_remove_callbacks()

void linphone_call_remove_callbacks ( LinphoneCall call,
LinphoneCallCbs cbs 
)

Remove a listener from a LinphoneCall.

Parameters
[in]callLinphoneCall object
[in]cbsLinphoneCallCbs object to remove.

◆ linphone_call_send_info_message()

LinphoneStatus linphone_call_send_info_message ( LinphoneCall call,
const LinphoneInfoMessage info 
)

Send a LinphoneInfoMessage through an established call.

Parameters
callthe call
infothe info message

◆ linphone_call_set_microphone_volume_gain()

void linphone_call_set_microphone_volume_gain ( LinphoneCall call,
float  volume 
)

Set microphone volume gain.

If the sound backend supports it, the new gain will synchronized with the system mixer.

Parameters
callThe call.
volumePercentage of the max supported gain. Valid values are in [ 0.0 : 1.0 ].

◆ linphone_call_set_params()

void linphone_call_set_params ( LinphoneCall call,
const LinphoneCallParams params 
)

Set call parameters - advanced and not recommended feature - use with caution.

Local call parameters applicable to an outgoing or incoming shall usually be passed to linphone_core_invite_address_with_params() or linphone_call_accept_with_params(). However, in some cases it might be desirable from a software design standpoint to modify local parameters outside of the application layer, typically in the purpose of implementing a custom logic including special headers in INVITE or 200Ok requests, driven by a call_state_changed listener method. This function accepts to assign a new LinphoneCallParams only in LinphoneCallOutgoingInit and LinphoneCallIncomingReceived states.

Parameters
callthe LinphoneCall object

◆ linphone_call_set_speaker_volume_gain()

void linphone_call_set_speaker_volume_gain ( LinphoneCall call,
float  volume 
)

Set speaker volume gain.

If the sound backend supports it, the new gain will synchronized with the system mixer.

Parameters
callThe call.
volumePercentage of the max supported gain. Valid values are in [ 0.0 : 1.0 ].

◆ linphone_call_start_recording()

void linphone_call_start_recording ( LinphoneCall call)

Start call recording.

The output file where audio is recorded must be previously specified with linphone_call_params_set_record_file().

◆ linphone_call_stats_get_download_bandwidth()

float linphone_call_stats_get_download_bandwidth ( const LinphoneCallStats stats)

Get the bandwidth measurement of the received stream, expressed in kbit/s, including IP/UDP/RTP headers.

Parameters
[in]statsLinphoneCallStats object
Returns
The bandwidth measurement of the received stream in kbit/s.

◆ linphone_call_stats_get_ice_state()

LinphoneIceState linphone_call_stats_get_ice_state ( const LinphoneCallStats stats)

Get the state of ICE processing.

Parameters
[in]statsLinphoneCallStats object
Returns
The state of ICE processing.

◆ linphone_call_stats_get_ip_family_of_remote()

LinphoneAddressFamily linphone_call_stats_get_ip_family_of_remote ( const LinphoneCallStats stats)

Get the IP address family of the remote peer.

Parameters
[in]statsLinphoneCallStats object
Returns
The IP address family of the remote peer.

◆ linphone_call_stats_get_jitter_buffer_size_ms()

float linphone_call_stats_get_jitter_buffer_size_ms ( const LinphoneCallStats stats)

Get the jitter buffer size in ms.

Parameters
[in]statsLinphoneCallStats object
Returns
The jitter buffer size in ms.

◆ linphone_call_stats_get_late_packets_cumulative_number()

uint64_t linphone_call_stats_get_late_packets_cumulative_number ( const LinphoneCallStats stats)

Gets the cumulative number of late packets.

Parameters
[in]statsLinphoneCallStats object
Returns
The cumulative number of late packets

◆ linphone_call_stats_get_local_late_rate()

float linphone_call_stats_get_local_late_rate ( const LinphoneCallStats stats)

Gets the local late rate since last report.

Returns
The local late rate

◆ linphone_call_stats_get_local_loss_rate()

float linphone_call_stats_get_local_loss_rate ( const LinphoneCallStats stats)

Get the local loss rate since last report.

Returns
The local loss rate

◆ linphone_call_stats_get_receiver_interarrival_jitter()

float linphone_call_stats_get_receiver_interarrival_jitter ( const LinphoneCallStats stats)

Gets the remote reported interarrival jitter.

Parameters
[in]statsLinphoneCallStats object
Returns
The interarrival jitter at last received receiver report

◆ linphone_call_stats_get_receiver_loss_rate()

float linphone_call_stats_get_receiver_loss_rate ( const LinphoneCallStats stats)

Gets the remote reported loss rate since last report.

Returns
The receiver loss rate

◆ linphone_call_stats_get_round_trip_delay()

float linphone_call_stats_get_round_trip_delay ( const LinphoneCallStats stats)

Get the round trip delay in s.

Parameters
[in]statsLinphoneCallStats object
Returns
The round trip delay in s.

◆ linphone_call_stats_get_sender_interarrival_jitter()

float linphone_call_stats_get_sender_interarrival_jitter ( const LinphoneCallStats stats)

Gets the local interarrival jitter.

Parameters
[in]statsLinphoneCallStats object
Returns
The interarrival jitter at last emitted sender report

◆ linphone_call_stats_get_sender_loss_rate()

float linphone_call_stats_get_sender_loss_rate ( const LinphoneCallStats stats)

Get the local loss rate since last report.

Returns
The sender loss rate

◆ linphone_call_stats_get_type()

LinphoneStreamType linphone_call_stats_get_type ( const LinphoneCallStats stats)

Get the type of the stream the stats refer to.

Parameters
[in]statsLinphoneCallStats object
Returns
The type of the stream the stats refer to

◆ linphone_call_stats_get_upload_bandwidth()

float linphone_call_stats_get_upload_bandwidth ( const LinphoneCallStats stats)

Get the bandwidth measurement of the sent stream, expressed in kbit/s, including IP/UDP/RTP headers.

Parameters
[in]statsLinphoneCallStats object
Returns
The bandwidth measurement of the sent stream in kbit/s.

◆ linphone_call_stats_get_upnp_state()

LinphoneUpnpState linphone_call_stats_get_upnp_state ( const LinphoneCallStats stats)

Get the state of uPnP processing.

Parameters
[in]statsLinphoneCallStats object
Returns
The state of uPnP processing.