summaryrefslogtreecommitdiff
path: root/toxav/toxav.h
blob: 101047edf2eaffa6480174542b9c65dd4c2cdc82 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
/**  toxav.h
 * 
 *   Copyright (C) 2013-2015 Tox project All Rights Reserved.
 *
 *   This file is part of Tox.
 *
 *   Tox is free software: you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License as published by
 *   the Free Software Foundation, either version 3 of the License, or
 *   (at your option) any later version.
 *
 *   Tox is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with Tox. If not, see <http://www.gnu.org/licenses/>.
 *
 */

#ifndef TOXAV_H
#define TOXAV_H

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
/** \page av Public audio/video API for Tox clients.
 * 
 * Unlike the Core API, this API is fully thread-safe. The library will ensure
 * the proper synchronisation of parallel calls.
 */
/**
 * The type of the Tox Audio/Video subsystem object.
 */
typedef struct toxAV ToxAV;
#ifndef TOX_DEFINED
#define TOX_DEFINED
/**
 * The type of a Tox instance. Repeated here so this file does not have a direct
 * dependency on the Core interface.
 */
typedef struct Tox Tox;
#endif
/*******************************************************************************
 * 
 * :: Creation and destruction
 *
 ******************************************************************************/
typedef enum TOXAV_ERR_NEW {
    TOXAV_ERR_NEW_OK,
    TOXAV_ERR_NEW_NULL,
    /**
     * Memory allocation failure while trying to allocate structures required for
     * the A/V session.
     */
    TOXAV_ERR_NEW_MALLOC,
    /**
     * Attempted to create a second session for the same Tox instance.
     */
    TOXAV_ERR_NEW_MULTIPLE
} TOXAV_ERR_NEW;
/**
 * Start new A/V session. There can only be only one session per Tox instance.
 */
ToxAV *toxav_new(Tox *tox, TOXAV_ERR_NEW *error);
/**
 * Releases all resources associated with the A/V session.
 *
 * If any calls were ongoing, these will be forcibly terminated without
 * notifying peers. After calling this function, no other functions may be
 * called and the av pointer becomes invalid.
 */
void toxav_kill(ToxAV *av);
/**
 * Returns the Tox instance the A/V object was created for.
 */
Tox *toxav_get_tox(ToxAV *av);
/*******************************************************************************
 * 
 * :: A/V event loop
 *
 ******************************************************************************/
/**
 * Returns the interval in milliseconds when the next toxav_iteration should be
 * called. If no call is active at the moment, this function returns 200.
 */
uint32_t toxav_iteration_interval(ToxAV const *av);
/**
 * Main loop for the session. This function needs to be called in intervals of
 * toxav_iteration_interval() milliseconds. It is best called in the same loop
 * as tox_iteration.
 */
void toxav_iteration(ToxAV *av);
/*******************************************************************************
 * 
 * :: Call setup
 *
 ******************************************************************************/
typedef enum TOXAV_ERR_CALL {
    TOXAV_ERR_CALL_OK,
    /**
     * A resource allocation error occurred while trying to create the structures
     * required for the call.
     */
    TOXAV_ERR_CALL_MALLOC,
    /**
     * The friend number did not designate a valid friend.
     */
    TOXAV_ERR_CALL_FRIEND_NOT_FOUND,
    /**
     * The friend was valid, but not currently connected.
     */
    TOXAV_ERR_CALL_FRIEND_NOT_CONNECTED,
    /**
     * Attempted to call a friend while already in an audio or video call with
     * them.
     */
    TOXAV_ERR_CALL_FRIEND_ALREADY_IN_CALL,
    /**
     * Audio or video bit rate is invalid.
     */
    TOXAV_ERR_CALL_INVALID_BIT_RATE
} TOXAV_ERR_CALL;
/**
 * Call a friend. This will start ringing the friend.
 *
 * It is the client's responsibility to stop ringing after a certain timeout,
 * if such behaviour is desired. If the client does not stop ringing, the A/V
 * library will not stop until the friend is disconnected.
 *
 * @param friend_number The friend number of the friend that should be called.
 * @param audio_bit_rate Audio bit rate in Kb/sec. Set this to 0 to disable
 * audio sending.
 * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable
 * video sending.
 */
bool toxav_call(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, TOXAV_ERR_CALL *error);
/**
 * The function type for the `call` callback.
 */
typedef void toxav_call_cb(ToxAV *av, uint32_t friend_number, bool audio_enabled, bool video_enabled, void *user_data);
/**
 * Set the callback for the `call` event. Pass NULL to unset.
 *
 * This event is triggered when a call is received from a friend.
 */
