diff options
Diffstat (limited to 'toxav/toxav.h')
-rw-r--r-- | toxav/toxav.h | 856 |
1 files changed, 652 insertions, 204 deletions
diff --git a/toxav/toxav.h b/toxav/toxav.h index 7285f45c..c75f8bff 100644 --- a/toxav/toxav.h +++ b/toxav/toxav.h | |||
@@ -1,329 +1,777 @@ | |||
1 | /** toxav.h | 1 | /* toxav.h |
2 | * | ||
3 | * Copyright (C) 2013-2015 Tox project All Rights Reserved. | ||
2 | * | 4 | * |
3 | * Copyright (C) 2013 Tox project All Rights Reserved. | 5 | * This file is part of Tox. |
4 | * | 6 | * |
5 | * This file is part of Tox. | 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 | ||
9 | * the Free Software Foundation, either version 3 of the License, or | ||
10 | * (at your option) any later version. | ||
6 | * | 11 | * |
7 | * Tox is free software: you can redistribute it and/or modify | 12 | * Tox is distributed in the hope that it will be useful, |
8 | * it under the terms of the GNU General Public License as published by | 13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
9 | * the Free Software Foundation, either version 3 of the License, or | 14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
10 | * (at your option) any later version. | 15 | * GNU General Public License for more details. |
11 | * | ||
12 | * Tox is distributed in the hope that it will be useful, | ||
13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
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 | ||
23 | #define TOXAV_H | ||
22 | 24 | ||
23 | #ifndef __TOXAV | 25 | #include <stdbool.h> |
24 | #define __TOXAV | 26 | #include <stddef.h> |
25 | #include <inttypes.h> | 27 | #include <stdint.h> |
26 | 28 | ||
27 | #ifdef __cplusplus | 29 | #ifdef __cplusplus |
28 | extern "C" { | 30 | extern "C" { |
29 | #endif | 31 | #endif |
30 | 32 | ||
31 | typedef struct _ToxAv ToxAv; | 33 | /** \page av Public audio/video API for Tox clients. |
32 | 34 | * | |
33 | /* vpx_image_t */ | 35 | * This API can handle multiple calls. Each call has its state, in very rare |
34 | #include <vpx/vpx_image.h> | 36 | * occasions the library can change the state of the call without apps knowledge. |
35 | 37 | * | |
36 | typedef void ( *ToxAVCallback ) ( void *agent, int32_t call_idx, void *arg ); | 38 | */ |
37 | typedef void ( *ToxAvAudioCallback ) (void *agent, int32_t call_idx, const int16_t *PCM, uint16_t size, void *data); | 39 | /** \subsection events Events and callbacks |
38 | typedef void ( *ToxAvVideoCallback ) (void *agent, int32_t call_idx, const vpx_image_t *img, void *data); | 40 | * |
39 | 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 | * | ||
54 | * Unlike the Core API, this API is fully thread-safe. The library will ensure | ||
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 | * | ||
61 | */ | ||
62 | /** | ||
63 | * External Tox type. | ||
64 | */ | ||
40 | #ifndef TOX_DEFINED | 65 | #ifndef TOX_DEFINED |
41 | #define TOX_DEFINED | 66 | #define TOX_DEFINED |
42 | typedef struct Tox Tox; | 67 | typedef struct Tox Tox; |
43 | #endif | 68 | #endif /* TOX_DEFINED */ |
44 | |||
45 | #define RTP_PAYLOAD_SIZE 65535 | ||
46 | |||
47 | 69 | ||
48 | /** | 70 | /** |
49 | * Callbacks ids that handle the call states. | 71 | * ToxAV. |
50 | */ | 72 | */ |
51 | typedef enum { | ||
52 | av_OnInvite, /* Incoming call */ | ||
53 | av_OnRinging, /* When peer is ready to accept/reject the call */ | ||
54 | av_OnStart, /* Call (RTP transmission) started */ | ||
55 | av_OnCancel, /* The side that initiated call canceled invite */ | ||
56 | av_OnReject, /* The side that was invited rejected the call */ | ||
57 | av_OnEnd, /* Call that was active ended */ | ||
58 | av_OnRequestTimeout, /* When the requested action didn't get response in specified time */ | ||
59 | av_OnPeerTimeout, /* Peer timed out; stop the call */ | ||
60 | av_OnPeerCSChange, /* Peer changing Csettings. Prepare for changed AV */ | ||
61 | av_OnSelfCSChange /* Csettings change confirmation. Once triggered peer is ready to recv changed AV */ | ||
62 | } ToxAvCallbackID; | ||
63 | |||
64 | |||
65 | /** | 73 | /** |
66 | * Call type identifier. | 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 | * | ||
67 | */ | 80 | */ |
68 | typedef enum { | 81 | #ifndef TOXAV_DEFINED |
69 | av_TypeAudio = 192, | 82 | #define TOXAV_DEFINED |
70 | av_TypeVideo | 83 | typedef struct ToxAV ToxAV; |
71 | } ToxAvCallType; | 84 | #endif /* TOXAV_DEFINED */ |
72 | 85 | ||
73 | 86 | ||
74 | typedef enum { | 87 | /******************************************************************************* |
75 | av_CallNonExistent = -1, | 88 | * |
76 | av_CallInviting, /* when sending call invite */ | 89 | * :: API version |
77 | av_CallStarting, /* when getting call invite */ | 90 | * |
78 | av_CallActive, | 91 | ******************************************************************************/ |
79 | av_CallHold, | ||
80 | av_CallHungUp | ||
81 | } ToxAvCallState; | ||
82 | 92 | ||
83 | /** | ||
84 | * Error indicators. Values under -20 are reserved for toxcore. | ||
85 | */ | ||
86 | typedef enum { | ||
87 | av_ErrorNone = 0, | ||
88 | av_ErrorUnknown = -1, /* Unknown error */ | ||
89 | av_ErrorNoCall = -20, /* Trying to perform call action while not in a call */ | ||
90 | av_ErrorInvalidState = -21, /* Trying to perform call action while in invalid state*/ | ||
91 | av_ErrorAlreadyInCallWithPeer = -22, /* Trying to call peer when already in a call with peer */ | ||
92 | av_ErrorReachedCallLimit = -23, /* Cannot handle more calls */ | ||
93 | av_ErrorInitializingCodecs = -30, /* Failed creating CSSession */ | ||
94 | av_ErrorSettingVideoResolution = -31, /* Error setting resolution */ | ||
95 | av_ErrorSettingVideoBitrate = -32, /* Error setting bitrate */ | ||
96 | av_ErrorSplittingVideoPayload = -33, /* Error splitting video payload */ | ||
97 | av_ErrorEncodingVideo = -34, /* vpx_codec_encode failed */ | ||
98 | av_ErrorEncodingAudio = -35, /* opus_encode failed */ | ||
99 | av_ErrorSendingPayload = -40, /* Sending lossy packet failed */ | ||
100 | av_ErrorCreatingRtpSessions = -41, /* One of the rtp sessions failed to initialize */ | ||
101 | av_ErrorNoRtpSession = -50, /* Trying to perform rtp action on invalid session */ | ||
102 | av_ErrorInvalidCodecState = -51, /* Codec state not initialized */ | ||
103 | av_ErrorPacketTooLarge = -52, /* Split packet exceeds it's limit */ | ||
104 | } ToxAvError; | ||
105 | 93 | ||
106 | 94 | ||
107 | /** | 95 | /** |
108 | * Locally supported capabilities. | 96 | * The major version number. Incremented when the API or ABI changes in an |
97 | * incompatible way. | ||
109 | */ | 98 | */ |
110 | typedef enum { | 99 | #define TOXAV_VERSION_MAJOR 0u |
111 | av_AudioEncoding = 1 << 0, | ||
112 | av_AudioDecoding = 1 << 1, | ||
113 | av_VideoEncoding = 1 << 2, | ||
114 | av_VideoDecoding = 1 << 3 | ||
115 | } ToxAvCapabilities; | ||
116 | |||
117 | 100 | ||
118 | /** | 101 | /** |
119 | * Encoding settings. | 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. | ||
120 | */ | 105 | */ |
121 | typedef struct _ToxAvCSettings { | 106 | #define TOXAV_VERSION_MINOR 0u |
122 | ToxAvCallType call_type; | ||
123 | |||
124 | uint32_t video_bitrate; /* In kbits/s */ | ||
125 | uint16_t max_video_width; /* In px */ | ||
126 | uint16_t max_video_height; /* In px */ | ||
127 | |||
128 | uint32_t audio_bitrate; /* In bits/s */ | ||
129 | uint16_t audio_frame_duration; /* In ms */ | ||
130 | uint32_t audio_sample_rate; /* In Hz */ | ||
131 | uint32_t audio_channels; | ||
132 | } ToxAvCSettings; | ||
133 | |||
134 | extern const ToxAvCSettings av_DefaultSettings; | ||
135 | 107 | ||
136 | /** | 108 | /** |
137 | * Start new A/V session. There can only be one session at the time. | 109 | * The patch or revision number. Incremented when bugfixes are applied without |
110 | * changing any functionality or API or ABI. | ||
138 | */ | 111 | */ |
139 | ToxAv *toxav_new(Tox *messenger, int32_t max_calls); | 112 | #define TOXAV_VERSION_PATCH 0u |
140 | 113 | ||
141 | /** | 114 | /** |
142 | * Remove A/V session. | 115 | * A macro to check at preprocessing time whether the client code is compatible |
116 | * with the installed version of ToxAV. | ||
143 | */ | 117 | */ |
144 | void toxav_kill(ToxAv *av); | 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))) | ||
145 | 123 | ||
146 | /** | 124 | /** |
147 | * Returns the interval in milliseconds when the next toxav_do() should be called. | 125 | * A macro to make compilation fail if the client code is not compatible with |
148 | * If no call is active at the moment returns 200. | 126 | * the installed version of ToxAV. |
149 | */ | 127 | */ |
150 | uint32_t toxav_do_interval(ToxAv *av); | 128 | #define TOXAV_VERSION_REQUIRE(MAJOR, MINOR, PATCH) \ |
129 | typedef char toxav_required_version[TOXAV_IS_COMPATIBLE(MAJOR, MINOR, PATCH) ? 1 : -1] | ||
151 | 130 | ||
152 | /** | 131 | /** |
153 | * Main loop for the session. Best called right after tox_do(); | 132 | * A convenience macro to call toxav_version_is_compatible with the currently |
133 | * compiling API version. | ||
154 | */ | 134 | */ |
155 | void toxav_do(ToxAv *av); | 135 | #define TOXAV_VERSION_IS_ABI_COMPATIBLE() \ |
136 | toxav_version_is_compatible(TOXAV_VERSION_MAJOR, TOXAV_VERSION_MINOR, TOXAV_VERSION_PATCH) | ||
156 | 137 | ||
157 | /** | 138 | /** |
158 | * Register callback for call state. | 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. | ||
159 | */ | 142 | */ |
160 | void toxav_register_callstate_callback (ToxAv *av, ToxAVCallback cb, ToxAvCallbackID id, void *userdata); | 143 | uint32_t toxav_version_major(void); |
161 | 144 | ||
162 | /** | 145 | /** |
163 | * Register callback for audio data. | 146 | * Return the minor version number of the library. |
164 | */ | 147 | */ |
165 | void toxav_register_audio_callback (ToxAv *av, ToxAvAudioCallback cb, void *userdata); | 148 | uint32_t toxav_version_minor(void); |
166 | 149 | ||
167 | /** | 150 | /** |
168 | * Register callback for video data. | 151 | * Return the patch number of the library. |
169 | */ | 152 | */ |
170 | void toxav_register_video_callback (ToxAv *av, ToxAvVideoCallback cb, void *userdata); | 153 | uint32_t toxav_version_patch(void); |
171 | 154 | ||
172 | /** | 155 | /** |
173 | * Call user. Use its friend_id. | 156 | * Return whether the compiled library version is compatible with the passed |
157 | * version numbers. | ||
174 | */ | 158 | */ |
175 | int toxav_call(ToxAv *av, | 159 | bool toxav_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch); |
176 | int32_t *call_index, | 160 | |
177 | int friend_id, | 161 | |
178 | const ToxAvCSettings *csettings, | 162 | /******************************************************************************* |
179 | int ringing_seconds); | 163 | * |
164 | * :: Creation and destruction | ||
165 | * | ||
166 | ******************************************************************************/ | ||
167 | |||
168 | |||
169 | |||
170 | typedef enum TOXAV_ERR_NEW { | ||
171 | |||
172 | /** | ||
173 | * The function returned successfully. | ||
174 | */ | ||
175 | TOXAV_ERR_NEW_OK, | ||
176 | |||
177 | /** | ||
178 | * One of the arguments to the function was NULL when it was not expected. | ||
179 | */ | ||
180 | TOXAV_ERR_NEW_NULL, | ||
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 | |||
193 | } TOXAV_ERR_NEW; | ||
194 | |||
180 | 195 | ||
181 | /** | 196 | /** |
182 | * Hangup active call. | 197 | * Start new A/V session. There can only be only one session per Tox instance. |
183 | */ | 198 | */ |
184 | int toxav_hangup(ToxAv *av, int32_t call_index); | 199 | ToxAV *toxav_new(Tox *tox, TOXAV_ERR_NEW *error); |
185 | 200 | ||
186 | /** | 201 | /** |
187 | * Answer incoming call. Pass the csettings that you will use. | 202 | * Releases all resources associated with the A/V session. |
203 | * | ||
204 | * If any calls were ongoing, these will be forcibly terminated without | ||
205 | * notifying peers. After calling this function, no other functions may be | ||
206 | * called and the av pointer becomes invalid. | ||
188 | */ | 207 | */ |
189 | int toxav_answer(ToxAv *av, int32_t call_index, const ToxAvCSettings *csettings ); | 208 | void toxav_kill(ToxAV *toxAV); |
190 | 209 | ||
191 | /** | 210 | /** |
192 | * Reject incoming call. | 211 | * Returns the Tox instance the A/V object was created for. |
193 | */ | 212 | */ |
194 | int toxav_reject(ToxAv *av, int32_t call_index, const char *reason); | 213 | Tox *toxav_get_tox(const ToxAV *toxAV); |
214 | |||
215 | |||
216 | /******************************************************************************* | ||
217 | * | ||
218 | * :: A/V event loop | ||
219 | * | ||
220 | ******************************************************************************/ | ||
221 | |||
222 | |||
195 | 223 | ||
196 | /** | 224 | /** |
197 | * Cancel outgoing request. | 225 | * Returns the interval in milliseconds when the next toxav_iterate call should |
226 | * be. If no call is active at the moment, this function returns 200. | ||
198 | */ | 227 | */ |
199 | int toxav_cancel(ToxAv *av, int32_t call_index, int peer_id, const char *reason); | 228 | uint32_t toxav_iteration_interval(const ToxAV *toxAV); |
200 | 229 | ||
201 | /** | 230 | /** |
202 | * Notify peer that we are changing codec settings. | 231 | * Main loop for the session. This function needs to be called in intervals of |
232 | * toxav_iteration_interval() milliseconds. It is best called in the separate | ||
233 | * thread from tox_iterate. | ||
203 | */ | 234 | */ |
204 | int toxav_change_settings(ToxAv *av, int32_t call_index, const ToxAvCSettings *csettings); | 235 | void toxav_iterate(ToxAV *toxAV); |
236 | |||
237 | |||
238 | /******************************************************************************* | ||
239 | * | ||
240 | * :: Call setup | ||
241 | * | ||
242 | ******************************************************************************/ | ||
243 | |||
244 | |||
245 | |||
246 | typedef enum TOXAV_ERR_CALL { | ||
247 | |||
248 | /** | ||
249 | * The function returned successfully. | ||
250 | */ | ||
251 | TOXAV_ERR_CALL_OK, | ||
252 | |||
253 | /** | ||
254 | * A resource allocation error occurred while trying to create the structures | ||
255 | * required for the call. | ||
256 | */ | ||
257 | TOXAV_ERR_CALL_MALLOC, | ||
258 | |||
259 | /** | ||
260 | * The friend number did not designate a valid friend. | ||
261 | */ | ||
262 | TOXAV_ERR_CALL_FRIEND_NOT_FOUND, | ||
263 | |||
264 | /** | ||
265 | * The friend was valid, but not currently connected. | ||
266 | */ | ||
267 | TOXAV_ERR_CALL_FRIEND_NOT_CONNECTED, | ||
268 | |||
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 | |||
280 | } TOXAV_ERR_CALL; | ||
281 | |||
205 | 282 | ||
206 | /** | 283 | /** |
207 | * Terminate transmission. Note that transmission will be | 284 | * Call a friend. This will start ringing the friend. |
208 | * terminated without informing remote peer. Usually called when we can't inform peer. | 285 | * |
286 | * It is the client's responsibility to stop ringing after a certain timeout, | ||
287 | * if such behaviour is desired. If the client does not stop ringing, the | ||
288 | * library will not stop until the friend is disconnected. | ||
289 | * | ||
290 | * @param friend_number The friend number of the friend that should be called. | ||
291 | * @param audio_bit_rate Audio bit rate in Kb/sec. Set this to 0 to disable | ||
292 | * audio sending. | ||
293 | * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable | ||
294 | * video sending. | ||
209 | */ | 295 | */ |
210 | int toxav_stop_call(ToxAv *av, int32_t call_index); | 296 | bool toxav_call(ToxAV *toxAV, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, TOXAV_ERR_CALL *error); |
211 | 297 | ||
212 | /** | 298 | /** |
213 | * Allocates transmission data. Must be call before calling toxav_prepare_* and toxav_send_*. | 299 | * The function type for the call callback. |
214 | * Also, it must be called when call is started | 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. | ||
215 | */ | 304 | */ |
216 | int toxav_prepare_transmission(ToxAv *av, int32_t call_index, int support_video); | 305 | typedef void toxav_call_cb(ToxAV *toxAV, uint32_t friend_number, bool audio_enabled, bool video_enabled, void *user_data); |
306 | |||
217 | 307 | ||
218 | /** | 308 | /** |
219 | * Clears transmission data. Call this at the end of the transmission. | 309 | * Set the callback for the `call` event. Pass NULL to unset. |
310 | * | ||
220 | */ | 311 | */ |
221 | int toxav_kill_transmission(ToxAv *av, int32_t call_index); | 312 | void toxav_callback_call(ToxAV *toxAV, toxav_call_cb *callback, void *user_data); |
313 | |||
314 | typedef enum TOXAV_ERR_ANSWER { | ||
315 | |||
316 | /** | ||
317 | * The function returned successfully. | ||
318 | */ | ||
319 | TOXAV_ERR_ANSWER_OK, | ||
320 | |||
321 | /** | ||
322 | * Failed to initialize codecs for call session. Note that codec initiation | ||
323 | * will fail if there is no receive callback registered for either audio or | ||
324 | * video. | ||
325 | */ | ||
326 | TOXAV_ERR_ANSWER_CODEC_INITIALIZATION, | ||
327 | |||
328 | /** | ||
329 | * The friend number did not designate a valid friend. | ||
330 | */ | ||
331 | TOXAV_ERR_ANSWER_FRIEND_NOT_FOUND, | ||
332 | |||
333 | /** | ||
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 | |||
344 | } TOXAV_ERR_ANSWER; | ||
345 | |||
222 | 346 | ||
223 | /** | 347 | /** |
224 | * Encode video frame. | 348 | * Accept an incoming call. |
349 | * | ||
350 | * If answering fails for any reason, the call will still be pending and it is | ||
351 | * possible to try and answer it later. | ||
352 | * | ||
353 | * @param friend_number The friend number of the friend that is calling. | ||
354 | * @param audio_bit_rate Audio bit rate in Kb/sec. Set this to 0 to disable | ||
355 | * audio sending. | ||
356 | * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable | ||
357 | * video sending. | ||
225 | */ | 358 | */ |
226 | int toxav_prepare_video_frame ( ToxAv *av, | 359 | bool toxav_answer(ToxAV *toxAV, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, TOXAV_ERR_ANSWER *error); |
227 | int32_t call_index, | 360 | |
228 | uint8_t *dest, | 361 | |
229 | int dest_max, | 362 | /******************************************************************************* |
230 | vpx_image_t *input); | 363 | * |
364 | * :: Call state graph | ||
365 | * | ||
366 | ******************************************************************************/ | ||
367 | |||
368 | |||
369 | |||
370 | enum TOXAV_CALL_STATE { | ||
371 | |||
372 | /** | ||
373 | * Set by the AV core if an error occurred on the remote end or if friend | ||
374 | * timed out. This is the final state after which no more state | ||
375 | * transitions can occur for the call. This call state will never be triggered | ||
376 | * in combination with other call states. | ||
377 | */ | ||
378 | TOXAV_CALL_STATE_ERROR = 1, | ||
379 | |||
380 | /** | ||
381 | * The call has finished. This is the final state after which no more state | ||
382 | * transitions can occur for the call. This call state will never be | ||
383 | * triggered in combination with other call states. | ||
384 | */ | ||
385 | TOXAV_CALL_STATE_FINISHED = 2, | ||
386 | |||
387 | /** | ||
388 | * The flag that marks that friend is sending audio. | ||
389 | */ | ||
390 | TOXAV_CALL_STATE_SENDING_A = 4, | ||
391 | |||
392 | /** | ||
393 | * The flag that marks that friend is sending video. | ||
394 | */ | ||
395 | TOXAV_CALL_STATE_SENDING_V = 8, | ||
396 | |||
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 | |||
407 | }; | ||
408 | |||
231 | 409 | ||
232 | /** | 410 | /** |
233 | * Send encoded video packet. | 411 | * The function type for the call_state callback. |
412 | * | ||
413 | * @param friend_number The friend number for which the call state changed. | ||
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. | ||
234 | */ | 416 | */ |
235 | int toxav_send_video ( ToxAv *av, int32_t call_index, const uint8_t *frame, uint32_t frame_size); | 417 | typedef void toxav_call_state_cb(ToxAV *toxAV, uint32_t friend_number, uint32_t state, void *user_data); |
418 | |||
236 | 419 | ||
237 | /** | 420 | /** |
238 | * Encode audio frame. | 421 | * Set the callback for the `call_state` event. Pass NULL to unset. |
422 | * | ||
239 | */ | 423 | */ |
240 | int toxav_prepare_audio_frame ( ToxAv *av, | 424 | void toxav_callback_call_state(ToxAV *toxAV, toxav_call_state_cb *callback, void *user_data); |
241 | int32_t call_index, | 425 | |
242 | uint8_t *dest, | 426 | |
243 | int dest_max, | 427 | /******************************************************************************* |
244 | const int16_t *frame, | 428 | * |
245 | int frame_size); | 429 | * :: Call control |
430 | * | ||
431 | ******************************************************************************/ | ||
432 | |||
433 | |||
434 | |||
435 | typedef enum TOXAV_CALL_CONTROL { | ||
436 | |||
437 | /** | ||
438 | * Resume a previously paused call. Only valid if the pause was caused by this | ||
439 | * client, if not, this control is ignored. Not valid before the call is accepted. | ||
440 | */ | ||
441 | TOXAV_CALL_CONTROL_RESUME, | ||
442 | |||
443 | /** | ||
444 | * Put a call on hold. Not valid before the call is accepted. | ||
445 | */ | ||
446 | TOXAV_CALL_CONTROL_PAUSE, | ||
447 | |||
448 | /** | ||
449 | * Reject a call if it was not answered, yet. Cancel a call after it was | ||
450 | * answered. | ||
451 | */ | ||
452 | TOXAV_CALL_CONTROL_CANCEL, | ||
453 | |||
454 | /** | ||
455 | * Request that the friend stops sending audio. Regardless of the friend's | ||
456 | * compliance, this will cause the audio_receive_frame event to stop being | ||
457 | * triggered on receiving an audio frame from the friend. | ||
458 | */ | ||
459 | TOXAV_CALL_CONTROL_MUTE_AUDIO, | ||
460 | |||
461 | /** | ||
462 | * Calling this control will notify client to start sending audio again. | ||
463 | */ | ||
464 | TOXAV_CALL_CONTROL_UNMUTE_AUDIO, | ||
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 | |||
478 | } TOXAV_CALL_CONTROL; | ||
479 | |||
480 | |||
481 | typedef enum TOXAV_ERR_CALL_CONTROL { | ||
482 | |||
483 | /** | ||
484 | * The function returned successfully. | ||
485 | */ | ||
486 | TOXAV_ERR_CALL_CONTROL_OK, | ||
487 | |||
488 | /** | ||
489 | * The friend_number passed did not designate a valid friend. | ||
490 | */ | ||
491 | TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_FOUND, | ||
492 | |||
493 | /** | ||
494 | * This client is currently not in a call with the friend. Before the call is | ||
495 | * answered, only CANCEL is a valid control. | ||
496 | */ | ||
497 | TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_IN_CALL, | ||
498 | |||
499 | /** | ||
500 | * Happens if user tried to pause an already paused call or if trying to | ||
501 | * resume a call that is not paused. | ||
502 | */ | ||
503 | TOXAV_ERR_CALL_CONTROL_INVALID_TRANSITION, | ||
504 | |||
505 | } TOXAV_ERR_CALL_CONTROL; | ||
506 | |||
246 | 507 | ||
247 | /** | 508 | /** |
248 | * Send encoded audio frame. | 509 | * Sends a call control command to a friend. |
510 | * | ||
511 | * @param friend_number The friend number of the friend this client is in a call | ||
512 | * with. | ||
513 | * @param control The control command to send. | ||
514 | * | ||
515 | * @return true on success. | ||
249 | */ | 516 | */ |
250 | int toxav_send_audio ( ToxAv *av, int32_t call_index, const uint8_t *frame, unsigned int size); | 517 | bool toxav_call_control(ToxAV *toxAV, uint32_t friend_number, TOXAV_CALL_CONTROL control, TOXAV_ERR_CALL_CONTROL *error); |
518 | |||
519 | |||
520 | /******************************************************************************* | ||
521 | * | ||
522 | * :: Controlling bit rates | ||
523 | * | ||
524 | ******************************************************************************/ | ||
525 | |||
526 | |||
527 | |||
528 | typedef enum TOXAV_ERR_SET_BIT_RATE { | ||
529 | |||
530 | /** | ||
531 | * The function returned successfully. | ||
532 | */ | ||
533 | TOXAV_ERR_SET_BIT_RATE_OK, | ||
534 | |||
535 | /** | ||
536 | * The bit rate passed was not one of the supported values. | ||
537 | */ | ||
538 | TOXAV_ERR_SET_BIT_RATE_INVALID, | ||
539 | |||
540 | /** | ||
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 | |||
251 | 552 | ||
252 | /** | 553 | /** |
253 | * Get codec settings from the peer. These were exchanged during call initialization | 554 | * The function type for the audio_bit_rate_status callback. |
254 | * or when peer send us new csettings. | 555 | * |
556 | * @param friend_number The friend number of the friend for which to set the | ||
557 | * audio bit rate. | ||
558 | * @param stable Is the stream stable enough to keep the bit rate. | ||
559 | * Upon successful, non forceful, bit rate change, this is set to | ||
560 | * true and 'bit_rate' is set to new bit rate. | ||
561 | * The stable is set to false with bit_rate set to the unstable | ||
562 | * bit rate when either current stream is unstable with said bit rate | ||
563 | * or the non forceful change failed. | ||
564 | * @param bit_rate The bit rate in Kb/sec. | ||
255 | */ | 565 | */ |
256 | int toxav_get_peer_csettings ( ToxAv *av, int32_t call_index, int peer, ToxAvCSettings *dest ); | 566 | typedef void toxav_audio_bit_rate_status_cb(ToxAV *toxAV, uint32_t friend_number, bool stable, uint32_t bit_rate, void *user_data); |
567 | |||
257 | 568 | ||
258 | /** | 569 | /** |
259 | * Get friend id of peer participating in conversation. | 570 | * Set the callback for the `audio_bit_rate_status` event. Pass NULL to unset. |
571 | * | ||
260 | */ | 572 | */ |
261 | int toxav_get_peer_id ( ToxAv *av, int32_t call_index, int peer ); | 573 | void toxav_callback_audio_bit_rate_status(ToxAV *toxAV, toxav_audio_bit_rate_status_cb *callback, void *user_data); |
262 | 574 | ||
263 | /** | 575 | /** |
264 | * Get current call state. | 576 | * Set the audio bit rate to be used in subsequent audio frames. If the passed |
577 | * bit rate is the same as the current bit rate this function will return true | ||
578 | * without calling a callback. If there is an active non forceful setup with the | ||
579 | * passed audio bit rate and the new set request is forceful, the bit rate is | ||
580 | * forcefully set and the previous non forceful request is cancelled. The active | ||
581 | * non forceful setup will be canceled in favour of new non forceful setup. | ||
582 | * | ||
583 | * @param friend_number The friend number of the friend for which to set the | ||
584 | * audio bit rate. | ||
585 | * @param audio_bit_rate The new audio bit rate in Kb/sec. Set to 0 to disable | ||
586 | * audio sending. | ||
587 | * @param force True if the bit rate change is forceful. | ||
588 | * | ||
265 | */ | 589 | */ |
266 | ToxAvCallState toxav_get_call_state ( ToxAv *av, int32_t call_index ); | 590 | bool toxav_audio_bit_rate_set(ToxAV *toxAV, uint32_t friend_number, uint32_t audio_bit_rate, bool force, TOXAV_ERR_SET_BIT_RATE *error); |
267 | 591 | ||
268 | /** | 592 | /** |
269 | * Is certain capability supported. Used to determine if encoding/decoding is ready. | 593 | * The function type for the video_bit_rate_status callback. |
594 | * | ||
595 | * @param friend_number The friend number of the friend for which to set the | ||
596 | * video bit rate. | ||
597 | * @param stable Is the stream stable enough to keep the bit rate. | ||
598 | * Upon successful, non forceful, bit rate change, this is set to | ||
599 | * true and 'bit_rate' is set to new bit rate. | ||
600 | * The stable is set to false with bit_rate set to the unstable | ||
601 | * bit rate when either current stream is unstable with said bit rate | ||
602 | * or the non forceful change failed. | ||
603 | * @param bit_rate The bit rate in Kb/sec. | ||
270 | */ | 604 | */ |
271 | int toxav_capability_supported ( ToxAv *av, int32_t call_index, ToxAvCapabilities capability ); | 605 | typedef void toxav_video_bit_rate_status_cb(ToxAV *toxAV, uint32_t friend_number, bool stable, uint32_t bit_rate, void *user_data); |
606 | |||
272 | 607 | ||
273 | /** | 608 | /** |
274 | * Returns tox reference. | 609 | * Set the callback for the `video_bit_rate_status` event. Pass NULL to unset. |
610 | * | ||
275 | */ | 611 | */ |
276 | Tox *toxav_get_tox (ToxAv *av); | 612 | void toxav_callback_video_bit_rate_status(ToxAV *toxAV, toxav_video_bit_rate_status_cb *callback, void *user_data); |
277 | 613 | ||
278 | /** | 614 | /** |
279 | * Returns number of active calls or -1 on error. | 615 | * Set the video bit rate to be used in subsequent video frames. If the passed |
616 | * bit rate is the same as the current bit rate this function will return true | ||
617 | * without calling a callback. If there is an active non forceful setup with the | ||
618 | * passed video bit rate and the new set request is forceful, the bit rate is | ||
619 | * forcefully set and the previous non forceful request is cancelled. The active | ||
620 | * non forceful setup will be canceled in favour of new non forceful setup. | ||
621 | * | ||
622 | * @param friend_number The friend number of the friend for which to set the | ||
623 | * video bit rate. | ||
624 | * @param audio_bit_rate The new video bit rate in Kb/sec. Set to 0 to disable | ||
625 | * video sending. | ||
626 | * @param force True if the bit rate change is forceful. | ||
627 | * | ||
280 | */ | 628 | */ |
281 | int toxav_get_active_count (ToxAv *av); | 629 | bool 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 | |||
282 | 631 | ||
283 | /* Create a new toxav group. | 632 | /******************************************************************************* |
633 | * | ||
634 | * :: A/V sending | ||
284 | * | 635 | * |
285 | * return group number on success. | 636 | ******************************************************************************/ |
286 | * return -1 on failure. | 637 | |
638 | |||
639 | |||
640 | typedef enum TOXAV_ERR_SEND_FRAME { | ||
641 | |||
642 | /** | ||
643 | * The function returned successfully. | ||
644 | */ | ||
645 | TOXAV_ERR_SEND_FRAME_OK, | ||
646 | |||
647 | /** | ||
648 | * In case of video, one of Y, U, or V was NULL. In case of audio, the samples | ||
649 | * data pointer was NULL. | ||
650 | */ | ||
651 | TOXAV_ERR_SEND_FRAME_NULL, | ||
652 | |||
653 | /** | ||
654 | * The friend_number passed did not designate a valid friend. | ||
655 | */ | ||
656 | TOXAV_ERR_SEND_FRAME_FRIEND_NOT_FOUND, | ||
657 | |||
658 | /** | ||
659 | * This client is currently not in a call with the friend. | ||
660 | */ | ||
661 | TOXAV_ERR_SEND_FRAME_FRIEND_NOT_IN_CALL, | ||
662 | |||
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 | |||
674 | } TOXAV_ERR_SEND_FRAME; | ||
675 | |||
676 | |||
677 | /** | ||
678 | * Send an audio frame to a friend. | ||
679 | * | ||
680 | * The expected format of the PCM data is: [s1c1][s1c2][...][s2c1][s2c2][...]... | ||
681 | * Meaning: sample 1 for channel 1, sample 1 for channel 2, ... | ||
682 | * For mono audio, this has no meaning, every sample is subsequent. For stereo, | ||
683 | * this means the expected format is LRLRLR... with samples for left and right | ||
684 | * alternating. | ||
685 | * | ||
686 | * @param friend_number The friend number of the friend to which to send an | ||
687 | * audio frame. | ||
688 | * @param pcm An array of audio samples. The size of this array must be | ||
689 | * sample_count * channels. | ||
690 | * @param sample_count Number of samples in this frame. Valid numbers here are | ||
691 | * ((sample rate) * (audio length) / 1000), where audio length can be | ||
692 | * 2.5, 5, 10, 20, 40 or 60 millseconds. | ||
693 | * @param channels Number of audio channels. Supported values are 1 and 2. | ||
694 | * @param sampling_rate Audio sampling rate used in this frame. Valid sampling | ||
695 | * rates are 8000, 12000, 16000, 24000, or 48000. | ||
696 | */ | ||
697 | bool 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); | ||
698 | |||
699 | /** | ||
700 | * Send a video frame to a friend. | ||
287 | * | 701 | * |
288 | * Audio data callback format: | 702 | * Y - plane should be of size: height * width |
289 | * audio_callback(Tox *tox, int groupnumber, int peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, unsigned int sample_rate, void *userdata) | 703 | * U - plane should be of size: (height/2) * (width/2) |
704 | * V - plane should be of size: (height/2) * (width/2) | ||
290 | * | 705 | * |
291 | * Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)). | 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. | ||
292 | */ | 714 | */ |
293 | int toxav_add_av_groupchat(Tox *tox, void (*audio_callback)(Tox *, int, int, const int16_t *, unsigned int, uint8_t, | 715 | bool 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); |
294 | unsigned int, void *), void *userdata); | 716 | |
295 | 717 | ||
296 | /* Join a AV group (you need to have been invited first.) | 718 | /******************************************************************************* |
719 | * | ||
720 | * :: A/V receiving | ||
297 | * | 721 | * |
298 | * returns group number on success | 722 | ******************************************************************************/ |
299 | * returns -1 on failure. | 723 | |
724 | |||
725 | |||
726 | /** | ||
727 | * The function type for the audio_receive_frame callback. | ||
300 | * | 728 | * |
301 | * Audio data callback format (same as the one for toxav_add_av_groupchat()): | 729 | * @param friend_number The friend number of the friend who sent an audio frame. |
302 | * audio_callback(Tox *tox, int groupnumber, int peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, unsigned int sample_rate, void *userdata) | 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. | ||
303 | * | 734 | * |
304 | * Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)). | ||
305 | */ | 735 | */ |
306 | int toxav_join_av_groupchat(Tox *tox, int32_t friendnumber, const uint8_t *data, uint16_t length, | 736 | typedef 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); |
307 | void (*audio_callback)(Tox *, int, int, const int16_t *, unsigned int, uint8_t, unsigned int, void *), void *userdata); | ||
308 | 737 | ||
309 | /* Send audio to the group chat. | 738 | |
310 | * | 739 | /** |
311 | * return 0 on success. | 740 | * Set the callback for the `audio_receive_frame` event. Pass NULL to unset. |
312 | * return -1 on failure. | ||
313 | * | 741 | * |
314 | * Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)). | 742 | */ |
743 | void 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. | ||
315 | * | 747 | * |
316 | * Valid number of samples are ((sample rate) * (audio length (Valid ones are: 2.5, 5, 10, 20, 40 or 60 ms)) / 1000) | 748 | * @param friend_number The friend number of the friend who sent a video frame. |
317 | * Valid number of channels are 1 or 2. | 749 | * @param width Width of the frame in pixels. |
318 | * Valid sample rates are 8000, 12000, 16000, 24000, or 48000. | 750 | * @param height Height of the frame in pixels. |
751 | * @param y | ||
752 | * @param u | ||
753 | * @param v Plane data. | ||
754 | * The size of plane data is derived from width and height where | ||
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. | ||
759 | * @param ystride | ||
760 | * @param ustride | ||
761 | * @param vstride | ||
762 | * @param astride Strides data. Strides represent padding for each plane | ||
763 | * that may or may not be present. You must handle strides in | ||
764 | * your image processing code. Strides are negative if the | ||
765 | * image is bottom-up hence why you MUST abs() it when | ||
766 | * calculating plane buffer size. | ||
767 | */ | ||
768 | typedef 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 | |||
771 | /** | ||
772 | * Set the callback for the `video_receive_frame` event. Pass NULL to unset. | ||
319 | * | 773 | * |
320 | * Recommended values are: samples = 960, channels = 1, sample_rate = 48000 | ||
321 | */ | 774 | */ |
322 | int toxav_group_send_audio(Tox *tox, int groupnumber, const int16_t *pcm, unsigned int samples, uint8_t channels, | 775 | void toxav_callback_video_receive_frame(ToxAV *toxAV, toxav_video_receive_frame_cb *callback, void *user_data); |
323 | unsigned int sample_rate); | ||
324 | 776 | ||
325 | #ifdef __cplusplus | ||
326 | } | ||
327 | #endif | 777 | #endif |
328 | |||
329 | #endif /* __TOXAV */ | ||