diff options
Diffstat (limited to 'other/apidsl')
-rw-r--r-- | other/apidsl/toxav.in.h | 128 |
1 files changed, 54 insertions, 74 deletions
diff --git a/other/apidsl/toxav.in.h b/other/apidsl/toxav.in.h index f437eeb3..c272b934 100644 --- a/other/apidsl/toxav.in.h +++ b/other/apidsl/toxav.in.h | |||
@@ -56,12 +56,19 @@ extern "C" { | |||
56 | /** \subsection threading Threading implications | 56 | /** \subsection threading Threading implications |
57 | * | 57 | * |
58 | * Unlike the Core API, this API is fully thread-safe. The library will ensure | 58 | * Unlike the Core API, this API is fully thread-safe. The library will ensure |
59 | * the proper synchronisation of parallel calls. | 59 | * the proper synchronization of parallel calls. |
60 | * | 60 | * |
61 | * A common way to run ToxAV (multiple or single instance) is to have a thread, | 61 | * A common way to run ToxAV (multiple or single instance) is to have a thread, |
62 | * separate from tox instance thread, running a simple ${toxAV.iterate} loop, | 62 | * separate from tox instance thread, running a simple ${toxAV.iterate} loop, |
63 | * sleeping for ${toxAV.iteration_interval} * milliseconds on each iteration. | 63 | * sleeping for ${toxAV.iteration_interval} * milliseconds on each iteration. |
64 | * | 64 | * |
65 | * An important thing to note is that events are triggered from both tox and | ||
66 | * toxav thread (see above). audio and video receive frame events are triggered | ||
67 | * from toxav thread while all the other events are triggered from tox thread. | ||
68 | * | ||
69 | * Tox thread has priority with mutex mechanisms. Any api function can | ||
70 | * fail if mutexes are held by tox thread in which case they will set SYNC | ||
71 | * error code. | ||
65 | */ | 72 | */ |
66 | 73 | ||
67 | /** | 74 | /** |
@@ -232,6 +239,10 @@ bool call(uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_ra | |||
232 | */ | 239 | */ |
233 | MALLOC, | 240 | MALLOC, |
234 | /** | 241 | /** |
242 | * Synchronization error occurred. | ||
243 | */ | ||
244 | SYNC, | ||
245 | /** | ||
235 | * The friend number did not designate a valid friend. | 246 | * The friend number did not designate a valid friend. |
236 | */ | 247 | */ |
237 | FRIEND_NOT_FOUND, | 248 | FRIEND_NOT_FOUND, |
@@ -274,6 +285,10 @@ event call { | |||
274 | */ | 285 | */ |
275 | bool answer(uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate) { | 286 | bool answer(uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate) { |
276 | /** | 287 | /** |
288 | * Synchronization error occurred. | ||
289 | */ | ||
290 | SYNC, | ||
291 | /** | ||
277 | * Failed to initialize codecs for call session. Note that codec initiation | 292 | * Failed to initialize codecs for call session. Note that codec initiation |
278 | * will fail if there is no receive callback registered for either audio or | 293 | * will fail if there is no receive callback registered for either audio or |
279 | * video. | 294 | * video. |
@@ -347,7 +362,7 @@ event call_state { | |||
347 | * | 362 | * |
348 | ******************************************************************************/ | 363 | ******************************************************************************/ |
349 | enum class CALL_CONTROL { | 364 | enum class CALL_CONTROL { |
350 | /** | 365 | /** |
351 | * Resume a previously paused call. Only valid if the pause was caused by this | 366 | * Resume a previously paused call. Only valid if the pause was caused by this |
352 | * client, if not, this control is ignored. Not valid before the call is accepted. | 367 | * client, if not, this control is ignored. Not valid before the call is accepted. |
353 | */ | 368 | */ |
@@ -393,6 +408,10 @@ enum class CALL_CONTROL { | |||
393 | */ | 408 | */ |
394 | bool call_control (uint32_t friend_number, CALL_CONTROL control) { | 409 | bool call_control (uint32_t friend_number, CALL_CONTROL control) { |
395 | /** | 410 | /** |
411 | * Synchronization error occurred. | ||
412 | */ | ||
413 | SYNC, | ||
414 | /** | ||
396 | * The friend_number passed did not designate a valid friend. | 415 | * The friend_number passed did not designate a valid friend. |
397 | */ | 416 | */ |
398 | FRIEND_NOT_FOUND, | 417 | FRIEND_NOT_FOUND, |
@@ -412,38 +431,7 @@ bool call_control (uint32_t friend_number, CALL_CONTROL control) { | |||
412 | * :: Controlling bit rates | 431 | * :: Controlling bit rates |
413 | * | 432 | * |
414 | ******************************************************************************/ | 433 | ******************************************************************************/ |
415 | error for set_bit_rate { | 434 | namespace bit_rate { |
416 | /** | ||
417 | * The bit rate passed was not one of the supported values. | ||
418 | */ | ||
419 | INVALID, | ||
420 | /** | ||
421 | * The friend_number passed did not designate a valid friend. | ||
422 | */ | ||
423 | FRIEND_NOT_FOUND, | ||
424 | /** | ||
425 | * This client is currently not in a call with the friend. | ||
426 | */ | ||
427 | FRIEND_NOT_IN_CALL, | ||
428 | } | ||
429 | namespace audio { | ||
430 | namespace bit_rate { | ||
431 | event status { | ||
432 | /** | ||
433 | * The function type for the ${event status} callback. | ||
434 | * | ||
435 | * @param friend_number The friend number of the friend for which to set the | ||
436 | * audio bit rate. | ||
437 | * @param stable Is the stream stable enough to keep the bit rate. | ||
438 | * Upon successful, non forceful, bit rate change, this is set to | ||
439 | * true and 'bit_rate' is set to new bit rate. | ||
440 | * The stable is set to false with bit_rate set to the unstable | ||
441 | * bit rate when either current stream is unstable with said bit rate | ||
442 | * or the non forceful change failed. | ||
443 | * @param bit_rate The bit rate in Kb/sec. | ||
444 | */ | ||
445 | typedef void(uint32_t friend_number, bool stable, uint32_t bit_rate); | ||
446 | } | ||
447 | /** | 435 | /** |
448 | * Set the audio bit rate to be used in subsequent audio frames. If the passed | 436 | * Set the audio bit rate to be used in subsequent audio frames. If the passed |
449 | * bit rate is the same as the current bit rate this function will return true | 437 | * bit rate is the same as the current bit rate this function will return true |
@@ -452,51 +440,43 @@ namespace audio { | |||
452 | * forcefully set and the previous non forceful request is cancelled. The active | 440 | * forcefully set and the previous non forceful request is cancelled. The active |
453 | * non forceful setup will be canceled in favour of new non forceful setup. | 441 | * non forceful setup will be canceled in favour of new non forceful setup. |
454 | * | 442 | * |
455 | * @param friend_number The friend number of the friend for which to set the | 443 | * @param friend_number The friend number. |
456 | * audio bit rate. | ||
457 | * @param audio_bit_rate The new audio bit rate in Kb/sec. Set to 0 to disable | 444 | * @param audio_bit_rate The new audio bit rate in Kb/sec. Set to 0 to disable |
458 | * audio sending. | 445 | * audio sending. Set to -1 to leave unchanged. |
459 | * @param force True if the bit rate change is forceful. | 446 | * @param video_bit_rate The new video bit rate in Kb/sec. Set to 0 to disable |
447 | * video sending. Set to -1 to leave unchanged. | ||
460 | * | 448 | * |
461 | */ | 449 | */ |
462 | bool set(uint32_t friend_number, uint32_t audio_bit_rate, bool force) with error for set_bit_rate; | 450 | bool set(uint32_t friend_number, int32_t audio_bit_rate, int32_t video_bit_rate) { |
463 | } | 451 | /** |
464 | } | 452 | * Synchronization error occurred. |
465 | namespace video { | 453 | */ |
466 | namespace bit_rate { | 454 | SYNC, |
455 | /** | ||
456 | * The bit rate passed was not one of the supported values. | ||
457 | */ | ||
458 | INVALID, | ||
459 | /** | ||
460 | * The friend_number passed did not designate a valid friend. | ||
461 | */ | ||
462 | FRIEND_NOT_FOUND, | ||
463 | /** | ||
464 | * This client is currently not in a call with the friend. | ||
465 | */ | ||
466 | FRIEND_NOT_IN_CALL, | ||
467 | } | ||
467 | event status { | 468 | event status { |
468 | /** | 469 | /** |
469 | * The function type for the ${event status} callback. | 470 | * The function type for the ${event status} callback. The event is triggered |
470 | * | 471 | * when the network becomes too saturated for current bit rates at which |
471 | * @param friend_number The friend number of the friend for which to set the | 472 | * point core suggests new bit rates. |
472 | * video bit rate. | 473 | * |
473 | * @param stable Is the stream stable enough to keep the bit rate. | 474 | * @param friend_number The friend number. |
474 | * Upon successful, non forceful, bit rate change, this is set to | 475 | * @param audio_bit_rate Suggested maximum audio bit rate in Kb/sec. |
475 | * true and 'bit_rate' is set to new bit rate. | 476 | * @param video_bit_rate Suggested maximum video bit rate in Kb/sec. |
476 | * The stable is set to false with bit_rate set to the unstable | 477 | */ |
477 | * bit rate when either current stream is unstable with said bit rate | 478 | typedef void(uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate); |
478 | * or the non forceful change failed. | ||
479 | * @param bit_rate The bit rate in Kb/sec. | ||
480 | */ | ||
481 | typedef void(uint32_t friend_number, bool stable, uint32_t bit_rate); | ||
482 | } | 479 | } |
483 | /** | ||
484 | * Set the video bit rate to be used in subsequent video frames. If the passed | ||
485 | * bit rate is the same as the current bit rate this function will return true | ||
486 | * without calling a callback. If there is an active non forceful setup with the | ||
487 | * passed video bit rate and the new set request is forceful, the bit rate is | ||
488 | * forcefully set and the previous non forceful request is cancelled. The active | ||
489 | * non forceful setup will be canceled in favour of new non forceful setup. | ||
490 | * | ||
491 | * @param friend_number The friend number of the friend for which to set the | ||
492 | * video bit rate. | ||
493 | * @param video_bit_rate The new video bit rate in Kb/sec. Set to 0 to disable | ||
494 | * video sending. | ||
495 | * @param force True if the bit rate change is forceful. | ||
496 | * | ||
497 | */ | ||
498 | bool set(uint32_t friend_number, uint32_t video_bit_rate, bool force) with error for set_bit_rate; | ||
499 | } | ||
500 | } | 480 | } |
501 | /******************************************************************************* | 481 | /******************************************************************************* |
502 | * | 482 | * |