diff options
-rw-r--r-- | other/apidsl/toxav.in.h | 104 |
1 files changed, 78 insertions, 26 deletions
diff --git a/other/apidsl/toxav.in.h b/other/apidsl/toxav.in.h index ab89b0ea..63397420 100644 --- a/other/apidsl/toxav.in.h +++ b/other/apidsl/toxav.in.h | |||
@@ -1,6 +1,6 @@ | |||
1 | %{ | 1 | %{ |
2 | /* toxav.h | 2 | /* toxav.h |
3 | * | 3 | * |
4 | * Copyright (C) 2013-2015 Tox project All Rights Reserved. | 4 | * Copyright (C) 2013-2015 Tox project All Rights Reserved. |
5 | * | 5 | * |
6 | * This file is part of Tox. | 6 | * This file is part of Tox. |
@@ -17,7 +17,7 @@ | |||
17 | * | 17 | * |
18 | * You should have received a copy of the GNU General Public License | 18 | * You should have received a copy of the GNU General Public License |
19 | * along with Tox. If not, see <http://www.gnu.org/licenses/>. | 19 | * along with Tox. If not, see <http://www.gnu.org/licenses/>. |
20 | * | 20 | * |
21 | */ | 21 | */ |
22 | 22 | ||
23 | #ifndef TOXAV_H | 23 | #ifndef TOXAV_H |
@@ -33,39 +33,39 @@ extern "C" { | |||
33 | %} | 33 | %} |
34 | 34 | ||
35 | /** \page av Public audio/video API for Tox clients. | 35 | /** \page av Public audio/video API for Tox clients. |
36 | * | 36 | * |
37 | * This API can handle multiple calls. Each call has its state, in very rare | 37 | * This API can handle multiple calls. Each call has its state, in very rare |
38 | * occasions the library can change the state of the call without apps knowledge. | 38 | * occasions the library can change the state of the call without apps knowledge. |
39 | * | 39 | * |
40 | */ | 40 | */ |
41 | 41 | ||
42 | /** \subsection events Events and callbacks | 42 | /** \subsection events Events and callbacks |
43 | * | 43 | * |
44 | * As in Core API, events are handled by callbacks. One callback can be | 44 | * As in Core API, events are handled by callbacks. One callback can be |
45 | * registered per event. All events have a callback function type named | 45 | * registered per event. All events have a callback function type named |
46 | * `toxav_{event}_cb` and a function to register it named `tox_callback_{event}`. | 46 | * `toxav_{event}_cb` and a function to register it named `toxav_callback_{event}`. |
47 | * Passing a NULL callback will result in no callback being registered for that | 47 | * Passing a NULL callback will result in no callback being registered for that |
48 | * event. Only one callback per event can be registered, so if a client needs | 48 | * event. Only one callback per event can be registered, so if a client needs |
49 | * multiple event listeners, it needs to implement the dispatch functionality | 49 | * multiple event listeners, it needs to implement the dispatch functionality |
50 | * itself. Unlike Core API, lack of some event handlers will cause the the | 50 | * itself. Unlike Core API, lack of some event handlers will cause the the |
51 | * library to drop calls before they are started. Hanging up call from a | 51 | * library to drop calls before they are started. Hanging up call from a |
52 | * callback causes undefined behaviour. | 52 | * callback causes undefined behaviour. |
53 | * | 53 | * |
54 | */ | 54 | */ |
55 | 55 | ||
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 synchronization 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 | 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 | 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. | 67 | * from toxav thread while all the other events are triggered from tox thread. |
68 | * | 68 | * |
69 | * Tox thread has priority with mutex mechanisms. Any api function can | 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 | 70 | * fail if mutexes are held by tox thread in which case they will set SYNC |
71 | * error code. | 71 | * error code. |
@@ -87,9 +87,9 @@ class toxAV { | |||
87 | * The ToxAV instance type. Each ToxAV instance can be bound to only one Tox | 87 | * The ToxAV instance type. Each ToxAV instance can be bound to only one Tox |
88 | * instance, and Tox instance can have only one ToxAV instance. One must make | 88 | * instance, and Tox instance can have only one ToxAV instance. One must make |
89 | * sure to close ToxAV instance prior closing Tox instance otherwise undefined | 89 | * sure to close ToxAV instance prior closing Tox instance otherwise undefined |
90 | * behaviour occurs. Upon closing of ToxAV instance, all active calls will be | 90 | * behaviour occurs. Upon closing of ToxAV instance, all active calls will be |
91 | * forcibly terminated without notifying peers. | 91 | * forcibly terminated without notifying peers. |
92 | * | 92 | * |
93 | */ | 93 | */ |
94 | struct this; | 94 | struct this; |
95 | /******************************************************************************* | 95 | /******************************************************************************* |
@@ -166,7 +166,7 @@ static namespace version { | |||
166 | 166 | ||
167 | } | 167 | } |
168 | /******************************************************************************* | 168 | /******************************************************************************* |
169 | * | 169 | * |
170 | * :: Creation and destruction | 170 | * :: Creation and destruction |
171 | * | 171 | * |
172 | ******************************************************************************/ | 172 | ******************************************************************************/ |
@@ -433,9 +433,10 @@ bool call_control (uint32_t friend_number, CALL_CONTROL control) { | |||
433 | ******************************************************************************/ | 433 | ******************************************************************************/ |
434 | namespace bit_rate { | 434 | namespace bit_rate { |
435 | /** | 435 | /** |
436 | * Set the audio bit rate to be used in subsequent audio/video frames. | 436 | * Set the bit rate to be used in subsequent audio/video frames. |
437 | * | 437 | * |
438 | * @param friend_number The friend number. | 438 | * @param friend_number The friend number of the friend for which to set the |
439 | * bit rate. | ||
439 | * @param audio_bit_rate The new audio bit rate in Kb/sec. Set to 0 to disable | 440 | * @param audio_bit_rate The new audio bit rate in Kb/sec. Set to 0 to disable |
440 | * audio sending. Set to -1 to leave unchanged. | 441 | * audio sending. Set to -1 to leave unchanged. |
441 | * @param video_bit_rate The new video bit rate in Kb/sec. Set to 0 to disable | 442 | * @param video_bit_rate The new video bit rate in Kb/sec. Set to 0 to disable |
@@ -448,9 +449,13 @@ namespace bit_rate { | |||
448 | */ | 449 | */ |
449 | SYNC, | 450 | SYNC, |
450 | /** | 451 | /** |
451 | * The bit rate passed was not one of the supported values. | 452 | * The audio bit rate passed was not one of the supported values. |
453 | */ | ||
454 | INVALID_AUDIO_BIT_RATE, | ||
455 | /** | ||
456 | * The video bit rate passed was not one of the supported values. | ||
452 | */ | 457 | */ |
453 | INVALID, | 458 | INVALID_VIDEO_BIT_RATE, |
454 | /** | 459 | /** |
455 | * The friend_number passed did not designate a valid friend. | 460 | * The friend_number passed did not designate a valid friend. |
456 | */ | 461 | */ |
@@ -466,7 +471,8 @@ namespace bit_rate { | |||
466 | * when the network becomes too saturated for current bit rates at which | 471 | * when the network becomes too saturated for current bit rates at which |
467 | * point core suggests new bit rates. | 472 | * point core suggests new bit rates. |
468 | * | 473 | * |
469 | * @param friend_number The friend number. | 474 | * @param friend_number The friend number of the friend for which to set the |
475 | * bit rate. | ||
470 | * @param audio_bit_rate Suggested maximum audio bit rate in Kb/sec. | 476 | * @param audio_bit_rate Suggested maximum audio bit rate in Kb/sec. |
471 | * @param video_bit_rate Suggested maximum video bit rate in Kb/sec. | 477 | * @param video_bit_rate Suggested maximum video bit rate in Kb/sec. |
472 | */ | 478 | */ |
@@ -607,7 +613,53 @@ namespace video { | |||
607 | } | 613 | } |
608 | 614 | ||
609 | } | 615 | } |
616 | |||
610 | %{ | 617 | %{ |
618 | /** | ||
619 | * NOTE Compatibility with old toxav group calls TODO remove | ||
620 | */ | ||
621 | /* Create a new toxav group. | ||
622 | * | ||
623 | * return group number on success. | ||
624 | * return -1 on failure. | ||
625 | * | ||
626 | * Audio data callback format: | ||
627 | * audio_callback(Tox *tox, int groupnumber, int peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, unsigned int sample_rate, void *userdata) | ||
628 | * | ||
629 | * Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)). | ||
630 | */ | ||
631 | int toxav_add_av_groupchat(Tox *tox, void (*audio_callback)(void *, int, int, const int16_t *, unsigned int, uint8_t, | ||
632 | unsigned int, void *), void *userdata); | ||
633 | |||
634 | /* Join a AV group (you need to have been invited first.) | ||
635 | * | ||
636 | * returns group number on success | ||
637 | * returns -1 on failure. | ||
638 | * | ||
639 | * Audio data callback format (same as the one for toxav_add_av_groupchat()): | ||
640 | * audio_callback(Tox *tox, int groupnumber, int peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, unsigned int sample_rate, void *userdata) | ||
641 | * | ||
642 | * Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)). | ||
643 | */ | ||
644 | int toxav_join_av_groupchat(Tox *tox, int32_t friendnumber, const uint8_t *data, uint16_t length, | ||
645 | void (*audio_callback)(void *, int, int, const int16_t *, unsigned int, uint8_t, unsigned int, void *), void *userdata); | ||
646 | |||
647 | /* Send audio to the group chat. | ||
648 | * | ||
649 | * return 0 on success. | ||
650 | * return -1 on failure. | ||
651 | * | ||
652 | * Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)). | ||
653 | * | ||
654 | * Valid number of samples are ((sample rate) * (audio length (Valid ones are: 2.5, 5, 10, 20, 40 or 60 ms)) / 1000) | ||
655 | * Valid number of channels are 1 or 2. | ||
656 | * Valid sample rates are 8000, 12000, 16000, 24000, or 48000. | ||
657 | * | ||
658 | * Recommended values are: samples = 960, channels = 1, sample_rate = 48000 | ||
659 | */ | ||
660 | int toxav_group_send_audio(Tox *tox, int groupnumber, const int16_t *pcm, unsigned int samples, uint8_t channels, | ||
661 | unsigned int sample_rate); | ||
662 | |||
611 | #ifdef __cplusplus | 663 | #ifdef __cplusplus |
612 | } | 664 | } |
613 | #endif | 665 | #endif |