summaryrefslogtreecommitdiff
path: root/toxav/toxav.h
diff options
context:
space:
mode:
authormannol <eniz_vukovic@hotmail.com>2015-05-22 23:22:31 +0200
committermannol <eniz_vukovic@hotmail.com>2015-05-22 23:22:31 +0200
commit3100042a2b78f4f80d23f67e6113797cd8fb5df0 (patch)
treec226f4b25002784d93f9bb6415be4b55b76cddd1 /toxav/toxav.h
parent62c40af1a0c557ba8c77583c972ae3af9af15cf1 (diff)
parent2ba076ac5cc6efb5eb41fb4aa6a77a151885f26c (diff)
Updated with master
Diffstat (limited to 'toxav/toxav.h')
-rw-r--r--toxav/toxav.h820
1 files changed, 536 insertions, 284 deletions
diff --git a/toxav/toxav.h b/toxav/toxav.h
index b0e7e37d..c75f8bff 100644
--- a/toxav/toxav.h
+++ b/toxav/toxav.h
@@ -1,22 +1,22 @@
1/** toxav.h 1/* toxav.h
2 * 2 *
3 * Copyright (C) 2013-2015 Tox project All Rights Reserved. 3 * Copyright (C) 2013-2015 Tox project All Rights Reserved.
4 * 4 *
5 * This file is part of Tox. 5 * This file is part of Tox.
6 * 6 *
7 * Tox is free software: you can redistribute it and/or modify 7 * Tox is free software: you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by 8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation, either version 3 of the License, or 9 * the Free Software Foundation, either version 3 of the License, or
10 * (at your option) any later version. 10 * (at your option) any later version.
11 * 11 *
12 * Tox is distributed in the hope that it will be useful, 12 * Tox is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details. 15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with Tox. If not, see <http://www.gnu.org/licenses/>.
19 * 16 *
17 * You should have received a copy of the GNU General Public License
18 * along with Tox. If not, see <http://www.gnu.org/licenses/>.
19 *
20 */ 20 */
21 21
22#ifndef TOXAV_H 22#ifndef TOXAV_H
@@ -29,45 +29,175 @@
29#ifdef __cplusplus 29#ifdef __cplusplus
30extern "C" { 30extern "C" {
31#endif 31#endif
32
32/** \page av Public audio/video API for Tox clients. 33/** \page av Public audio/video API for Tox clients.
33 * 34 *
35 * This API can handle multiple calls. Each call has its state, in very rare
36 * occasions the library can change the state of the call without apps knowledge.
37 *
38 */
39/** \subsection events Events and callbacks
40 *
41 * As in Core API, events are handled by callbacks. One callback can be
42 * registered per event. All events have a callback function type named
43 * `toxav_{event}_cb` and a function to register it named `tox_callback_{event}`.
44 * Passing a NULL callback will result in no callback being registered for that
45 * event. Only one callback per event can be registered, so if a client needs
46 * multiple event listeners, it needs to implement the dispatch functionality
47 * itself. Unlike Core API, lack of some event handlers will cause the the
48 * library to drop calls before they are started. Hanging up call from a
49 * callback causes undefined behaviour.
50 *
51 */
52/** \subsection threading Threading implications
53 *
34 * Unlike the Core API, this API is fully thread-safe. The library will ensure 54 * Unlike the Core API, this API is fully thread-safe. The library will ensure
35 * the proper synchronisation of parallel calls. 55 * the proper synchronisation of parallel calls.
56 *
57 * A common way to run ToxAV (multiple or single instance) is to have a thread,
58 * separate from tox instance thread, running a simple toxav_iterate loop,
59 * sleeping for toxav_iteration_interval * milliseconds on each iteration.
60 *
36 */ 61 */
37/** 62/**
38 * The type of the Tox Audio/Video subsystem object. 63 * External Tox type.
39 */ 64 */
40typedef struct ToxAV ToxAV;
41#ifndef TOX_DEFINED 65#ifndef TOX_DEFINED
42#define TOX_DEFINED 66#define TOX_DEFINED
67typedef struct Tox Tox;
68#endif /* TOX_DEFINED */
69
43/** 70/**
44 * The type of a Tox instance. Repeated here so this file does not have a direct 71 * ToxAV.
45 * dependency on the Core interface.
46 */ 72 */
47typedef struct Tox Tox; 73/**
48#endif 74 * The ToxAV instance type. Each ToxAV instance can be bound to only one Tox
75 * instance, and Tox instance can have only one ToxAV instance. One must make
76 * sure to close ToxAV instance prior closing Tox instance otherwise undefined
77 * behaviour occurs. Upon closing of ToxAV instance, all active calls will be
78 * forcibly terminated without notifying peers.
79 *
80 */
81#ifndef TOXAV_DEFINED
82#define TOXAV_DEFINED
83typedef struct ToxAV ToxAV;
84#endif /* TOXAV_DEFINED */
85
86
87/*******************************************************************************
88 *
89 * :: API version
90 *
91 ******************************************************************************/
92
93
94
95/**
96 * The major version number. Incremented when the API or ABI changes in an
97 * incompatible way.
98 */
99#define TOXAV_VERSION_MAJOR 0u
100
101/**
102 * The minor version number. Incremented when functionality is added without
103 * breaking the API or ABI. Set to 0 when the major version number is
104 * incremented.
105 */
106#define TOXAV_VERSION_MINOR 0u
107
108/**
109 * The patch or revision number. Incremented when bugfixes are applied without
110 * changing any functionality or API or ABI.
111 */
112#define TOXAV_VERSION_PATCH 0u
113
114/**
115 * A macro to check at preprocessing time whether the client code is compatible
116 * with the installed version of ToxAV.
117 */
118#define TOXAV_VERSION_IS_API_COMPATIBLE(MAJOR, MINOR, PATCH) \
119 (TOXAV_VERSION_MAJOR == MAJOR && \
120 (TOXAV_VERSION_MINOR > MINOR || \
121 (TOXAV_VERSION_MINOR == MINOR && \
122 TOXAV_VERSION_PATCH >= PATCH)))
123
124/**
125 * A macro to make compilation fail if the client code is not compatible with
126 * the installed version of ToxAV.
127 */
128#define TOXAV_VERSION_REQUIRE(MAJOR, MINOR, PATCH) \
129 typedef char toxav_required_version[TOXAV_IS_COMPATIBLE(MAJOR, MINOR, PATCH) ? 1 : -1]
130
131/**
132 * A convenience macro to call toxav_version_is_compatible with the currently
133 * compiling API version.
134 */
135#define TOXAV_VERSION_IS_ABI_COMPATIBLE() \
136 toxav_version_is_compatible(TOXAV_VERSION_MAJOR, TOXAV_VERSION_MINOR, TOXAV_VERSION_PATCH)
137
138/**
139 * Return the major version number of the library. Can be used to display the
140 * ToxAV library version or to check whether the client is compatible with the
141 * dynamically linked version of ToxAV.
142 */
143uint32_t toxav_version_major(void);
144
145/**
146 * Return the minor version number of the library.
147 */
148uint32_t toxav_version_minor(void);
149
150/**
151 * Return the patch number of the library.
152 */
153uint32_t toxav_version_patch(void);
154
155/**
156 * Return whether the compiled library version is compatible with the passed
157 * version numbers.
158 */
159bool toxav_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch);
160
161
49/******************************************************************************* 162/*******************************************************************************
50 * 163 *
51 * :: Creation and destruction 164 * :: Creation and destruction
52 * 165 *
53 ******************************************************************************/ 166 ******************************************************************************/
167
168
169
54typedef enum TOXAV_ERR_NEW { 170typedef enum TOXAV_ERR_NEW {
55 TOXAV_ERR_NEW_OK, 171
56 TOXAV_ERR_NEW_NULL, 172 /**
57 /** 173 * The function returned successfully.
58 * Memory allocation failure while trying to allocate structures required for 174 */
59 * the A/V session. 175 TOXAV_ERR_NEW_OK,
60 */ 176
61 TOXAV_ERR_NEW_MALLOC, 177 /**
62 /** 178 * One of the arguments to the function was NULL when it was not expected.
63 * Attempted to create a second session for the same Tox instance. 179 */
64 */ 180 TOXAV_ERR_NEW_NULL,
65 TOXAV_ERR_NEW_MULTIPLE 181
182 /**
183 * Memory allocation failure while trying to allocate structures required for
184 * the A/V session.
185 */
186 TOXAV_ERR_NEW_MALLOC,
187
188 /**
189 * Attempted to create a second session for the same Tox instance.
190 */
191 TOXAV_ERR_NEW_MULTIPLE,
192
66} TOXAV_ERR_NEW; 193} TOXAV_ERR_NEW;
194
195
67/** 196/**
68 * Start new A/V session. There can only be only one session per Tox instance. 197 * Start new A/V session. There can only be only one session per Tox instance.
69 */ 198 */
70ToxAV *toxav_new(Tox *tox, TOXAV_ERR_NEW *error); 199ToxAV *toxav_new(Tox *tox, TOXAV_ERR_NEW *error);
200
71/** 201/**
72 * Releases all resources associated with the A/V session. 202 * Releases all resources associated with the A/V session.
73 * 203 *
@@ -75,62 +205,86 @@ ToxAV *toxav_new(Tox *tox, TOXAV_ERR_NEW *error);
75 * notifying peers. After calling this function, no other functions may be 205 * notifying peers. After calling this function, no other functions may be
76 * called and the av pointer becomes invalid. 206 * called and the av pointer becomes invalid.
77 */ 207 */
78void toxav_kill(ToxAV *av); 208void toxav_kill(ToxAV *toxAV);
209
79/** 210/**
80 * Returns the Tox instance the A/V object was created for. 211 * Returns the Tox instance the A/V object was created for.
81 */ 212 */
82Tox *toxav_get_tox(ToxAV *av); 213Tox *toxav_get_tox(const ToxAV *toxAV);
214
215
83/******************************************************************************* 216/*******************************************************************************
84 * 217 *
85 * :: A/V event loop 218 * :: A/V event loop
86 * 219 *
87 ******************************************************************************/ 220 ******************************************************************************/
221
222
223
88/** 224/**
89 * Returns the interval in milliseconds when the next toxav_iterate call should 225 * Returns the interval in milliseconds when the next toxav_iterate call should
90 * be. If no call is active at the moment, this function returns 200. 226 * be. If no call is active at the moment, this function returns 200.
91 */ 227 */
92uint32_t toxav_iteration_interval(ToxAV const *av); 228uint32_t toxav_iteration_interval(const ToxAV *toxAV);
229
93/** 230/**
94 * Main loop for the session. This function needs to be called in intervals of 231 * Main loop for the session. This function needs to be called in intervals of
95 * toxav_iteration_interval() milliseconds. It is best called in the separate 232 * toxav_iteration_interval() milliseconds. It is best called in the separate
96 * thread from tox_iterate. 233 * thread from tox_iterate.
97 */ 234 */
98void toxav_iterate(ToxAV *av); 235void toxav_iterate(ToxAV *toxAV);
236
237
99/******************************************************************************* 238/*******************************************************************************
100 * 239 *
101 * :: Call setup 240 * :: Call setup
102 * 241 *
103 ******************************************************************************/ 242 ******************************************************************************/
243
244
245
104typedef enum TOXAV_ERR_CALL { 246typedef enum TOXAV_ERR_CALL {
105 TOXAV_ERR_CALL_OK, 247
106 /** 248 /**
107 * A resource allocation error occurred while trying to create the structures 249 * The function returned successfully.
108 * required for the call. 250 */
109 */ 251 TOXAV_ERR_CALL_OK,
110 TOXAV_ERR_CALL_MALLOC, 252
111 /** 253 /**
112 * The friend number did not designate a valid friend. 254 * A resource allocation error occurred while trying to create the structures
113 */ 255 * required for the call.
114 TOXAV_ERR_CALL_FRIEND_NOT_FOUND, 256 */
115 /** 257 TOXAV_ERR_CALL_MALLOC,
116 * The friend was valid, but not currently connected. 258
117 */ 259 /**
118 TOXAV_ERR_CALL_FRIEND_NOT_CONNECTED, 260 * The friend number did not designate a valid friend.
119 /** 261 */
120 * Attempted to call a friend while already in an audio or video call with 262 TOXAV_ERR_CALL_FRIEND_NOT_FOUND,
121 * them. 263
122 */ 264 /**
123 TOXAV_ERR_CALL_FRIEND_ALREADY_IN_CALL, 265 * The friend was valid, but not currently connected.
124 /** 266 */
125 * Audio or video bit rate is invalid. 267 TOXAV_ERR_CALL_FRIEND_NOT_CONNECTED,
126 */ 268
127 TOXAV_ERR_CALL_INVALID_BIT_RATE 269 /**
270 * Attempted to call a friend while already in an audio or video call with
271 * them.
272 */
273 TOXAV_ERR_CALL_FRIEND_ALREADY_IN_CALL,
274
275 /**
276 * Audio or video bit rate is invalid.
277 */
278 TOXAV_ERR_CALL_INVALID_BIT_RATE,
279
128} TOXAV_ERR_CALL; 280} TOXAV_ERR_CALL;
281
282
129/** 283/**
130 * Call a friend. This will start ringing the friend. 284 * Call a friend. This will start ringing the friend.
131 * 285 *
132 * It is the client's responsibility to stop ringing after a certain timeout, 286 * It is the client's responsibility to stop ringing after a certain timeout,
133 * if such behaviour is desired. If the client does not stop ringing, the A/V 287 * if such behaviour is desired. If the client does not stop ringing, the
134 * library will not stop until the friend is disconnected. 288 * library will not stop until the friend is disconnected.
135 * 289 *
136 * @param friend_number The friend number of the friend that should be called. 290 * @param friend_number The friend number of the friend that should be called.
@@ -139,39 +293,57 @@ typedef enum TOXAV_ERR_CALL {
139 * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable 293 * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable
140 * video sending. 294 * video sending.
141 */ 295 */
142bool toxav_call(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, TOXAV_ERR_CALL *error); 296bool toxav_call(ToxAV *toxAV, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, TOXAV_ERR_CALL *error);
297
143/** 298/**
144 * The function type for the `call` callback. 299 * The function type for the call callback.
300 *
301 * @param friend_number The friend number from which the call is incoming.
302 * @param audio_enabled True if friend is sending audio.
303 * @param video_enabled True if friend is sending video.
145 */ 304 */
146typedef void toxav_call_cb(ToxAV *av, uint32_t friend_number, bool audio_enabled, bool video_enabled, void *user_data); 305typedef void toxav_call_cb(ToxAV *toxAV, uint32_t friend_number, bool audio_enabled, bool video_enabled, void *user_data);
306
307
147/** 308/**
148 * Set the callback for the `call` event. Pass NULL to unset. 309 * Set the callback for the `call` event. Pass NULL to unset.
149 * 310 *
150 * This event is triggered when a call is received from a friend.
151 */ 311 */
152void toxav_callback_call(ToxAV *av, toxav_call_cb *function, void *user_data); 312void toxav_callback_call(ToxAV *toxAV, toxav_call_cb *callback, void *user_data);
313
153typedef enum TOXAV_ERR_ANSWER { 314typedef enum TOXAV_ERR_ANSWER {
154 TOXAV_ERR_ANSWER_OK, 315
155 /** 316 /**
156 * Failed to initialize codecs for call session. Note that codec initiation 317 * The function returned successfully.
157 * will fail if there is no receive callback registered for either audio or 318 */
158 * video. 319 TOXAV_ERR_ANSWER_OK,
159 */ 320
160 TOXAV_ERR_ANSWER_CODEC_INITIALIZATION, 321 /**
161 /** 322 * Failed to initialize codecs for call session. Note that codec initiation
162 * The friend number did not designate a valid friend. 323 * will fail if there is no receive callback registered for either audio or
163 */ 324 * video.
164 TOXAV_ERR_ANSWER_FRIEND_NOT_FOUND, 325 */
165 /** 326 TOXAV_ERR_ANSWER_CODEC_INITIALIZATION,
166 * The friend was valid, but they are not currently trying to initiate a call. 327
167 * This is also returned if this client is already in a call with the friend. 328 /**
168 */ 329 * The friend number did not designate a valid friend.
169 TOXAV_ERR_ANSWER_FRIEND_NOT_CALLING, 330 */
170 /** 331 TOXAV_ERR_ANSWER_FRIEND_NOT_FOUND,
171 * Audio or video bit rate is invalid. 332
172 */ 333 /**
173 TOXAV_ERR_ANSWER_INVALID_BIT_RATE 334 * The friend was valid, but they are not currently trying to initiate a call.
335 * This is also returned if this client is already in a call with the friend.
336 */
337 TOXAV_ERR_ANSWER_FRIEND_NOT_CALLING,
338
339 /**
340 * Audio or video bit rate is invalid.
341 */
342 TOXAV_ERR_ANSWER_INVALID_BIT_RATE,
343
174} TOXAV_ERR_ANSWER; 344} TOXAV_ERR_ANSWER;
345
346
175/** 347/**
176 * Accept an incoming call. 348 * Accept an incoming call.
177 * 349 *
@@ -184,113 +356,155 @@ typedef enum TOXAV_ERR_ANSWER {
184 * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable 356 * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable
185 * video sending. 357 * video sending.
186 */ 358 */
187bool toxav_answer(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, TOXAV_ERR_ANSWER *error); 359bool toxav_answer(ToxAV *toxAV, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, TOXAV_ERR_ANSWER *error);
360
361
188/******************************************************************************* 362/*******************************************************************************
189 * 363 *
190 * :: Call state graph 364 * :: Call state graph
191 * 365 *
192 ******************************************************************************/ 366 ******************************************************************************/
367
368
369
193enum TOXAV_CALL_STATE { 370enum TOXAV_CALL_STATE {
194 /** 371
195 * The flag that marks that friend is sending audio. 372 /**
196 */ 373 * Set by the AV core if an error occurred on the remote end or if friend
197 TOXAV_CALL_STATE_SENDING_A = 1, 374 * timed out. This is the final state after which no more state
198 /** 375 * transitions can occur for the call. This call state will never be triggered
199 * The flag that marks that friend is sending video. 376 * in combination with other call states.
200 */ 377 */
201 TOXAV_CALL_STATE_SENDING_V = 2, 378 TOXAV_CALL_STATE_ERROR = 1,
202 /** 379
203 * The flag that marks that friend is receiving audio. 380 /**
204 */ 381 * The call has finished. This is the final state after which no more state
205 TOXAV_CALL_STATE_RECEIVING_A = 4, 382 * transitions can occur for the call. This call state will never be
206 /** 383 * triggered in combination with other call states.
207 * The flag that marks that friend is receiving video. 384 */
208 */ 385 TOXAV_CALL_STATE_FINISHED = 2,
209 TOXAV_CALL_STATE_RECEIVING_V = 8, 386
210 /** 387 /**
211 * The call has finished. This is the final state after which no more state 388 * The flag that marks that friend is sending audio.
212 * transitions can occur for the call. This call state will never be 389 */
213 * triggered in combination with other call states. 390 TOXAV_CALL_STATE_SENDING_A = 4,
214 */ 391
215 TOXAV_CALL_STATE_FINISHED = 16, 392 /**
216 /** 393 * The flag that marks that friend is sending video.
217 * Set by the AV core if an error occurred on the remote end. This call 394 */
218 * state will never be triggered in combination with other call states. 395 TOXAV_CALL_STATE_SENDING_V = 8,
219 */ 396
220 TOXAV_CALL_STATE_ERROR = 32768 397 /**
398 * The flag that marks that friend is receiving audio.
399 */
400 TOXAV_CALL_STATE_RECEIVING_A = 16,
401
402 /**
403 * The flag that marks that friend is receiving video.
404 */
405 TOXAV_CALL_STATE_RECEIVING_V = 32,
406
221}; 407};
408
409
222/** 410/**
223 * The function type for the `call_state` callback. 411 * The function type for the call_state callback.
224 * 412 *
225 * @param friend_number The friend number for which the call state changed. 413 * @param friend_number The friend number for which the call state changed.
226 * @param state The new call state. 414 * @param state The new call state which is guaranteed to be different than
415 * the previous state. The state is set to 0 when the call is paused.
227 */ 416 */
228typedef void toxav_call_state_cb(ToxAV *av, uint32_t friend_number, uint32_t state, void *user_data); 417typedef void toxav_call_state_cb(ToxAV *toxAV, uint32_t friend_number, uint32_t state, void *user_data);
418
419
229/** 420/**
230 * Set the callback for the `call_state` event. Pass NULL to unset. 421 * Set the callback for the `call_state` event. Pass NULL to unset.
231 * 422 *
232 * This event is triggered when a call state transition occurs.
233 */ 423 */
234void toxav_callback_call_state(ToxAV *av, toxav_call_state_cb *function, void *user_data); 424void toxav_callback_call_state(ToxAV *toxAV, toxav_call_state_cb *callback, void *user_data);
425
426
235/******************************************************************************* 427/*******************************************************************************
236 * 428 *
237 * :: Call control 429 * :: Call control
238 * 430 *
239 ******************************************************************************/ 431 ******************************************************************************/
432
433
434
240typedef enum TOXAV_CALL_CONTROL { 435typedef enum TOXAV_CALL_CONTROL {
241 /** 436
242 * Resume a previously paused call. Only valid if the pause was caused by this 437 /**
243 * client, if not, this control is ignored. Not valid before the call is accepted. 438 * Resume a previously paused call. Only valid if the pause was caused by this
244 */ 439 * client, if not, this control is ignored. Not valid before the call is accepted.
245 TOXAV_CALL_CONTROL_RESUME, 440 */
246 /** 441 TOXAV_CALL_CONTROL_RESUME,
247 * Put a call on hold. Not valid before the call is accepted. 442
248 */ 443 /**
249 TOXAV_CALL_CONTROL_PAUSE, 444 * Put a call on hold. Not valid before the call is accepted.
250 /** 445 */
251 * Reject a call if it was not answered, yet. Cancel a call after it was 446 TOXAV_CALL_CONTROL_PAUSE,
252 * answered. 447
253 */ 448 /**
254 TOXAV_CALL_CONTROL_CANCEL, 449 * Reject a call if it was not answered, yet. Cancel a call after it was
255 /** 450 * answered.
256 * Request that the friend stops sending audio. Regardless of the friend's 451 */
257 * compliance, this will cause the `receive_audio_frame` event to stop being 452 TOXAV_CALL_CONTROL_CANCEL,
258 * triggered on receiving an audio frame from the friend. If the audio was 453
259 * already muted, calling this control will notify client to start sending 454 /**
260 * audio again. 455 * Request that the friend stops sending audio. Regardless of the friend's
261 */ 456 * compliance, this will cause the audio_receive_frame event to stop being
262 TOXAV_CALL_CONTROL_TOGGLE_MUTE_AUDIO, 457 * triggered on receiving an audio frame from the friend.
263 /** 458 */
264 * Request that the friend stops sending video. Regardless of the friend's 459 TOXAV_CALL_CONTROL_MUTE_AUDIO,
265 * compliance, this will cause the `receive_video_frame` event to stop being 460
266 * triggered on receiving an video frame from the friend. If the video was 461 /**
267 * already hidden, calling this control will notify client to start sending 462 * Calling this control will notify client to start sending audio again.
268 * video again. 463 */
269 */ 464 TOXAV_CALL_CONTROL_UNMUTE_AUDIO,
270 TOXAV_CALL_CONTROL_TOGGLE_HIDE_VIDEO 465
466 /**
467 * Request that the friend stops sending video. Regardless of the friend's
468 * compliance, this will cause the video_receive_frame event to stop being
469 * triggered on receiving an video frame from the friend.
470 */
471 TOXAV_CALL_CONTROL_HIDE_VIDEO,
472
473 /**
474 * Calling this control will notify client to start sending video again.
475 */
476 TOXAV_CALL_CONTROL_SHOW_VIDEO,
477
271} TOXAV_CALL_CONTROL; 478} TOXAV_CALL_CONTROL;
479
480
272typedef enum TOXAV_ERR_CALL_CONTROL { 481typedef enum TOXAV_ERR_CALL_CONTROL {
273 TOXAV_ERR_CALL_CONTROL_OK, 482
274 /** 483 /**
275 * The friend_number passed did not designate a valid friend. 484 * The function returned successfully.
276 */ 485 */
277 TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_FOUND, 486 TOXAV_ERR_CALL_CONTROL_OK,
278 /** 487
279 * This client is currently not in a call with the friend. Before the call is 488 /**
280 * answered, only CANCEL is a valid control. 489 * The friend_number passed did not designate a valid friend.
281 */ 490 */
282 TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_IN_CALL, 491 TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_FOUND,
283 /** 492
284 * Attempted to resume a call that was not paused. 493 /**
285 */ 494 * This client is currently not in a call with the friend. Before the call is
286 TOXAV_ERR_CALL_CONTROL_NOT_PAUSED, 495 * answered, only CANCEL is a valid control.
287 /** 496 */
288 * The call was already paused on this client. It is valid to pause if the 497 TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_IN_CALL,
289 * other party paused the call. The call will resume after both parties sent 498
290 * the RESUME control. 499 /**
291 */ 500 * Happens if user tried to pause an already paused call or if trying to
292 TOXAV_ERR_CALL_CONTROL_ALREADY_PAUSED 501 * resume a call that is not paused.
502 */
503 TOXAV_ERR_CALL_CONTROL_INVALID_TRANSITION,
504
293} TOXAV_ERR_CALL_CONTROL; 505} TOXAV_ERR_CALL_CONTROL;
506
507
294/** 508/**
295 * Sends a call control command to a friend. 509 * Sends a call control command to a friend.
296 * 510 *
@@ -300,29 +514,44 @@ typedef enum TOXAV_ERR_CALL_CONTROL {
300 * 514 *
301 * @return true on success. 515 * @return true on success.
302 */ 516 */
303bool toxav_call_control(ToxAV *av, uint32_t friend_number, TOXAV_CALL_CONTROL control, TOXAV_ERR_CALL_CONTROL *error); 517bool toxav_call_control(ToxAV *toxAV, uint32_t friend_number, TOXAV_CALL_CONTROL control, TOXAV_ERR_CALL_CONTROL *error);
518
519
304/******************************************************************************* 520/*******************************************************************************
305 * 521 *
306 * :: Controlling bit rates 522 * :: Controlling bit rates
307 * 523 *
308 ******************************************************************************/ 524 ******************************************************************************/
309typedef enum TOXAV_ERR_BIT_RATE { 525
310 TOXAV_ERR_BIT_RATE_OK, 526
311 /** 527
312 * The bit rate passed was not one of the supported values. 528typedef enum TOXAV_ERR_SET_BIT_RATE {
313 */ 529
314 TOXAV_ERR_BIT_RATE_INVALID, 530 /**
315 /** 531 * The function returned successfully.
316 * The friend_number passed did not designate a valid friend. 532 */
317 */ 533 TOXAV_ERR_SET_BIT_RATE_OK,
318 TOXAV_ERR_BIT_RATE_FRIEND_NOT_FOUND, 534
319 /** 535 /**
320 * This client is currently not in a call with the friend. 536 * The bit rate passed was not one of the supported values.
321 */ 537 */
322 TOXAV_ERR_BIT_RATE_FRIEND_NOT_IN_CALL 538 TOXAV_ERR_SET_BIT_RATE_INVALID,
323} TOXAV_ERR_BIT_RATE; 539
324/** 540 /**
325 * The function type for the `audio_bit_rate_status` callback. 541 * The friend_number passed did not designate a valid friend.
542 */
543 TOXAV_ERR_SET_BIT_RATE_FRIEND_NOT_FOUND,
544
545 /**
546 * This client is currently not in a call with the friend.
547 */
548 TOXAV_ERR_SET_BIT_RATE_FRIEND_NOT_IN_CALL,
549
550} TOXAV_ERR_SET_BIT_RATE;
551
552
553/**
554 * The function type for the audio_bit_rate_status callback.
326 * 555 *
327 * @param friend_number The friend number of the friend for which to set the 556 * @param friend_number The friend number of the friend for which to set the
328 * audio bit rate. 557 * audio bit rate.
@@ -334,11 +563,15 @@ typedef enum TOXAV_ERR_BIT_RATE {
334 * or the non forceful change failed. 563 * or the non forceful change failed.
335 * @param bit_rate The bit rate in Kb/sec. 564 * @param bit_rate The bit rate in Kb/sec.
336 */ 565 */
337typedef void toxav_audio_bit_rate_status_cb(ToxAV *av, uint32_t friend_number, bool stable, uint32_t bit_rate, void *user_data); 566typedef void toxav_audio_bit_rate_status_cb(ToxAV *toxAV, uint32_t friend_number, bool stable, uint32_t bit_rate, void *user_data);
567
568
338/** 569/**
339 * Set the callback for the `audio_bit_rate_status` event. Pass NULL to unset. 570 * Set the callback for the `audio_bit_rate_status` event. Pass NULL to unset.
571 *
340 */ 572 */
341void toxav_callback_audio_bit_rate_status(ToxAV *av, toxav_audio_bit_rate_status_cb *function, void *user_data); 573void toxav_callback_audio_bit_rate_status(ToxAV *toxAV, toxav_audio_bit_rate_status_cb *callback, void *user_data);
574
342/** 575/**
343 * Set the audio bit rate to be used in subsequent audio frames. If the passed 576 * Set the audio bit rate to be used in subsequent audio frames. If the passed
344 * bit rate is the same as the current bit rate this function will return true 577 * bit rate is the same as the current bit rate this function will return true
@@ -351,12 +584,13 @@ void toxav_callback_audio_bit_rate_status(ToxAV *av, toxav_audio_bit_rate_status
351 * audio bit rate. 584 * audio bit rate.
352 * @param audio_bit_rate The new audio bit rate in Kb/sec. Set to 0 to disable 585 * @param audio_bit_rate The new audio bit rate in Kb/sec. Set to 0 to disable
353 * audio sending. 586 * audio sending.
354 * 587 * @param force True if the bit rate change is forceful.
355 * @see toxav_call for the valid bit rates. 588 *
356 */ 589 */
357bool toxav_set_audio_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, bool force, TOXAV_ERR_BIT_RATE *error); 590bool toxav_audio_bit_rate_set(ToxAV *toxAV, uint32_t friend_number, uint32_t audio_bit_rate, bool force, TOXAV_ERR_SET_BIT_RATE *error);
591
358/** 592/**
359 * The function type for the `video_bit_rate_status` callback. 593 * The function type for the video_bit_rate_status callback.
360 * 594 *
361 * @param friend_number The friend number of the friend for which to set the 595 * @param friend_number The friend number of the friend for which to set the
362 * video bit rate. 596 * video bit rate.
@@ -368,79 +602,78 @@ bool toxav_set_audio_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t audio_
368 * or the non forceful change failed. 602 * or the non forceful change failed.
369 * @param bit_rate The bit rate in Kb/sec. 603 * @param bit_rate The bit rate in Kb/sec.
370 */ 604 */
371typedef void toxav_video_bit_rate_status_cb(ToxAV *av, uint32_t friend_number, bool stable, uint32_t bit_rate, void *user_data); 605typedef void toxav_video_bit_rate_status_cb(ToxAV *toxAV, uint32_t friend_number, bool stable, uint32_t bit_rate, void *user_data);
606
607
372/** 608/**
373 * Set the callback for the `video_bit_rate_status` event. Pass NULL to unset. 609 * Set the callback for the `video_bit_rate_status` event. Pass NULL to unset.
610 *
374 */ 611 */
375void toxav_callback_video_bit_rate_status(ToxAV *av, toxav_video_bit_rate_status_cb *function, void *user_data); 612void toxav_callback_video_bit_rate_status(ToxAV *toxAV, toxav_video_bit_rate_status_cb *callback, void *user_data);
613
376/** 614/**
377 * Set the video bit rate to be used in subsequent video frames. If the passed 615 * Set the video bit rate to be used in subsequent video frames. If the passed
378 * bit rate is the same as the current bit rate this function will return true 616 * bit rate is the same as the current bit rate this function will return true
379 * without calling a callback. If there is an active non forceful setup with the 617 * without calling a callback. If there is an active non forceful setup with the
380 * passed bit rate and the new set request is forceful, the bit rate is 618 * passed video bit rate and the new set request is forceful, the bit rate is
381 * forcefully set and the previous non forceful request is cancelled. The active 619 * forcefully set and the previous non forceful request is cancelled. The active
382 * non forceful setup will be canceled in favour of new non forceful setup. 620 * non forceful setup will be canceled in favour of new non forceful setup.
383 * 621 *
384 * @param friend_number The friend number of the friend for which to set the 622 * @param friend_number The friend number of the friend for which to set the
385 * video bit rate. 623 * video bit rate.
386 * @param video_bit_rate The new video bit rate in Kb/sec. Set to 0 to disable 624 * @param audio_bit_rate The new video bit rate in Kb/sec. Set to 0 to disable
387 * video sending. 625 * video sending.
388 * 626 * @param force True if the bit rate change is forceful.
389 * @see toxav_call for the valid bit rates. 627 *
390 */ 628 */
391bool toxav_set_video_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t video_bit_rate, bool force, TOXAV_ERR_BIT_RATE *error); 629bool toxav_video_bit_rate_set(ToxAV *toxAV, uint32_t friend_number, uint32_t audio_bit_rate, bool force, TOXAV_ERR_SET_BIT_RATE *error);
630
631
392/******************************************************************************* 632/*******************************************************************************
393 * 633 *
394 * :: A/V sending 634 * :: A/V sending
395 * 635 *
396 ******************************************************************************/ 636 ******************************************************************************/
397/** 637
398 * Common error codes for the send_*_frame functions. 638
399 */ 639
400typedef enum TOXAV_ERR_SEND_FRAME { 640typedef enum TOXAV_ERR_SEND_FRAME {
401 TOXAV_ERR_SEND_FRAME_OK, 641
402 /** 642 /**
403 * In case of video, one of Y, U, or V was NULL. In case of audio, the samples 643 * The function returned successfully.
404 * data pointer was NULL. 644 */
405 */ 645 TOXAV_ERR_SEND_FRAME_OK,
406 TOXAV_ERR_SEND_FRAME_NULL, 646
407 /** 647 /**
408 * The friend_number passed did not designate a valid friend. 648 * In case of video, one of Y, U, or V was NULL. In case of audio, the samples
409 */ 649 * data pointer was NULL.
410 TOXAV_ERR_SEND_FRAME_FRIEND_NOT_FOUND, 650 */
411 /** 651 TOXAV_ERR_SEND_FRAME_NULL,
412 * This client is currently not in a call with the friend. 652
413 */ 653 /**
414 TOXAV_ERR_SEND_FRAME_FRIEND_NOT_IN_CALL, 654 * The friend_number passed did not designate a valid friend.
415 /** 655 */
416 * One of the frame parameters was invalid. E.g. the resolution may be too 656 TOXAV_ERR_SEND_FRAME_FRIEND_NOT_FOUND,
417 * small or too large, or the audio sampling rate may be unsupported. 657
418 */ 658 /**
419 TOXAV_ERR_SEND_FRAME_INVALID, 659 * This client is currently not in a call with the friend.
420 /** 660 */
421 * Failed to push frame through rtp interface. 661 TOXAV_ERR_SEND_FRAME_FRIEND_NOT_IN_CALL,
422 */ 662
423 TOXAV_ERR_SEND_FRAME_RTP_FAILED 663 /**
664 * One of the frame parameters was invalid. E.g. the resolution may be too
665 * small or too large, or the audio sampling rate may be unsupported.
666 */
667 TOXAV_ERR_SEND_FRAME_INVALID,
668
669 /**
670 * Failed to push frame through rtp interface.
671 */
672 TOXAV_ERR_SEND_FRAME_RTP_FAILED,
673
424} TOXAV_ERR_SEND_FRAME; 674} TOXAV_ERR_SEND_FRAME;
425/** 675
426 * Send a video frame to a friend. 676
427 *
428 * Y - plane should be of size: height * width
429 * U - plane should be of size: (height/2) * (width/2)
430 * V - plane should be of size: (height/2) * (width/2)
431 *
432 * @param friend_number The friend number of the friend to which to send a video
433 * frame.
434 * @param width Width of the frame in pixels.
435 * @param height Height of the frame in pixels.
436 * @param y Y (Luminance) plane data.
437 * @param u U (Chroma) plane data.
438 * @param v V (Chroma) plane data.
439 */
440bool toxav_send_video_frame(ToxAV *av, uint32_t friend_number,
441 uint16_t width, uint16_t height,
442 uint8_t const *y, uint8_t const *u, uint8_t const *v,
443 TOXAV_ERR_SEND_FRAME *error);
444/** 677/**
445 * Send an audio frame to a friend. 678 * Send an audio frame to a friend.
446 * 679 *
@@ -461,19 +694,56 @@ bool toxav_send_video_frame(ToxAV *av, uint32_t friend_number,
461 * @param sampling_rate Audio sampling rate used in this frame. Valid sampling 694 * @param sampling_rate Audio sampling rate used in this frame. Valid sampling
462 * rates are 8000, 12000, 16000, 24000, or 48000. 695 * rates are 8000, 12000, 16000, 24000, or 48000.
463 */ 696 */
464bool toxav_send_audio_frame(ToxAV *av, uint32_t friend_number, 697bool toxav_audio_send_frame(ToxAV *toxAV, uint32_t friend_number, const int16_t *pcm, size_t sample_count, uint8_t channels, uint32_t sampling_rate, TOXAV_ERR_SEND_FRAME *error);
465 int16_t const *pcm, 698
466 size_t sample_count, 699/**
467 uint8_t channels, 700 * Send a video frame to a friend.
468 uint32_t sampling_rate, 701 *
469 TOXAV_ERR_SEND_FRAME *error); 702 * Y - plane should be of size: height * width
703 * U - plane should be of size: (height/2) * (width/2)
704 * V - plane should be of size: (height/2) * (width/2)
705 *
706 * @param friend_number The friend number of the friend to which to send a video
707 * frame.
708 * @param width Width of the frame in pixels.
709 * @param height Height of the frame in pixels.
710 * @param y Y (Luminance) plane data.
711 * @param u U (Chroma) plane data.
712 * @param v V (Chroma) plane data.
713 * @param a A (Alpha) plane data.
714 */
715bool toxav_video_send_frame(ToxAV *toxAV, uint32_t friend_number, uint16_t width, uint16_t height, const uint8_t *y, const uint8_t *u, const uint8_t *v, const uint8_t *a, TOXAV_ERR_SEND_FRAME *error);
716
717
470/******************************************************************************* 718/*******************************************************************************
471 * 719 *
472 * :: A/V receiving 720 * :: A/V receiving
473 * 721 *
474 ******************************************************************************/ 722 ******************************************************************************/
723
724
725
475/** 726/**
476 * The function type for the `receive_video_frame` callback. 727 * The function type for the audio_receive_frame callback.
728 *
729 * @param friend_number The friend number of the friend who sent an audio frame.
730 * @param pcm An array of audio samples (sample_count * channels elements).
731 * @param sample_count The number of audio samples per channel in the PCM array.
732 * @param channels Number of audio channels.
733 * @param sampling_rate Sampling rate used in this frame.
734 *
735 */
736typedef void toxav_audio_receive_frame_cb(ToxAV *toxAV, uint32_t friend_number, const int16_t *pcm, size_t sample_count, uint8_t channels, uint32_t sampling_rate, void *user_data);
737
738
739/**
740 * Set the callback for the `audio_receive_frame` event. Pass NULL to unset.
741 *
742 */
743void toxav_callback_audio_receive_frame(ToxAV *toxAV, toxav_audio_receive_frame_cb *callback, void *user_data);
744
745/**
746 * The function type for the video_receive_frame callback.
477 * 747 *
478 * @param friend_number The friend number of the friend who sent a video frame. 748 * @param friend_number The friend number of the friend who sent a video frame.
479 * @param width Width of the frame in pixels. 749 * @param width Width of the frame in pixels.
@@ -482,44 +752,26 @@ bool toxav_send_audio_frame(ToxAV *av, uint32_t friend_number,
482 * @param u 752 * @param u
483 * @param v Plane data. 753 * @param v Plane data.
484 * The size of plane data is derived from width and height where 754 * The size of plane data is derived from width and height where
485 * Y = width * height, U = (width/2) * (height/2) and V = (width/2) * (height/2). 755 * Y = MAX(width, abs(ystride)) * height,
756 * U = MAX(width/2, abs(ustride)) * (height/2) and
757 * V = MAX(width/2, abs(vstride)) * (height/2).
758 * A = MAX(width, abs(astride)) * height.
486 * @param ystride 759 * @param ystride
487 * @param ustride 760 * @param ustride
488 * @param vstride Strides data. 761 * @param vstride
489 */ 762 * @param astride Strides data. Strides represent padding for each plane
490typedef void toxav_receive_video_frame_cb(ToxAV *av, uint32_t friend_number, 763 * that may or may not be present. You must handle strides in
491 uint16_t width, uint16_t height, 764 * your image processing code. Strides are negative if the
492 uint8_t const *y, uint8_t const *u, uint8_t const *v, 765 * image is bottom-up hence why you MUST abs() it when
493 int32_t ystride, int32_t ustride, int32_t vstride, 766 * calculating plane buffer size.
494 void *user_data);
495/**
496 * Set the callback for the `receive_video_frame` event. Pass NULL to unset.
497 */ 767 */
498void toxav_callback_receive_video_frame(ToxAV *av, toxav_receive_video_frame_cb *function, void *user_data); 768typedef void toxav_video_receive_frame_cb(ToxAV *toxAV, uint32_t friend_number, uint16_t width, uint16_t height, const uint8_t *y, const uint8_t *u, const uint8_t *v, const uint8_t *a, int32_t ystride, int32_t ustride, int32_t vstride, int32_t astride, void *user_data);
769
770
499/** 771/**
500 * The function type for the `receive_audio_frame` callback. 772 * Set the callback for the `video_receive_frame` event. Pass NULL to unset.
501 *
502 * @param friend_number The friend number of the friend who sent an audio frame.
503 * @param pcm An array of audio samples (sample_count * channels elements).
504 * @param sample_count The number of audio samples per channel in the PCM array.
505 * @param channels Number of audio channels.
506 * @param sampling_rate Sampling rate used in this frame.
507 * 773 *
508 * @see toxav_send_audio_frame for the audio format.
509 */
510typedef void toxav_receive_audio_frame_cb(ToxAV *av, uint32_t friend_number,
511 int16_t const *pcm,
512 size_t sample_count,
513 uint8_t channels,
514 uint32_t sampling_rate,
515 void *user_data);
516/**
517 * Set the callback for the `receive_audio_frame` event. Pass NULL to unset.
518 */ 774 */
519void toxav_callback_receive_audio_frame(ToxAV *av, toxav_receive_audio_frame_cb *function, void *user_data); 775void toxav_callback_video_receive_frame(ToxAV *toxAV, toxav_video_receive_frame_cb *callback, void *user_data);
520 776
521#ifdef __cplusplus
522}
523#endif 777#endif
524
525#endif /* TOXAV_H */