diff options
Diffstat (limited to 'other/apidsl/toxav.in.h')
-rw-r--r-- | other/apidsl/toxav.in.h | 162 |
1 files changed, 99 insertions, 63 deletions
diff --git a/other/apidsl/toxav.in.h b/other/apidsl/toxav.in.h index 8cb189f0..4bb7487d 100644 --- a/other/apidsl/toxav.in.h +++ b/other/apidsl/toxav.in.h | |||
@@ -92,27 +92,37 @@ class toxAV { | |||
92 | * | 92 | * |
93 | */ | 93 | */ |
94 | struct this; | 94 | struct this; |
95 | |||
96 | |||
95 | /******************************************************************************* | 97 | /******************************************************************************* |
96 | * | 98 | * |
97 | * :: API version | 99 | * :: API version |
98 | * | 100 | * |
99 | ******************************************************************************/ | 101 | ******************************************************************************/ |
102 | |||
103 | |||
100 | /** | 104 | /** |
101 | * The major version number. Incremented when the API or ABI changes in an | 105 | * The major version number. Incremented when the API or ABI changes in an |
102 | * incompatible way. | 106 | * incompatible way. |
107 | * | ||
108 | * The function variants of these constants return the version number of the | ||
109 | * library. They can be used to display the Tox library version or to check | ||
110 | * whether the client is compatible with the dynamically linked version of Tox. | ||
103 | */ | 111 | */ |
104 | #define TOXAV_VERSION_MAJOR 0u | 112 | const VERSION_MAJOR = 0; |
113 | |||
105 | /** | 114 | /** |
106 | * The minor version number. Incremented when functionality is added without | 115 | * The minor version number. Incremented when functionality is added without |
107 | * breaking the API or ABI. Set to 0 when the major version number is | 116 | * breaking the API or ABI. Set to 0 when the major version number is |
108 | * incremented. | 117 | * incremented. |
109 | */ | 118 | */ |
110 | #define TOXAV_VERSION_MINOR 0u | 119 | const VERSION_MINOR = 0; |
120 | |||
111 | /** | 121 | /** |
112 | * The patch or revision number. Incremented when bugfixes are applied without | 122 | * The patch or revision number. Incremented when bugfixes are applied without |
113 | * changing any functionality or API or ABI. | 123 | * changing any functionality or API or ABI. |
114 | */ | 124 | */ |
115 | #define TOXAV_VERSION_PATCH 0u | 125 | const VERSION_PATCH = 0; |
116 | 126 | ||
117 | /** | 127 | /** |
118 | * A macro to check at preprocessing time whether the client code is compatible | 128 | * A macro to check at preprocessing time whether the client code is compatible |
@@ -142,38 +152,25 @@ struct this; | |||
142 | static namespace version { | 152 | static namespace version { |
143 | 153 | ||
144 | /** | 154 | /** |
145 | * Return the major version number of the library. Can be used to display the | ||
146 | * ToxAV library version or to check whether the client is compatible with the | ||
147 | * dynamically linked version of ToxAV. | ||
148 | */ | ||
149 | uint32_t major(); | ||
150 | |||
151 | /** | ||
152 | * Return the minor version number of the library. | ||
153 | */ | ||
154 | uint32_t minor(); | ||
155 | |||
156 | /** | ||
157 | * Return the patch number of the library. | ||
158 | */ | ||
159 | uint32_t patch(); | ||
160 | |||
161 | /** | ||
162 | * Return whether the compiled library version is compatible with the passed | 155 | * Return whether the compiled library version is compatible with the passed |
163 | * version numbers. | 156 | * version numbers. |
164 | */ | 157 | */ |
165 | bool is_compatible(uint32_t major, uint32_t minor, uint32_t patch); | 158 | bool is_compatible(uint32_t major, uint32_t minor, uint32_t patch); |
166 | 159 | ||
167 | } | 160 | } |
161 | |||
162 | |||
168 | /******************************************************************************* | 163 | /******************************************************************************* |
169 | * | 164 | * |
170 | * :: Creation and destruction | 165 | * :: Creation and destruction |
171 | * | 166 | * |
172 | ******************************************************************************/ | 167 | ******************************************************************************/ |
168 | |||
169 | |||
173 | /** | 170 | /** |
174 | * Start new A/V session. There can only be only one session per Tox instance. | 171 | * Start new A/V session. There can only be only one session per Tox instance. |
175 | */ | 172 | */ |
176 | static this new (tox::this *tox) { | 173 | static this new(tox::this *tox) { |
177 | NULL, | 174 | NULL, |
178 | /** | 175 | /** |
179 | * Memory allocation failure while trying to allocate structures required for | 176 | * Memory allocation failure while trying to allocate structures required for |
@@ -185,6 +182,7 @@ static this new (tox::this *tox) { | |||
185 | */ | 182 | */ |
186 | MULTIPLE, | 183 | MULTIPLE, |
187 | } | 184 | } |
185 | |||
188 | /** | 186 | /** |
189 | * Releases all resources associated with the A/V session. | 187 | * Releases all resources associated with the A/V session. |
190 | * | 188 | * |
@@ -193,31 +191,41 @@ static this new (tox::this *tox) { | |||
193 | * called and the av pointer becomes invalid. | 191 | * called and the av pointer becomes invalid. |
194 | */ | 192 | */ |
195 | void kill(); | 193 | void kill(); |
194 | |||
196 | /** | 195 | /** |
197 | * Returns the Tox instance the A/V object was created for. | 196 | * Returns the Tox instance the A/V object was created for. |
198 | */ | 197 | */ |
199 | tox::this *tox { get(); } | 198 | tox::this *tox { get(); } |
199 | |||
200 | |||
200 | /******************************************************************************* | 201 | /******************************************************************************* |
201 | * | 202 | * |
202 | * :: A/V event loop | 203 | * :: A/V event loop |
203 | * | 204 | * |
204 | ******************************************************************************/ | 205 | ******************************************************************************/ |
206 | |||
207 | |||
205 | /** | 208 | /** |
206 | * Returns the interval in milliseconds when the next toxav_iterate call should | 209 | * Returns the interval in milliseconds when the next toxav_iterate call should |
207 | * be. If no call is active at the moment, this function returns 200. | 210 | * be. If no call is active at the moment, this function returns 200. |
208 | */ | 211 | */ |
209 | const uint32_t iteration_interval(); | 212 | const uint32_t iteration_interval(); |
213 | |||
210 | /** | 214 | /** |
211 | * Main loop for the session. This function needs to be called in intervals of | 215 | * Main loop for the session. This function needs to be called in intervals of |
212 | * toxav_iteration_interval() milliseconds. It is best called in the separate | 216 | * toxav_iteration_interval() milliseconds. It is best called in the separate |
213 | * thread from tox_iterate. | 217 | * thread from tox_iterate. |
214 | */ | 218 | */ |
215 | void iterate(); | 219 | void iterate(); |
220 | |||
221 | |||
216 | /******************************************************************************* | 222 | /******************************************************************************* |
217 | * | 223 | * |
218 | * :: Call setup | 224 | * :: Call setup |
219 | * | 225 | * |
220 | ******************************************************************************/ | 226 | ******************************************************************************/ |
227 | |||
228 | |||
221 | /** | 229 | /** |
222 | * Call a friend. This will start ringing the friend. | 230 | * Call a friend. This will start ringing the friend. |
223 | * | 231 | * |
@@ -260,6 +268,7 @@ bool call(uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_ra | |||
260 | */ | 268 | */ |
261 | INVALID_BIT_RATE, | 269 | INVALID_BIT_RATE, |
262 | } | 270 | } |
271 | |||
263 | event call { | 272 | event call { |
264 | /** | 273 | /** |
265 | * The function type for the ${event call} callback. | 274 | * The function type for the ${event call} callback. |
@@ -270,6 +279,7 @@ event call { | |||
270 | */ | 279 | */ |
271 | typedef void(uint32_t friend_number, bool audio_enabled, bool video_enabled); | 280 | typedef void(uint32_t friend_number, bool audio_enabled, bool video_enabled); |
272 | } | 281 | } |
282 | |||
273 | /** | 283 | /** |
274 | * Accept an incoming call. | 284 | * Accept an incoming call. |
275 | * | 285 | * |
@@ -308,11 +318,15 @@ bool answer(uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_ | |||
308 | */ | 318 | */ |
309 | INVALID_BIT_RATE, | 319 | INVALID_BIT_RATE, |
310 | } | 320 | } |
321 | |||
322 | |||
311 | /******************************************************************************* | 323 | /******************************************************************************* |
312 | * | 324 | * |
313 | * :: Call state graph | 325 | * :: Call state graph |
314 | * | 326 | * |
315 | ******************************************************************************/ | 327 | ******************************************************************************/ |
328 | |||
329 | |||
316 | bitmask FRIEND_CALL_STATE { | 330 | bitmask FRIEND_CALL_STATE { |
317 | /** | 331 | /** |
318 | * Set by the AV core if an error occurred on the remote end or if friend | 332 | * Set by the AV core if an error occurred on the remote end or if friend |
@@ -344,6 +358,7 @@ bitmask FRIEND_CALL_STATE { | |||
344 | */ | 358 | */ |
345 | ACCEPTING_V, | 359 | ACCEPTING_V, |
346 | } | 360 | } |
361 | |||
347 | event call_state { | 362 | event call_state { |
348 | /** | 363 | /** |
349 | * The function type for the ${event call_state} callback. | 364 | * The function type for the ${event call_state} callback. |
@@ -356,11 +371,15 @@ event call_state { | |||
356 | */ | 371 | */ |
357 | typedef void(uint32_t friend_number, uint32_t state); | 372 | typedef void(uint32_t friend_number, uint32_t state); |
358 | } | 373 | } |
374 | |||
375 | |||
359 | /******************************************************************************* | 376 | /******************************************************************************* |
360 | * | 377 | * |
361 | * :: Call control | 378 | * :: Call control |
362 | * | 379 | * |
363 | ******************************************************************************/ | 380 | ******************************************************************************/ |
381 | |||
382 | |||
364 | enum class CALL_CONTROL { | 383 | enum class CALL_CONTROL { |
365 | /** | 384 | /** |
366 | * Resume a previously paused call. Only valid if the pause was caused by this | 385 | * Resume a previously paused call. Only valid if the pause was caused by this |
@@ -397,6 +416,7 @@ enum class CALL_CONTROL { | |||
397 | */ | 416 | */ |
398 | SHOW_VIDEO, | 417 | SHOW_VIDEO, |
399 | } | 418 | } |
419 | |||
400 | /** | 420 | /** |
401 | * Sends a call control command to a friend. | 421 | * Sends a call control command to a friend. |
402 | * | 422 | * |
@@ -406,7 +426,7 @@ enum class CALL_CONTROL { | |||
406 | * | 426 | * |
407 | * @return true on success. | 427 | * @return true on success. |
408 | */ | 428 | */ |
409 | bool call_control (uint32_t friend_number, CALL_CONTROL control) { | 429 | bool call_control(uint32_t friend_number, CALL_CONTROL control) { |
410 | /** | 430 | /** |
411 | * Synchronization error occurred. | 431 | * Synchronization error occurred. |
412 | */ | 432 | */ |
@@ -426,64 +446,73 @@ bool call_control (uint32_t friend_number, CALL_CONTROL control) { | |||
426 | */ | 446 | */ |
427 | INVALID_TRANSITION, | 447 | INVALID_TRANSITION, |
428 | } | 448 | } |
449 | |||
450 | |||
429 | /******************************************************************************* | 451 | /******************************************************************************* |
430 | * | 452 | * |
431 | * :: Controlling bit rates | 453 | * :: Controlling bit rates |
432 | * | 454 | * |
433 | ******************************************************************************/ | 455 | ******************************************************************************/ |
456 | |||
457 | |||
434 | namespace bit_rate { | 458 | namespace bit_rate { |
459 | /** | ||
460 | * Set the bit rate to be used in subsequent audio/video frames. | ||
461 | * | ||
462 | * @param friend_number The friend number of the friend for which to set the | ||
463 | * bit rate. | ||
464 | * @param audio_bit_rate The new audio bit rate in Kb/sec. Set to 0 to disable | ||
465 | * audio sending. Set to -1 to leave unchanged. | ||
466 | * @param video_bit_rate The new video bit rate in Kb/sec. Set to 0 to disable | ||
467 | * video sending. Set to -1 to leave unchanged. | ||
468 | * | ||
469 | */ | ||
470 | bool set(uint32_t friend_number, int32_t audio_bit_rate, int32_t video_bit_rate) { | ||
471 | /** | ||
472 | * Synchronization error occurred. | ||
473 | */ | ||
474 | SYNC, | ||
475 | /** | ||
476 | * The audio bit rate passed was not one of the supported values. | ||
477 | */ | ||
478 | INVALID_AUDIO_BIT_RATE, | ||
479 | /** | ||
480 | * The video bit rate passed was not one of the supported values. | ||
481 | */ | ||
482 | INVALID_VIDEO_BIT_RATE, | ||
435 | /** | 483 | /** |
436 | * Set the bit rate to be used in subsequent audio/video frames. | 484 | * The friend_number passed did not designate a valid friend. |
485 | */ | ||
486 | FRIEND_NOT_FOUND, | ||
487 | /** | ||
488 | * This client is currently not in a call with the friend. | ||
489 | */ | ||
490 | FRIEND_NOT_IN_CALL, | ||
491 | } | ||
492 | |||
493 | event status { | ||
494 | /** | ||
495 | * The function type for the ${event status} callback. The event is triggered | ||
496 | * when the network becomes too saturated for current bit rates at which | ||
497 | * point core suggests new bit rates. | ||
437 | * | 498 | * |
438 | * @param friend_number The friend number of the friend for which to set the | 499 | * @param friend_number The friend number of the friend for which to set the |
439 | * bit rate. | 500 | * bit rate. |
440 | * @param audio_bit_rate The new audio bit rate in Kb/sec. Set to 0 to disable | 501 | * @param audio_bit_rate Suggested maximum audio bit rate in Kb/sec. |
441 | * audio sending. Set to -1 to leave unchanged. | 502 | * @param video_bit_rate Suggested maximum video bit rate in Kb/sec. |
442 | * @param video_bit_rate The new video bit rate in Kb/sec. Set to 0 to disable | ||
443 | * video sending. Set to -1 to leave unchanged. | ||
444 | * | ||
445 | */ | 503 | */ |
446 | bool set(uint32_t friend_number, int32_t audio_bit_rate, int32_t video_bit_rate) { | 504 | typedef void(uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate); |
447 | /** | 505 | } |
448 | * Synchronization error occurred. | ||
449 | */ | ||
450 | SYNC, | ||
451 | /** | ||
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. | ||
457 | */ | ||
458 | INVALID_VIDEO_BIT_RATE, | ||
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 | } | ||
468 | event status { | ||
469 | /** | ||
470 | * The function type for the ${event status} callback. The event is triggered | ||
471 | * when the network becomes too saturated for current bit rates at which | ||
472 | * point core suggests new bit rates. | ||
473 | * | ||
474 | * @param friend_number The friend number of the friend for which to set the | ||
475 | * bit rate. | ||
476 | * @param audio_bit_rate Suggested maximum audio bit rate in Kb/sec. | ||
477 | * @param video_bit_rate Suggested maximum video bit rate in Kb/sec. | ||
478 | */ | ||
479 | typedef void(uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate); | ||
480 | } | ||
481 | } | 506 | } |
507 | |||
508 | |||
482 | /******************************************************************************* | 509 | /******************************************************************************* |
483 | * | 510 | * |
484 | * :: A/V sending | 511 | * :: A/V sending |
485 | * | 512 | * |
486 | ******************************************************************************/ | 513 | ******************************************************************************/ |
514 | |||
515 | |||
487 | error for send_frame { | 516 | error for send_frame { |
488 | /** | 517 | /** |
489 | * In case of video, one of Y, U, or V was NULL. In case of audio, the samples | 518 | * In case of video, one of Y, U, or V was NULL. In case of audio, the samples |
@@ -517,6 +546,7 @@ error for send_frame { | |||
517 | */ | 546 | */ |
518 | RTP_FAILED, | 547 | RTP_FAILED, |
519 | } | 548 | } |
549 | |||
520 | namespace audio { | 550 | namespace audio { |
521 | /** | 551 | /** |
522 | * Send an audio frame to a friend. | 552 | * Send an audio frame to a friend. |
@@ -541,6 +571,7 @@ namespace audio { | |||
541 | bool send_frame(uint32_t friend_number, const int16_t *pcm, size_t sample_count, | 571 | bool send_frame(uint32_t friend_number, const int16_t *pcm, size_t sample_count, |
542 | uint8_t channels, uint32_t sampling_rate) with error for send_frame; | 572 | uint8_t channels, uint32_t sampling_rate) with error for send_frame; |
543 | } | 573 | } |
574 | |||
544 | namespace video { | 575 | namespace video { |
545 | /** | 576 | /** |
546 | * Send a video frame to a friend. | 577 | * Send a video frame to a friend. |
@@ -560,11 +591,15 @@ namespace video { | |||
560 | bool send_frame(uint32_t friend_number, uint16_t width, uint16_t height, | 591 | bool send_frame(uint32_t friend_number, uint16_t width, uint16_t height, |
561 | const uint8_t *y, const uint8_t *u, const uint8_t *v) with error for send_frame; | 592 | const uint8_t *y, const uint8_t *u, const uint8_t *v) with error for send_frame; |
562 | } | 593 | } |
594 | |||
595 | |||
563 | /******************************************************************************* | 596 | /******************************************************************************* |
564 | * | 597 | * |
565 | * :: A/V receiving | 598 | * :: A/V receiving |
566 | * | 599 | * |
567 | ******************************************************************************/ | 600 | ******************************************************************************/ |
601 | |||
602 | |||
568 | namespace audio { | 603 | namespace audio { |
569 | event receive_frame { | 604 | event receive_frame { |
570 | /** | 605 | /** |
@@ -583,6 +618,7 @@ namespace audio { | |||
583 | uint8_t channels, uint32_t sampling_rate); | 618 | uint8_t channels, uint32_t sampling_rate); |
584 | } | 619 | } |
585 | } | 620 | } |
621 | |||
586 | namespace video { | 622 | namespace video { |
587 | event receive_frame { | 623 | event receive_frame { |
588 | /** | 624 | /** |