quality_reporting.h 6.21 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
/*
linphone
Copyright (C) 2014 - Belledonne Communications, Grenoble, France

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
17
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
18 19 20 21 22
*/

#ifndef quality_reporting_h
#define quality_reporting_h

23
#include "linphone/core.h"
24
#include "c-wrapper/internal/c-sal.h"
25 26 27 28

#ifdef __cplusplus
extern "C"{
#endif
29

30 31

/**
32
 * Linphone quality report sub object storing address related information.
33
 */
34
typedef struct reporting_addr {
35
	char * id;
36 37 38
	char * ip;
	int port;
	uint32_t ssrc;
39 40 41

	char * group;
	char * mac; // optional
42 43
} reporting_addr_t;

44
/**
45
 * Linphone quality report sub object storing media metrics information as required by RFC6035.
46 47
 */

48 49 50 51 52 53 54 55 56 57
typedef struct reporting_content_metrics {
	// timestamps - mandatory
	struct {
		time_t start;
		time_t stop;
	} timestamps;

	// session description - optional
	struct {
		int payload_type;
58 59 60
		char * payload_desc;
		int sample_rate;
		int frame_duration;
61
		char * fmtp;
62
		int packet_loss_concealment;
63 64 65 66
	} session_description;

	// jitter buffet - optional
	struct {
67 68 69 70
		int adaptive;
		int nominal;
		int max;
		int abs_max;
71 72 73 74
	} jitter_buffer;

	// packet loss - optional
	struct {
75 76
		float network_packet_loss_rate;
		float jitter_buffer_discard_rate;
77 78 79 80
	} packet_loss;

	// delay - optional
	struct {
81 82 83 84 85
		int round_trip_delay;
		int end_system_delay;
		int symm_one_way_delay;
		int interarrival_jitter;
		int mean_abs_jitter;
86 87 88 89
	} delay;

	// signal - optional
	struct {
90 91
		int level;
		int noise_level;
92 93 94 95
	} signal;

	// quality estimates - optional
	struct {
96 97
		float moslq;
		float moscq;
98
	} quality_estimates;
99

100 101 102
	// custom extension
	char * user_agent;

103 104
	// for internal processing
	uint8_t rtcp_xr_count; // number of RTCP XR packets received since last report, used to compute average of instantaneous parameters as stated in the RFC 6035 (4.5)
105
	uint8_t rtcp_sr_count; // number of RTCP SR packets received since last report, used to compute RTT average values in case RTCP XR voip metrics is not enabled
106

107
} reporting_content_metrics_t;
108

109 110 111 112 113

/**
 * Linphone quality report main object created by function linphone_reporting_new().
 * It contains all fields required by RFC6035
 */
114 115 116 117 118 119 120 121 122 123 124 125
typedef struct reporting_session_report {
	struct {
		char * call_id;
		char * orig_id;
		reporting_addr_t local_addr;
		reporting_addr_t remote_addr;
	} info;

	reporting_content_metrics_t local_metrics;
	reporting_content_metrics_t remote_metrics; // optional

	char * dialog_id; // optional
126

127 128 129 130 131 132 133
	// Quality of Service analyzer - custom extension
	/* This should allow us to analysis bad network conditions and quality adaptation
	on server side*/
	struct {
		char * name; /*type of the QoS analyzer used*/
		char* timestamp; /*time of each decision in seconds*/
		char* input_leg; /*input parameters' name*/
134
		char* input; /*set of inputs for each semicolon separated decision*/
135
		char* output_leg; /*output parameters' name*/
136
		char* output; /*set of outputs for each semicolon separated decision*/
137 138
	} qos_analyzer;

139 140
	// for internal processing
	time_t last_report_date;
141
	LinphoneCall *call;
142 143
} reporting_session_report_t;

144

145
typedef void (*LinphoneQualityReportingReportSendCb)(const LinphoneCall *call, SalStreamType stream_type, const LinphoneContent *content);
146

147
reporting_session_report_t * linphone_reporting_new(void);
148
void linphone_reporting_destroy(reporting_session_report_t * report);
149 150 151 152 153 154 155 156

/**
 * Fill media information about a given call. This function must be called before
 * stopping the media stream.
 * @param call #LinphoneCall object to consider
 * @param stats_type the media type (LINPHONE_CALL_STATS_AUDIO or LINPHONE_CALL_STATS_VIDEO)
 *
 */
157
void linphone_reporting_update_media_info(LinphoneCall * call, int stats_type);
158 159 160

/**
 * Fill IP information about a given call. This function must be called each
161
 * time call state is 'LinphoneCallStreamsRunning' since IP might be updated (if we
162
 * found a direct route between caller and callee for example).
163
 * When call is starting, remote IP/port might be the proxy ones to which callee is registered
164 165 166
 * @param call #LinphoneCall object to consider
 *
 */
167
void linphone_reporting_update_ip(LinphoneCall * call);
168 169

/**
170 171 172
 * Publish a session report. This function should be called when session terminates,
 * media change (codec change or session fork), session terminates due to no media packets being received.
 * @param call #LinphoneCall object to consider
173
 * @param call_term whether the call has ended or is continuing
174
 *
175
 * @return error code. 0 for success, positive value otherwise.
176
 */
177
int linphone_reporting_publish_session_report(LinphoneCall* call, bool_t call_term);
178 179 180

/**
 * Publish an interval report. This function should be used for periodic interval
181
 * @param call #LinphoneCall object to consider
182
 * @return error code. 0 for success, positive value otherwise.
183 184
 *
 */
185
int linphone_reporting_publish_interval_report(LinphoneCall* call);
186 187

/**
188
 * Update publish reports with newly sent/received RTCP-XR packets (if available).
189
 * @param call #LinphoneCall object to consider
190
 * @param stats_type the media type
191 192
 *
 */
193
void linphone_reporting_on_rtcp_update(LinphoneCall *call, SalStreamType stats_type);
194

195 196 197 198 199 200 201
/**
 * Update publish reports on call state change.
 * @param call #LinphoneCall object to consider
 *
 */
void linphone_reporting_call_state_updated(LinphoneCall *call);

202 203 204 205 206 207 208 209
/**
 * Setter of the #LinphoneQualityReportingReportSendCb callback method which is
 * notified each time a report will be submitted to the collector, if quality
 * reporting is enabled
 * @param call #LinphoneCall object to consider
 * @param cb #LinphoneQualityReportingReportSendCb callback function to notify
 *
 */
210
LINPHONE_PUBLIC void linphone_reporting_set_on_report_send(LinphoneCall *call, LinphoneQualityReportingReportSendCb cb);
211

212 213 214 215 216
#ifdef __cplusplus
}
#endif

#endif