void toxav_callback_call(ToxAV *av, toxav_call_cb *function, void *user_data);
typedef enum TOXAV_ERR_ANSWER {
    TOXAV_ERR_ANSWER_OK,
    /**
     * A resource allocation error occurred while trying to create the structures
     * required for the call.
     */
    TOXAV_ERR_ANSWER_MALLOC,
    /**
     * The friend number did not designate a valid friend.
     */
    TOXAV_ERR_ANSWER_FRIEND_NOT_FOUND,
    /**
     * The friend was valid, but they are not currently trying to initiate a call.
     * This is also returned if this client is already in a call with the friend.
     */
    TOXAV_ERR_ANSWER_FRIEND_NOT_CALLING,
    /**
     * Audio or video bit rate is invalid.
     */
    TOXAV_ERR_ANSWER_INVALID_BIT_RATE
} TOXAV_ERR_ANSWER;
/**
 * Accept an incoming call.
 *
 * If an allocation error occurs while answering a call, both participants will
 * receive TOXAV_CALL_STATE_ERROR and the call will end.
 *
 * @param friend_number The friend number of the friend that is calling.
 * @param audio_bit_rate Audio bit rate in Kb/sec. Set this to 0 to disable
 * audio sending.
 * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable
 * video sending.
 */
bool toxav_answer(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, TOXAV_ERR_ANSWER *error);
/*******************************************************************************
 * 
 * :: Call state graph
 *
 ******************************************************************************/
typedef enum TOXAV_CALL_STATE {
    /**
     * Not sending nor receiving anything, meaning, one of the sides requested pause.
     * The call will be resumed once the side that initiated pause resumes it.
     */
    TOXAV_CALL_STATE_PAUSED = 0,
    /**
     * The flag that marks that friend is sending audio.
     */
    TOXAV_CALL_STATE_SENDING_A = 1,
    /**
     * The flag that marks that friend is sending video.
     */
    TOXAV_CALL_STATE_SENDING_V = 2,
    /**
     * The flag that marks that friend is receiving audio.
     */
    TOXAV_CALL_STATE_RECEIVING_A = 4,
    /**
     * The flag that marks that friend is receiving video.
     */
    TOXAV_CALL_STATE_RECEIVING_V = 8,
    
    /** 
     * The core will never set TOXAV_CALL_STATE_END or TOXAV_CALL_STATE_ERROR 
     * together with other states.
     */
    
    /**
     * The call has finished. This is the final state after which no more state
     * transitions can occur for the call.
     */
    TOXAV_CALL_STATE_END = 16,
    /**
     * Sent by the AV core if an error occurred on the remote end.
     */
    TOXAV_CALL_STATE_ERROR = 32
} TOXAV_CALL_STATE;
/**
 * The function type for the `call_state` callback.
 *
 * @param friend_number The friend number for which the call state changed.
 * @param state The new call state.
 */
typedef void toxav_call_state_cb(ToxAV *av, uint32_t friend_number, uint32_t state, void *user_data);
/**
 * Set the callback for the `call_state` event. Pass NULL to unset.
 *
 * This event is triggered when a call state transition occurs.
 */
void toxav_callback_call_state(ToxAV *av, toxav_call_state_cb *function, void *user_data);
/*******************************************************************************
 * 
 * :: Call control
 *
 ******************************************************************************/
typedef enum TOXAV_CALL_CONTROL {
    /**
     * Resume a previously paused call. Only valid if the pause was caused by this
     * client, if not, this control is ignored. Not valid before the call is accepted.
     */
    TOXAV_CALL_CONTROL_RESUME,
    /**
     * Put a call on hold. Not valid before the call is accepted.
     */
    TOXAV_CALL_CONTROL_PAUSE,
    /**
     * Reject a call if it was not answered, yet. Cancel a call after it was
     * answered.
     */
    TOXAV_CALL_CONTROL_CANCEL,
    /**
     * Request that the friend stops sending audio. Regardless of the friend's
     * compliance, this will cause the `receive_audio_frame` event to stop being
     * triggered on receiving an audio frame from the friend. If the audio was
     * already muted, calling this control will notify client to start sending
     * audio again.
     */
    TOXAV_CALL_CONTROL_TOGGLE_MUTE_AUDIO,
    /**
     * Request that the friend stops sending video. Regardless of the friend's
     * compliance, this will cause the `receive_video_frame` event to stop being
     * triggered on receiving an video frame from the friend. If the video was
     * already muted, calling this control will notify client to start sending
     * video again.
     */
    TOXAV_CALL_CONTROL_TOGGLE_MUTE_VIDEO,
} TOXAV_CALL_CONTROL;
typedef enum TOXAV_ERR_CALL_CONTROL {
    TOXAV_ERR_CALL_CONTROL_OK,
    /**
     * The friend_number passed did not designate a valid friend.
     */
    TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_FOUND,
    /**
     * This client is currently not in a call with the friend. Before the call is
     * answered, only CANCEL is a valid control.
     */
    TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_IN_CALL,
    /**
     * Attempted to resume a call that was not paused.
     */
    TOXAV_ERR_CALL_CONTROL_NOT_PAUSED,
    /**
     * Attempted to resume a call that was paused by the other party. Also set if
     * the client attempted to send a system-only control.
     */
    TOXAV_ERR_CALL_CONTROL_DENIED,
    /**
     * The call was already paused on this client. It is valid to pause if the
     * other party paused the call. The call will resume after both parties sent
     * the RESUME control.
     */
    TOXAV_ERR_CALL_CONTROL_ALREADY_PAUSED,
    /**
     * Tried to unmute a call that was not already muted.
     */
    TOXAV_ERR_CALL_CONTROL_NOT_MUTED
} TOXAV_ERR_CALL_CONTROL;
/**
 * Sends a call control command to a friend.
 *
 * @param friend_number The friend number of the friend this client is in a call
 * with.
 * @param control The control command to send.
 *
 * @return true on success.
 */
