diff options
author | mannol <eniz_vukovic@hotmail.com> | 2015-05-22 23:22:31 +0200 |
---|---|---|
committer | mannol <eniz_vukovic@hotmail.com> | 2015-05-22 23:22:31 +0200 |
commit | 3100042a2b78f4f80d23f67e6113797cd8fb5df0 (patch) | |
tree | c226f4b25002784d93f9bb6415be4b55b76cddd1 /toxav/toxav.h | |
parent | 62c40af1a0c557ba8c77583c972ae3af9af15cf1 (diff) | |
parent | 2ba076ac5cc6efb5eb41fb4aa6a77a151885f26c (diff) |
Updated with master
Diffstat (limited to 'toxav/toxav.h')
-rw-r--r-- | toxav/toxav.h | 820 |
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 |
30 | extern "C" { | 30 | extern "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 | */ |
40 | typedef struct ToxAV ToxAV; | ||
41 | #ifndef TOX_DEFINED | 65 | #ifndef TOX_DEFINED |
42 | #define TOX_DEFINED | 66 | #define TOX_DEFINED |
67 | typedef 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 | */ |
47 | typedef 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 | ||
83 | typedef 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 | */ | ||
143 | uint32_t toxav_version_major(void); | ||
144 | |||
145 | /** | ||
146 | * Return the minor version number of the library. | ||
147 | */ | ||
148 | uint32_t toxav_version_minor(void); | ||
149 | |||
150 | /** | ||
151 | * Return the patch number of the library. | ||
152 | */ | ||
153 | uint32_t toxav_version_patch(void); | ||
154 | |||
155 | /** | ||
156 | * Return whether the compiled library version is compatible with the passed | ||
157 | * version numbers. | ||
158 | */ | ||
159 | bool 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 | |||
54 | typedef enum TOXAV_ERR_NEW { | 170 | typedef 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 | */ |
70 | ToxAV *toxav_new(Tox *tox, TOXAV_ERR_NEW *error); | 199 | ToxAV *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 | */ |
78 | void toxav_kill(ToxAV *av); | 208 | void 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 | */ |
82 | Tox *toxav_get_tox(ToxAV *av); | 213 | Tox *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 | */ |
92 | uint32_t toxav_iteration_interval(ToxAV const *av); | 228 | uint32_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 | */ |
98 | void toxav_iterate(ToxAV *av); | 235 | void toxav_iterate(ToxAV *toxAV); |
236 | |||
237 | |||
99 | /******************************************************************************* | 238 | /******************************************************************************* |
100 | * | 239 | * |
101 | * :: Call setup | 240 | * :: Call setup |
102 | * | 241 | * |
103 | ******************************************************************************/ | 242 | ******************************************************************************/ |
243 | |||
244 | |||
245 | |||
104 | typedef enum TOXAV_ERR_CALL { | 246 | typedef 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 | */ |
142 | bool toxav_call(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, TOXAV_ERR_CALL *error); | 296 | bool 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 | */ |
146 | typedef void toxav_call_cb(ToxAV *av, uint32_t friend_number, bool audio_enabled, bool video_enabled, void *user_data); | 305 | typedef 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 | */ |
152 | void toxav_callback_call(ToxAV *av, toxav_call_cb *function, void *user_data); | 312 | void toxav_callback_call(ToxAV *toxAV, toxav_call_cb *callback, void *user_data); |
313 | |||
153 | typedef enum TOXAV_ERR_ANSWER { | 314 | typedef 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 | */ |
187 | bool toxav_answer(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, TOXAV_ERR_ANSWER *error); | 359 | bool 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 | |||
193 | enum TOXAV_CALL_STATE { | 370 | enum 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 | */ |
228 | typedef void toxav_call_state_cb(ToxAV *av, uint32_t friend_number, uint32_t state, void *user_data); | 417 | typedef 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 | */ |
234 | void toxav_callback_call_state(ToxAV *av, toxav_call_state_cb *function, void *user_data); | 424 | void 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 | |||
240 | typedef enum TOXAV_CALL_CONTROL { | 435 | typedef 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 | |||
272 | typedef enum TOXAV_ERR_CALL_CONTROL { | 481 | typedef 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 | */ |
303 | bool toxav_call_control(ToxAV *av, uint32_t friend_number, TOXAV_CALL_CONTROL control, TOXAV_ERR_CALL_CONTROL *error); | 517 | bool 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 | ******************************************************************************/ |
309 | typedef 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. | 528 | typedef 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 | */ |
337 | typedef void toxav_audio_bit_rate_status_cb(ToxAV *av, uint32_t friend_number, bool stable, uint32_t bit_rate, void *user_data); | 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 | |||
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 | */ |
341 | void toxav_callback_audio_bit_rate_status(ToxAV *av, toxav_audio_bit_rate_status_cb *function, void *user_data); | 573 | void 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 | */ |
357 | bool toxav_set_audio_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, bool force, TOXAV_ERR_BIT_RATE *error); | 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); |
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 | */ |
371 | typedef void toxav_video_bit_rate_status_cb(ToxAV *av, uint32_t friend_number, bool stable, uint32_t bit_rate, void *user_data); | 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 | |||
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 | */ |
375 | void toxav_callback_video_bit_rate_status(ToxAV *av, toxav_video_bit_rate_status_cb *function, void *user_data); | 612 | void 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 | */ |
391 | bool toxav_set_video_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t video_bit_rate, bool force, TOXAV_ERR_BIT_RATE *error); | 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 | |||
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 | |
400 | typedef enum TOXAV_ERR_SEND_FRAME { | 640 | typedef 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 | */ | ||
440 | bool 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 | */ |
464 | bool toxav_send_audio_frame(ToxAV *av, uint32_t friend_number, | 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); |
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 | */ | ||
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); | ||
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 | */ | ||
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); | ||
737 | |||
738 | |||
739 | /** | ||
740 | * Set the callback for the `audio_receive_frame` event. Pass NULL to unset. | ||
741 | * | ||
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. | ||
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 |
490 | typedef 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 | */ |
498 | void toxav_callback_receive_video_frame(ToxAV *av, toxav_receive_video_frame_cb *function, void *user_data); | 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 | |||
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 | */ | ||
510 | typedef 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 | */ |
519 | void toxav_callback_receive_audio_frame(ToxAV *av, toxav_receive_audio_frame_cb *function, void *user_data); | 775 | void 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 */ | ||