diff options
Diffstat (limited to 'toxcore/tox.h')
-rw-r--r-- | toxcore/tox.h | 742 |
1 files changed, 485 insertions, 257 deletions
diff --git a/toxcore/tox.h b/toxcore/tox.h index 8e368851..abd2f051 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h | |||
@@ -67,23 +67,21 @@ extern "C" { | |||
67 | * function will try to use a sane default, but there will be no error code, | 67 | * function will try to use a sane default, but there will be no error code, |
68 | * and one possible action for the function to take is to have no effect. | 68 | * and one possible action for the function to take is to have no effect. |
69 | */ | 69 | */ |
70 | |||
71 | /** \subsection events Events and callbacks | 70 | /** \subsection events Events and callbacks |
72 | * | 71 | * |
73 | * Events are handled by callbacks. One callback can be registered per event. | 72 | * Events are handled by callbacks. One callback can be registered per event. |
74 | * All events have a callback function type named `tox_${event}_cb` and a | 73 | * All events have a callback function type named `tox_{event}_cb` and a |
75 | * function to register it named `tox_callback_${event}`. Passing a NULL | 74 | * function to register it named `tox_callback_{event}`. Passing a NULL |
76 | * callback will result in no callback being registered for that event. Only | 75 | * callback will result in no callback being registered for that event. Only |
77 | * one callback per event can be registered, so if a client needs multiple | 76 | * one callback per event can be registered, so if a client needs multiple |
78 | * event listeners, it needs to implement the dispatch functionality itself. | 77 | * event listeners, it needs to implement the dispatch functionality itself. |
79 | */ | 78 | */ |
80 | |||
81 | /** \subsection threading Threading implications | 79 | /** \subsection threading Threading implications |
82 | * | 80 | * |
83 | * It is possible to run multiple concurrent threads with a Tox instance for | 81 | * It is possible to run multiple concurrent threads with a Tox instance for |
84 | * each thread. It is also possible to run all Tox instances in the same thread. | 82 | * each thread. It is also possible to run all Tox instances in the same thread. |
85 | * A common way to run Tox (multiple or single instance) is to have one thread | 83 | * A common way to run Tox (multiple or single instance) is to have one thread |
86 | * running a simple tox_iteration loop, sleeping for tox_iteration_interval | 84 | * running a simple tox_iterate loop, sleeping for tox_iteration_interval |
87 | * milliseconds on each iteration. | 85 | * milliseconds on each iteration. |
88 | * | 86 | * |
89 | * If you want to access a single Tox instance from multiple threads, access | 87 | * If you want to access a single Tox instance from multiple threads, access |
@@ -108,12 +106,9 @@ extern "C" { | |||
108 | * \endcode | 106 | * \endcode |
109 | * | 107 | * |
110 | * If any other thread calls tox_self_set_name while this thread is allocating | 108 | * If any other thread calls tox_self_set_name while this thread is allocating |
111 | * memory, the length will have become invalid, and the call to | 109 | * memory, the length may have become invalid, and the call to |
112 | * tox_self_get_name may cause undefined behaviour. | 110 | * tox_self_get_name may cause undefined behaviour. |
113 | */ | 111 | */ |
114 | |||
115 | #ifndef TOX_DEFINED | ||
116 | #define TOX_DEFINED | ||
117 | /** | 112 | /** |
118 | * The Tox instance type. All the state associated with a connection is held | 113 | * The Tox instance type. All the state associated with a connection is held |
119 | * within the instance. Multiple instances can exist and operate concurrently. | 114 | * within the instance. Multiple instances can exist and operate concurrently. |
@@ -121,8 +116,10 @@ extern "C" { | |||
121 | * device is limited. Note that this is not just a per-process limit, since the | 116 | * device is limited. Note that this is not just a per-process limit, since the |
122 | * limiting factor is the number of usable ports on a device. | 117 | * limiting factor is the number of usable ports on a device. |
123 | */ | 118 | */ |
119 | #ifndef TOX_DEFINED | ||
120 | #define TOX_DEFINED | ||
124 | typedef struct Tox Tox; | 121 | typedef struct Tox Tox; |
125 | #endif | 122 | #endif /* TOX_DEFINED */ |
126 | 123 | ||
127 | 124 | ||
128 | /******************************************************************************* | 125 | /******************************************************************************* |
@@ -132,17 +129,20 @@ typedef struct Tox Tox; | |||
132 | ******************************************************************************/ | 129 | ******************************************************************************/ |
133 | 130 | ||
134 | 131 | ||
132 | |||
135 | /** | 133 | /** |
136 | * The major version number. Incremented when the API or ABI changes in an | 134 | * The major version number. Incremented when the API or ABI changes in an |
137 | * incompatible way. | 135 | * incompatible way. |
138 | */ | 136 | */ |
139 | #define TOX_VERSION_MAJOR 0u | 137 | #define TOX_VERSION_MAJOR 0u |
138 | |||
140 | /** | 139 | /** |
141 | * The minor version number. Incremented when functionality is added without | 140 | * The minor version number. Incremented when functionality is added without |
142 | * breaking the API or ABI. Set to 0 when the major version number is | 141 | * breaking the API or ABI. Set to 0 when the major version number is |
143 | * incremented. | 142 | * incremented. |
144 | */ | 143 | */ |
145 | #define TOX_VERSION_MINOR 0u | 144 | #define TOX_VERSION_MINOR 0u |
145 | |||
146 | /** | 146 | /** |
147 | * The patch or revision number. Incremented when bugfixes are applied without | 147 | * The patch or revision number. Incremented when bugfixes are applied without |
148 | * changing any functionality or API or ABI. | 148 | * changing any functionality or API or ABI. |
@@ -166,7 +166,6 @@ typedef struct Tox Tox; | |||
166 | #define TOX_VERSION_REQUIRE(MAJOR, MINOR, PATCH) \ | 166 | #define TOX_VERSION_REQUIRE(MAJOR, MINOR, PATCH) \ |
167 | typedef char tox_required_version[TOX_IS_COMPATIBLE(MAJOR, MINOR, PATCH) ? 1 : -1] | 167 | typedef char tox_required_version[TOX_IS_COMPATIBLE(MAJOR, MINOR, PATCH) ? 1 : -1] |
168 | 168 | ||
169 | |||
170 | /** | 169 | /** |
171 | * Return the major version number of the library. Can be used to display the | 170 | * Return the major version number of the library. Can be used to display the |
172 | * Tox library version or to check whether the client is compatible with the | 171 | * Tox library version or to check whether the client is compatible with the |
@@ -205,15 +204,16 @@ bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch); | |||
205 | ******************************************************************************/ | 204 | ******************************************************************************/ |
206 | 205 | ||
207 | 206 | ||
207 | |||
208 | /** | 208 | /** |
209 | * The size of a Tox Public Key in bytes. | 209 | * The size of a Tox Public Key in bytes. |
210 | */ | 210 | */ |
211 | #define TOX_PUBLIC_KEY_SIZE 32 | 211 | #define TOX_PUBLIC_KEY_SIZE 32 |
212 | 212 | ||
213 | /** | 213 | /** |
214 | * The size of a Tox Secret Key in bytes. | 214 | * The size of a Tox Secret Key in bytes. |
215 | */ | 215 | */ |
216 | #define TOX_SECRET_KEY_SIZE 32 | 216 | #define TOX_SECRET_KEY_SIZE 32 |
217 | 217 | ||
218 | /** | 218 | /** |
219 | * The size of a Tox address in bytes. Tox addresses are in the format | 219 | * The size of a Tox address in bytes. Tox addresses are in the format |
@@ -223,47 +223,48 @@ bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch); | |||
223 | * byte is an XOR of all the even bytes (0, 2, 4, ...), the second byte is an | 223 | * byte is an XOR of all the even bytes (0, 2, 4, ...), the second byte is an |
224 | * XOR of all the odd bytes (1, 3, 5, ...) of the Public Key and nospam. | 224 | * XOR of all the odd bytes (1, 3, 5, ...) of the Public Key and nospam. |
225 | */ | 225 | */ |
226 | #define TOX_ADDRESS_SIZE (TOX_PUBLIC_KEY_SIZE + sizeof(uint32_t) + sizeof(uint16_t)) | 226 | #define TOX_ADDRESS_SIZE (TOX_PUBLIC_KEY_SIZE + sizeof(uint32_t) + sizeof(uint16_t)) |
227 | 227 | ||
228 | /** | 228 | /** |
229 | * Maximum length of a nickname in bytes. | 229 | * Maximum length of a nickname in bytes. |
230 | */ | 230 | */ |
231 | #define TOX_MAX_NAME_LENGTH 128 | 231 | #define TOX_MAX_NAME_LENGTH 128 |
232 | 232 | ||
233 | /** | 233 | /** |
234 | * Maximum length of a status message in bytes. | 234 | * Maximum length of a status message in bytes. |
235 | */ | 235 | */ |
236 | #define TOX_MAX_STATUS_MESSAGE_LENGTH 1007 | 236 | #define TOX_MAX_STATUS_MESSAGE_LENGTH 1007 |
237 | 237 | ||
238 | /** | 238 | /** |
239 | * Maximum length of a friend request message in bytes. | 239 | * Maximum length of a friend request message in bytes. |
240 | */ | 240 | */ |
241 | #define TOX_MAX_FRIEND_REQUEST_LENGTH 1016 | 241 | #define TOX_MAX_FRIEND_REQUEST_LENGTH 1016 |
242 | 242 | ||
243 | /** | 243 | /** |
244 | * Maximum length of a single message after which it should be split. | 244 | * Maximum length of a single message after which it should be split. |
245 | */ | 245 | */ |
246 | #define TOX_MAX_MESSAGE_LENGTH 1372 | 246 | #define TOX_MAX_MESSAGE_LENGTH 1372 |
247 | 247 | ||
248 | /** | 248 | /** |
249 | * Maximum size of custom packets. TODO: should be LENGTH? | 249 | * Maximum size of custom packets. TODO: should be LENGTH? |
250 | */ | 250 | */ |
251 | #define TOX_MAX_CUSTOM_PACKET_SIZE 1373 | 251 | #define TOX_MAX_CUSTOM_PACKET_SIZE 1373 |
252 | 252 | ||
253 | /** | 253 | /** |
254 | * The number of bytes in a hash generated by tox_hash. | 254 | * The number of bytes in a hash generated by tox_hash. |
255 | */ | 255 | */ |
256 | #define TOX_HASH_LENGTH /*crypto_hash_sha256_BYTES*/ 32 | 256 | #define TOX_HASH_LENGTH 32 |
257 | 257 | ||
258 | /** | 258 | /** |
259 | * The number of bytes in a file id. | 259 | * The number of bytes in a file id. |
260 | */ | 260 | */ |
261 | #define TOX_FILE_ID_LENGTH 32 | 261 | #define TOX_FILE_ID_LENGTH 32 |
262 | 262 | ||
263 | /** | 263 | /** |
264 | * Maximum file name length for file tran. | 264 | * Maximum file name length for file transfers. |
265 | */ | 265 | */ |
266 | #define TOX_MAX_FILENAME_LENGTH 255 | 266 | #define TOX_MAX_FILENAME_LENGTH 255 |
267 | |||
267 | 268 | ||
268 | /******************************************************************************* | 269 | /******************************************************************************* |
269 | * | 270 | * |
@@ -272,42 +273,53 @@ bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch); | |||
272 | ******************************************************************************/ | 273 | ******************************************************************************/ |
273 | 274 | ||
274 | 275 | ||
276 | |||
275 | /** | 277 | /** |
276 | * Represents the possible statuses a client can have. | 278 | * Represents the possible statuses a client can have. |
277 | */ | 279 | */ |
278 | typedef enum TOX_USER_STATUS { | 280 | typedef enum TOX_USER_STATUS { |
281 | |||
279 | /** | 282 | /** |
280 | * User is online and available. | 283 | * User is online and available. |
281 | */ | 284 | */ |
282 | TOX_USER_STATUS_NONE, | 285 | TOX_USER_STATUS_NONE, |
286 | |||
283 | /** | 287 | /** |
284 | * User is away. Clients can set this e.g. after a user defined | 288 | * User is away. Clients can set this e.g. after a user defined |
285 | * inactivity time. | 289 | * inactivity time. |
286 | */ | 290 | */ |
287 | TOX_USER_STATUS_AWAY, | 291 | TOX_USER_STATUS_AWAY, |
292 | |||
288 | /** | 293 | /** |
289 | * User is busy. Signals to other clients that this client does not | 294 | * User is busy. Signals to other clients that this client does not |
290 | * currently wish to communicate. | 295 | * currently wish to communicate. |
291 | */ | 296 | */ |
292 | TOX_USER_STATUS_BUSY | 297 | TOX_USER_STATUS_BUSY, |
298 | |||
293 | } TOX_USER_STATUS; | 299 | } TOX_USER_STATUS; |
294 | 300 | ||
301 | |||
295 | /** | 302 | /** |
296 | * Represents message types for friend messages and group chat | 303 | * Represents message types for tox_friend_send_message and group chat |
297 | * messages. | 304 | * messages. |
298 | */ | 305 | */ |
299 | typedef enum TOX_MESSAGE_TYPE { | 306 | typedef enum TOX_MESSAGE_TYPE { |
307 | |||
300 | /** | 308 | /** |
301 | * Normal text message. Similar to PRIVMSG on IRC. | 309 | * Normal text message. Similar to PRIVMSG on IRC. |
302 | */ | 310 | */ |
303 | TOX_MESSAGE_TYPE_NORMAL, | 311 | TOX_MESSAGE_TYPE_NORMAL, |
312 | |||
304 | /** | 313 | /** |
305 | * A message describing an user action. This is similar to /me (CTCP ACTION) | 314 | * A message describing an user action. This is similar to /me (CTCP ACTION) |
306 | * on IRC. | 315 | * on IRC. |
307 | */ | 316 | */ |
308 | TOX_MESSAGE_TYPE_ACTION | 317 | TOX_MESSAGE_TYPE_ACTION, |
318 | |||
309 | } TOX_MESSAGE_TYPE; | 319 | } TOX_MESSAGE_TYPE; |
310 | 320 | ||
321 | |||
322 | |||
311 | /******************************************************************************* | 323 | /******************************************************************************* |
312 | * | 324 | * |
313 | * :: Startup options | 325 | * :: Startup options |
@@ -315,19 +327,27 @@ typedef enum TOX_MESSAGE_TYPE { | |||
315 | ******************************************************************************/ | 327 | ******************************************************************************/ |
316 | 328 | ||
317 | 329 | ||
330 | |||
331 | /** | ||
332 | * Type of proxy used to connect to TCP relays. | ||
333 | */ | ||
318 | typedef enum TOX_PROXY_TYPE { | 334 | typedef enum TOX_PROXY_TYPE { |
335 | |||
319 | /** | 336 | /** |
320 | * Don't use a proxy. | 337 | * Don't use a proxy. |
321 | */ | 338 | */ |
322 | TOX_PROXY_TYPE_NONE, | 339 | TOX_PROXY_TYPE_NONE, |
340 | |||
323 | /** | 341 | /** |
324 | * HTTP proxy using CONNECT. | 342 | * HTTP proxy using CONNECT. |
325 | */ | 343 | */ |
326 | TOX_PROXY_TYPE_HTTP, | 344 | TOX_PROXY_TYPE_HTTP, |
345 | |||
327 | /** | 346 | /** |
328 | * SOCKS proxy for simple socket pipes. | 347 | * SOCKS proxy for simple socket pipes. |
329 | */ | 348 | */ |
330 | TOX_PROXY_TYPE_SOCKS5 | 349 | TOX_PROXY_TYPE_SOCKS5, |
350 | |||
331 | } TOX_PROXY_TYPE; | 351 | } TOX_PROXY_TYPE; |
332 | 352 | ||
333 | 353 | ||
@@ -337,6 +357,7 @@ typedef enum TOX_PROXY_TYPE { | |||
337 | * tox_options_new to get a new default options object. | 357 | * tox_options_new to get a new default options object. |
338 | */ | 358 | */ |
339 | struct Tox_Options { | 359 | struct Tox_Options { |
360 | |||
340 | /** | 361 | /** |
341 | * The type of socket to create. | 362 | * The type of socket to create. |
342 | * | 363 | * |
@@ -347,6 +368,7 @@ struct Tox_Options { | |||
347 | */ | 368 | */ |
348 | bool ipv6_enabled; | 369 | bool ipv6_enabled; |
349 | 370 | ||
371 | |||
350 | /** | 372 | /** |
351 | * Enable the use of UDP communication when available. | 373 | * Enable the use of UDP communication when available. |
352 | * | 374 | * |
@@ -356,11 +378,13 @@ struct Tox_Options { | |||
356 | */ | 378 | */ |
357 | bool udp_enabled; | 379 | bool udp_enabled; |
358 | 380 | ||
381 | |||
359 | /** | 382 | /** |
360 | * Pass communications through a proxy. | 383 | * Pass communications through a proxy. |
361 | */ | 384 | */ |
362 | TOX_PROXY_TYPE proxy_type; | 385 | TOX_PROXY_TYPE proxy_type; |
363 | 386 | ||
387 | |||
364 | /** | 388 | /** |
365 | * The IP address or DNS name of the proxy to be used. | 389 | * The IP address or DNS name of the proxy to be used. |
366 | * | 390 | * |
@@ -368,18 +392,20 @@ struct Tox_Options { | |||
368 | * exceed 255 characters, and be in a NUL-terminated C string format | 392 | * exceed 255 characters, and be in a NUL-terminated C string format |
369 | * (255 chars + 1 NUL byte). | 393 | * (255 chars + 1 NUL byte). |
370 | * | 394 | * |
371 | * This member is ignored (it can be NULL) if proxy_enabled is false. | 395 | * This member is ignored (it can be NULL) if proxy_type is TOX_PROXY_TYPE_NONE. |
372 | */ | 396 | */ |
373 | const char *proxy_host; | 397 | const char *proxy_host; |
374 | 398 | ||
399 | |||
375 | /** | 400 | /** |
376 | * The port to use to connect to the proxy server. | 401 | * The port to use to connect to the proxy server. |
377 | * | 402 | * |
378 | * Ports must be in the range (1, 65535). The value is ignored if | 403 | * Ports must be in the range (1, 65535). The value is ignored if |
379 | * proxy_enabled is false. | 404 | * proxy_type is TOX_PROXY_TYPE_NONE. |
380 | */ | 405 | */ |
381 | uint16_t proxy_port; | 406 | uint16_t proxy_port; |
382 | 407 | ||
408 | |||
383 | /** | 409 | /** |
384 | * The start port of the inclusive port range to attempt to use. | 410 | * The start port of the inclusive port range to attempt to use. |
385 | * | 411 | * |
@@ -394,10 +420,12 @@ struct Tox_Options { | |||
394 | */ | 420 | */ |
395 | uint16_t start_port; | 421 | uint16_t start_port; |
396 | 422 | ||
423 | |||
397 | /** | 424 | /** |
398 | * The end port of the inclusive port range to attempt to use. | 425 | * The end port of the inclusive port range to attempt to use. |
399 | */ | 426 | */ |
400 | uint16_t end_port; | 427 | uint16_t end_port; |
428 | |||
401 | }; | 429 | }; |
402 | 430 | ||
403 | 431 | ||
@@ -414,15 +442,21 @@ struct Tox_Options { | |||
414 | */ | 442 | */ |
415 | void tox_options_default(struct Tox_Options *options); | 443 | void tox_options_default(struct Tox_Options *options); |
416 | 444 | ||
417 | |||
418 | typedef enum TOX_ERR_OPTIONS_NEW { | 445 | typedef enum TOX_ERR_OPTIONS_NEW { |
446 | |||
447 | /** | ||
448 | * The function returned successfully. | ||
449 | */ | ||
419 | TOX_ERR_OPTIONS_NEW_OK, | 450 | TOX_ERR_OPTIONS_NEW_OK, |
451 | |||
420 | /** | 452 | /** |
421 | * The function failed to allocate enough memory for the options struct. | 453 | * The function failed to allocate enough memory for the options struct. |
422 | */ | 454 | */ |
423 | TOX_ERR_OPTIONS_NEW_MALLOC | 455 | TOX_ERR_OPTIONS_NEW_MALLOC, |
456 | |||
424 | } TOX_ERR_OPTIONS_NEW; | 457 | } TOX_ERR_OPTIONS_NEW; |
425 | 458 | ||
459 | |||
426 | /** | 460 | /** |
427 | * Allocates a new Tox_Options object and initialises it with the default | 461 | * Allocates a new Tox_Options object and initialises it with the default |
428 | * options. This function can be used to preserve long term ABI compatibility by | 462 | * options. This function can be used to preserve long term ABI compatibility by |
@@ -435,7 +469,6 @@ typedef enum TOX_ERR_OPTIONS_NEW { | |||
435 | */ | 469 | */ |
436 | struct Tox_Options *tox_options_new(TOX_ERR_OPTIONS_NEW *error); | 470 | struct Tox_Options *tox_options_new(TOX_ERR_OPTIONS_NEW *error); |
437 | 471 | ||
438 | |||
439 | /** | 472 | /** |
440 | * Releases all resources associated with an options objects. | 473 | * Releases all resources associated with an options objects. |
441 | * | 474 | * |
@@ -452,41 +485,58 @@ void tox_options_free(struct Tox_Options *options); | |||
452 | ******************************************************************************/ | 485 | ******************************************************************************/ |
453 | 486 | ||
454 | 487 | ||
488 | |||
455 | typedef enum TOX_ERR_NEW { | 489 | typedef enum TOX_ERR_NEW { |
490 | |||
491 | /** | ||
492 | * The function returned successfully. | ||
493 | */ | ||
456 | TOX_ERR_NEW_OK, | 494 | TOX_ERR_NEW_OK, |
495 | |||
496 | /** | ||
497 | * One of the arguments to the function was NULL when it was not expected. | ||
498 | */ | ||
457 | TOX_ERR_NEW_NULL, | 499 | TOX_ERR_NEW_NULL, |
500 | |||
458 | /** | 501 | /** |
459 | * The function was unable to allocate enough memory to store the internal | 502 | * The function was unable to allocate enough memory to store the internal |
460 | * structures for the Tox object. | 503 | * structures for the Tox object. |
461 | */ | 504 | */ |
462 | TOX_ERR_NEW_MALLOC, | 505 | TOX_ERR_NEW_MALLOC, |
506 | |||
463 | /** | 507 | /** |
464 | * The function was unable to bind to a port. This may mean that all ports | 508 | * The function was unable to bind to a port. This may mean that all ports |
465 | * have already been bound, e.g. by other Tox instances, or it may mean | 509 | * have already been bound, e.g. by other Tox instances, or it may mean |
466 | * a permission error. You may be able to gather more information from errno. | 510 | * a permission error. You may be able to gather more information from errno. |
467 | */ | 511 | */ |
468 | TOX_ERR_NEW_PORT_ALLOC, | 512 | TOX_ERR_NEW_PORT_ALLOC, |
513 | |||
469 | /** | 514 | /** |
470 | * proxy_type was invalid. | 515 | * proxy_type was invalid. |
471 | */ | 516 | */ |
472 | TOX_ERR_NEW_PROXY_BAD_TYPE, | 517 | TOX_ERR_NEW_PROXY_BAD_TYPE, |
518 | |||
473 | /** | 519 | /** |
474 | * proxy_type was valid but the proxy_host passed had an invalid format | 520 | * proxy_type was valid but the proxy_host passed had an invalid format |
475 | * or was NULL. | 521 | * or was NULL. |
476 | */ | 522 | */ |
477 | TOX_ERR_NEW_PROXY_BAD_HOST, | 523 | TOX_ERR_NEW_PROXY_BAD_HOST, |
524 | |||
478 | /** | 525 | /** |
479 | * proxy_type was valid, but the proxy_port was invalid. | 526 | * proxy_type was valid, but the proxy_port was invalid. |
480 | */ | 527 | */ |
481 | TOX_ERR_NEW_PROXY_BAD_PORT, | 528 | TOX_ERR_NEW_PROXY_BAD_PORT, |
529 | |||
482 | /** | 530 | /** |
483 | * The proxy host passed could not be resolved. | 531 | * The proxy address passed could not be resolved. |
484 | */ | 532 | */ |
485 | TOX_ERR_NEW_PROXY_NOT_FOUND, | 533 | TOX_ERR_NEW_PROXY_NOT_FOUND, |
534 | |||
486 | /** | 535 | /** |
487 | * The byte array to be loaded contained an encrypted save. | 536 | * The byte array to be loaded contained an encrypted save. |
488 | */ | 537 | */ |
489 | TOX_ERR_NEW_LOAD_ENCRYPTED, | 538 | TOX_ERR_NEW_LOAD_ENCRYPTED, |
539 | |||
490 | /** | 540 | /** |
491 | * The data format was invalid. This can happen when loading data that was | 541 | * The data format was invalid. This can happen when loading data that was |
492 | * saved by an older version of Tox, or when the data has been corrupted. | 542 | * saved by an older version of Tox, or when the data has been corrupted. |
@@ -494,7 +544,8 @@ typedef enum TOX_ERR_NEW { | |||
494 | * and the rest is discarded. Passing an invalid length parameter also | 544 | * and the rest is discarded. Passing an invalid length parameter also |
495 | * causes this error. | 545 | * causes this error. |
496 | */ | 546 | */ |
497 | TOX_ERR_NEW_LOAD_BAD_FORMAT | 547 | TOX_ERR_NEW_LOAD_BAD_FORMAT, |
548 | |||
498 | } TOX_ERR_NEW; | 549 | } TOX_ERR_NEW; |
499 | 550 | ||
500 | 551 | ||
@@ -516,11 +567,10 @@ typedef enum TOX_ERR_NEW { | |||
516 | * @param length The length of the byte array data. If this parameter is 0, the | 567 | * @param length The length of the byte array data. If this parameter is 0, the |
517 | * data parameter is ignored. | 568 | * data parameter is ignored. |
518 | * | 569 | * |
519 | * @see tox_iteration for the event loop. | 570 | * @see tox_iterate for the event loop. |
520 | */ | 571 | */ |
521 | Tox *tox_new(const struct Tox_Options *options, const uint8_t *data, size_t length, TOX_ERR_NEW *error); | 572 | Tox *tox_new(const struct Tox_Options *options, const uint8_t *data, size_t length, TOX_ERR_NEW *error); |
522 | 573 | ||
523 | |||
524 | /** | 574 | /** |
525 | * Releases all resources associated with the Tox instance and disconnects from | 575 | * Releases all resources associated with the Tox instance and disconnects from |
526 | * the network. | 576 | * the network. |
@@ -530,11 +580,9 @@ Tox *tox_new(const struct Tox_Options *options, const uint8_t *data, size_t leng | |||
530 | */ | 580 | */ |
531 | void tox_kill(Tox *tox); | 581 | void tox_kill(Tox *tox); |
532 | 582 | ||
533 | |||
534 | /** | 583 | /** |
535 | * Calculates the number of bytes required to store the tox instance with | 584 | * Calculates the number of bytes required to store the tox instance with |
536 | * tox_get_savedata. This function cannot fail. The result is always greater | 585 | * tox_get_savedata. This function cannot fail. The result is always greater than 0. |
537 | * than 0. | ||
538 | * | 586 | * |
539 | * @see threading for concurrency implications. | 587 | * @see threading for concurrency implications. |
540 | */ | 588 | */ |
@@ -547,7 +595,7 @@ size_t tox_get_savedata_size(const Tox *tox); | |||
547 | * Call tox_get_savedata_size to find the number of bytes required. If this parameter | 595 | * Call tox_get_savedata_size to find the number of bytes required. If this parameter |
548 | * is NULL, this function has no effect. | 596 | * is NULL, this function has no effect. |
549 | */ | 597 | */ |
550 | void tox_get_savedata(const Tox *tox, uint8_t *data); | 598 | void tox_get_savedata(const Tox *tox, uint8_t *savedata); |
551 | 599 | ||
552 | 600 | ||
553 | /******************************************************************************* | 601 | /******************************************************************************* |
@@ -557,20 +605,33 @@ void tox_get_savedata(const Tox *tox, uint8_t *data); | |||
557 | ******************************************************************************/ | 605 | ******************************************************************************/ |
558 | 606 | ||
559 | 607 | ||
608 | |||
560 | typedef enum TOX_ERR_BOOTSTRAP { | 609 | typedef enum TOX_ERR_BOOTSTRAP { |
610 | |||
611 | /** | ||
612 | * The function returned successfully. | ||
613 | */ | ||
561 | TOX_ERR_BOOTSTRAP_OK, | 614 | TOX_ERR_BOOTSTRAP_OK, |
615 | |||
616 | /** | ||
617 | * One of the arguments to the function was NULL when it was not expected. | ||
618 | */ | ||
562 | TOX_ERR_BOOTSTRAP_NULL, | 619 | TOX_ERR_BOOTSTRAP_NULL, |
620 | |||
563 | /** | 621 | /** |
564 | * The host could not be resolved to an IP address, or the IP address | 622 | * The address could not be resolved to an IP address, or the IP address |
565 | * passed was invalid. | 623 | * passed was invalid. |
566 | */ | 624 | */ |
567 | TOX_ERR_BOOTSTRAP_BAD_HOST, | 625 | TOX_ERR_BOOTSTRAP_BAD_HOST, |
626 | |||
568 | /** | 627 | /** |
569 | * The port passed was invalid. The valid port range is (1, 65535). | 628 | * The port passed was invalid. The valid port range is (1, 65535). |
570 | */ | 629 | */ |
571 | TOX_ERR_BOOTSTRAP_BAD_PORT | 630 | TOX_ERR_BOOTSTRAP_BAD_PORT, |
631 | |||
572 | } TOX_ERR_BOOTSTRAP; | 632 | } TOX_ERR_BOOTSTRAP; |
573 | 633 | ||
634 | |||
574 | /** | 635 | /** |
575 | * Sends a "get nodes" request to the given bootstrap node with IP, port, and | 636 | * Sends a "get nodes" request to the given bootstrap node with IP, port, and |
576 | * public key to setup connections. | 637 | * public key to setup connections. |
@@ -583,15 +644,14 @@ typedef enum TOX_ERR_BOOTSTRAP { | |||
583 | * also use the TCP connection when NAT hole punching is slow, and later switch | 644 | * also use the TCP connection when NAT hole punching is slow, and later switch |
584 | * to UDP if hole punching succeeds. | 645 | * to UDP if hole punching succeeds. |
585 | * | 646 | * |
586 | * @param host The hostname or IP address (IPv4 or IPv6) of the node. | 647 | * @param address The hostname or IP address (IPv4 or IPv6) of the node. |
587 | * @param port The port on the host on which the bootstrap Tox instance is | 648 | * @param port The port on the host on which the bootstrap Tox instance is |
588 | * listening. | 649 | * listening. |
589 | * @param public_key The long term public key of the bootstrap node | 650 | * @param public_key The long term public key of the bootstrap node |
590 | * (TOX_PUBLIC_KEY_SIZE bytes). | 651 | * (TOX_PUBLIC_KEY_SIZE bytes). |
591 | * @return true on success. | 652 | * @return true on success. |
592 | */ | 653 | */ |
593 | bool tox_bootstrap(Tox *tox, const char *host, uint16_t port, const uint8_t *public_key, TOX_ERR_BOOTSTRAP *error); | 654 | bool tox_bootstrap(Tox *tox, const char *address, uint16_t port, const uint8_t *public_key, TOX_ERR_BOOTSTRAP *error); |
594 | |||
595 | 655 | ||
596 | /** | 656 | /** |
597 | * Adds additional host:port pair as TCP relay. | 657 | * Adds additional host:port pair as TCP relay. |
@@ -600,35 +660,41 @@ bool tox_bootstrap(Tox *tox, const char *host, uint16_t port, const uint8_t *pub | |||
600 | * the same bootstrap node, or to add TCP relays without using them as | 660 | * the same bootstrap node, or to add TCP relays without using them as |
601 | * bootstrap nodes. | 661 | * bootstrap nodes. |
602 | * | 662 | * |
603 | * @param host The hostname or IP address (IPv4 or IPv6) of the TCP relay. | 663 | * @param address The hostname or IP address (IPv4 or IPv6) of the TCP relay. |
604 | * @param port The port on the host on which the TCP relay is listening. | 664 | * @param port The port on the host on which the TCP relay is listening. |
605 | * @param public_key The long term public key of the TCP relay | 665 | * @param public_key The long term public key of the TCP relay |
606 | * (TOX_PUBLIC_KEY_SIZE bytes). | 666 | * (TOX_PUBLIC_KEY_SIZE bytes). |
607 | * @return true on success. | 667 | * @return true on success. |
608 | */ | 668 | */ |
609 | bool tox_add_tcp_relay(Tox *tox, const char *host, uint16_t port, const uint8_t *public_key, | 669 | bool tox_add_tcp_relay(Tox *tox, const char *address, uint16_t port, const uint8_t *public_key, |
610 | TOX_ERR_BOOTSTRAP *error); | 670 | TOX_ERR_BOOTSTRAP *error); |
611 | 671 | ||
612 | 672 | /** | |
673 | * Protocols that can be used to connect to the network or friends. | ||
674 | */ | ||
613 | typedef enum TOX_CONNECTION { | 675 | typedef enum TOX_CONNECTION { |
676 | |||
614 | /** | 677 | /** |
615 | * There is no connection. This instance, or the friend the state change is | 678 | * There is no connection. This instance, or the friend the state change is |
616 | * about, is now offline. | 679 | * about, is now offline. |
617 | */ | 680 | */ |
618 | TOX_CONNECTION_NONE, | 681 | TOX_CONNECTION_NONE, |
682 | |||
619 | /** | 683 | /** |
620 | * A TCP connection has been established. For the own instance, this means it | 684 | * A TCP connection has been established. For the own instance, this means it |
621 | * is connected through a TCP relay, only. For a friend, this means that the | 685 | * is connected through a TCP relay, only. For a friend, this means that the |
622 | * connection to that particular friend goes through a TCP relay. | 686 | * connection to that particular friend goes through a TCP relay. |
623 | */ | 687 | */ |
624 | TOX_CONNECTION_TCP, | 688 | TOX_CONNECTION_TCP, |
689 | |||
625 | /** | 690 | /** |
626 | * A UDP connection has been established. For the own instance, this means it | 691 | * A UDP connection has been established. For the own instance, this means it |
627 | * is able to send UDP packets to DHT nodes, but may still be connected to | 692 | * is able to send UDP packets to DHT nodes, but may still be connected to |
628 | * a TCP relay. For a friend, this means that the connection to that | 693 | * a TCP relay. For a friend, this means that the connection to that |
629 | * particular friend was built using direct UDP packets. | 694 | * particular friend was built using direct UDP packets. |
630 | */ | 695 | */ |
631 | TOX_CONNECTION_UDP | 696 | TOX_CONNECTION_UDP, |
697 | |||
632 | } TOX_CONNECTION; | 698 | } TOX_CONNECTION; |
633 | 699 | ||
634 | 700 | ||
@@ -639,13 +705,11 @@ typedef enum TOX_CONNECTION { | |||
639 | TOX_CONNECTION tox_self_get_connection_status(const Tox *tox); | 705 | TOX_CONNECTION tox_self_get_connection_status(const Tox *tox); |
640 | 706 | ||
641 | /** | 707 | /** |
642 | * The function type for the `self_connection_status` callback. | 708 | * @param connection_status Whether we are connected to the DHT. |
643 | * | ||
644 | * @param connection_status Equal to the return value of | ||
645 | * tox_self_get_connection_status. | ||
646 | */ | 709 | */ |
647 | typedef void tox_self_connection_status_cb(Tox *tox, TOX_CONNECTION connection_status, void *user_data); | 710 | typedef void tox_self_connection_status_cb(Tox *tox, TOX_CONNECTION connection_status, void *user_data); |
648 | 711 | ||
712 | |||
649 | /** | 713 | /** |
650 | * Set the callback for the `self_connection_status` event. Pass NULL to unset. | 714 | * Set the callback for the `self_connection_status` event. Pass NULL to unset. |
651 | * | 715 | * |
@@ -657,16 +721,14 @@ typedef void tox_self_connection_status_cb(Tox *tox, TOX_CONNECTION connection_s | |||
657 | * | 721 | * |
658 | * TODO: how long should a client wait before bootstrapping again? | 722 | * TODO: how long should a client wait before bootstrapping again? |
659 | */ | 723 | */ |
660 | void tox_callback_self_connection_status(Tox *tox, tox_self_connection_status_cb *function, void *user_data); | 724 | void tox_callback_self_connection_status(Tox *tox, tox_self_connection_status_cb *callback, void *user_data); |
661 | |||
662 | 725 | ||
663 | /** | 726 | /** |
664 | * Return the time in milliseconds before tox_iteration() should be called again | 727 | * Return the time in milliseconds before tox_iterate() should be called again |
665 | * for optimal performance. | 728 | * for optimal performance. |
666 | */ | 729 | */ |
667 | uint32_t tox_iteration_interval(const Tox *tox); | 730 | uint32_t tox_iteration_interval(const Tox *tox); |
668 | 731 | ||
669 | |||
670 | /** | 732 | /** |
671 | * The main loop that needs to be run in intervals of tox_iteration_interval() | 733 | * The main loop that needs to be run in intervals of tox_iteration_interval() |
672 | * milliseconds. | 734 | * milliseconds. |
@@ -681,6 +743,7 @@ void tox_iterate(Tox *tox); | |||
681 | ******************************************************************************/ | 743 | ******************************************************************************/ |
682 | 744 | ||
683 | 745 | ||
746 | |||
684 | /** | 747 | /** |
685 | * Writes the Tox friend address of the client to a byte array. The address is | 748 | * Writes the Tox friend address of the client to a byte array. The address is |
686 | * not in human-readable format. If a client wants to display the address, | 749 | * not in human-readable format. If a client wants to display the address, |
@@ -692,7 +755,6 @@ void tox_iterate(Tox *tox); | |||
692 | */ | 755 | */ |
693 | void tox_self_get_address(const Tox *tox, uint8_t *address); | 756 | void tox_self_get_address(const Tox *tox, uint8_t *address); |
694 | 757 | ||
695 | |||
696 | /** | 758 | /** |
697 | * Set the 4-byte nospam part of the address. | 759 | * Set the 4-byte nospam part of the address. |
698 | * | 760 | * |
@@ -706,7 +768,7 @@ void tox_self_set_nospam(Tox *tox, uint32_t nospam); | |||
706 | uint32_t tox_self_get_nospam(const Tox *tox); | 768 | uint32_t tox_self_get_nospam(const Tox *tox); |
707 | 769 | ||
708 | /** | 770 | /** |
709 | * Copy the Tox Public Key (long term public key) from the Tox object. | 771 | * Copy the Tox Public Key (long term) from the Tox object. |
710 | * | 772 | * |
711 | * @param public_key A memory region of at least TOX_PUBLIC_KEY_SIZE bytes. If | 773 | * @param public_key A memory region of at least TOX_PUBLIC_KEY_SIZE bytes. If |
712 | * this parameter is NULL, this function has no effect. | 774 | * this parameter is NULL, this function has no effect. |
@@ -714,7 +776,7 @@ uint32_t tox_self_get_nospam(const Tox *tox); | |||
714 | void tox_self_get_public_key(const Tox *tox, uint8_t *public_key); | 776 | void tox_self_get_public_key(const Tox *tox, uint8_t *public_key); |
715 | 777 | ||
716 | /** | 778 | /** |
717 | * Copy the secret key from the Tox object. | 779 | * Copy the Tox Secret Key from the Tox object. |
718 | * | 780 | * |
719 | * @param secret_key A memory region of at least TOX_SECRET_KEY_SIZE bytes. If | 781 | * @param secret_key A memory region of at least TOX_SECRET_KEY_SIZE bytes. If |
720 | * this parameter is NULL, this function has no effect. | 782 | * this parameter is NULL, this function has no effect. |
@@ -729,17 +791,28 @@ void tox_self_get_secret_key(const Tox *tox, uint8_t *secret_key); | |||
729 | ******************************************************************************/ | 791 | ******************************************************************************/ |
730 | 792 | ||
731 | 793 | ||
794 | |||
732 | /** | 795 | /** |
733 | * Common error codes for all functions that set a piece of user-visible | 796 | * Common error codes for all functions that set a piece of user-visible |
734 | * client information. | 797 | * client information. |
735 | */ | 798 | */ |
736 | typedef enum TOX_ERR_SET_INFO { | 799 | typedef enum TOX_ERR_SET_INFO { |
800 | |||
801 | /** | ||
802 | * The function returned successfully. | ||
803 | */ | ||
737 | TOX_ERR_SET_INFO_OK, | 804 | TOX_ERR_SET_INFO_OK, |
805 | |||
806 | /** | ||
807 | * One of the arguments to the function was NULL when it was not expected. | ||
808 | */ | ||
738 | TOX_ERR_SET_INFO_NULL, | 809 | TOX_ERR_SET_INFO_NULL, |
810 | |||
739 | /** | 811 | /** |
740 | * Information length exceeded maximum permissible size. | 812 | * Information length exceeded maximum permissible size. |
741 | */ | 813 | */ |
742 | TOX_ERR_SET_INFO_TOO_LONG | 814 | TOX_ERR_SET_INFO_TOO_LONG, |
815 | |||
743 | } TOX_ERR_SET_INFO; | 816 | } TOX_ERR_SET_INFO; |
744 | 817 | ||
745 | 818 | ||
@@ -787,11 +860,10 @@ void tox_self_get_name(const Tox *tox, uint8_t *name); | |||
787 | * length is 0, the status parameter is ignored (it can be NULL), and the | 860 | * length is 0, the status parameter is ignored (it can be NULL), and the |
788 | * user status is set back to empty. | 861 | * user status is set back to empty. |
789 | */ | 862 | */ |
790 | bool tox_self_set_status_message(Tox *tox, const uint8_t *status, size_t length, TOX_ERR_SET_INFO *error); | 863 | bool tox_self_set_status_message(Tox *tox, const uint8_t *status_message, size_t length, TOX_ERR_SET_INFO *error); |
791 | 864 | ||
792 | /** | 865 | /** |
793 | * Return the length of the current status message as passed to | 866 | * Return the length of the current status message as passed to tox_self_set_status_message. |
794 | * tox_self_set_status_message. | ||
795 | * | 867 | * |
796 | * If no status message was set before calling this function, the status | 868 | * If no status message was set before calling this function, the status |
797 | * is empty, and this function returns 0. | 869 | * is empty, and this function returns 0. |
@@ -806,21 +878,20 @@ size_t tox_self_get_status_message_size(const Tox *tox); | |||
806 | * If no status message was set before calling this function, the status is | 878 | * If no status message was set before calling this function, the status is |
807 | * empty, and this function has no effect. | 879 | * empty, and this function has no effect. |
808 | * | 880 | * |
809 | * Call tox_self_status_message_size to find out how much memory to allocate for | 881 | * Call tox_self_get_status_message_size to find out how much memory to allocate for |
810 | * the result. | 882 | * the result. |
811 | * | 883 | * |
812 | * @param status A valid memory location large enough to hold the status message. | 884 | * @param status A valid memory location large enough to hold the status message. |
813 | * If this parameter is NULL, the function has no effect. | 885 | * If this parameter is NULL, the function has no effect. |
814 | */ | 886 | */ |
815 | void tox_self_get_status_message(const Tox *tox, uint8_t *status); | 887 | void tox_self_get_status_message(const Tox *tox, uint8_t *status_message); |
816 | |||
817 | 888 | ||
818 | /** | 889 | /** |
819 | * Set the client's user status. | 890 | * Set the client's user status. |
820 | * | 891 | * |
821 | * @param user_status One of the user statuses listed in the enumeration above. | 892 | * @param user_status One of the user statuses listed in the enumeration above. |
822 | */ | 893 | */ |
823 | void tox_self_set_status(Tox *tox, TOX_USER_STATUS user_status); | 894 | void tox_self_set_status(Tox *tox, TOX_USER_STATUS status); |
824 | 895 | ||
825 | /** | 896 | /** |
826 | * Returns the client's user status. | 897 | * Returns the client's user status. |
@@ -835,42 +906,60 @@ TOX_USER_STATUS tox_self_get_status(const Tox *tox); | |||
835 | ******************************************************************************/ | 906 | ******************************************************************************/ |
836 | 907 | ||
837 | 908 | ||
909 | |||
838 | typedef enum TOX_ERR_FRIEND_ADD { | 910 | typedef enum TOX_ERR_FRIEND_ADD { |
911 | |||
912 | /** | ||
913 | * The function returned successfully. | ||
914 | */ | ||
839 | TOX_ERR_FRIEND_ADD_OK, | 915 | TOX_ERR_FRIEND_ADD_OK, |
916 | |||
917 | /** | ||
918 | * One of the arguments to the function was NULL when it was not expected. | ||
919 | */ | ||
840 | TOX_ERR_FRIEND_ADD_NULL, | 920 | TOX_ERR_FRIEND_ADD_NULL, |
921 | |||
841 | /** | 922 | /** |
842 | * The length of the friend request message exceeded | 923 | * The length of the friend request message exceeded |
843 | * TOX_MAX_FRIEND_REQUEST_LENGTH. | 924 | * TOX_MAX_FRIEND_REQUEST_LENGTH. |
844 | */ | 925 | */ |
845 | TOX_ERR_FRIEND_ADD_TOO_LONG, | 926 | TOX_ERR_FRIEND_ADD_TOO_LONG, |
927 | |||
846 | /** | 928 | /** |
847 | * The friend request message was empty. This, and the TOO_LONG code will | 929 | * The friend request message was empty. This, and the TOO_LONG code will |
848 | * never be returned from tox_friend_add_norequest. | 930 | * never be returned from tox_friend_add_norequest. |
849 | */ | 931 | */ |
850 | TOX_ERR_FRIEND_ADD_NO_MESSAGE, | 932 | TOX_ERR_FRIEND_ADD_NO_MESSAGE, |
933 | |||
851 | /** | 934 | /** |
852 | * The friend address belongs to the sending client. | 935 | * The friend address belongs to the sending client. |
853 | */ | 936 | */ |
854 | TOX_ERR_FRIEND_ADD_OWN_KEY, | 937 | TOX_ERR_FRIEND_ADD_OWN_KEY, |
938 | |||
855 | /** | 939 | /** |
856 | * A friend request has already been sent, or the address belongs to a friend | 940 | * A friend request has already been sent, or the address belongs to a friend |
857 | * that is already on the friend list. | 941 | * that is already on the friend list. |
858 | */ | 942 | */ |
859 | TOX_ERR_FRIEND_ADD_ALREADY_SENT, | 943 | TOX_ERR_FRIEND_ADD_ALREADY_SENT, |
944 | |||
860 | /** | 945 | /** |
861 | * The friend address checksum failed. | 946 | * The friend address checksum failed. |
862 | */ | 947 | */ |
863 | TOX_ERR_FRIEND_ADD_BAD_CHECKSUM, | 948 | TOX_ERR_FRIEND_ADD_BAD_CHECKSUM, |
949 | |||
864 | /** | 950 | /** |
865 | * The friend was already there, but the nospam value was different. | 951 | * The friend was already there, but the nospam value was different. |
866 | */ | 952 | */ |
867 | TOX_ERR_FRIEND_ADD_SET_NEW_NOSPAM, | 953 | TOX_ERR_FRIEND_ADD_SET_NEW_NOSPAM, |
954 | |||
868 | /** | 955 | /** |
869 | * A memory allocation failed when trying to increase the friend list size. | 956 | * A memory allocation failed when trying to increase the friend list size. |
870 | */ | 957 | */ |
871 | TOX_ERR_FRIEND_ADD_MALLOC | 958 | TOX_ERR_FRIEND_ADD_MALLOC, |
959 | |||
872 | } TOX_ERR_FRIEND_ADD; | 960 | } TOX_ERR_FRIEND_ADD; |
873 | 961 | ||
962 | |||
874 | /** | 963 | /** |
875 | * Add a friend to the friend list and send a friend request. | 964 | * Add a friend to the friend list and send a friend request. |
876 | * | 965 | * |
@@ -897,7 +986,6 @@ typedef enum TOX_ERR_FRIEND_ADD { | |||
897 | uint32_t tox_friend_add(Tox *tox, const uint8_t *address, const uint8_t *message, size_t length, | 986 | uint32_t tox_friend_add(Tox *tox, const uint8_t *address, const uint8_t *message, size_t length, |
898 | TOX_ERR_FRIEND_ADD *error); | 987 | TOX_ERR_FRIEND_ADD *error); |
899 | 988 | ||
900 | |||
901 | /** | 989 | /** |
902 | * Add a friend without sending a friend request. | 990 | * Add a friend without sending a friend request. |
903 | * | 991 | * |
@@ -918,28 +1006,31 @@ uint32_t tox_friend_add(Tox *tox, const uint8_t *address, const uint8_t *message | |||
918 | */ | 1006 | */ |
919 | uint32_t tox_friend_add_norequest(Tox *tox, const uint8_t *public_key, TOX_ERR_FRIEND_ADD *error); | 1007 | uint32_t tox_friend_add_norequest(Tox *tox, const uint8_t *public_key, TOX_ERR_FRIEND_ADD *error); |
920 | 1008 | ||
921 | |||
922 | typedef enum TOX_ERR_FRIEND_DELETE { | 1009 | typedef enum TOX_ERR_FRIEND_DELETE { |
1010 | |||
1011 | /** | ||
1012 | * The function returned successfully. | ||
1013 | */ | ||
923 | TOX_ERR_FRIEND_DELETE_OK, | 1014 | TOX_ERR_FRIEND_DELETE_OK, |
1015 | |||
924 | /** | 1016 | /** |
925 | * There was no friend with the given friend number. No friends were deleted. | 1017 | * There was no friend with the given friend number. No friends were deleted. |
926 | */ | 1018 | */ |
927 | TOX_ERR_FRIEND_DELETE_FRIEND_NOT_FOUND | 1019 | TOX_ERR_FRIEND_DELETE_FRIEND_NOT_FOUND, |
1020 | |||
928 | } TOX_ERR_FRIEND_DELETE; | 1021 | } TOX_ERR_FRIEND_DELETE; |
929 | 1022 | ||
1023 | |||
930 | /** | 1024 | /** |
931 | * Remove a friend from the friend list. | 1025 | * Remove a friend from the friend list. |
932 | * Other friend numbers are unchanged. | ||
933 | * The friend_number can be reused by toxcore as a friend number for a new friend. | ||
934 | * | 1026 | * |
935 | * This does not notify the friend of their deletion. After calling this | 1027 | * This does not notify the friend of their deletion. After calling this |
936 | * function, this client will appear offline to the friend and no communication | 1028 | * function, this client will appear offline to the friend and no communication |
937 | * can occur between the two. | 1029 | * can occur between the two. |
938 | * | 1030 | * |
939 | * @friend_number Friend number for the friend to be deleted. | 1031 | * @param friend_number Friend number for the friend to be deleted. |
940 | * | 1032 | * |
941 | * @return true on success. | 1033 | * @return true on success. |
942 | * @see tox_friend_add for detailed description of friend numbers. | ||
943 | */ | 1034 | */ |
944 | bool tox_friend_delete(Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_DELETE *error); | 1035 | bool tox_friend_delete(Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_DELETE *error); |
945 | 1036 | ||
@@ -951,15 +1042,27 @@ bool tox_friend_delete(Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_DELETE * | |||
951 | ******************************************************************************/ | 1042 | ******************************************************************************/ |
952 | 1043 | ||
953 | 1044 | ||
1045 | |||
954 | typedef enum TOX_ERR_FRIEND_BY_PUBLIC_KEY { | 1046 | typedef enum TOX_ERR_FRIEND_BY_PUBLIC_KEY { |
1047 | |||
1048 | /** | ||
1049 | * The function returned successfully. | ||
1050 | */ | ||
955 | TOX_ERR_FRIEND_BY_PUBLIC_KEY_OK, | 1051 | TOX_ERR_FRIEND_BY_PUBLIC_KEY_OK, |
1052 | |||
1053 | /** | ||
1054 | * One of the arguments to the function was NULL when it was not expected. | ||
1055 | */ | ||
956 | TOX_ERR_FRIEND_BY_PUBLIC_KEY_NULL, | 1056 | TOX_ERR_FRIEND_BY_PUBLIC_KEY_NULL, |
1057 | |||
957 | /** | 1058 | /** |
958 | * No friend with the given Public Key exists on the friend list. | 1059 | * No friend with the given Public Key exists on the friend list. |
959 | */ | 1060 | */ |
960 | TOX_ERR_FRIEND_BY_PUBLIC_KEY_NOT_FOUND | 1061 | TOX_ERR_FRIEND_BY_PUBLIC_KEY_NOT_FOUND, |
1062 | |||
961 | } TOX_ERR_FRIEND_BY_PUBLIC_KEY; | 1063 | } TOX_ERR_FRIEND_BY_PUBLIC_KEY; |
962 | 1064 | ||
1065 | |||
963 | /** | 1066 | /** |
964 | * Return the friend number associated with that Public Key. | 1067 | * Return the friend number associated with that Public Key. |
965 | * | 1068 | * |
@@ -968,15 +1071,45 @@ typedef enum TOX_ERR_FRIEND_BY_PUBLIC_KEY { | |||
968 | */ | 1071 | */ |
969 | uint32_t tox_friend_by_public_key(const Tox *tox, const uint8_t *public_key, TOX_ERR_FRIEND_BY_PUBLIC_KEY *error); | 1072 | uint32_t tox_friend_by_public_key(const Tox *tox, const uint8_t *public_key, TOX_ERR_FRIEND_BY_PUBLIC_KEY *error); |
970 | 1073 | ||
1074 | /** | ||
1075 | * Checks if a friend with the given friend number exists and returns true if | ||
1076 | * it does. | ||
1077 | */ | ||
1078 | bool tox_friend_exists(const Tox *tox, uint32_t friend_number); | ||
1079 | |||
1080 | /** | ||
1081 | * Return the number of friends on the friend list. | ||
1082 | * | ||
1083 | * This function can be used to determine how much memory to allocate for | ||
1084 | * tox_self_get_friend_list. | ||
1085 | */ | ||
1086 | size_t tox_self_get_friend_list_size(const Tox *tox); | ||
1087 | |||
1088 | /** | ||
1089 | * Copy a list of valid friend numbers into an array. | ||
1090 | * | ||
1091 | * Call tox_self_get_friend_list_size to determine the number of elements to allocate. | ||
1092 | * | ||
1093 | * @param list A memory region with enough space to hold the friend list. If | ||
1094 | * this parameter is NULL, this function has no effect. | ||
1095 | */ | ||
1096 | void tox_self_get_friend_list(const Tox *tox, uint32_t *friend_list); | ||
971 | 1097 | ||
972 | typedef enum TOX_ERR_FRIEND_GET_PUBLIC_KEY { | 1098 | typedef enum TOX_ERR_FRIEND_GET_PUBLIC_KEY { |
1099 | |||
1100 | /** | ||
1101 | * The function returned successfully. | ||
1102 | */ | ||
973 | TOX_ERR_FRIEND_GET_PUBLIC_KEY_OK, | 1103 | TOX_ERR_FRIEND_GET_PUBLIC_KEY_OK, |
1104 | |||
974 | /** | 1105 | /** |
975 | * No friend with the given number exists on the friend list. | 1106 | * No friend with the given number exists on the friend list. |
976 | */ | 1107 | */ |
977 | TOX_ERR_FRIEND_GET_PUBLIC_KEY_FRIEND_NOT_FOUND | 1108 | TOX_ERR_FRIEND_GET_PUBLIC_KEY_FRIEND_NOT_FOUND, |
1109 | |||
978 | } TOX_ERR_FRIEND_GET_PUBLIC_KEY; | 1110 | } TOX_ERR_FRIEND_GET_PUBLIC_KEY; |
979 | 1111 | ||
1112 | |||
980 | /** | 1113 | /** |
981 | * Copies the Public Key associated with a given friend number to a byte array. | 1114 | * Copies the Public Key associated with a given friend number to a byte array. |
982 | * | 1115 | * |
@@ -989,21 +1122,21 @@ typedef enum TOX_ERR_FRIEND_GET_PUBLIC_KEY { | |||
989 | bool tox_friend_get_public_key(const Tox *tox, uint32_t friend_number, uint8_t *public_key, | 1122 | bool tox_friend_get_public_key(const Tox *tox, uint32_t friend_number, uint8_t *public_key, |
990 | TOX_ERR_FRIEND_GET_PUBLIC_KEY *error); | 1123 | TOX_ERR_FRIEND_GET_PUBLIC_KEY *error); |
991 | 1124 | ||
992 | |||
993 | /** | ||
994 | * Checks if a friend with the given friend number exists and returns true if | ||
995 | * it does. | ||
996 | */ | ||
997 | bool tox_friend_exists(const Tox *tox, uint32_t friend_number); | ||
998 | |||
999 | typedef enum TOX_ERR_FRIEND_GET_LAST_ONLINE { | 1125 | typedef enum TOX_ERR_FRIEND_GET_LAST_ONLINE { |
1126 | |||
1127 | /** | ||
1128 | * The function returned successfully. | ||
1129 | */ | ||
1000 | TOX_ERR_FRIEND_GET_LAST_ONLINE_OK, | 1130 | TOX_ERR_FRIEND_GET_LAST_ONLINE_OK, |
1131 | |||
1001 | /** | 1132 | /** |
1002 | * No friend with the given number exists on the friend list. | 1133 | * No friend with the given number exists on the friend list. |
1003 | */ | 1134 | */ |
1004 | TOX_ERR_FRIEND_GET_LAST_ONLINE_FRIEND_NOT_FOUND, | 1135 | TOX_ERR_FRIEND_GET_LAST_ONLINE_FRIEND_NOT_FOUND, |
1136 | |||
1005 | } TOX_ERR_FRIEND_GET_LAST_ONLINE; | 1137 | } TOX_ERR_FRIEND_GET_LAST_ONLINE; |
1006 | 1138 | ||
1139 | |||
1007 | /** | 1140 | /** |
1008 | * Return a unix-time timestamp of the last time the friend associated with a given | 1141 | * Return a unix-time timestamp of the last time the friend associated with a given |
1009 | * friend number was seen online. This function will return UINT64_MAX on error. | 1142 | * friend number was seen online. This function will return UINT64_MAX on error. |
@@ -1012,26 +1145,6 @@ typedef enum TOX_ERR_FRIEND_GET_LAST_ONLINE { | |||
1012 | */ | 1145 | */ |
1013 | uint64_t tox_friend_get_last_online(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_GET_LAST_ONLINE *error); | 1146 | uint64_t tox_friend_get_last_online(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_GET_LAST_ONLINE *error); |
1014 | 1147 | ||
1015 | /** | ||
1016 | * Return the number of friends on the friend list. | ||
1017 | * | ||
1018 | * This function can be used to determine how much memory to allocate for | ||
1019 | * tox_self_get_friend_list. | ||
1020 | */ | ||
1021 | size_t tox_self_get_friend_list_size(const Tox *tox); | ||
1022 | |||
1023 | |||
1024 | /** | ||
1025 | * Copy a list of valid friend numbers into an array. | ||
1026 | * | ||
1027 | * Call tox_self_get_friend_list_size to determine the number of elements to allocate. | ||
1028 | * | ||
1029 | * @param list A memory region with enough space to hold the friend list. If | ||
1030 | * this parameter is NULL, this function has no effect. | ||
1031 | */ | ||
1032 | void tox_self_get_friend_list(const Tox *tox, uint32_t *list); | ||
1033 | |||
1034 | |||
1035 | 1148 | ||
1036 | /******************************************************************************* | 1149 | /******************************************************************************* |
1037 | * | 1150 | * |
@@ -1040,27 +1153,35 @@ void tox_self_get_friend_list(const Tox *tox, uint32_t *list); | |||
1040 | ******************************************************************************/ | 1153 | ******************************************************************************/ |
1041 | 1154 | ||
1042 | 1155 | ||
1156 | |||
1043 | /** | 1157 | /** |
1044 | * Common error codes for friend state query functions. | 1158 | * Common error codes for friend state query functions. |
1045 | */ | 1159 | */ |
1046 | typedef enum TOX_ERR_FRIEND_QUERY { | 1160 | typedef enum TOX_ERR_FRIEND_QUERY { |
1161 | |||
1162 | /** | ||
1163 | * The function returned successfully. | ||
1164 | */ | ||
1047 | TOX_ERR_FRIEND_QUERY_OK, | 1165 | TOX_ERR_FRIEND_QUERY_OK, |
1166 | |||
1048 | /** | 1167 | /** |
1049 | * The pointer parameter for storing the query result (name, message) was | 1168 | * The pointer parameter for storing the query result (name, message) was |
1050 | * NULL. Unlike the `_self_` variants of these functions, which have no effect | 1169 | * NULL. Unlike the `_self_` variants of these functions, which have no effect |
1051 | * when a parameter is NULL, these functions return an error in that case. | 1170 | * when a parameter is NULL, these functions return an error in that case. |
1052 | */ | 1171 | */ |
1053 | TOX_ERR_FRIEND_QUERY_NULL, | 1172 | TOX_ERR_FRIEND_QUERY_NULL, |
1173 | |||
1054 | /** | 1174 | /** |
1055 | * The friend_number did not designate a valid friend. | 1175 | * The friend_number did not designate a valid friend. |
1056 | */ | 1176 | */ |
1057 | TOX_ERR_FRIEND_QUERY_FRIEND_NOT_FOUND | 1177 | TOX_ERR_FRIEND_QUERY_FRIEND_NOT_FOUND, |
1178 | |||
1058 | } TOX_ERR_FRIEND_QUERY; | 1179 | } TOX_ERR_FRIEND_QUERY; |
1059 | 1180 | ||
1060 | 1181 | ||
1061 | /** | 1182 | /** |
1062 | * Return the length of the friend's name. If the friend number is invalid, the | 1183 | * Return the length of the friend's name. If the friend number is invalid, the |
1063 | * return value is SIZE_MAX. | 1184 | * return value is unspecified. |
1064 | * | 1185 | * |
1065 | * The return value is equal to the `length` argument received by the last | 1186 | * The return value is equal to the `length` argument received by the last |
1066 | * `friend_name` callback. | 1187 | * `friend_name` callback. |
@@ -1084,8 +1205,6 @@ size_t tox_friend_get_name_size(const Tox *tox, uint32_t friend_number, TOX_ERR_ | |||
1084 | bool tox_friend_get_name(const Tox *tox, uint32_t friend_number, uint8_t *name, TOX_ERR_FRIEND_QUERY *error); | 1205 | bool tox_friend_get_name(const Tox *tox, uint32_t friend_number, uint8_t *name, TOX_ERR_FRIEND_QUERY *error); |
1085 | 1206 | ||
1086 | /** | 1207 | /** |
1087 | * The function type for the `friend_name` callback. | ||
1088 | * | ||
1089 | * @param friend_number The friend number of the friend whose name changed. | 1208 | * @param friend_number The friend number of the friend whose name changed. |
1090 | * @param name A byte array containing the same data as | 1209 | * @param name A byte array containing the same data as |
1091 | * tox_friend_get_name would write to its `name` parameter. | 1210 | * tox_friend_get_name would write to its `name` parameter. |
@@ -1094,13 +1213,13 @@ bool tox_friend_get_name(const Tox *tox, uint32_t friend_number, uint8_t *name, | |||
1094 | */ | 1213 | */ |
1095 | typedef void tox_friend_name_cb(Tox *tox, uint32_t friend_number, const uint8_t *name, size_t length, void *user_data); | 1214 | typedef void tox_friend_name_cb(Tox *tox, uint32_t friend_number, const uint8_t *name, size_t length, void *user_data); |
1096 | 1215 | ||
1216 | |||
1097 | /** | 1217 | /** |
1098 | * Set the callback for the `friend_name` event. Pass NULL to unset. | 1218 | * Set the callback for the `friend_name` event. Pass NULL to unset. |
1099 | * | 1219 | * |
1100 | * This event is triggered when a friend changes their name. | 1220 | * This event is triggered when a friend changes their name. |
1101 | */ | 1221 | */ |
1102 | void tox_callback_friend_name(Tox *tox, tox_friend_name_cb *function, void *user_data); | 1222 | void tox_callback_friend_name(Tox *tox, tox_friend_name_cb *callback, void *user_data); |
1103 | |||
1104 | 1223 | ||
1105 | /** | 1224 | /** |
1106 | * Return the length of the friend's status message. If the friend number is | 1225 | * Return the length of the friend's status message. If the friend number is |
@@ -1112,37 +1231,35 @@ size_t tox_friend_get_status_message_size(const Tox *tox, uint32_t friend_number | |||
1112 | * Write the name of the friend designated by the given friend number to a byte | 1231 | * Write the name of the friend designated by the given friend number to a byte |
1113 | * array. | 1232 | * array. |
1114 | * | 1233 | * |
1115 | * Call tox_friend_get_name_size to determine the allocation size for the `name` | 1234 | * Call tox_friend_get_status_message_size to determine the allocation size for the `status_name` |
1116 | * parameter. | 1235 | * parameter. |
1117 | * | 1236 | * |
1118 | * The data written to `message` is equal to the data received by the last | 1237 | * The data written to `status_message` is equal to the data received by the last |
1119 | * `friend_status_message` callback. | 1238 | * `friend_status_message` callback. |
1120 | * | 1239 | * |
1121 | * @param name A valid memory region large enough to store the friend's name. | 1240 | * @param name A valid memory region large enough to store the friend's name. |
1122 | */ | 1241 | */ |
1123 | bool tox_friend_get_status_message(const Tox *tox, uint32_t friend_number, uint8_t *message, | 1242 | bool tox_friend_get_status_message(const Tox *tox, uint32_t friend_number, uint8_t *status_message, |
1124 | TOX_ERR_FRIEND_QUERY *error); | 1243 | TOX_ERR_FRIEND_QUERY *error); |
1125 | 1244 | ||
1126 | /** | 1245 | /** |
1127 | * The function type for the `friend_status_message` callback. | ||
1128 | * | ||
1129 | * @param friend_number The friend number of the friend whose status message | 1246 | * @param friend_number The friend number of the friend whose status message |
1130 | * changed. | 1247 | * changed. |
1131 | * @param message A byte array containing the same data as | 1248 | * @param message A byte array containing the same data as |
1132 | * tox_friend_get_status_message would write to its `message` parameter. | 1249 | * tox_friend_get_status_message would write to its `status_message` parameter. |
1133 | * @param length A value equal to the return value of | 1250 | * @param length A value equal to the return value of |
1134 | * tox_friend_get_status_message_size. | 1251 | * tox_friend_get_status_message_size. |
1135 | */ | 1252 | */ |
1136 | typedef void tox_friend_status_message_cb(Tox *tox, uint32_t friend_number, const uint8_t *message, size_t length, | 1253 | typedef void tox_friend_status_message_cb(Tox *tox, uint32_t friend_number, const uint8_t *message, size_t length, |
1137 | void *user_data); | 1254 | void *user_data); |
1255 | |||
1138 | 1256 | ||
1139 | /** | 1257 | /** |
1140 | * Set the callback for the `friend_status_message` event. Pass NULL to unset. | 1258 | * Set the callback for the `friend_status_message` event. Pass NULL to unset. |
1141 | * | 1259 | * |
1142 | * This event is triggered when a friend changes their status message. | 1260 | * This event is triggered when a friend changes their status message. |
1143 | */ | 1261 | */ |
1144 | void tox_callback_friend_status_message(Tox *tox, tox_friend_status_message_cb *function, void *user_data); | 1262 | void tox_callback_friend_status_message(Tox *tox, tox_friend_status_message_cb *callback, void *user_data); |
1145 | |||
1146 | 1263 | ||
1147 | /** | 1264 | /** |
1148 | * Return the friend's user status (away/busy/...). If the friend number is | 1265 | * Return the friend's user status (away/busy/...). If the friend number is |
@@ -1154,21 +1271,19 @@ void tox_callback_friend_status_message(Tox *tox, tox_friend_status_message_cb * | |||
1154 | TOX_USER_STATUS tox_friend_get_status(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); | 1271 | TOX_USER_STATUS tox_friend_get_status(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); |
1155 | 1272 | ||
1156 | /** | 1273 | /** |
1157 | * The function type for the `friend_status` callback. | ||
1158 | * | ||
1159 | * @param friend_number The friend number of the friend whose user status | 1274 | * @param friend_number The friend number of the friend whose user status |
1160 | * changed. | 1275 | * changed. |
1161 | * @param status The new user status. | 1276 | * @param status The new user status. |
1162 | */ | 1277 | */ |
1163 | typedef void tox_friend_status_cb(Tox *tox, uint32_t friend_number, TOX_USER_STATUS status, void *user_data); | 1278 | typedef void tox_friend_status_cb(Tox *tox, uint32_t friend_number, TOX_USER_STATUS status, void *user_data); |
1164 | 1279 | ||
1280 | |||
1165 | /** | 1281 | /** |
1166 | * Set the callback for the `friend_status` event. Pass NULL to unset. | 1282 | * Set the callback for the `friend_status` event. Pass NULL to unset. |
1167 | * | 1283 | * |
1168 | * This event is triggered when a friend changes their user status. | 1284 | * This event is triggered when a friend changes their user status. |
1169 | */ | 1285 | */ |
1170 | void tox_callback_friend_status(Tox *tox, tox_friend_status_cb *function, void *user_data); | 1286 | void tox_callback_friend_status(Tox *tox, tox_friend_status_cb *callback, void *user_data); |
1171 | |||
1172 | 1287 | ||
1173 | /** | 1288 | /** |
1174 | * Check whether a friend is currently connected to this client. | 1289 | * Check whether a friend is currently connected to this client. |
@@ -1185,28 +1300,25 @@ void tox_callback_friend_status(Tox *tox, tox_friend_status_cb *function, void * | |||
1185 | TOX_CONNECTION tox_friend_get_connection_status(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); | 1300 | TOX_CONNECTION tox_friend_get_connection_status(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); |
1186 | 1301 | ||
1187 | /** | 1302 | /** |
1188 | * The function type for the `friend_connection_status` callback. | ||
1189 | * | ||
1190 | * @param friend_number The friend number of the friend whose connection status | 1303 | * @param friend_number The friend number of the friend whose connection status |
1191 | * changed. | 1304 | * changed. |
1192 | * @param connection_status The result of calling | 1305 | * @param connection_status The result of calling |
1193 | * tox_friend_get_connection_status on the passed friend_number. | 1306 | * tox_friend_get_connection_status on the passed friend_number. |
1194 | */ | 1307 | */ |
1195 | typedef void tox_friend_connection_status_cb(Tox *tox, uint32_t friend_number, TOX_CONNECTION connection_status, | 1308 | typedef void tox_friend_connection_status_cb(Tox *tox, uint32_t friend_number, TOX_CONNECTION connection_status, |
1196 | void *user_data); | 1309 | void *user_data); |
1310 | |||
1197 | 1311 | ||
1198 | /** | 1312 | /** |
1199 | * Set the callback for the `friend_connection_status` event. Pass NULL to | 1313 | * Set the callback for the `friend_connection_status` event. Pass NULL to unset. |
1200 | * unset. | ||
1201 | * | 1314 | * |
1202 | * This event is triggered when a friend goes offline after having been online, | 1315 | * This event is triggered when a friend goes offline after having been online, |
1203 | * or when a friend goes online. | 1316 | * or when a friend goes online. |
1204 | * | 1317 | * |
1205 | * This callback is not called when adding friends. It is assumed that when | 1318 | * This callback is not called when adding friends. It is assumed that when |
1206 | * adding friends, their connection status is offline. | 1319 | * adding friends, their connection status is initially offline. |
1207 | */ | 1320 | */ |
1208 | void tox_callback_friend_connection_status(Tox *tox, tox_friend_connection_status_cb *function, void *user_data); | 1321 | void tox_callback_friend_connection_status(Tox *tox, tox_friend_connection_status_cb *callback, void *user_data); |
1209 | |||
1210 | 1322 | ||
1211 | /** | 1323 | /** |
1212 | * Check whether a friend is currently typing a message. | 1324 | * Check whether a friend is currently typing a message. |
@@ -1220,8 +1332,6 @@ void tox_callback_friend_connection_status(Tox *tox, tox_friend_connection_statu | |||
1220 | bool tox_friend_get_typing(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); | 1332 | bool tox_friend_get_typing(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); |
1221 | 1333 | ||
1222 | /** | 1334 | /** |
1223 | * The function type for the `friend_typing` callback. | ||
1224 | * | ||
1225 | * @param friend_number The friend number of the friend who started or stopped | 1335 | * @param friend_number The friend number of the friend who started or stopped |
1226 | * typing. | 1336 | * typing. |
1227 | * @param is_typing The result of calling tox_friend_get_typing on the passed | 1337 | * @param is_typing The result of calling tox_friend_get_typing on the passed |
@@ -1229,12 +1339,13 @@ bool tox_friend_get_typing(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEN | |||
1229 | */ | 1339 | */ |
1230 | typedef void tox_friend_typing_cb(Tox *tox, uint32_t friend_number, bool is_typing, void *user_data); | 1340 | typedef void tox_friend_typing_cb(Tox *tox, uint32_t friend_number, bool is_typing, void *user_data); |
1231 | 1341 | ||
1342 | |||
1232 | /** | 1343 | /** |
1233 | * Set the callback for the `friend_typing` event. Pass NULL to unset. | 1344 | * Set the callback for the `friend_typing` event. Pass NULL to unset. |
1234 | * | 1345 | * |
1235 | * This event is triggered when a friend starts or stops typing. | 1346 | * This event is triggered when a friend starts or stops typing. |
1236 | */ | 1347 | */ |
1237 | void tox_callback_friend_typing(Tox *tox, tox_friend_typing_cb *function, void *user_data); | 1348 | void tox_callback_friend_typing(Tox *tox, tox_friend_typing_cb *callback, void *user_data); |
1238 | 1349 | ||
1239 | 1350 | ||
1240 | /******************************************************************************* | 1351 | /******************************************************************************* |
@@ -1244,90 +1355,115 @@ void tox_callback_friend_typing(Tox *tox, tox_friend_typing_cb *function, void * | |||
1244 | ******************************************************************************/ | 1355 | ******************************************************************************/ |
1245 | 1356 | ||
1246 | 1357 | ||
1358 | |||
1247 | typedef enum TOX_ERR_SET_TYPING { | 1359 | typedef enum TOX_ERR_SET_TYPING { |
1360 | |||
1361 | /** | ||
1362 | * The function returned successfully. | ||
1363 | */ | ||
1248 | TOX_ERR_SET_TYPING_OK, | 1364 | TOX_ERR_SET_TYPING_OK, |
1365 | |||
1249 | /** | 1366 | /** |
1250 | * The friend number did not designate a valid friend. | 1367 | * The friend number did not designate a valid friend. |
1251 | */ | 1368 | */ |
1252 | TOX_ERR_SET_TYPING_FRIEND_NOT_FOUND | 1369 | TOX_ERR_SET_TYPING_FRIEND_NOT_FOUND, |
1370 | |||
1253 | } TOX_ERR_SET_TYPING; | 1371 | } TOX_ERR_SET_TYPING; |
1254 | 1372 | ||
1373 | |||
1255 | /** | 1374 | /** |
1256 | * Set the client's typing status for a friend. | 1375 | * Set the client's typing status for a friend. |
1257 | * | 1376 | * |
1258 | * The client is responsible for turning it on or off. | 1377 | * The client is responsible for turning it on or off. |
1259 | * | 1378 | * |
1260 | * @param friend_number The friend to which the client is typing a message. | 1379 | * @param friend_number The friend to which the client is typing a message. |
1261 | * @param is_typing The typing status. True means the client is typing. | 1380 | * @param typing The typing status. True means the client is typing. |
1262 | * | 1381 | * |
1263 | * @return true on success. | 1382 | * @return true on success. |
1264 | */ | 1383 | */ |
1265 | bool tox_self_set_typing(Tox *tox, uint32_t friend_number, bool is_typing, TOX_ERR_SET_TYPING *error); | 1384 | bool tox_self_set_typing(Tox *tox, uint32_t friend_number, bool typing, TOX_ERR_SET_TYPING *error); |
1266 | |||
1267 | 1385 | ||
1268 | typedef enum TOX_ERR_FRIEND_SEND_MESSAGE { | 1386 | typedef enum TOX_ERR_FRIEND_SEND_MESSAGE { |
1387 | |||
1388 | /** | ||
1389 | * The function returned successfully. | ||
1390 | */ | ||
1269 | TOX_ERR_FRIEND_SEND_MESSAGE_OK, | 1391 | TOX_ERR_FRIEND_SEND_MESSAGE_OK, |
1392 | |||
1393 | /** | ||
1394 | * One of the arguments to the function was NULL when it was not expected. | ||
1395 | */ | ||
1270 | TOX_ERR_FRIEND_SEND_MESSAGE_NULL, | 1396 | TOX_ERR_FRIEND_SEND_MESSAGE_NULL, |
1397 | |||
1271 | /** | 1398 | /** |
1272 | * The friend number did not designate a valid friend. | 1399 | * The friend number did not designate a valid friend. |
1273 | */ | 1400 | */ |
1274 | TOX_ERR_FRIEND_SEND_MESSAGE_FRIEND_NOT_FOUND, | 1401 | TOX_ERR_FRIEND_SEND_MESSAGE_FRIEND_NOT_FOUND, |
1402 | |||
1275 | /** | 1403 | /** |
1276 | * This client is currently not connected to the friend. | 1404 | * This client is currently not connected to the friend. |
1277 | */ | 1405 | */ |
1278 | TOX_ERR_FRIEND_SEND_MESSAGE_FRIEND_NOT_CONNECTED, | 1406 | TOX_ERR_FRIEND_SEND_MESSAGE_FRIEND_NOT_CONNECTED, |
1407 | |||
1279 | /** | 1408 | /** |
1280 | * An allocation error occurred while increasing the send queue size. | 1409 | * An allocation error occurred while increasing the send queue size. |
1281 | */ | 1410 | */ |
1282 | TOX_ERR_FRIEND_SEND_MESSAGE_SENDQ, | 1411 | TOX_ERR_FRIEND_SEND_MESSAGE_SENDQ, |
1412 | |||
1283 | /** | 1413 | /** |
1284 | * Message length exceeded TOX_MAX_MESSAGE_LENGTH. | 1414 | * Message length exceeded TOX_MAX_MESSAGE_LENGTH. |
1285 | */ | 1415 | */ |
1286 | TOX_ERR_FRIEND_SEND_MESSAGE_TOO_LONG, | 1416 | TOX_ERR_FRIEND_SEND_MESSAGE_TOO_LONG, |
1417 | |||
1287 | /** | 1418 | /** |
1288 | * Attempted to send a zero-length message. | 1419 | * Attempted to send a zero-length message. |
1289 | */ | 1420 | */ |
1290 | TOX_ERR_FRIEND_SEND_MESSAGE_EMPTY | 1421 | TOX_ERR_FRIEND_SEND_MESSAGE_EMPTY, |
1422 | |||
1291 | } TOX_ERR_FRIEND_SEND_MESSAGE; | 1423 | } TOX_ERR_FRIEND_SEND_MESSAGE; |
1292 | 1424 | ||
1425 | |||
1293 | /** | 1426 | /** |
1294 | * Send a text chat message to an online friend. | 1427 | * Send a text chat message to an online friend. |
1295 | * | 1428 | * |
1296 | * This function creates a chat message packet and pushes it into the send | 1429 | * This function creates a chat message packet and pushes it into the send |
1297 | * queue. | 1430 | * queue. |
1298 | * | 1431 | * |
1299 | * Type corresponds to the message type, for a list of valid types see TOX_MESSAGE_TYPE. | ||
1300 | * | ||
1301 | * The message length may not exceed TOX_MAX_MESSAGE_LENGTH. Larger messages | 1432 | * The message length may not exceed TOX_MAX_MESSAGE_LENGTH. Larger messages |
1302 | * must be split by the client and sent as separate messages. Other clients can | 1433 | * must be split by the client and sent as separate messages. Other clients can |
1303 | * then reassemble the fragments. Messages may not be empty. | 1434 | * then reassemble the fragments. Messages may not be empty. |
1304 | * | 1435 | * |
1305 | * The return value of this function is the message ID. If a read receipt is | 1436 | * The return value of this function is the message ID. If a read receipt is |
1306 | * received, the triggered `read_receipt` event will be passed this message ID. | 1437 | * received, the triggered `friend_read_receipt` event will be passed this message ID. |
1307 | * | 1438 | * |
1308 | * Message IDs are unique per friend. The first message ID is 0. Message IDs are | 1439 | * Message IDs are unique per friend. The first message ID is 0. Message IDs are |
1309 | * incremented by 1 each time a message is sent. If UINT32_MAX messages were | 1440 | * incremented by 1 each time a message is sent. If UINT32_MAX messages were |
1310 | * sent, the next message ID is 0. | 1441 | * sent, the next message ID is 0. |
1442 | * | ||
1443 | * @param type Message type (normal, action, ...). | ||
1444 | * @param friend_number The friend number of the friend to send the message to. | ||
1445 | * @param message A non-NULL pointer to the first element of a byte array | ||
1446 | * containing the message text. | ||
1447 | * @param length Length of the message to be sent. | ||
1311 | */ | 1448 | */ |
1312 | uint32_t tox_friend_send_message(Tox *tox, uint32_t friend_number, TOX_MESSAGE_TYPE type, const uint8_t *message, | 1449 | uint32_t tox_friend_send_message(Tox *tox, uint32_t friend_number, TOX_MESSAGE_TYPE type, const uint8_t *message, |
1313 | size_t length, TOX_ERR_FRIEND_SEND_MESSAGE *error); | 1450 | size_t length, TOX_ERR_FRIEND_SEND_MESSAGE *error); |
1314 | 1451 | ||
1315 | /** | 1452 | /** |
1316 | * The function type for the `read_receipt` callback. | ||
1317 | * | ||
1318 | * @param friend_number The friend number of the friend who received the message. | 1453 | * @param friend_number The friend number of the friend who received the message. |
1319 | * @param message_id The message ID as returned from tox_friend_send_message | 1454 | * @param message_id The message ID as returned from tox_friend_send_message |
1320 | * corresponding to the message sent. | 1455 | * corresponding to the message sent. |
1321 | */ | 1456 | */ |
1322 | typedef void tox_friend_read_receipt_cb(Tox *tox, uint32_t friend_number, uint32_t message_id, void *user_data); | 1457 | typedef void tox_friend_read_receipt_cb(Tox *tox, uint32_t friend_number, uint32_t message_id, void *user_data); |
1323 | 1458 | ||
1459 | |||
1324 | /** | 1460 | /** |
1325 | * Set the callback for the `read_receipt` event. Pass NULL to unset. | 1461 | * Set the callback for the `friend_read_receipt` event. Pass NULL to unset. |
1326 | * | 1462 | * |
1327 | * This event is triggered when the friend receives the message sent with | 1463 | * This event is triggered when the friend receives the message sent with |
1328 | * tox_friend_send_message with the corresponding message ID. | 1464 | * tox_friend_send_message with the corresponding message ID. |
1329 | */ | 1465 | */ |
1330 | void tox_callback_friend_read_receipt(Tox *tox, tox_friend_read_receipt_cb *function, void *user_data); | 1466 | void tox_callback_friend_read_receipt(Tox *tox, tox_friend_read_receipt_cb *callback, void *user_data); |
1331 | 1467 | ||
1332 | 1468 | ||
1333 | /******************************************************************************* | 1469 | /******************************************************************************* |
@@ -1337,41 +1473,46 @@ void tox_callback_friend_read_receipt(Tox *tox, tox_friend_read_receipt_cb *func | |||
1337 | ******************************************************************************/ | 1473 | ******************************************************************************/ |
1338 | 1474 | ||
1339 | 1475 | ||
1476 | |||
1340 | /** | 1477 | /** |
1341 | * The function type for the `friend_request` callback. | ||
1342 | * | ||
1343 | * @param public_key The Public Key of the user who sent the friend request. | 1478 | * @param public_key The Public Key of the user who sent the friend request. |
1479 | * @param time_delta A delta in seconds between when the message was composed | ||
1480 | * and when it is being transmitted. For messages that are sent immediately, | ||
1481 | * it will be 0. If a message was written and couldn't be sent immediately | ||
1482 | * (due to a connection failure, for example), the time_delta is an | ||
1483 | * approximation of when it was composed. | ||
1344 | * @param message The message they sent along with the request. | 1484 | * @param message The message they sent along with the request. |
1345 | * @param length The size of the message byte array. | 1485 | * @param length The size of the message byte array. |
1346 | */ | 1486 | */ |
1347 | typedef void tox_friend_request_cb(Tox *tox, const uint8_t *public_key, const uint8_t *message, size_t length, | 1487 | typedef void tox_friend_request_cb(Tox *tox, const uint8_t *public_key, const uint8_t *message, size_t length, |
1348 | void *user_data); | 1488 | void *user_data); |
1349 | 1489 | ||
1490 | |||
1350 | /** | 1491 | /** |
1351 | * Set the callback for the `friend_request` event. Pass NULL to unset. | 1492 | * Set the callback for the `friend_request` event. Pass NULL to unset. |
1352 | * | 1493 | * |
1353 | * This event is triggered when a friend request is received. | 1494 | * This event is triggered when a friend request is received. |
1354 | */ | 1495 | */ |
1355 | void tox_callback_friend_request(Tox *tox, tox_friend_request_cb *function, void *user_data); | 1496 | void tox_callback_friend_request(Tox *tox, tox_friend_request_cb *callback, void *user_data); |
1356 | |||
1357 | 1497 | ||
1358 | /** | 1498 | /** |
1359 | * The function type for the `friend_message` callback. | ||
1360 | * | ||
1361 | * @param friend_number The friend number of the friend who sent the message. | 1499 | * @param friend_number The friend number of the friend who sent the message. |
1362 | * @param type The message type, for a list of valid types see TOX_MESSAGE_TYPE. | 1500 | * @param time_delta Time between composition and sending. |
1363 | * @param message The message data they sent. | 1501 | * @param message The message data they sent. |
1364 | * @param length The size of the message byte array. | 1502 | * @param length The size of the message byte array. |
1503 | * | ||
1504 | * @see friend_request for more information on time_delta. | ||
1365 | */ | 1505 | */ |
1366 | typedef void tox_friend_message_cb(Tox *tox, uint32_t friend_number, TOX_MESSAGE_TYPE type, const uint8_t *message, | 1506 | typedef void tox_friend_message_cb(Tox *tox, uint32_t friend_number, TOX_MESSAGE_TYPE type, const uint8_t *message, |
1367 | size_t length, void *user_data); | 1507 | size_t length, void *user_data); |
1368 | 1508 | ||
1509 | |||
1369 | /** | 1510 | /** |
1370 | * Set the callback for the `friend_message` event. Pass NULL to unset. | 1511 | * Set the callback for the `friend_message` event. Pass NULL to unset. |
1371 | * | 1512 | * |
1372 | * This event is triggered when a message from a friend is received. | 1513 | * This event is triggered when a message from a friend is received. |
1373 | */ | 1514 | */ |
1374 | void tox_callback_friend_message(Tox *tox, tox_friend_message_cb *function, void *user_data); | 1515 | void tox_callback_friend_message(Tox *tox, tox_friend_message_cb *callback, void *user_data); |
1375 | 1516 | ||
1376 | 1517 | ||
1377 | /******************************************************************************* | 1518 | /******************************************************************************* |
@@ -1381,12 +1522,36 @@ void tox_callback_friend_message(Tox *tox, tox_friend_message_cb *function, void | |||
1381 | ******************************************************************************/ | 1522 | ******************************************************************************/ |
1382 | 1523 | ||
1383 | 1524 | ||
1525 | |||
1526 | /** | ||
1527 | * Generates a cryptographic hash of the given data. | ||
1528 | * | ||
1529 | * This function may be used by clients for any purpose, but is provided | ||
1530 | * primarily for validating cached avatars. This use is highly recommended to | ||
1531 | * avoid unnecessary avatar updates. | ||
1532 | * | ||
1533 | * If hash is NULL or data is NULL while length is not 0 the function returns false, | ||
1534 | * otherwise it returns true. | ||
1535 | * | ||
1536 | * This function is a wrapper to internal message-digest functions. | ||
1537 | * | ||
1538 | * @param hash A valid memory location the hash data. It must be at least | ||
1539 | * TOX_HASH_LENGTH bytes in size. | ||
1540 | * @param data Data to be hashed or NULL. | ||
1541 | * @param length Size of the data array or 0. | ||
1542 | * | ||
1543 | * @return true if hash was not NULL. | ||
1544 | */ | ||
1545 | bool tox_hash(uint8_t *hash, const uint8_t *data, size_t length); | ||
1546 | |||
1384 | enum TOX_FILE_KIND { | 1547 | enum TOX_FILE_KIND { |
1548 | |||
1385 | /** | 1549 | /** |
1386 | * Arbitrary file data. Clients can choose to handle it based on the file name | 1550 | * Arbitrary file data. Clients can choose to handle it based on the file name |
1387 | * or magic or any other way they choose. | 1551 | * or magic or any other way they choose. |
1388 | */ | 1552 | */ |
1389 | TOX_FILE_KIND_DATA, | 1553 | TOX_FILE_KIND_DATA, |
1554 | |||
1390 | /** | 1555 | /** |
1391 | * Avatar filename. This consists of tox_hash(image). | 1556 | * Avatar filename. This consists of tox_hash(image). |
1392 | * Avatar data. This consists of the image data. | 1557 | * Avatar data. This consists of the image data. |
@@ -1404,41 +1569,22 @@ enum TOX_FILE_KIND { | |||
1404 | * this hash with a saved hash and send TOX_FILE_CONTROL_CANCEL to terminate the avatar | 1569 | * this hash with a saved hash and send TOX_FILE_CONTROL_CANCEL to terminate the avatar |
1405 | * transfer if it matches. | 1570 | * transfer if it matches. |
1406 | * | 1571 | * |
1407 | * When file_size is set to 0 in the transfer request it means that the client has no | 1572 | * When file_size is set to 0 in the transfer request it means that the client |
1408 | * avatar. | 1573 | * has no avatar. |
1409 | */ | 1574 | */ |
1410 | TOX_FILE_KIND_AVATAR | 1575 | TOX_FILE_KIND_AVATAR, |
1411 | }; | ||
1412 | |||
1413 | 1576 | ||
1414 | /** | 1577 | }; |
1415 | * Generates a cryptographic hash of the given data. | ||
1416 | * | ||
1417 | * This function may be used by clients for any purpose, but is provided | ||
1418 | * primarily for validating cached avatars. This use is highly recommended to | ||
1419 | * avoid unnecessary avatar updates. | ||
1420 | * | ||
1421 | * If hash is NULL or data is NULL while length is not 0 the function returns false, | ||
1422 | * otherwise it returns true. | ||
1423 | * | ||
1424 | * This function is a wrapper to internal message-digest functions. | ||
1425 | * | ||
1426 | * @param hash A valid memory location the hash data. It must be at least | ||
1427 | * TOX_HASH_LENGTH bytes in size. | ||
1428 | * @param data Data to be hashed or NULL. | ||
1429 | * @param length Size of the data array or 0. | ||
1430 | * | ||
1431 | * @return true if hash was not NULL. | ||
1432 | */ | ||
1433 | bool tox_hash(uint8_t *hash, const uint8_t *data, size_t length); | ||
1434 | 1578 | ||
1435 | 1579 | ||
1436 | typedef enum TOX_FILE_CONTROL { | 1580 | typedef enum TOX_FILE_CONTROL { |
1581 | |||
1437 | /** | 1582 | /** |
1438 | * Sent by the receiving side to accept a file send request. Also sent after a | 1583 | * Sent by the receiving side to accept a file send request. Also sent after a |
1439 | * TOX_FILE_CONTROL_PAUSE command to continue sending or receiving. | 1584 | * TOX_FILE_CONTROL_PAUSE command to continue sending or receiving. |
1440 | */ | 1585 | */ |
1441 | TOX_FILE_CONTROL_RESUME, | 1586 | TOX_FILE_CONTROL_RESUME, |
1587 | |||
1442 | /** | 1588 | /** |
1443 | * Sent by clients to pause the file transfer. The initial state of a file | 1589 | * Sent by clients to pause the file transfer. The initial state of a file |
1444 | * transfer is always paused on the receiving side and running on the sending | 1590 | * transfer is always paused on the receiving side and running on the sending |
@@ -1446,47 +1592,62 @@ typedef enum TOX_FILE_CONTROL { | |||
1446 | * need to send TOX_FILE_CONTROL_RESUME for the transfer to resume. | 1592 | * need to send TOX_FILE_CONTROL_RESUME for the transfer to resume. |
1447 | */ | 1593 | */ |
1448 | TOX_FILE_CONTROL_PAUSE, | 1594 | TOX_FILE_CONTROL_PAUSE, |
1595 | |||
1449 | /** | 1596 | /** |
1450 | * Sent by the receiving side to reject a file send request before any other | 1597 | * Sent by the receiving side to reject a file send request before any other |
1451 | * commands are sent. Also sent by either side to terminate a file transfer. | 1598 | * commands are sent. Also sent by either side to terminate a file transfer. |
1452 | */ | 1599 | */ |
1453 | TOX_FILE_CONTROL_CANCEL | 1600 | TOX_FILE_CONTROL_CANCEL, |
1601 | |||
1454 | } TOX_FILE_CONTROL; | 1602 | } TOX_FILE_CONTROL; |
1455 | 1603 | ||
1456 | 1604 | ||
1457 | typedef enum TOX_ERR_FILE_CONTROL { | 1605 | typedef enum TOX_ERR_FILE_CONTROL { |
1606 | |||
1607 | /** | ||
1608 | * The function returned successfully. | ||
1609 | */ | ||
1458 | TOX_ERR_FILE_CONTROL_OK, | 1610 | TOX_ERR_FILE_CONTROL_OK, |
1611 | |||
1459 | /** | 1612 | /** |
1460 | * The friend_number passed did not designate a valid friend. | 1613 | * The friend_number passed did not designate a valid friend. |
1461 | */ | 1614 | */ |
1462 | TOX_ERR_FILE_CONTROL_FRIEND_NOT_FOUND, | 1615 | TOX_ERR_FILE_CONTROL_FRIEND_NOT_FOUND, |
1616 | |||
1463 | /** | 1617 | /** |
1464 | * This client is currently not connected to the friend. | 1618 | * This client is currently not connected to the friend. |
1465 | */ | 1619 | */ |
1466 | TOX_ERR_FILE_CONTROL_FRIEND_NOT_CONNECTED, | 1620 | TOX_ERR_FILE_CONTROL_FRIEND_NOT_CONNECTED, |
1621 | |||
1467 | /** | 1622 | /** |
1468 | * No file transfer with the given file number was found for the given friend. | 1623 | * No file transfer with the given file number was found for the given friend. |
1469 | */ | 1624 | */ |
1470 | TOX_ERR_FILE_CONTROL_NOT_FOUND, | 1625 | TOX_ERR_FILE_CONTROL_NOT_FOUND, |
1626 | |||
1471 | /** | 1627 | /** |
1472 | * A RESUME control was sent, but the file transfer is running normally. | 1628 | * A RESUME control was sent, but the file transfer is running normally. |
1473 | */ | 1629 | */ |
1474 | TOX_ERR_FILE_CONTROL_NOT_PAUSED, | 1630 | TOX_ERR_FILE_CONTROL_NOT_PAUSED, |
1631 | |||
1475 | /** | 1632 | /** |
1476 | * A RESUME control was sent, but the file transfer was paused by the other | 1633 | * A RESUME control was sent, but the file transfer was paused by the other |
1477 | * party. Only the party that paused the transfer can resume it. | 1634 | * party. Only the party that paused the transfer can resume it. |
1478 | */ | 1635 | */ |
1479 | TOX_ERR_FILE_CONTROL_DENIED, | 1636 | TOX_ERR_FILE_CONTROL_DENIED, |
1637 | |||
1480 | /** | 1638 | /** |
1481 | * A PAUSE control was sent, but the file transfer was already paused. | 1639 | * A PAUSE control was sent, but the file transfer was already paused. |
1482 | */ | 1640 | */ |
1483 | TOX_ERR_FILE_CONTROL_ALREADY_PAUSED, | 1641 | TOX_ERR_FILE_CONTROL_ALREADY_PAUSED, |
1642 | |||
1484 | /** | 1643 | /** |
1485 | * Packet queue is full. | 1644 | * Packet queue is full. |
1486 | */ | 1645 | */ |
1487 | TOX_ERR_FILE_CONTROL_SENDQ | 1646 | TOX_ERR_FILE_CONTROL_SENDQ, |
1647 | |||
1488 | } TOX_ERR_FILE_CONTROL; | 1648 | } TOX_ERR_FILE_CONTROL; |
1489 | 1649 | ||
1650 | |||
1490 | /** | 1651 | /** |
1491 | * Sends a file control command to a friend for a given file transfer. | 1652 | * Sends a file control command to a friend for a given file transfer. |
1492 | * | 1653 | * |
@@ -1500,10 +1661,7 @@ typedef enum TOX_ERR_FILE_CONTROL { | |||
1500 | bool tox_file_control(Tox *tox, uint32_t friend_number, uint32_t file_number, TOX_FILE_CONTROL control, | 1661 | bool tox_file_control(Tox *tox, uint32_t friend_number, uint32_t file_number, TOX_FILE_CONTROL control, |
1501 | TOX_ERR_FILE_CONTROL *error); | 1662 | TOX_ERR_FILE_CONTROL *error); |
1502 | 1663 | ||
1503 | |||
1504 | /** | 1664 | /** |
1505 | * The function type for the `file_control` callback. | ||
1506 | * | ||
1507 | * When receiving TOX_FILE_CONTROL_CANCEL, the client should release the | 1665 | * When receiving TOX_FILE_CONTROL_CANCEL, the client should release the |
1508 | * resources associated with the file number and consider the transfer failed. | 1666 | * resources associated with the file number and consider the transfer failed. |
1509 | * | 1667 | * |
@@ -1515,43 +1673,55 @@ bool tox_file_control(Tox *tox, uint32_t friend_number, uint32_t file_number, TO | |||
1515 | typedef void tox_file_recv_control_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, TOX_FILE_CONTROL control, | 1673 | typedef void tox_file_recv_control_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, TOX_FILE_CONTROL control, |
1516 | void *user_data); | 1674 | void *user_data); |
1517 | 1675 | ||
1676 | |||
1518 | /** | 1677 | /** |
1519 | * Set the callback for the `file_control` event. Pass NULL to unset. | 1678 | * Set the callback for the `file_recv_control` event. Pass NULL to unset. |
1520 | * | 1679 | * |
1521 | * This event is triggered when a file control command is received from a | 1680 | * This event is triggered when a file control command is received from a |
1522 | * friend. | 1681 | * friend. |
1523 | */ | 1682 | */ |
1524 | void tox_callback_file_recv_control(Tox *tox, tox_file_recv_control_cb *function, void *user_data); | 1683 | void tox_callback_file_recv_control(Tox *tox, tox_file_recv_control_cb *callback, void *user_data); |
1525 | |||
1526 | 1684 | ||
1527 | typedef enum TOX_ERR_FILE_SEEK { | 1685 | typedef enum TOX_ERR_FILE_SEEK { |
1686 | |||
1687 | /** | ||
1688 | * The function returned successfully. | ||
1689 | */ | ||
1528 | TOX_ERR_FILE_SEEK_OK, | 1690 | TOX_ERR_FILE_SEEK_OK, |
1691 | |||
1529 | /** | 1692 | /** |
1530 | * The friend_number passed did not designate a valid friend. | 1693 | * The friend_number passed did not designate a valid friend. |
1531 | */ | 1694 | */ |
1532 | TOX_ERR_FILE_SEEK_FRIEND_NOT_FOUND, | 1695 | TOX_ERR_FILE_SEEK_FRIEND_NOT_FOUND, |
1696 | |||
1533 | /** | 1697 | /** |
1534 | * This client is currently not connected to the friend. | 1698 | * This client is currently not connected to the friend. |
1535 | */ | 1699 | */ |
1536 | TOX_ERR_FILE_SEEK_FRIEND_NOT_CONNECTED, | 1700 | TOX_ERR_FILE_SEEK_FRIEND_NOT_CONNECTED, |
1701 | |||
1537 | /** | 1702 | /** |
1538 | * No file transfer with the given file number was found for the given friend. | 1703 | * No file transfer with the given file number was found for the given friend. |
1539 | */ | 1704 | */ |
1540 | TOX_ERR_FILE_SEEK_NOT_FOUND, | 1705 | TOX_ERR_FILE_SEEK_NOT_FOUND, |
1706 | |||
1541 | /** | 1707 | /** |
1542 | * File was not in a state where it could be seeked. | 1708 | * File was not in a state where it could be seeked. |
1543 | */ | 1709 | */ |
1544 | TOX_ERR_FILE_SEEK_DENIED, | 1710 | TOX_ERR_FILE_SEEK_DENIED, |
1711 | |||
1545 | /** | 1712 | /** |
1546 | * Seek position was invalid | 1713 | * Seek position was invalid |
1547 | */ | 1714 | */ |
1548 | TOX_ERR_FILE_SEEK_INVALID_POSITION, | 1715 | TOX_ERR_FILE_SEEK_INVALID_POSITION, |
1716 | |||
1549 | /** | 1717 | /** |
1550 | * Packet queue is full. | 1718 | * Packet queue is full. |
1551 | */ | 1719 | */ |
1552 | TOX_ERR_FILE_SEEK_SENDQ | 1720 | TOX_ERR_FILE_SEEK_SENDQ, |
1721 | |||
1553 | } TOX_ERR_FILE_SEEK; | 1722 | } TOX_ERR_FILE_SEEK; |
1554 | 1723 | ||
1724 | |||
1555 | /** | 1725 | /** |
1556 | * Sends a file seek control command to a friend for a given file transfer. | 1726 | * Sends a file seek control command to a friend for a given file transfer. |
1557 | * | 1727 | * |
@@ -1563,26 +1733,33 @@ typedef enum TOX_ERR_FILE_SEEK { | |||
1563 | * @param file_number The friend-specific identifier for the file transfer. | 1733 | * @param file_number The friend-specific identifier for the file transfer. |
1564 | * @param position The position that the file should be seeked to. | 1734 | * @param position The position that the file should be seeked to. |
1565 | */ | 1735 | */ |
1566 | bool tox_file_seek(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, | 1736 | bool tox_file_seek(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, TOX_ERR_FILE_SEEK *error); |
1567 | TOX_ERR_FILE_SEEK *error); | ||
1568 | 1737 | ||
1569 | typedef enum TOX_ERR_FILE_GET { | 1738 | typedef enum TOX_ERR_FILE_GET { |
1739 | |||
1740 | /** | ||
1741 | * The function returned successfully. | ||
1742 | */ | ||
1570 | TOX_ERR_FILE_GET_OK, | 1743 | TOX_ERR_FILE_GET_OK, |
1744 | |||
1571 | /** | 1745 | /** |
1572 | * The friend_number passed did not designate a valid friend. | 1746 | * The friend_number passed did not designate a valid friend. |
1573 | */ | 1747 | */ |
1574 | TOX_ERR_FILE_GET_FRIEND_NOT_FOUND, | 1748 | TOX_ERR_FILE_GET_FRIEND_NOT_FOUND, |
1749 | |||
1575 | /** | 1750 | /** |
1576 | * No file transfer with the given file number was found for the given friend. | 1751 | * No file transfer with the given file number was found for the given friend. |
1577 | */ | 1752 | */ |
1578 | TOX_ERR_FILE_GET_NOT_FOUND | 1753 | TOX_ERR_FILE_GET_NOT_FOUND, |
1754 | |||
1579 | } TOX_ERR_FILE_GET; | 1755 | } TOX_ERR_FILE_GET; |
1580 | 1756 | ||
1757 | |||
1581 | /** | 1758 | /** |
1582 | * Copy the file id associated to the file transfer to a byte array. | 1759 | * Copy the file id associated to the file transfer to a byte array. |
1583 | * | 1760 | * |
1584 | * @param friend_number The friend number of the friend the file is being | 1761 | * @param friend_number The friend number of the friend the file is being |
1585 | * transferred to. | 1762 | * transferred to or received from. |
1586 | * @param file_number The friend-specific identifier for the file transfer. | 1763 | * @param file_number The friend-specific identifier for the file transfer. |
1587 | * @param file_id A memory region of at least TOX_FILE_ID_LENGTH bytes. If | 1764 | * @param file_id A memory region of at least TOX_FILE_ID_LENGTH bytes. If |
1588 | * this parameter is NULL, this function has no effect. | 1765 | * this parameter is NULL, this function has no effect. |
@@ -1592,6 +1769,7 @@ typedef enum TOX_ERR_FILE_GET { | |||
1592 | bool tox_file_get_file_id(const Tox *tox, uint32_t friend_number, uint32_t file_number, uint8_t *file_id, | 1769 | bool tox_file_get_file_id(const Tox *tox, uint32_t friend_number, uint32_t file_number, uint8_t *file_id, |
1593 | TOX_ERR_FILE_GET *error); | 1770 | TOX_ERR_FILE_GET *error); |
1594 | 1771 | ||
1772 | |||
1595 | /******************************************************************************* | 1773 | /******************************************************************************* |
1596 | * | 1774 | * |
1597 | * :: File transmission: sending | 1775 | * :: File transmission: sending |
@@ -1599,36 +1777,51 @@ bool tox_file_get_file_id(const Tox *tox, uint32_t friend_number, uint32_t file_ | |||
1599 | ******************************************************************************/ | 1777 | ******************************************************************************/ |
1600 | 1778 | ||
1601 | 1779 | ||
1780 | |||
1602 | typedef enum TOX_ERR_FILE_SEND { | 1781 | typedef enum TOX_ERR_FILE_SEND { |
1782 | |||
1783 | /** | ||
1784 | * The function returned successfully. | ||
1785 | */ | ||
1603 | TOX_ERR_FILE_SEND_OK, | 1786 | TOX_ERR_FILE_SEND_OK, |
1787 | |||
1788 | /** | ||
1789 | * One of the arguments to the function was NULL when it was not expected. | ||
1790 | */ | ||
1604 | TOX_ERR_FILE_SEND_NULL, | 1791 | TOX_ERR_FILE_SEND_NULL, |
1792 | |||
1605 | /** | 1793 | /** |
1606 | * The friend_number passed did not designate a valid friend. | 1794 | * The friend_number passed did not designate a valid friend. |
1607 | */ | 1795 | */ |
1608 | TOX_ERR_FILE_SEND_FRIEND_NOT_FOUND, | 1796 | TOX_ERR_FILE_SEND_FRIEND_NOT_FOUND, |
1797 | |||
1609 | /** | 1798 | /** |
1610 | * This client is currently not connected to the friend. | 1799 | * This client is currently not connected to the friend. |
1611 | */ | 1800 | */ |
1612 | TOX_ERR_FILE_SEND_FRIEND_NOT_CONNECTED, | 1801 | TOX_ERR_FILE_SEND_FRIEND_NOT_CONNECTED, |
1802 | |||
1613 | /** | 1803 | /** |
1614 | * Filename length exceeded TOX_MAX_FILENAME_LENGTH bytes. | 1804 | * Filename length exceeded TOX_MAX_FILENAME_LENGTH bytes. |
1615 | */ | 1805 | */ |
1616 | TOX_ERR_FILE_SEND_NAME_TOO_LONG, | 1806 | TOX_ERR_FILE_SEND_NAME_TOO_LONG, |
1807 | |||
1617 | /** | 1808 | /** |
1618 | * Too many ongoing transfers. The maximum number of concurrent file transfers | 1809 | * Too many ongoing transfers. The maximum number of concurrent file transfers |
1619 | * is 256 per friend per direction (sending and receiving). | 1810 | * is 256 per friend per direction (sending and receiving). |
1620 | */ | 1811 | */ |
1621 | TOX_ERR_FILE_SEND_TOO_MANY | 1812 | TOX_ERR_FILE_SEND_TOO_MANY, |
1813 | |||
1622 | } TOX_ERR_FILE_SEND; | 1814 | } TOX_ERR_FILE_SEND; |
1623 | 1815 | ||
1816 | |||
1624 | /** | 1817 | /** |
1625 | * Send a file transmission request. | 1818 | * Send a file transmission request. |
1626 | * | 1819 | * |
1627 | * Maximum filename length is TOX_MAX_FILENAME_LENGTH bytes. The filename should generally just be | 1820 | * Maximum filename length is TOX_MAX_FILENAME_LENGTH bytes. The filename |
1628 | * a file name, not a path with directory names. | 1821 | * should generally just be a file name, not a path with directory names. |
1629 | * | 1822 | * |
1630 | * If a non-zero file size is provided, this can be used by both sides to | 1823 | * If a non-UINT64_MAX file size is provided, it can be used by both sides to |
1631 | * determine the sending progress. File size can be set to zero for streaming | 1824 | * determine the sending progress. File size can be set to UINT64_MAX for streaming |
1632 | * data of unknown size. | 1825 | * data of unknown size. |
1633 | * | 1826 | * |
1634 | * File transmission occurs in chunks, which are requested through the | 1827 | * File transmission occurs in chunks, which are requested through the |
@@ -1642,13 +1835,14 @@ typedef enum TOX_ERR_FILE_SEND { | |||
1642 | * was modified and how the client determines the file size. | 1835 | * was modified and how the client determines the file size. |
1643 | * | 1836 | * |
1644 | * - If the file size was increased | 1837 | * - If the file size was increased |
1645 | * - and sending mode was streaming (file_size = UINT64_MAX), the behaviour will be as | 1838 | * - and sending mode was streaming (file_size = UINT64_MAX), the behaviour |
1646 | * expected. | 1839 | * will be as expected. |
1647 | * - and sending mode was file (file_size != UINT64_MAX), the file_chunk_request | 1840 | * - and sending mode was file (file_size != UINT64_MAX), the |
1648 | * callback will receive length = 0 when Core thinks the file transfer has | 1841 | * file_chunk_request callback will receive length = 0 when Core thinks |
1649 | * finished. If the client remembers the file size as it was when sending | 1842 | * the file transfer has finished. If the client remembers the file size as |
1650 | * the request, it will terminate the transfer normally. If the client | 1843 | * it was when sending the request, it will terminate the transfer normally. |
1651 | * re-reads the size, it will think the friend cancelled the transfer. | 1844 | * If the client re-reads the size, it will think the friend cancelled the |
1845 | * transfer. | ||
1652 | * - If the file size was decreased | 1846 | * - If the file size was decreased |
1653 | * - and sending mode was streaming, the behaviour is as expected. | 1847 | * - and sending mode was streaming, the behaviour is as expected. |
1654 | * - and sending mode was file, the callback will return 0 at the new | 1848 | * - and sending mode was file, the callback will return 0 at the new |
@@ -1676,52 +1870,65 @@ typedef enum TOX_ERR_FILE_SEND { | |||
1676 | * | 1870 | * |
1677 | * @return A file number used as an identifier in subsequent callbacks. This | 1871 | * @return A file number used as an identifier in subsequent callbacks. This |
1678 | * number is per friend. File numbers are reused after a transfer terminates. | 1872 | * number is per friend. File numbers are reused after a transfer terminates. |
1679 | * on failure, this function returns UINT32_MAX. Any pattern in file numbers | 1873 | * On failure, this function returns UINT32_MAX. Any pattern in file numbers |
1680 | * should not be relied on. | 1874 | * should not be relied on. |
1681 | */ | 1875 | */ |
1682 | uint32_t tox_file_send(Tox *tox, uint32_t friend_number, uint32_t kind, uint64_t file_size, const uint8_t *file_id, | 1876 | uint32_t tox_file_send(Tox *tox, uint32_t friend_number, uint32_t kind, uint64_t file_size, const uint8_t *file_id, |
1683 | const uint8_t *filename, size_t filename_length, TOX_ERR_FILE_SEND *error); | 1877 | const uint8_t *filename, size_t filename_length, TOX_ERR_FILE_SEND *error); |
1684 | 1878 | ||
1685 | |||
1686 | typedef enum TOX_ERR_FILE_SEND_CHUNK { | 1879 | typedef enum TOX_ERR_FILE_SEND_CHUNK { |
1880 | |||
1881 | /** | ||
1882 | * The function returned successfully. | ||
1883 | */ | ||
1687 | TOX_ERR_FILE_SEND_CHUNK_OK, | 1884 | TOX_ERR_FILE_SEND_CHUNK_OK, |
1885 | |||
1688 | /** | 1886 | /** |
1689 | * The length parameter was non-zero, but data was NULL. | 1887 | * The length parameter was non-zero, but data was NULL. |
1690 | */ | 1888 | */ |
1691 | TOX_ERR_FILE_SEND_CHUNK_NULL, | 1889 | TOX_ERR_FILE_SEND_CHUNK_NULL, |
1890 | |||
1692 | /** | 1891 | /** |
1693 | * The friend_number passed did not designate a valid friend. | 1892 | * The friend_number passed did not designate a valid friend. |
1694 | */ | 1893 | */ |
1695 | TOX_ERR_FILE_SEND_CHUNK_FRIEND_NOT_FOUND, | 1894 | TOX_ERR_FILE_SEND_CHUNK_FRIEND_NOT_FOUND, |
1895 | |||
1696 | /** | 1896 | /** |
1697 | * This client is currently not connected to the friend. | 1897 | * This client is currently not connected to the friend. |
1698 | */ | 1898 | */ |
1699 | TOX_ERR_FILE_SEND_CHUNK_FRIEND_NOT_CONNECTED, | 1899 | TOX_ERR_FILE_SEND_CHUNK_FRIEND_NOT_CONNECTED, |
1900 | |||
1700 | /** | 1901 | /** |
1701 | * No file transfer with the given file number was found for the given friend. | 1902 | * No file transfer with the given file number was found for the given friend. |
1702 | */ | 1903 | */ |
1703 | TOX_ERR_FILE_SEND_CHUNK_NOT_FOUND, | 1904 | TOX_ERR_FILE_SEND_CHUNK_NOT_FOUND, |
1905 | |||
1704 | /** | 1906 | /** |
1705 | * File transfer was found but isn't in a transferring state: (paused, done, | 1907 | * File transfer was found but isn't in a transferring state: (paused, done, |
1706 | * broken, etc...) (happens only when not called from the request chunk callback). | 1908 | * broken, etc...) (happens only when not called from the request chunk callback). |
1707 | */ | 1909 | */ |
1708 | TOX_ERR_FILE_SEND_CHUNK_NOT_TRANSFERRING, | 1910 | TOX_ERR_FILE_SEND_CHUNK_NOT_TRANSFERRING, |
1911 | |||
1709 | /** | 1912 | /** |
1710 | * Attempted to send more or less data than requested. The requested data size is | 1913 | * Attempted to send more or less data than requested. The requested data size is |
1711 | * adjusted according to maximum transmission unit and the expected end of | 1914 | * adjusted according to maximum transmission unit and the expected end of |
1712 | * the file. Trying to send less or more than requested will return this error. | 1915 | * the file. Trying to send less or more than requested will return this error. |
1713 | */ | 1916 | */ |
1714 | TOX_ERR_FILE_SEND_CHUNK_INVALID_LENGTH, | 1917 | TOX_ERR_FILE_SEND_CHUNK_INVALID_LENGTH, |
1918 | |||
1715 | /** | 1919 | /** |
1716 | * Packet queue is full. | 1920 | * Packet queue is full. |
1717 | */ | 1921 | */ |
1718 | TOX_ERR_FILE_SEND_CHUNK_SENDQ, | 1922 | TOX_ERR_FILE_SEND_CHUNK_SENDQ, |
1923 | |||
1719 | /** | 1924 | /** |
1720 | * Position parameter was wrong. | 1925 | * Position parameter was wrong. |
1721 | */ | 1926 | */ |
1722 | TOX_ERR_FILE_SEND_CHUNK_WRONG_POSITION | 1927 | TOX_ERR_FILE_SEND_CHUNK_WRONG_POSITION, |
1928 | |||
1723 | } TOX_ERR_FILE_SEND_CHUNK; | 1929 | } TOX_ERR_FILE_SEND_CHUNK; |
1724 | 1930 | ||
1931 | |||
1725 | /** | 1932 | /** |
1726 | * Send a chunk of file data to a friend. | 1933 | * Send a chunk of file data to a friend. |
1727 | * | 1934 | * |
@@ -1741,10 +1948,7 @@ typedef enum TOX_ERR_FILE_SEND_CHUNK { | |||
1741 | bool tox_file_send_chunk(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, const uint8_t *data, | 1948 | bool tox_file_send_chunk(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, const uint8_t *data, |
1742 | size_t length, TOX_ERR_FILE_SEND_CHUNK *error); | 1949 | size_t length, TOX_ERR_FILE_SEND_CHUNK *error); |
1743 | 1950 | ||
1744 | |||
1745 | /** | 1951 | /** |
1746 | * The function type for the `file_chunk_request` callback. | ||
1747 | * | ||
1748 | * If the length parameter is 0, the file transfer is finished, and the client's | 1952 | * If the length parameter is 0, the file transfer is finished, and the client's |
1749 | * resources associated with the file number should be released. After a call | 1953 | * resources associated with the file number should be released. After a call |
1750 | * with zero length, the file number can be reused for future file transfers. | 1954 | * with zero length, the file number can be reused for future file transfers. |
@@ -1769,10 +1973,13 @@ bool tox_file_send_chunk(Tox *tox, uint32_t friend_number, uint32_t file_number, | |||
1769 | typedef void tox_file_chunk_request_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, | 1973 | typedef void tox_file_chunk_request_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, |
1770 | size_t length, void *user_data); | 1974 | size_t length, void *user_data); |
1771 | 1975 | ||
1976 | |||
1772 | /** | 1977 | /** |
1773 | * Set the callback for the `file_chunk_request` event. Pass NULL to unset. | 1978 | * Set the callback for the `file_chunk_request` event. Pass NULL to unset. |
1979 | * | ||
1980 | * This event is triggered when Core is ready to send more file data. | ||
1774 | */ | 1981 | */ |
1775 | void tox_callback_file_chunk_request(Tox *tox, tox_file_chunk_request_cb *function, void *user_data); | 1982 | void tox_callback_file_chunk_request(Tox *tox, tox_file_chunk_request_cb *callback, void *user_data); |
1776 | 1983 | ||
1777 | 1984 | ||
1778 | /******************************************************************************* | 1985 | /******************************************************************************* |
@@ -1782,12 +1989,8 @@ void tox_callback_file_chunk_request(Tox *tox, tox_file_chunk_request_cb *functi | |||
1782 | ******************************************************************************/ | 1989 | ******************************************************************************/ |
1783 | 1990 | ||
1784 | 1991 | ||
1992 | |||
1785 | /** | 1993 | /** |
1786 | * The function type for the `file_receive` callback. | ||
1787 | * | ||
1788 | * Maximum filename length is TOX_MAX_FILENAME_LENGTH bytes. The filename should generally just be | ||
1789 | * a file name, not a path with directory names. | ||
1790 | * | ||
1791 | * The client should acquire resources to be associated with the file transfer. | 1994 | * The client should acquire resources to be associated with the file transfer. |
1792 | * Incoming file transfers start in the PAUSED state. After this callback | 1995 | * Incoming file transfers start in the PAUSED state. After this callback |
1793 | * returns, a transfer can be rejected by sending a TOX_FILE_CONTROL_CANCEL | 1996 | * returns, a transfer can be rejected by sending a TOX_FILE_CONTROL_CANCEL |
@@ -1799,27 +2002,24 @@ void tox_callback_file_chunk_request(Tox *tox, tox_file_chunk_request_cb *functi | |||
1799 | * @param file_number The friend-specific file number the data received is | 2002 | * @param file_number The friend-specific file number the data received is |
1800 | * associated with. | 2003 | * associated with. |
1801 | * @param kind The meaning of the file to be sent. | 2004 | * @param kind The meaning of the file to be sent. |
1802 | * @param file_size Size in bytes of the file about to be received from the client, | 2005 | * @param file_size Size in bytes of the file the client wants to send, |
1803 | * UINT64_MAX if unknown or streaming. | 2006 | * UINT64_MAX if unknown or streaming. |
2007 | * @param filename Name of the file. Does not need to be the actual name. This | ||
2008 | * name will be sent along with the file send request. | ||
1804 | * @param filename_length Size in bytes of the filename. | 2009 | * @param filename_length Size in bytes of the filename. |
1805 | */ | 2010 | */ |
1806 | typedef void tox_file_recv_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, uint32_t kind, | 2011 | typedef void tox_file_recv_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, uint32_t kind, uint64_t file_size, |
1807 | uint64_t file_size, const uint8_t *filename, size_t filename_length, void *user_data); | 2012 | const uint8_t *filename, size_t filename_length, void *user_data); |
2013 | |||
1808 | 2014 | ||
1809 | /** | 2015 | /** |
1810 | * Set the callback for the `file_receive` event. Pass NULL to unset. | 2016 | * Set the callback for the `file_recv` event. Pass NULL to unset. |
1811 | * | 2017 | * |
1812 | * This event is triggered when a file transfer request is received. | 2018 | * This event is triggered when a file transfer request is received. |
1813 | */ | 2019 | */ |
1814 | void tox_callback_file_recv(Tox *tox, tox_file_recv_cb *function, void *user_data); | 2020 | void tox_callback_file_recv(Tox *tox, tox_file_recv_cb *callback, void *user_data); |
1815 | |||
1816 | 2021 | ||
1817 | /** | 2022 | /** |
1818 | * The function type for the `file_receive_chunk` callback. | ||
1819 | * | ||
1820 | * This function is first called when a file transfer request is received, and | ||
1821 | * subsequently when a chunk of file data for an accepted request was received. | ||
1822 | * | ||
1823 | * When length is 0, the transfer is finished and the client should release the | 2023 | * When length is 0, the transfer is finished and the client should release the |
1824 | * resources it acquired for the transfer. After a call with length = 0, the | 2024 | * resources it acquired for the transfer. After a call with length = 0, the |
1825 | * file number can be reused for new file transfers. | 2025 | * file number can be reused for new file transfers. |
@@ -1838,10 +2038,14 @@ void tox_callback_file_recv(Tox *tox, tox_file_recv_cb *function, void *user_dat | |||
1838 | typedef void tox_file_recv_chunk_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, | 2038 | typedef void tox_file_recv_chunk_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, |
1839 | const uint8_t *data, size_t length, void *user_data); | 2039 | const uint8_t *data, size_t length, void *user_data); |
1840 | 2040 | ||
2041 | |||
1841 | /** | 2042 | /** |
1842 | * Set the callback for the `file_receive_chunk` event. Pass NULL to unset. | 2043 | * Set the callback for the `file_recv_chunk` event. Pass NULL to unset. |
2044 | * | ||
2045 | * This event is first triggered when a file transfer request is received, and | ||
2046 | * subsequently when a chunk of file data for an accepted request was received. | ||
1843 | */ | 2047 | */ |
1844 | void tox_callback_file_recv_chunk(Tox *tox, tox_file_recv_chunk_cb *function, void *user_data); | 2048 | void tox_callback_file_recv_chunk(Tox *tox, tox_file_recv_chunk_cb *callback, void *user_data); |
1845 | 2049 | ||
1846 | 2050 | ||
1847 | /******************************************************************************* | 2051 | /******************************************************************************* |
@@ -1851,13 +2055,16 @@ void tox_callback_file_recv_chunk(Tox *tox, tox_file_recv_chunk_cb *function, vo | |||
1851 | ******************************************************************************/ | 2055 | ******************************************************************************/ |
1852 | 2056 | ||
1853 | 2057 | ||
1854 | /****************************************************************************** | 2058 | |
2059 | |||
2060 | /******************************************************************************* | ||
1855 | * | 2061 | * |
1856 | * :: Group chat message sending and receiving | 2062 | * :: Group chat message sending and receiving |
1857 | * | 2063 | * |
1858 | ******************************************************************************/ | 2064 | ******************************************************************************/ |
1859 | 2065 | ||
1860 | /* See: tox_old.h for now. */ | 2066 | |
2067 | |||
1861 | 2068 | ||
1862 | /******************************************************************************* | 2069 | /******************************************************************************* |
1863 | * | 2070 | * |
@@ -1866,34 +2073,50 @@ void tox_callback_file_recv_chunk(Tox *tox, tox_file_recv_chunk_cb *function, vo | |||
1866 | ******************************************************************************/ | 2073 | ******************************************************************************/ |
1867 | 2074 | ||
1868 | 2075 | ||
2076 | |||
1869 | typedef enum TOX_ERR_FRIEND_CUSTOM_PACKET { | 2077 | typedef enum TOX_ERR_FRIEND_CUSTOM_PACKET { |
2078 | |||
2079 | /** | ||
2080 | * The function returned successfully. | ||
2081 | */ | ||
1870 | TOX_ERR_FRIEND_CUSTOM_PACKET_OK, | 2082 | TOX_ERR_FRIEND_CUSTOM_PACKET_OK, |
2083 | |||
2084 | /** | ||
2085 | * One of the arguments to the function was NULL when it was not expected. | ||
2086 | */ | ||
1871 | TOX_ERR_FRIEND_CUSTOM_PACKET_NULL, | 2087 | TOX_ERR_FRIEND_CUSTOM_PACKET_NULL, |
2088 | |||
1872 | /** | 2089 | /** |
1873 | * The friend number did not designate a valid friend. | 2090 | * The friend number did not designate a valid friend. |
1874 | */ | 2091 | */ |
1875 | TOX_ERR_FRIEND_CUSTOM_PACKET_FRIEND_NOT_FOUND, | 2092 | TOX_ERR_FRIEND_CUSTOM_PACKET_FRIEND_NOT_FOUND, |
2093 | |||
1876 | /** | 2094 | /** |
1877 | * This client is currently not connected to the friend. | 2095 | * This client is currently not connected to the friend. |
1878 | */ | 2096 | */ |
1879 | TOX_ERR_FRIEND_CUSTOM_PACKET_FRIEND_NOT_CONNECTED, | 2097 | TOX_ERR_FRIEND_CUSTOM_PACKET_FRIEND_NOT_CONNECTED, |
2098 | |||
1880 | /** | 2099 | /** |
1881 | * The first byte of data was not in the specified range for the packet type. | 2100 | * The first byte of data was not in the specified range for the packet type. |
1882 | * This range is 200-254 for lossy, and 160-191 for lossless packets. | 2101 | * This range is 200-254 for lossy, and 160-191 for lossless packets. |
1883 | */ | 2102 | */ |
1884 | TOX_ERR_FRIEND_CUSTOM_PACKET_INVALID, | 2103 | TOX_ERR_FRIEND_CUSTOM_PACKET_INVALID, |
2104 | |||
1885 | /** | 2105 | /** |
1886 | * Attempted to send an empty packet. | 2106 | * Attempted to send an empty packet. |
1887 | */ | 2107 | */ |
1888 | TOX_ERR_FRIEND_CUSTOM_PACKET_EMPTY, | 2108 | TOX_ERR_FRIEND_CUSTOM_PACKET_EMPTY, |
2109 | |||
1889 | /** | 2110 | /** |
1890 | * Packet data length exceeded TOX_MAX_CUSTOM_PACKET_SIZE. | 2111 | * Packet data length exceeded TOX_MAX_CUSTOM_PACKET_SIZE. |
1891 | */ | 2112 | */ |
1892 | TOX_ERR_FRIEND_CUSTOM_PACKET_TOO_LONG, | 2113 | TOX_ERR_FRIEND_CUSTOM_PACKET_TOO_LONG, |
2114 | |||
1893 | /** | 2115 | /** |
1894 | * Send queue size exceeded. | 2116 | * Packet queue is full. |
1895 | */ | 2117 | */ |
1896 | TOX_ERR_FRIEND_CUSTOM_PACKET_SENDQ | 2118 | TOX_ERR_FRIEND_CUSTOM_PACKET_SENDQ, |
2119 | |||
1897 | } TOX_ERR_FRIEND_CUSTOM_PACKET; | 2120 | } TOX_ERR_FRIEND_CUSTOM_PACKET; |
1898 | 2121 | ||
1899 | 2122 | ||
@@ -1921,22 +2144,6 @@ bool tox_friend_send_lossy_packet(Tox *tox, uint32_t friend_number, const uint8_ | |||
1921 | TOX_ERR_FRIEND_CUSTOM_PACKET *error); | 2144 | TOX_ERR_FRIEND_CUSTOM_PACKET *error); |
1922 | 2145 | ||
1923 | /** | 2146 | /** |
1924 | * The function type for the `friend_lossy_packet` callback. | ||
1925 | * | ||
1926 | * @param friend_number The friend number of the friend who sent a lossy packet. | ||
1927 | * @param data A byte array containing the received packet data. | ||
1928 | * @param length The length of the packet data byte array. | ||
1929 | */ | ||
1930 | typedef void tox_friend_lossy_packet_cb(Tox *tox, uint32_t friend_number, const uint8_t *data, size_t length, | ||
1931 | void *user_data); | ||
1932 | |||
1933 | /** | ||
1934 | * Set the callback for the `friend_lossy_packet` event. Pass NULL to unset. | ||
1935 | */ | ||
1936 | void tox_callback_friend_lossy_packet(Tox *tox, tox_friend_lossy_packet_cb *function, void *user_data); | ||
1937 | |||
1938 | |||
1939 | /** | ||
1940 | * Send a custom lossless packet to a friend. | 2147 | * Send a custom lossless packet to a friend. |
1941 | * | 2148 | * |
1942 | * The first byte of data must be in the range 160-191. Maximum length of a | 2149 | * The first byte of data must be in the range 160-191. Maximum length of a |
@@ -1956,20 +2163,34 @@ bool tox_friend_send_lossless_packet(Tox *tox, uint32_t friend_number, const uin | |||
1956 | TOX_ERR_FRIEND_CUSTOM_PACKET *error); | 2163 | TOX_ERR_FRIEND_CUSTOM_PACKET *error); |
1957 | 2164 | ||
1958 | /** | 2165 | /** |
1959 | * The function type for the `friend_lossless_packet` callback. | 2166 | * @param friend_number The friend number of the friend who sent a lossy packet. |
2167 | * @param data A byte array containing the received packet data. | ||
2168 | * @param length The length of the packet data byte array. | ||
2169 | */ | ||
2170 | typedef void tox_friend_lossy_packet_cb(Tox *tox, uint32_t friend_number, const uint8_t *data, size_t length, | ||
2171 | void *user_data); | ||
2172 | |||
2173 | |||
2174 | /** | ||
2175 | * Set the callback for the `friend_lossy_packet` event. Pass NULL to unset. | ||
1960 | * | 2176 | * |
2177 | */ | ||
2178 | void tox_callback_friend_lossy_packet(Tox *tox, tox_friend_lossy_packet_cb *callback, void *user_data); | ||
2179 | |||
2180 | /** | ||
1961 | * @param friend_number The friend number of the friend who sent the packet. | 2181 | * @param friend_number The friend number of the friend who sent the packet. |
1962 | * @param data A byte array containing the received packet data. | 2182 | * @param data A byte array containing the received packet data. |
1963 | * @param length The length of the packet data byte array. | 2183 | * @param length The length of the packet data byte array. |
1964 | */ | 2184 | */ |
1965 | typedef void tox_friend_lossless_packet_cb(Tox *tox, uint32_t friend_number, const uint8_t *data, size_t length, | 2185 | typedef void tox_friend_lossless_packet_cb(Tox *tox, uint32_t friend_number, const uint8_t *data, size_t length, |
1966 | void *user_data); | 2186 | void *user_data); |
2187 | |||
1967 | 2188 | ||
1968 | /** | 2189 | /** |
1969 | * Set the callback for the `friend_lossless_packet` event. Pass NULL to unset. | 2190 | * Set the callback for the `friend_lossless_packet` event. Pass NULL to unset. |
2191 | * | ||
1970 | */ | 2192 | */ |
1971 | void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb *function, void *user_data); | 2193 | void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb *callback, void *user_data); |
1972 | |||
1973 | 2194 | ||
1974 | 2195 | ||
1975 | /******************************************************************************* | 2196 | /******************************************************************************* |
@@ -1979,11 +2200,12 @@ void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb | |||
1979 | ******************************************************************************/ | 2200 | ******************************************************************************/ |
1980 | 2201 | ||
1981 | 2202 | ||
2203 | |||
1982 | /** | 2204 | /** |
1983 | * Writes the temporary DHT public key of this instance to a byte array. | 2205 | * Writes the temporary DHT public key of this instance to a byte array. |
1984 | * | 2206 | * |
1985 | * This can be used in combination with an externally accessible IP address and | 2207 | * This can be used in combination with an externally accessible IP address and |
1986 | * the bound port (from tox_get_udp_port) to run a temporary bootstrap node. | 2208 | * the bound port (from tox_self_get_udp_port) to run a temporary bootstrap node. |
1987 | * | 2209 | * |
1988 | * Be aware that every time a new instance is created, the DHT public key | 2210 | * Be aware that every time a new instance is created, the DHT public key |
1989 | * changes, meaning this cannot be used to run a permanent bootstrap node. | 2211 | * changes, meaning this cannot be used to run a permanent bootstrap node. |
@@ -1993,15 +2215,21 @@ void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb | |||
1993 | */ | 2215 | */ |
1994 | void tox_self_get_dht_id(const Tox *tox, uint8_t *dht_id); | 2216 | void tox_self_get_dht_id(const Tox *tox, uint8_t *dht_id); |
1995 | 2217 | ||
1996 | |||
1997 | typedef enum TOX_ERR_GET_PORT { | 2218 | typedef enum TOX_ERR_GET_PORT { |
2219 | |||
2220 | /** | ||
2221 | * The function returned successfully. | ||
2222 | */ | ||
1998 | TOX_ERR_GET_PORT_OK, | 2223 | TOX_ERR_GET_PORT_OK, |
2224 | |||
1999 | /** | 2225 | /** |
2000 | * The instance was not bound to any port. | 2226 | * The instance was not bound to any port. |
2001 | */ | 2227 | */ |
2002 | TOX_ERR_GET_PORT_NOT_BOUND | 2228 | TOX_ERR_GET_PORT_NOT_BOUND, |
2229 | |||
2003 | } TOX_ERR_GET_PORT; | 2230 | } TOX_ERR_GET_PORT; |
2004 | 2231 | ||
2232 | |||
2005 | /** | 2233 | /** |
2006 | * Return the UDP port this Tox instance is bound to. | 2234 | * Return the UDP port this Tox instance is bound to. |
2007 | */ | 2235 | */ |