bool toxav_call_control(ToxAV *av, uint32_t friend_number, TOXAV_CALL_CONTROL control, TOXAV_ERR_CALL_CONTROL *error);
/*******************************************************************************
 * 
 * :: Controlling bit rates
 *
 ******************************************************************************/
typedef enum TOXAV_ERR_BIT_RATE {
    TOXAV_ERR_BIT_RATE_OK,
    /**
     * The bit rate passed was not one of the supported values.
     */
    TOXAV_ERR_BIT_RATE_INVALID
} TOXAV_ERR_BIT_RATE;
/**
 * Set the audio bit rate to be used in subsequent audio frames.
 *
 * @param friend_number The friend number of the friend for which to set the
 * audio bit rate.
 * @param audio_bit_rate The new audio bit rate in Kb/sec. Set to 0 to disable
 * audio sending.
 *
 * @see toxav_call for the valid bit rates.
 */
bool toxav_set_audio_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, TOXAV_ERR_BIT_RATE *error);
/**
 * Set the video bit rate to be used in subsequent video frames.
 *
 * @param friend_number The friend number of the friend for which to set the
 * video bit rate.
 * @param video_bit_rate The new video bit rate in Kb/sec. Set to 0 to disable
 * video sending.
 *
 * @see toxav_call for the valid bit rates.
 */
bool toxav_set_video_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t video_bit_rate, TOXAV_ERR_BIT_RATE *error);
/*******************************************************************************
 * 
 * :: A/V sending
 *
 ******************************************************************************/
/**
 * Common error codes for the send_*_frame functions.
 */
typedef enum TOXAV_ERR_SEND_FRAME {
    TOXAV_ERR_SEND_FRAME_OK,
    /**
     * In case of video, one of Y, U, or V was NULL. In case of audio, the samples
     * data pointer was NULL.
     */
    TOXAV_ERR_SEND_FRAME_NULL,
    /**
     * The friend_number passed did not designate a valid friend.
     */
    TOXAV_ERR_SEND_FRAME_FRIEND_NOT_FOUND,
    /**
     * This client is currently not in a call with the friend.
     */
    TOXAV_ERR_SEND_FRAME_FRIEND_NOT_IN_CALL,
    /**
     * No video frame had been requested through the `request_video_frame` event,
     * but the client tried to send one, anyway.
     */
    TOXAV_ERR_SEND_FRAME_NOT_REQUESTED,
    /**
     * One of the frame parameters was invalid. E.g. the resolution may be too
     * small or too large, or the audio sampling rate may be unsupported.
     */
    TOXAV_ERR_SEND_FRAME_INVALID
} TOXAV_ERR_SEND_FRAME;
/**
 * The function type for the `request_video_frame` callback.
 *
 * @param friend_number The friend number of the friend for which the next video
 * frame should be sent.
 */
typedef void toxav_request_video_frame_cb(ToxAV *av, uint32_t friend_number, void *user_data);
/**
 * Set the callback for the `request_video_frame` event. Pass NULL to unset.
 */
void toxav_callback_request_video_frame(ToxAV *av, toxav_request_video_frame_cb *function, void *user_data);
/**
 * Send a video frame to a friend.
 *
 * This is called in response to receiving the `request_video_frame` event.
 *
 * Y - plane should be of size: height * width
 * U - plane should be of size: (height/2) * (width/2)
 * V - plane should be of size: (height/2) * (width/2)
 *
 * @param friend_number The friend number of the friend to which to send a video
 * frame.
 * @param width Width of the frame in pixels.
 * @param height Height of the frame in pixels.
 * @param y Y (Luminance) plane data.
 * @param u U (Chroma) plane data.
 * @param v V (Chroma) plane data.
 */
