1 /* 2 linphone 3 Copyright (C) 2010-2014 Belledonne Communications SARL 4 5 This program is free software; you can redistribute it and/or 6 modify it under the terms of the GNU General Public License 7 as published by the Free Software Foundation; either version 2 8 of the License, or (at your option) any later version. 9 10 This program is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 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 #ifndef __LINPHONE_CALL_PARAMS_H__ 22 #define __LINPHONE_CALL_PARAMS_H__ 23 24 25 #include "linphone/types.h" 26 #include "linphone/payload_type.h" 27 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /** 34 * @addtogroup call_control 35 * @{ 36 **/ 37 38 /******************************************************************************* 39 * Public functions * 40 ******************************************************************************/ 41 42 /** 43 * Add a custom SIP header in the INVITE for a call. 44 * @param[in] cp The #LinphoneCallParams to add a custom SIP header to. 45 * @param[in] header_name The name of the header to add. 46 * @param[in] header_value The content of the header to add. 47 **/ 48 LINPHONE_PUBLIC void linphone_call_params_add_custom_header(LinphoneCallParams *cp, const char *header_name, const char *header_value); 49 50 /** 51 * Copy an existing LinphoneCallParams object to a new LinphoneCallParams object. 52 * @param[in] cp The LinphoneCallParams object to copy. 53 * @return A copy of the LinphoneCallParams object. 54 **/ 55 LINPHONE_PUBLIC LinphoneCallParams * linphone_call_params_copy(const LinphoneCallParams *cp); 56 57 /** 58 * Indicate whether sending of early media was enabled. 59 * @param[in] cp LinphoneCallParams object 60 * @return A boolean value telling whether sending of early media was enabled. 61 **/ 62 LINPHONE_PUBLIC bool_t linphone_call_params_early_media_sending_enabled(const LinphoneCallParams *cp); 63 64 /** 65 * Enable sending of real early media (during outgoing calls). 66 * @param[in] cp LinphoneCallParams object 67 * @param[in] enabled A boolean value telling whether to enable early media sending or not. 68 **/ 69 LINPHONE_PUBLIC void linphone_call_params_enable_early_media_sending(LinphoneCallParams *cp, bool_t enabled); 70 71 /** 72 * Indicate low bandwith mode. 73 * 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 74 * is lowered to the minimum possible. Typically, ptime (packetization time) will be increased, audio codec's output bitrate will be targetted to 20kbit/s provided 75 * that it is achievable by the codec selected after SDP handshake. Video is automatically disabled. 76 * @param[in] cp LinphoneCallParams object 77 * @param[in] enabled A boolean value telling whether to activate the low bandwidth mode or not. 78 **/ 79 LINPHONE_PUBLIC void linphone_call_params_enable_low_bandwidth(LinphoneCallParams *cp, bool_t enabled); 80 81 /** 82 * Enable audio stream. 83 * @param[in] cp LinphoneCallParams object 84 * @param[in] enabled A boolean value telling whether to enable audio or not. 85 **/ 86 LINPHONE_PUBLIC void linphone_call_params_enable_audio(LinphoneCallParams *cp, bool_t enabled); 87 88 /** 89 * Enable video stream. 90 * @param[in] cp LinphoneCallParams object 91 * @param[in] enabled A boolean value telling whether to enable video or not. 92 **/ 93 LINPHONE_PUBLIC void linphone_call_params_enable_video(LinphoneCallParams *cp, bool_t enabled); 94 95 /** 96 * Get a custom SIP header. 97 * @param[in] cp The #LinphoneCallParams to get the custom SIP header from. 98 * @param[in] header_name The name of the header to get. 99 * @return The content of the header or NULL if not found. 100 **/ 101 LINPHONE_PUBLIC const char *linphone_call_params_get_custom_header(const LinphoneCallParams *cp, const char *header_name); 102 103 /** 104 * Tell whether the call is part of the locally managed conference. 105 * @warning If a conference server is used to manage conferences, 106 * that function does not return TRUE even if the conference is running.<br/> 107 * If you want to test whether the conference is running, you should test 108 * whether linphone_core_get_conference() return a non-null pointer. 109 * @param[in] cp LinphoneCallParams object 110 * @return A boolean value telling whether the call is part of the locally managed conference. 111 **/ 112 LINPHONE_PUBLIC bool_t linphone_call_params_get_local_conference_mode(const LinphoneCallParams *cp); 113 114 /** 115 * Get the kind of media encryption selected for the call. 116 * @param[in] cp LinphoneCallParams object 117 * @return The kind of media encryption selected for the call. 118 **/ 119 LINPHONE_PUBLIC LinphoneMediaEncryption linphone_call_params_get_media_encryption(const LinphoneCallParams *cp); 120 121 /** 122 * Get requested level of privacy for the call. 123 * @param[in] cp LinphoneCallParams object 124 * @return The privacy mode used for the call. 125 **/ 126 LINPHONE_PUBLIC LinphonePrivacyMask linphone_call_params_get_privacy(const LinphoneCallParams *cp); 127 128 /** 129 * Get the framerate of the video that is received. 130 * @param[in] cp LinphoneCallParams object 131 * @return The actual received framerate in frames per seconds, 0 if not available. 132 */ 133 LINPHONE_PUBLIC float linphone_call_params_get_received_framerate(const LinphoneCallParams *cp); 134 135 /** 136 * Get the definition of the received video. 137 * @param[in] cp LinphoneCallParams object 138 * @return The received LinphoneVideoDefinition 139 */ 140 LINPHONE_PUBLIC const LinphoneVideoDefinition * linphone_call_params_get_received_video_definition(const LinphoneCallParams *cp); 141 142 /** 143 * Get the size of the video that is received. 144 * @param[in] cp LinphoneCallParams object 145 * @return The received video size or MS_VIDEO_SIZE_UNKNOWN if not available. 146 * @deprecated Use linphone_call_params_get_received_video_definition() instead 147 */ 148 LINPHONE_PUBLIC LINPHONE_DEPRECATED MSVideoSize linphone_call_params_get_received_video_size(const LinphoneCallParams *cp); 149 150 /** 151 * Get the path for the audio recording of the call. 152 * @param[in] cp LinphoneCallParams object 153 * @return The path to the audio recording of the call. 154 **/ 155 LINPHONE_PUBLIC const char *linphone_call_params_get_record_file(const LinphoneCallParams *cp); 156 157 /** 158 * Get the RTP profile being used. 159 * @param[in] cp #LinphoneCallParams object 160 * @return The RTP profile. 161 */ 162 LINPHONE_PUBLIC const char * linphone_call_params_get_rtp_profile(const LinphoneCallParams *cp); 163 164 /** 165 * Get the framerate of the video that is sent. 166 * @param[in] cp LinphoneCallParams object 167 * @return The actual sent framerate in frames per seconds, 0 if not available. 168 */ 169 LINPHONE_PUBLIC float linphone_call_params_get_sent_framerate(const LinphoneCallParams *cp); 170 171 /** 172 * Get the definition of the sent video. 173 * @param[in] cp LinphoneCallParams object 174 * @return The sent LinphoneVideoDefinition 175 */ 176 LINPHONE_PUBLIC const LinphoneVideoDefinition * linphone_call_params_get_sent_video_definition(const LinphoneCallParams *cp); 177 178 /** 179 * Gets the size of the video that is sent. 180 * @param[in] cp LinphoneCalParams object 181 * @return The sent video size or MS_VIDEO_SIZE_UNKNOWN if not available. 182 * @deprecated Use linphone_call_params_get_sent_video_definition() instead 183 */ 184 LINPHONE_PUBLIC LINPHONE_DEPRECATED MSVideoSize linphone_call_params_get_sent_video_size(const LinphoneCallParams *cp); 185 186 /** 187 * Get the session name of the media session (ie in SDP). 188 * Subject from the SIP message can be retrieved using linphone_call_params_get_custom_header() and is different. 189 * @param[in] cp LinphoneCallParams object 190 * @return The session name of the media session. 191 **/ 192 LINPHONE_PUBLIC const char *linphone_call_params_get_session_name(const LinphoneCallParams *cp); 193 194 /** 195 * Get the audio payload type that has been selected by a call. 196 * @param[in] cp The call. 197 * @return The selected payload type. NULL is returned if no audio payload type has been seleced 198 * by the call. 199 **/ 200 LINPHONE_PUBLIC LinphonePayloadType *linphone_call_params_get_used_audio_payload_type(const LinphoneCallParams *cp); 201 202 /** 203 * Get the video payload type that has been selected by a call. 204 * @param[in] cp The call. 205 * @return The selected payload type. NULL is returned if no video payload type has been seleced 206 * by the call. 207 **/ 208 LINPHONE_PUBLIC LinphonePayloadType *linphone_call_params_get_used_video_payload_type(const LinphoneCallParams *cp); 209 210 /** 211 * Get the text payload type that has been selected by a call. 212 * @param[in] cp The call. 213 * @return The selected payload type. NULL is returned if no text payload type has been seleced 214 * by the call. 215 **/ 216 LINPHONE_PUBLIC LinphonePayloadType *linphone_call_params_get_used_text_payload_type(const LinphoneCallParams *cp); 217 218 /** 219 * Get the audio payload type that has been selected by a call. 220 * @param[in] cp The call. 221 * @return The selected payload type. NULL is returned if no audio payload type has been seleced by the call. 222 * @deprecated Use linphone_call_params_get_used_audio_payload_type() instead. 223 * @donotwrap 224 **/ 225 LINPHONE_PUBLIC LINPHONE_DEPRECATED const OrtpPayloadType *linphone_call_params_get_used_audio_codec(const LinphoneCallParams *cp); 226 227 /** 228 * Get the video payload type that has been selected by a call. 229 * @param[in] cp The call. 230 * @return The selected payload type. NULL is returned if no video payload type has been seleced by the call. 231 * @deprecated Use linphone_call_params_get_used_video_payload_type() instead. 232 * @donotwrap 233 **/ 234 LINPHONE_PUBLIC LINPHONE_DEPRECATED const OrtpPayloadType *linphone_call_params_get_used_video_codec(const LinphoneCallParams *cp); 235 236 /** 237 * Get the text payload type that has been selected by a call. 238 * @param[in] cp The call. 239 * @return The selected payload type. NULL is returned if no text payload type has been seleced by the call. 240 * @deprecated Use linphone_call_params_get_used_text_payload_type() instead. 241 * @donotwrap 242 **/ 243 LINPHONE_PUBLIC LINPHONE_DEPRECATED const OrtpPayloadType *linphone_call_params_get_used_text_codec(const LinphoneCallParams *cp); 244 245 /** 246 * Tell whether the call has been configured in low bandwidth mode or not. 247 * This mode can be automatically discovered thanks to a stun server when activate_edge_workarounds=1 in section [net] of configuration file. 248 * An application that would have reliable way to know network capacity may not use activate_edge_workarounds=1 but instead manually configure 249 * low bandwidth mode with linphone_call_params_enable_low_bandwidth(). 250 * When enabled, this param may transform a call request with video in audio only mode. 251 * @param[in] cp LinphoneCallParams object 252 * @return A boolean value telling whether the low bandwidth mode has been configured/detected. 253 */ 254 LINPHONE_PUBLIC bool_t linphone_call_params_low_bandwidth_enabled(const LinphoneCallParams *cp); 255 256 /** 257 * Refine bandwidth settings for this call by setting a bandwidth limit for audio streams. 258 * As a consequence, codecs whose bitrates are not compatible with this limit won't be used. 259 * @param[in] cp LinphoneCallParams object 260 * @param[in] bw The audio bandwidth limit to set in kbit/s. 261 **/ 262 LINPHONE_PUBLIC void linphone_call_params_set_audio_bandwidth_limit(LinphoneCallParams *cp, int bw); 263 264 /** 265 * Set requested media encryption for a call. 266 * @param[in] cp LinphoneCallParams object 267 * @param[in] enc The media encryption to use for the call. 268 **/ 269 LINPHONE_PUBLIC void linphone_call_params_set_media_encryption(LinphoneCallParams *cp, LinphoneMediaEncryption enc); 270 271 /** 272 * Set requested level of privacy for the call. 273 * \xmlonly <language-tags>javascript</language-tags> \endxmlonly 274 * @param[in] cp LinphoneCallParams object 275 * @param[in] privacy The privacy mode to used for the call. 276 **/ 277 LINPHONE_PUBLIC void linphone_call_params_set_privacy(LinphoneCallParams *cp, LinphonePrivacyMask privacy); 278 279 /** 280 * Enable recording of the call. 281 * This function must be used before the call parameters are assigned to the call. 282 * The call recording can be started and paused after the call is established with 283 * linphone_call_start_recording() and linphone_call_pause_recording(). 284 * @param[in] cp LinphoneCallParams object 285 * @param[in] path A string containing the path and filename of the file where audio/video streams are to be written. 286 * The filename must have either .mkv or .wav extention. The video stream will be written only if a MKV file is given. 287 **/ 288 LINPHONE_PUBLIC void linphone_call_params_set_record_file(LinphoneCallParams *cp, const char *path); 289 290 /** 291 * Set the session name of the media session (ie in SDP). 292 * Subject from the SIP message (which is different) can be set using linphone_call_params_set_custom_header(). 293 * @param[in] cp LinphoneCallParams object 294 * @param[in] name The session name to be used. 295 **/ 296 LINPHONE_PUBLIC void linphone_call_params_set_session_name(LinphoneCallParams *cp, const char *name); 297 298 /** 299 * Tell whether audio is enabled or not. 300 * @param[in] cp LinphoneCallParams object 301 * @return A boolean value telling whether audio is enabled or not. 302 **/ 303 LINPHONE_PUBLIC bool_t linphone_call_params_audio_enabled(const LinphoneCallParams *cp); 304 305 /** 306 * Tell whether video is enabled or not. 307 * @param[in] cp LinphoneCallParams object 308 * @return A boolean value telling whether video is enabled or not. 309 **/ 310 LINPHONE_PUBLIC bool_t linphone_call_params_video_enabled(const LinphoneCallParams *cp); 311 312 /** 313 * Get the audio stream direction. 314 * @param[in] cp LinphoneCallParams object 315 * @return The audio stream direction associated with the call params. 316 **/ 317 LINPHONE_PUBLIC LinphoneMediaDirection linphone_call_params_get_audio_direction(const LinphoneCallParams *cp); 318 319 /** 320 * Get the video stream direction. 321 * @param[in] cp LinphoneCallParams object 322 * @return The video stream direction associated with the call params. 323 **/ 324 LINPHONE_PUBLIC LinphoneMediaDirection linphone_call_params_get_video_direction(const LinphoneCallParams *cp); 325 326 /** 327 * Set the audio stream direction. 328 * @param[in] cp LinphoneCallParams object 329 * @param[in] dir The audio stream direction associated with this call params. 330 **/ 331 LINPHONE_PUBLIC void linphone_call_params_set_audio_direction(LinphoneCallParams *cp, LinphoneMediaDirection dir); 332 333 /** 334 * Set the video stream direction. 335 * @param[in] cp LinphoneCallParams object 336 * @param[in] dir The video stream direction associated with this call params. 337 **/ 338 LINPHONE_PUBLIC void linphone_call_params_set_video_direction(LinphoneCallParams *cp, LinphoneMediaDirection dir); 339 340 341 /******************************************************************************* 342 * Reference and user data handling functions * 343 ******************************************************************************/ 344 345 /** 346 * Get the user data associated with the call params. 347 * @param[in] cp LinphoneCallParams object 348 * @return The user data associated with the call params. 349 **/ 350 LINPHONE_PUBLIC void *linphone_call_params_get_user_data(const LinphoneCallParams *cp); 351 352 /** 353 * Assign a user data to the call params. 354 * @param[in] cp LinphoneCallParams object 355 * @param[in] ud The user data to associate with the call params. 356 **/ 357 LINPHONE_PUBLIC void linphone_call_params_set_user_data(LinphoneCallParams *cp, void *ud); 358 359 /** 360 * Acquire a reference to the call params. 361 * @param[in] cp LinphoneCallParams object 362 * @return The same LinphoneCallParams object 363 **/ 364 LINPHONE_PUBLIC LinphoneCallParams * linphone_call_params_ref(LinphoneCallParams *cp); 365 366 /** 367 * Release a reference to the call params. 368 * @param[in] cp LinphoneCallParams object 369 **/ 370 LINPHONE_PUBLIC void linphone_call_params_unref(LinphoneCallParams *cp); 371 372 373 /** 374 * Use to enable multicast rtp for audio stream. 375 * * If enabled, outgoing calls put a multicast address from #linphone_core_get_video_multicast_addr into audio cline. In case of outgoing call audio stream is sent to this multicast address. 376 * <br> For incoming calls behavior is unchanged. 377 * @param params #LinphoneCallParams 378 * @param yesno if yes, subsequent calls will propose multicast ip set by #linphone_core_set_audio_multicast_addr 379 * @ingroup media_parameters 380 **/ 381 LINPHONE_PUBLIC void linphone_call_params_enable_audio_multicast(LinphoneCallParams *params, bool_t yesno); 382 383 /** 384 * Use to get multicast state of audio stream. 385 * @param params #LinphoneCallParams 386 * @return true if subsequent calls will propose multicast ip set by #linphone_core_set_audio_multicast_addr 387 * @ingroup media_parameters 388 **/ 389 LINPHONE_PUBLIC bool_t linphone_call_params_audio_multicast_enabled(const LinphoneCallParams *params); 390 391 /** 392 * Use to enable multicast rtp for video stream. 393 * If enabled, outgoing calls put a multicast address from #linphone_core_get_video_multicast_addr into video cline. In case of outgoing call video stream is sent to this multicast address. 394 * <br> For incoming calls behavior is unchanged. 395 * @param params #LinphoneCallParams 396 * @param yesno if yes, subsequent outgoing calls will propose multicast ip set by #linphone_core_set_video_multicast_addr 397 * @ingroup media_parameters 398 **/ 399 LINPHONE_PUBLIC void linphone_call_params_enable_video_multicast(LinphoneCallParams *params, bool_t yesno); 400 401 /** 402 * Use to get multicast state of video stream. 403 * @param params #LinphoneCallParams 404 * @return true if subsequent calls will propose multicast ip set by #linphone_core_set_video_multicast_addr 405 * @ingroup media_parameters 406 **/ 407 LINPHONE_PUBLIC bool_t linphone_call_params_video_multicast_enabled(const LinphoneCallParams *params); 408 409 /** 410 * Use to enable real time text following rfc4103. 411 * If enabled, outgoing calls put a m=text line in SDP offer . 412 * @param params #LinphoneCallParams 413 * @param yesno if yes, subsequent outgoing calls will propose rtt 414 * @ingroup media_parameters 415 **/ 416 LINPHONE_PUBLIC LinphoneStatus linphone_call_params_enable_realtime_text(LinphoneCallParams *params, bool_t yesno); 417 418 /** 419 * Use to get real time text following rfc4103. 420 * @param params #LinphoneCallParams 421 * @returns returns true if call rtt is activated. 422 * @ingroup media_parameters 423 **/ 424 LINPHONE_PUBLIC bool_t linphone_call_params_realtime_text_enabled(const LinphoneCallParams *params); 425 426 /** 427 * Add a custom attribute related to all the streams in the SDP exchanged within SIP messages during a call. 428 * @param[in] params The #LinphoneCallParams to add a custom SDP attribute to. 429 * @param[in] attribute_name The name of the attribute to add. 430 * @param[in] attribute_value The content value of the attribute to add. 431 * @ingroup media_parameters 432 **/ 433 LINPHONE_PUBLIC void linphone_call_params_add_custom_sdp_attribute(LinphoneCallParams *params, const char *attribute_name, const char *attribute_value); 434 435 /** 436 * Add a custom attribute related to a specific stream in the SDP exchanged within SIP messages during a call. 437 * @param[in] params The #LinphoneCallParams to add a custom SDP attribute to. 438 * @param[in] type The type of the stream to add a custom SDP attribute to. 439 * @param[in] attribute_name The name of the attribute to add. 440 * @param[in] attribute_value The content value of the attribute to add. 441 * @ingroup media_parameters 442 **/ 443 LINPHONE_PUBLIC void linphone_call_params_add_custom_sdp_media_attribute(LinphoneCallParams *params, LinphoneStreamType type, const char *attribute_name, const char *attribute_value); 444 445 /** 446 * Get a custom SDP attribute that is related to all the streams. 447 * @param[in] params The #LinphoneCallParams to get the custom SDP attribute from. 448 * @param[in] attribute_name The name of the attribute to get. 449 * @return The content value of the attribute or NULL if not found. 450 * @ingroup media_parameters 451 **/ 452 LINPHONE_PUBLIC const char * linphone_call_params_get_custom_sdp_attribute(const LinphoneCallParams *params, const char *attribute_name); 453 454 /** 455 * Get a custom SDP attribute that is related to a specific stream. 456 * @param[in] params The #LinphoneCallParams to get the custom SDP attribute from. 457 * @param[in] type The type of the stream to add a custom SDP attribute to. 458 * @param[in] attribute_name The name of the attribute to get. 459 * @return The content value of the attribute or NULL if not found. 460 * @ingroup media_parameters 461 **/ 462 LINPHONE_PUBLIC const char * linphone_call_params_get_custom_sdp_media_attribute(const LinphoneCallParams *params, LinphoneStreamType type, const char *attribute_name); 463 464 /** 465 * Clear the custom SDP attributes related to all the streams in the SDP exchanged within SIP messages during a call. 466 * @param[in] params The #LinphoneCallParams to clear the custom SDP attributes from. 467 * @ingroup media_parameters 468 **/ 469 LINPHONE_PUBLIC void linphone_call_params_clear_custom_sdp_attributes(LinphoneCallParams *params); 470 471 /** 472 * Clear the custom SDP attributes related to a specific stream in the SDP exchanged within SIP messages during a call. 473 * @param[in] params The #LinphoneCallParams to clear the custom SDP attributes from. 474 * @param[in] type The type of the stream to clear the custom SDP attributes from. 475 * @ingroup media_parameters 476 **/ 477 LINPHONE_PUBLIC void linphone_call_params_clear_custom_sdp_media_attributes(LinphoneCallParams *params, LinphoneStreamType type); 478 479 480 /******************************************************************************* 481 * DEPRECATED * 482 ******************************************************************************/ 483 484 /** @deprecated Use linphone_call_params_get_local_conference_mode() instead. */ 485 #define linphone_call_params_local_conference_mode linphone_call_params_get_local_conference_mode 486 487 /** 488 * Destroy a LinphoneCallParams object. 489 * @param[in] cp LinphoneCallParams object 490 * @deprecated Use linphone_call_params_unref() instead. 491 * @donotwrap 492 **/ 493 LINPHONE_DEPRECATED LINPHONE_PUBLIC void linphone_call_params_destroy(LinphoneCallParams *cp); 494 495 /** 496 * @} 497 **/ 498 499 #ifdef __cplusplus 500 } 501 #endif 502 503 #endif /* __LINPHONE_CALL_PARAMS_H__ */ 504