bool toxav_send_video_frame(ToxAV *av, uint32_t friend_number,
                            uint16_t width, uint16_t height,
                            uint8_t const *y, uint8_t const *u, uint8_t const *v,
                            TOXAV_ERR_SEND_FRAME *error);
/**
 * The function type for the `request_audio_frame` callback.
 *
 * @param friend_number The friend number of the friend for which the next audio
 * frame should be sent.
 */
typedef void toxav_request_audio_frame_cb(ToxAV *av, uint32_t friend_number, void *user_data);
/**
 * Set the callback for the `request_audio_frame` event. Pass NULL to unset.
 */
void toxav_callback_request_audio_frame(ToxAV *av, toxav_request_audio_frame_cb *function, void *user_data);
/**
 * Send an audio frame to a friend.
 *
 * This is called in response to receiving the `request_audio_frame` event.
 *
 * The expected format of the PCM data is: [s1c1][s1c2][...][s2c1][s2c2][...]...
 * Meaning: sample 1 for channel 1, sample 1 for channel 2, ...
 * For mono audio, this has no meaning, every sample is subsequent. For stereo,
 * this means the expected format is LRLRLR... with samples for left and right
 * alternating.
 *
 * @param friend_number The friend number of the friend to which to send an
 * audio frame.
 * @param pcm An array of audio samples. The size of this array must be
 * sample_count * channels.
 * @param sample_count Number of samples in this frame. Valid numbers here are
 * ((sample rate) * (audio length) / 1000), where audio length can be
 * 2.5, 5, 10, 20, 40 or 60 millseconds.
 * @param channels Number of audio channels. Must be at least 1 for mono.
 * For voice over IP, more than 2 channels (stereo) typically doesn't make
 * sense, but up to 255 channels are supported.
 * @param sampling_rate Audio sampling rate used in this frame. Valid sampling
 * rates are 8000, 12000, 16000, 24000, or 48000.
 */
bool toxav_send_audio_frame(ToxAV *av, uint32_t friend_number,
                            int16_t const *pcm,
                            size_t sample_count,
                            uint8_t channels,
                            uint32_t sampling_rate,
                            TOXAV_ERR_SEND_FRAME *error);
/*******************************************************************************
 * 
 * :: A/V receiving
 *
 ******************************************************************************/
/**
 * The function type for the `receive_video_frame` callback.
 *
 * Each plane contains (width * height) pixels. The Alpha plane can be NULL, in
 * which case every pixel should be assumed fully opaque.
 *
 * @param friend_number The friend number of the friend who sent a video frame.
 * @param width Width of the frame in pixels.
 * @param height Height of the frame in pixels.
 * @param planes Plane data. To access Y (Luminance) plane use index 0,
 *                           To access U (Chroma) plane use index 1,
 *                           To access V (Chroma) plane use index 2.
 *               The size of plane data is derived from width and height where
 *               Y = width * height, U = (width/2) * (height/2) and V = (width/2) * (height/2).
 * @param stride Strides data. Indexing is the same as in 'planes' param.
 */
typedef void toxav_receive_video_frame_cb(ToxAV *av, uint32_t friend_number,
                                          uint16_t width, uint16_t height,
                                          uint8_t const *planes[], int32_t const stride[],
                                          void *user_data);
/**
 * Set the callback for the `receive_video_frame` event. Pass NULL to unset.
 */
void toxav_callback_receive_video_frame(ToxAV *av, toxav_receive_video_frame_cb *function, void *user_data);
/**
 * The function type for the `receive_audio_frame` callback.
 *
 * @param friend_number The friend number of the friend who sent an audio frame.
 * @param pcm An array of audio samples (sample_count * channels elements).
 * @param sample_count The number of audio samples per channel in the PCM array.
 * @param channels Number of audio channels.
 * @param sampling_rate Sampling rate used in this frame.
 *
 * @see toxav_send_audio_frame for the audio format.
 */
typedef void toxav_receive_audio_frame_cb(ToxAV *av, uint32_t friend_number,
                                          int16_t const *pcm,
                                          size_t sample_count,
                                          uint8_t channels,
                                          uint32_t sampling_rate,
                                          void *user_data);
/**
 * Set the callback for the `receive_audio_frame` event. Pass NULL to unset.
 */
void toxav_callback_receive_audio_frame(ToxAV *av, toxav_receive_audio_frame_cb *function, void *user_data);

#endif /* TOXAV_H */