1 /* SPDX-License-Identifier: GPL-3.0-or-later 2 * Copyright © 2016-2018 The TokTok team. 3 * Copyright © 2013 Tox project. 4 */ 5 6 /* 7 * The Tox public API. 8 */ 9 #ifndef C_TOXCORE_TOXCORE_TOX_H 10 #define C_TOXCORE_TOXCORE_TOX_H 11 12 #include <stdbool.h> 13 #include <stddef.h> 14 #include <stdint.h> 15 16 //!TOKSTYLE- 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 23 /******************************************************************************* 24 * `tox.h` SHOULD *NOT* BE EDITED MANUALLY – any changes should be made to * 25 * `tox.api.h`, located in `toxcore/`. For instructions on how to * 26 * generate `tox.h` from `tox.api.h` please refer to `docs/apidsl.md` * 27 ******************************************************************************/ 28 29 30 31 /** 32 * @page core Public core API for Tox clients. 33 * 34 * Every function that can fail takes a function-specific error code pointer 35 * that can be used to diagnose problems with the Tox state or the function 36 * arguments. The error code pointer can be NULL, which does not influence the 37 * function's behaviour, but can be done if the reason for failure is irrelevant 38 * to the client. 39 * 40 * The exception to this rule are simple allocation functions whose only failure 41 * mode is allocation failure. They return NULL in that case, and do not set an 42 * error code. 43 * 44 * Every error code type has an OK value to which functions will set their error 45 * code value on success. Clients can keep their error code uninitialised before 46 * passing it to a function. The library guarantees that after returning, the 47 * value pointed to by the error code pointer has been initialised. 48 * 49 * Functions with pointer parameters often have a NULL error code, meaning they 50 * could not perform any operation, because one of the required parameters was 51 * NULL. Some functions operate correctly or are defined as effectless on NULL. 52 * 53 * Some functions additionally return a value outside their 54 * return type domain, or a bool containing true on success and false on 55 * failure. 56 * 57 * All functions that take a Tox instance pointer will cause undefined behaviour 58 * when passed a NULL Tox pointer. 59 * 60 * All integer values are expected in host byte order. 61 * 62 * Functions with parameters with enum types cause unspecified behaviour if the 63 * enumeration value is outside the valid range of the type. If possible, the 64 * function will try to use a sane default, but there will be no error code, 65 * and one possible action for the function to take is to have no effect. 66 * 67 * Integer constants and the memory layout of publicly exposed structs are not 68 * part of the ABI. 69 */ 70 /** 71 * @subsection events Events and callbacks 72 * 73 * 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 75 * function to register it named `tox_callback_{event}`. Passing a NULL 76 * 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 78 * event listeners, it needs to implement the dispatch functionality itself. 79 * 80 * The last argument to a callback is the user data pointer. It is passed from 81 * tox_iterate to each callback in sequence. 82 * 83 * The user data pointer is never stored or dereferenced by any library code, so 84 * can be any pointer, including NULL. Callbacks must all operate on the same 85 * object type. In the apidsl code (tox.in.h), this is denoted with `any`. The 86 * `any` in tox_iterate must be the same `any` as in all callbacks. In C, 87 * lacking parametric polymorphism, this is a pointer to void. 88 * 89 * Old style callbacks that are registered together with a user data pointer 90 * receive that pointer as argument when they are called. They can each have 91 * their own user data pointer of their own type. 92 */ 93 /** 94 * @subsection threading Threading implications 95 * 96 * It is possible to run multiple concurrent threads with a Tox instance for 97 * each thread. It is also possible to run all Tox instances in the same thread. 98 * A common way to run Tox (multiple or single instance) is to have one thread 99 * running a simple tox_iterate loop, sleeping for tox_iteration_interval 100 * milliseconds on each iteration. 101 * 102 * If you want to access a single Tox instance from multiple threads, access 103 * to the instance must be synchronised. While multiple threads can concurrently 104 * access multiple different Tox instances, no more than one API function can 105 * operate on a single instance at any given time. 106 * 107 * Functions that write to variable length byte arrays will always have a size 108 * function associated with them. The result of this size function is only valid 109 * until another mutating function (one that takes a pointer to non-const Tox) 110 * is called. Thus, clients must ensure that no other thread calls a mutating 111 * function between the call to the size function and the call to the retrieval 112 * function. 113 * 114 * E.g. to get the current nickname, one would write 115 * 116 * @code 117 * size_t length = tox_self_get_name_size(tox); 118 * uint8_t *name = malloc(length); 119 * if (!name) abort(); 120 * tox_self_get_name(tox, name); 121 * @endcode 122 * 123 * If any other thread calls tox_self_set_name while this thread is allocating 124 * memory, the length may have become invalid, and the call to 125 * tox_self_get_name may cause undefined behaviour. 126 */ 127 /** 128 * The Tox instance type. All the state associated with a connection is held 129 * within the instance. Multiple instances can exist and operate concurrently. 130 * The maximum number of Tox instances that can exist on a single network 131 * device is limited. Note that this is not just a per-process limit, since the 132 * limiting factor is the number of usable ports on a device. 133 */ 134 #ifndef TOX_DEFINED 135 #define TOX_DEFINED 136 typedef struct Tox Tox; 137 #endif /* TOX_DEFINED */ 138 139 140 /******************************************************************************* 141 * 142 * :: API version 143 * 144 ******************************************************************************/ 145 146 147 148 /** 149 * The major version number. Incremented when the API or ABI changes in an 150 * incompatible way. 151 * 152 * The function variants of these constants return the version number of the 153 * library. They can be used to display the Tox library version or to check 154 * whether the client is compatible with the dynamically linked version of Tox. 155 */ 156 #define TOX_VERSION_MAJOR 0 157 158 uint32_t tox_version_major(void); 159 160 /** 161 * The minor version number. Incremented when functionality is added without 162 * breaking the API or ABI. Set to 0 when the major version number is 163 * incremented. 164 */ 165 #define TOX_VERSION_MINOR 2 166 167 uint32_t tox_version_minor(void); 168 169 /** 170 * The patch or revision number. Incremented when bugfixes are applied without 171 * changing any functionality or API or ABI. 172 */ 173 #define TOX_VERSION_PATCH 13 174 175 uint32_t tox_version_patch(void); 176 177 /** 178 * A macro to check at preprocessing time whether the client code is compatible 179 * with the installed version of Tox. Leading zeros in the version number are 180 * ignored. E.g. 0.1.5 is to 0.1.4 what 1.5 is to 1.4, that is: it can add new 181 * features, but can't break the API. 182 */ 183 #define TOX_VERSION_IS_API_COMPATIBLE(MAJOR, MINOR, PATCH) \ 184 ((TOX_VERSION_MAJOR > 0 && TOX_VERSION_MAJOR == MAJOR) && ( \ 185 /* 1.x.x, 2.x.x, etc. with matching major version. */ \ 186 TOX_VERSION_MINOR > MINOR || \ 187 (TOX_VERSION_MINOR == MINOR && TOX_VERSION_PATCH >= PATCH) \ 188 )) || ((TOX_VERSION_MAJOR == 0 && MAJOR == 0) && ( \ 189 /* 0.x.x makes minor behave like major above. */ \ 190 ((TOX_VERSION_MINOR > 0 && TOX_VERSION_MINOR == MINOR) && ( \ 191 TOX_VERSION_PATCH >= PATCH \ 192 )) || ((TOX_VERSION_MINOR == 0 && MINOR == 0) && ( \ 193 /* 0.0.x and 0.0.y are only compatible if x == y. */ \ 194 TOX_VERSION_PATCH == PATCH \ 195 )) \ 196 )) 197 198 /** 199 * Return whether the compiled library version is compatible with the passed 200 * version numbers. 201 */ 202 bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch); 203 204 /** 205 * A convenience macro to call tox_version_is_compatible with the currently 206 * compiling API version. 207 */ 208 #define TOX_VERSION_IS_ABI_COMPATIBLE() \ 209 tox_version_is_compatible(TOX_VERSION_MAJOR, TOX_VERSION_MINOR, TOX_VERSION_PATCH) 210 211 212 /******************************************************************************* 213 * 214 * :: Numeric constants 215 * 216 * The values of these are not part of the ABI. Prefer to use the function 217 * versions of them for code that should remain compatible with future versions 218 * of toxcore. 219 * 220 ******************************************************************************/ 221 222 223 224 /** 225 * The size of a Tox Public Key in bytes. 226 */ 227 #define TOX_PUBLIC_KEY_SIZE 32 228 229 uint32_t tox_public_key_size(void); 230 231 /** 232 * The size of a Tox Secret Key in bytes. 233 */ 234 #define TOX_SECRET_KEY_SIZE 32 235 236 uint32_t tox_secret_key_size(void); 237 238 /** 239 * The size of a Tox Conference unique id in bytes. 240 * 241 * @deprecated Use TOX_CONFERENCE_ID_SIZE instead. 242 */ 243 #define TOX_CONFERENCE_UID_SIZE 32 244 245 uint32_t tox_conference_uid_size(void); 246 247 /** 248 * The size of a Tox Conference unique id in bytes. 249 */ 250 #define TOX_CONFERENCE_ID_SIZE 32 251 252 uint32_t tox_conference_id_size(void); 253 254 /** 255 * The size of the nospam in bytes when written in a Tox address. 256 */ 257 #define TOX_NOSPAM_SIZE (sizeof(uint32_t)) 258 259 uint32_t tox_nospam_size(void); 260 261 /** 262 * The size of a Tox address in bytes. Tox addresses are in the format 263 * [Public Key (TOX_PUBLIC_KEY_SIZE bytes)][nospam (4 bytes)][checksum (2 bytes)]. 264 * 265 * The checksum is computed over the Public Key and the nospam value. The first 266 * byte is an XOR of all the even bytes (0, 2, 4, ...), the second byte is an 267 * XOR of all the odd bytes (1, 3, 5, ...) of the Public Key and nospam. 268 */ 269 #define TOX_ADDRESS_SIZE (TOX_PUBLIC_KEY_SIZE + TOX_NOSPAM_SIZE + sizeof(uint16_t)) 270 271 uint32_t tox_address_size(void); 272 273 /** 274 * Maximum length of a nickname in bytes. 275 * 276 * @deprecated The macro will be removed in 0.3.0. Use the function instead. 277 */ 278 #define TOX_MAX_NAME_LENGTH 128 279 280 uint32_t tox_max_name_length(void); 281 282 /** 283 * Maximum length of a status message in bytes. 284 * 285 * @deprecated The macro will be removed in 0.3.0. Use the function instead. 286 */ 287 #define TOX_MAX_STATUS_MESSAGE_LENGTH 1007 288 289 uint32_t tox_max_status_message_length(void); 290 291 /** 292 * Maximum length of a friend request message in bytes. 293 * 294 * @deprecated The macro will be removed in 0.3.0. Use the function instead. 295 */ 296 #define TOX_MAX_FRIEND_REQUEST_LENGTH 1016 297 298 uint32_t tox_max_friend_request_length(void); 299 300 /** 301 * Maximum length of a single message after which it should be split. 302 * 303 * @deprecated The macro will be removed in 0.3.0. Use the function instead. 304 */ 305 #define TOX_MAX_MESSAGE_LENGTH 1372 306 307 uint32_t tox_max_message_length(void); 308 309 /** 310 * Maximum size of custom packets. TODO(iphydf): should be LENGTH? 311 * 312 * @deprecated The macro will be removed in 0.3.0. Use the function instead. 313 */ 314 #define TOX_MAX_CUSTOM_PACKET_SIZE 1373 315 316 uint32_t tox_max_custom_packet_size(void); 317 318 /** 319 * The number of bytes in a hash generated by tox_hash. 320 */ 321 #define TOX_HASH_LENGTH 32 322 323 uint32_t tox_hash_length(void); 324 325 /** 326 * The number of bytes in a file id. 327 */ 328 #define TOX_FILE_ID_LENGTH 32 329 330 uint32_t tox_file_id_length(void); 331 332 /** 333 * Maximum file name length for file transfers. 334 * 335 * @deprecated The macro will be removed in 0.3.0. Use the function instead. 336 */ 337 #define TOX_MAX_FILENAME_LENGTH 255 338 339 uint32_t tox_max_filename_length(void); 340 341 /** 342 * Maximum length of a hostname, e.g. proxy or bootstrap node names. 343 * 344 * This length does not include the NUL byte. Hostnames are NUL-terminated C 345 * strings, so they are 255 characters plus one NUL byte. 346 * 347 * @deprecated The macro will be removed in 0.3.0. Use the function instead. 348 */ 349 #define TOX_MAX_HOSTNAME_LENGTH 255 350 351 uint32_t tox_max_hostname_length(void); 352 353 354 /******************************************************************************* 355 * 356 * :: Global enumerations 357 * 358 ******************************************************************************/ 359 360 361 362 /** 363 * Represents the possible statuses a client can have. 364 * 365 * @deprecated All UPPER_CASE enum type names are deprecated. Use the 366 * Camel_Snake_Case versions, instead. 367 */ 368 typedef enum TOX_USER_STATUS { 369 370 /** 371 * User is online and available. 372 */ 373 TOX_USER_STATUS_NONE, 374 375 /** 376 * User is away. Clients can set this e.g. after a user defined 377 * inactivity time. 378 */ 379 TOX_USER_STATUS_AWAY, 380 381 /** 382 * User is busy. Signals to other clients that this client does not 383 * currently wish to communicate. 384 */ 385 TOX_USER_STATUS_BUSY, 386 387 } TOX_USER_STATUS; 388 389 390 /** 391 * Represents message types for tox_friend_send_message and conference 392 * messages. 393 * 394 * @deprecated All UPPER_CASE enum type names are deprecated. Use the 395 * Camel_Snake_Case versions, instead. 396 */ 397 typedef enum TOX_MESSAGE_TYPE { 398 399 /** 400 * Normal text message. Similar to PRIVMSG on IRC. 401 */ 402 TOX_MESSAGE_TYPE_NORMAL, 403 404 /** 405 * A message describing an user action. This is similar to /me (CTCP ACTION) 406 * on IRC. 407 */ 408 TOX_MESSAGE_TYPE_ACTION, 409 410 } TOX_MESSAGE_TYPE; 411 412 413 414 /******************************************************************************* 415 * 416 * :: Startup options 417 * 418 ******************************************************************************/ 419 420 421 422 /** 423 * Type of proxy used to connect to TCP relays. 424 * 425 * @deprecated All UPPER_CASE enum type names are deprecated. Use the 426 * Camel_Snake_Case versions, instead. 427 */ 428 typedef enum TOX_PROXY_TYPE { 429 430 /** 431 * Don't use a proxy. 432 */ 433 TOX_PROXY_TYPE_NONE, 434 435 /** 436 * HTTP proxy using CONNECT. 437 */ 438 TOX_PROXY_TYPE_HTTP, 439 440 /** 441 * SOCKS proxy for simple socket pipes. 442 */ 443 TOX_PROXY_TYPE_SOCKS5, 444 445 } TOX_PROXY_TYPE; 446 447 448 /** 449 * Type of savedata to create the Tox instance from. 450 * 451 * @deprecated All UPPER_CASE enum type names are deprecated. Use the 452 * Camel_Snake_Case versions, instead. 453 */ 454 typedef enum TOX_SAVEDATA_TYPE { 455 456 /** 457 * No savedata. 458 */ 459 TOX_SAVEDATA_TYPE_NONE, 460 461 /** 462 * Savedata is one that was obtained from tox_get_savedata. 463 */ 464 TOX_SAVEDATA_TYPE_TOX_SAVE, 465 466 /** 467 * Savedata is a secret key of length TOX_SECRET_KEY_SIZE. 468 */ 469 TOX_SAVEDATA_TYPE_SECRET_KEY, 470 471 } TOX_SAVEDATA_TYPE; 472 473 474 /** 475 * Severity level of log messages. 476 * 477 * @deprecated All UPPER_CASE enum type names are deprecated. Use the 478 * Camel_Snake_Case versions, instead. 479 */ 480 typedef enum TOX_LOG_LEVEL { 481 482 /** 483 * Very detailed traces including all network activity. 484 */ 485 TOX_LOG_LEVEL_TRACE, 486 487 /** 488 * Debug messages such as which port we bind to. 489 */ 490 TOX_LOG_LEVEL_DEBUG, 491 492 /** 493 * Informational log messages such as video call status changes. 494 */ 495 TOX_LOG_LEVEL_INFO, 496 497 /** 498 * Warnings about internal inconsistency or logic errors. 499 */ 500 TOX_LOG_LEVEL_WARNING, 501 502 /** 503 * Severe unexpected errors caused by external or internal inconsistency. 504 */ 505 TOX_LOG_LEVEL_ERROR, 506 507 } TOX_LOG_LEVEL; 508 509 510 /** 511 * This event is triggered when the toxcore library logs an internal message. 512 * This is mostly useful for debugging. This callback can be called from any 513 * function, not just tox_iterate. This means the user data lifetime must at 514 * least extend between registering and unregistering it or tox_kill. 515 * 516 * Other toxcore modules such as toxav may concurrently call this callback at 517 * any time. Thus, user code must make sure it is equipped to handle concurrent 518 * execution, e.g. by employing appropriate mutex locking. 519 * 520 * @param level The severity of the log message. 521 * @param file The source file from which the message originated. 522 * @param line The source line from which the message originated. 523 * @param func The function from which the message originated. 524 * @param message The log message. 525 * @param user_data The user data pointer passed to tox_new in options. 526 */ 527 typedef void tox_log_cb(Tox *tox, TOX_LOG_LEVEL level, const char *file, uint32_t line, const char *func, 528 const char *message, void *user_data); 529 530 531 /** 532 * This struct contains all the startup options for Tox. You must tox_options_new to 533 * allocate an object of this type. 534 * 535 * WARNING: Although this struct happens to be visible in the API, it is 536 * effectively private. Do not allocate this yourself or access members 537 * directly, as it *will* break binary compatibility frequently. 538 * 539 * @deprecated The memory layout of this struct (size, alignment, and field 540 * order) is not part of the ABI. To remain compatible, prefer to use tox_options_new to 541 * allocate the object and accessor functions to set the members. The struct 542 * will become opaque (i.e. the definition will become private) in v0.3.0. 543 */ 544 struct Tox_Options { 545 546 /** 547 * The type of socket to create. 548 * 549 * If this is set to false, an IPv4 socket is created, which subsequently 550 * only allows IPv4 communication. 551 * If it is set to true, an IPv6 socket is created, allowing both IPv4 and 552 * IPv6 communication. 553 */ 554 bool ipv6_enabled; 555 556 557 /** 558 * Enable the use of UDP communication when available. 559 * 560 * Setting this to false will force Tox to use TCP only. Communications will 561 * need to be relayed through a TCP relay node, potentially slowing them down. 562 * 563 * If a proxy is enabled, UDP will be disabled if either toxcore or the 564 * proxy don't support proxying UDP messages. 565 */ 566 bool udp_enabled; 567 568 569 /** 570 * Enable local network peer discovery. 571 * 572 * Disabling this will cause Tox to not look for peers on the local network. 573 */ 574 bool local_discovery_enabled; 575 576 577 /** 578 * Pass communications through a proxy. 579 */ 580 TOX_PROXY_TYPE proxy_type; 581 582 583 /** 584 * The IP address or DNS name of the proxy to be used. 585 * 586 * If used, this must be non-NULL and be a valid DNS name. The name must not 587 * exceed TOX_MAX_HOSTNAME_LENGTH characters, and be in a NUL-terminated C string 588 * format (TOX_MAX_HOSTNAME_LENGTH includes the NUL byte). 589 * 590 * This member is ignored (it can be NULL) if proxy_type is TOX_PROXY_TYPE_NONE. 591 * 592 * The data pointed at by this member is owned by the user, so must 593 * outlive the options object. 594 */ 595 const char *proxy_host; 596 597 598 /** 599 * The port to use to connect to the proxy server. 600 * 601 * Ports must be in the range (1, 65535). The value is ignored if 602 * proxy_type is TOX_PROXY_TYPE_NONE. 603 */ 604 uint16_t proxy_port; 605 606 607 /** 608 * The start port of the inclusive port range to attempt to use. 609 * 610 * If both start_port and end_port are 0, the default port range will be 611 * used: [33445, 33545]. 612 * 613 * If either start_port or end_port is 0 while the other is non-zero, the 614 * non-zero port will be the only port in the range. 615 * 616 * Having start_port > end_port will yield the same behavior as if start_port 617 * and end_port were swapped. 618 */ 619 uint16_t start_port; 620 621 622 /** 623 * The end port of the inclusive port range to attempt to use. 624 */ 625 uint16_t end_port; 626 627 628 /** 629 * The port to use for the TCP server (relay). If 0, the TCP server is 630 * disabled. 631 * 632 * Enabling it is not required for Tox to function properly. 633 * 634 * When enabled, your Tox instance can act as a TCP relay for other Tox 635 * instance. This leads to increased traffic, thus when writing a client 636 * it is recommended to enable TCP server only if the user has an option 637 * to disable it. 638 */ 639 uint16_t tcp_port; 640 641 642 /** 643 * Enables or disables UDP hole-punching in toxcore. (Default: enabled). 644 */ 645 bool hole_punching_enabled; 646 647 648 /** 649 * The type of savedata to load from. 650 */ 651 TOX_SAVEDATA_TYPE savedata_type; 652 653 654 /** 655 * The savedata. 656 * 657 * The data pointed at by this member is owned by the user, so must 658 * outlive the options object. 659 */ 660 const uint8_t *savedata_data; 661 662 663 /** 664 * The length of the savedata. 665 */ 666 size_t savedata_length; 667 668 669 /** 670 * Logging callback for the new tox instance. 671 */ 672 tox_log_cb *log_callback; 673 674 675 /** 676 * User data pointer passed to the logging callback. 677 */ 678 void *log_user_data; 679 680 681 /** 682 * These options are experimental, so avoid writing code that depends on 683 * them. Options marked "experimental" may change their behaviour or go away 684 * entirely in the future, or may be renamed to something non-experimental 685 * if they become part of the supported API. 686 */ 687 /** 688 * Make public API functions thread-safe using a per-instance lock. 689 * 690 * Default: false. 691 */ 692 bool experimental_thread_safety; 693 694 }; 695 696 697 bool tox_options_get_ipv6_enabled(const struct Tox_Options *options); 698 699 void tox_options_set_ipv6_enabled(struct Tox_Options *options, bool ipv6_enabled); 700 701 bool tox_options_get_udp_enabled(const struct Tox_Options *options); 702 703 void tox_options_set_udp_enabled(struct Tox_Options *options, bool udp_enabled); 704 705 bool tox_options_get_local_discovery_enabled(const struct Tox_Options *options); 706 707 void tox_options_set_local_discovery_enabled(struct Tox_Options *options, bool local_discovery_enabled); 708 709 TOX_PROXY_TYPE tox_options_get_proxy_type(const struct Tox_Options *options); 710 711 void tox_options_set_proxy_type(struct Tox_Options *options, TOX_PROXY_TYPE type); 712 713 const char *tox_options_get_proxy_host(const struct Tox_Options *options); 714 715 void tox_options_set_proxy_host(struct Tox_Options *options, const char *host); 716 717 uint16_t tox_options_get_proxy_port(const struct Tox_Options *options); 718 719 void tox_options_set_proxy_port(struct Tox_Options *options, uint16_t port); 720 721 uint16_t tox_options_get_start_port(const struct Tox_Options *options); 722 723 void tox_options_set_start_port(struct Tox_Options *options, uint16_t start_port); 724 725 uint16_t tox_options_get_end_port(const struct Tox_Options *options); 726 727 void tox_options_set_end_port(struct Tox_Options *options, uint16_t end_port); 728 729 uint16_t tox_options_get_tcp_port(const struct Tox_Options *options); 730 731 void tox_options_set_tcp_port(struct Tox_Options *options, uint16_t tcp_port); 732 733 bool tox_options_get_hole_punching_enabled(const struct Tox_Options *options); 734 735 void tox_options_set_hole_punching_enabled(struct Tox_Options *options, bool hole_punching_enabled); 736 737 TOX_SAVEDATA_TYPE tox_options_get_savedata_type(const struct Tox_Options *options); 738 739 void tox_options_set_savedata_type(struct Tox_Options *options, TOX_SAVEDATA_TYPE type); 740 741 const uint8_t *tox_options_get_savedata_data(const struct Tox_Options *options); 742 743 void tox_options_set_savedata_data(struct Tox_Options *options, const uint8_t *data, size_t length); 744 745 size_t tox_options_get_savedata_length(const struct Tox_Options *options); 746 747 void tox_options_set_savedata_length(struct Tox_Options *options, size_t length); 748 749 tox_log_cb *tox_options_get_log_callback(const struct Tox_Options *options); 750 751 void tox_options_set_log_callback(struct Tox_Options *options, tox_log_cb *callback); 752 753 void *tox_options_get_log_user_data(const struct Tox_Options *options); 754 755 void tox_options_set_log_user_data(struct Tox_Options *options, void *user_data); 756 757 bool tox_options_get_experimental_thread_safety(const struct Tox_Options *options); 758 759 void tox_options_set_experimental_thread_safety(struct Tox_Options *options, bool thread_safety); 760 761 /** 762 * Initialises a Tox_Options object with the default options. 763 * 764 * The result of this function is independent of the original options. All 765 * values will be overwritten, no values will be read (so it is permissible 766 * to pass an uninitialised object). 767 * 768 * If options is NULL, this function has no effect. 769 * 770 * @param options An options object to be filled with default options. 771 */ 772 void tox_options_default(struct Tox_Options *options); 773 774 typedef enum TOX_ERR_OPTIONS_NEW { 775 776 /** 777 * The function returned successfully. 778 */ 779 TOX_ERR_OPTIONS_NEW_OK, 780 781 /** 782 * The function failed to allocate enough memory for the options struct. 783 */ 784 TOX_ERR_OPTIONS_NEW_MALLOC, 785 786 } TOX_ERR_OPTIONS_NEW; 787 788 789 /** 790 * Allocates a new Tox_Options object and initialises it with the default 791 * options. This function can be used to preserve long term ABI compatibility by 792 * giving the responsibility of allocation and deallocation to the Tox library. 793 * 794 * Objects returned from this function must be freed using the tox_options_free 795 * function. 796 * 797 * @return A new Tox_Options object with default options or NULL on failure. 798 */ 799 struct Tox_Options *tox_options_new(TOX_ERR_OPTIONS_NEW *error); 800 801 /** 802 * Releases all resources associated with an options objects. 803 * 804 * Passing a pointer that was not returned by tox_options_new results in 805 * undefined behaviour. 806 */ 807 void tox_options_free(struct Tox_Options *options); 808 809 810 /******************************************************************************* 811 * 812 * :: Creation and destruction 813 * 814 ******************************************************************************/ 815 816 817 818 typedef enum TOX_ERR_NEW { 819 820 /** 821 * The function returned successfully. 822 */ 823 TOX_ERR_NEW_OK, 824 825 /** 826 * One of the arguments to the function was NULL when it was not expected. 827 */ 828 TOX_ERR_NEW_NULL, 829 830 /** 831 * The function was unable to allocate enough memory to store the internal 832 * structures for the Tox object. 833 */ 834 TOX_ERR_NEW_MALLOC, 835 836 /** 837 * The function was unable to bind to a port. This may mean that all ports 838 * have already been bound, e.g. by other Tox instances, or it may mean 839 * a permission error. You may be able to gather more information from errno. 840 */ 841 TOX_ERR_NEW_PORT_ALLOC, 842 843 /** 844 * proxy_type was invalid. 845 */ 846 TOX_ERR_NEW_PROXY_BAD_TYPE, 847 848 /** 849 * proxy_type was valid but the proxy_host passed had an invalid format 850 * or was NULL. 851 */ 852 TOX_ERR_NEW_PROXY_BAD_HOST, 853 854 /** 855 * proxy_type was valid, but the proxy_port was invalid. 856 */ 857 TOX_ERR_NEW_PROXY_BAD_PORT, 858 859 /** 860 * The proxy address passed could not be resolved. 861 */ 862 TOX_ERR_NEW_PROXY_NOT_FOUND, 863 864 /** 865 * The byte array to be loaded contained an encrypted save. 866 */ 867 TOX_ERR_NEW_LOAD_ENCRYPTED, 868 869 /** 870 * The data format was invalid. This can happen when loading data that was 871 * saved by an older version of Tox, or when the data has been corrupted. 872 * When loading from badly formatted data, some data may have been loaded, 873 * and the rest is discarded. Passing an invalid length parameter also 874 * causes this error. 875 */ 876 TOX_ERR_NEW_LOAD_BAD_FORMAT, 877 878 } TOX_ERR_NEW; 879 880 881 /** 882 * @brief Creates and initialises a new Tox instance with the options passed. 883 * 884 * This function will bring the instance into a valid state. Running the event 885 * loop with a new instance will operate correctly. 886 * 887 * If loading failed or succeeded only partially, the new or partially loaded 888 * instance is returned and an error code is set. 889 * 890 * @param options An options object as described above. If this parameter is 891 * NULL, the default options are used. 892 * 893 * @see tox_iterate for the event loop. 894 * 895 * @return A new Tox instance pointer on success or NULL on failure. 896 */ 897 Tox *tox_new(const struct Tox_Options *options, TOX_ERR_NEW *error); 898 899 /** 900 * Releases all resources associated with the Tox instance and disconnects from 901 * the network. 902 * 903 * After calling this function, the Tox pointer becomes invalid. No other 904 * functions can be called, and the pointer value can no longer be read. 905 */ 906 void tox_kill(Tox *tox); 907 908 /** 909 * Calculates the number of bytes required to store the tox instance with 910 * tox_get_savedata. This function cannot fail. The result is always greater than 0. 911 * 912 * @see threading for concurrency implications. 913 */ 914 size_t tox_get_savedata_size(const Tox *tox); 915 916 /** 917 * Store all information associated with the tox instance to a byte array. 918 * 919 * @param savedata A memory region large enough to store the tox instance 920 * data. Call tox_get_savedata_size to find the number of bytes required. If this parameter 921 * is NULL, this function has no effect. 922 */ 923 void tox_get_savedata(const Tox *tox, uint8_t *savedata); 924 925 926 /******************************************************************************* 927 * 928 * :: Connection lifecycle and event loop 929 * 930 ******************************************************************************/ 931 932 933 934 typedef enum TOX_ERR_BOOTSTRAP { 935 936 /** 937 * The function returned successfully. 938 */ 939 TOX_ERR_BOOTSTRAP_OK, 940 941 /** 942 * One of the arguments to the function was NULL when it was not expected. 943 */ 944 TOX_ERR_BOOTSTRAP_NULL, 945 946 /** 947 * The hostname could not be resolved to an IP address, or the IP address 948 * passed was invalid. 949 */ 950 TOX_ERR_BOOTSTRAP_BAD_HOST, 951 952 /** 953 * The port passed was invalid. The valid port range is (1, 65535). 954 */ 955 TOX_ERR_BOOTSTRAP_BAD_PORT, 956 957 } TOX_ERR_BOOTSTRAP; 958 959 960 /** 961 * Sends a "get nodes" request to the given bootstrap node with IP, port, and 962 * public key to setup connections. 963 * 964 * This function will attempt to connect to the node using UDP. You must use 965 * this function even if Tox_Options.udp_enabled was set to false. 966 * 967 * @param host The hostname or IP address (IPv4 or IPv6) of the node. Must be 968 * at most TOX_MAX_HOSTNAME_LENGTH chars, including the NUL byte. 969 * @param port The port on the host on which the bootstrap Tox instance is 970 * listening. 971 * @param public_key The long term public key of the bootstrap node 972 * (TOX_PUBLIC_KEY_SIZE bytes). 973 * @return true on success. 974 */ 975 bool tox_bootstrap(Tox *tox, const char *host, uint16_t port, const uint8_t *public_key, TOX_ERR_BOOTSTRAP *error); 976 977 /** 978 * Adds additional host:port pair as TCP relay. 979 * 980 * This function can be used to initiate TCP connections to different ports on 981 * the same bootstrap node, or to add TCP relays without using them as 982 * bootstrap nodes. 983 * 984 * @param host The hostname or IP address (IPv4 or IPv6) of the TCP relay. 985 * Must be at most TOX_MAX_HOSTNAME_LENGTH chars, including the NUL byte. 986 * @param port The port on the host on which the TCP relay is listening. 987 * @param public_key The long term public key of the TCP relay 988 * (TOX_PUBLIC_KEY_SIZE bytes). 989 * @return true on success. 990 */ 991 bool tox_add_tcp_relay(Tox *tox, const char *host, uint16_t port, const uint8_t *public_key, TOX_ERR_BOOTSTRAP *error); 992 993 /** 994 * Protocols that can be used to connect to the network or friends. 995 * 996 * @deprecated All UPPER_CASE enum type names are deprecated. Use the 997 * Camel_Snake_Case versions, instead. 998 */ 999 typedef enum TOX_CONNECTION { 1000 1001 /** 1002 * There is no connection. This instance, or the friend the state change is 1003 * about, is now offline. 1004 */ 1005 TOX_CONNECTION_NONE, 1006 1007 /** 1008 * A TCP connection has been established. For the own instance, this means it 1009 * is connected through a TCP relay, only. For a friend, this means that the 1010 * connection to that particular friend goes through a TCP relay. 1011 */ 1012 TOX_CONNECTION_TCP, 1013 1014 /** 1015 * A UDP connection has been established. For the own instance, this means it 1016 * is able to send UDP packets to DHT nodes, but may still be connected to 1017 * a TCP relay. For a friend, this means that the connection to that 1018 * particular friend was built using direct UDP packets. 1019 */ 1020 TOX_CONNECTION_UDP, 1021 1022 } TOX_CONNECTION; 1023 1024 1025 /** 1026 * Return whether we are connected to the DHT. The return value is equal to the 1027 * last value received through the `self_connection_status` callback. 1028 * 1029 * @deprecated This getter is deprecated. Use the event and store the status 1030 * in the client state. 1031 */ 1032 TOX_CONNECTION tox_self_get_connection_status(const Tox *tox); 1033 1034 /** 1035 * @param connection_status Whether we are connected to the DHT. 1036 */ 1037 typedef void tox_self_connection_status_cb(Tox *tox, TOX_CONNECTION connection_status, void *user_data); 1038 1039 1040 /** 1041 * Set the callback for the `self_connection_status` event. Pass NULL to unset. 1042 * 1043 * This event is triggered whenever there is a change in the DHT connection 1044 * state. When disconnected, a client may choose to call tox_bootstrap again, to 1045 * reconnect to the DHT. Note that this state may frequently change for short 1046 * amounts of time. Clients should therefore not immediately bootstrap on 1047 * receiving a disconnect. 1048 * 1049 * TODO(iphydf): how long should a client wait before bootstrapping again? 1050 */ 1051 void tox_callback_self_connection_status(Tox *tox, tox_self_connection_status_cb *callback); 1052 1053 /** 1054 * Return the time in milliseconds before tox_iterate() should be called again 1055 * for optimal performance. 1056 */ 1057 uint32_t tox_iteration_interval(const Tox *tox); 1058 1059 /** 1060 * The main loop that needs to be run in intervals of tox_iteration_interval() 1061 * milliseconds. 1062 */ 1063 void tox_iterate(Tox *tox, void *user_data); 1064 1065 1066 /******************************************************************************* 1067 * 1068 * :: Internal client information (Tox address/id) 1069 * 1070 ******************************************************************************/ 1071 1072 1073 1074 /** 1075 * Writes the Tox friend address of the client to a byte array. The address is 1076 * not in human-readable format. If a client wants to display the address, 1077 * formatting is required. 1078 * 1079 * @param address A memory region of at least TOX_ADDRESS_SIZE bytes. If this 1080 * parameter is NULL, this function has no effect. 1081 * @see TOX_ADDRESS_SIZE for the address format. 1082 */ 1083 void tox_self_get_address(const Tox *tox, uint8_t *address); 1084 1085 /** 1086 * Set the 4-byte nospam part of the address. This value is expected in host 1087 * byte order. I.e. 0x12345678 will form the bytes [12, 34, 56, 78] in the 1088 * nospam part of the Tox friend address. 1089 * 1090 * @param nospam Any 32 bit unsigned integer. 1091 */ 1092 void tox_self_set_nospam(Tox *tox, uint32_t nospam); 1093 1094 /** 1095 * Get the 4-byte nospam part of the address. This value is returned in host 1096 * byte order. 1097 */ 1098 uint32_t tox_self_get_nospam(const Tox *tox); 1099 1100 /** 1101 * Copy the Tox Public Key (long term) from the Tox object. 1102 * 1103 * @param public_key A memory region of at least TOX_PUBLIC_KEY_SIZE bytes. If 1104 * this parameter is NULL, this function has no effect. 1105 */ 1106 void tox_self_get_public_key(const Tox *tox, uint8_t *public_key); 1107 1108 /** 1109 * Copy the Tox Secret Key from the Tox object. 1110 * 1111 * @param secret_key A memory region of at least TOX_SECRET_KEY_SIZE bytes. If 1112 * this parameter is NULL, this function has no effect. 1113 */ 1114 void tox_self_get_secret_key(const Tox *tox, uint8_t *secret_key); 1115 1116 1117 /******************************************************************************* 1118 * 1119 * :: User-visible client information (nickname/status) 1120 * 1121 ******************************************************************************/ 1122 1123 1124 1125 /** 1126 * Common error codes for all functions that set a piece of user-visible 1127 * client information. 1128 */ 1129 typedef enum TOX_ERR_SET_INFO { 1130 1131 /** 1132 * The function returned successfully. 1133 */ 1134 TOX_ERR_SET_INFO_OK, 1135 1136 /** 1137 * One of the arguments to the function was NULL when it was not expected. 1138 */ 1139 TOX_ERR_SET_INFO_NULL, 1140 1141 /** 1142 * Information length exceeded maximum permissible size. 1143 */ 1144 TOX_ERR_SET_INFO_TOO_LONG, 1145 1146 } TOX_ERR_SET_INFO; 1147 1148 1149 /** 1150 * Set the nickname for the Tox client. 1151 * 1152 * Nickname length cannot exceed TOX_MAX_NAME_LENGTH. If length is 0, the name 1153 * parameter is ignored (it can be NULL), and the nickname is set back to empty. 1154 * 1155 * @param name A byte array containing the new nickname. 1156 * @param length The size of the name byte array. 1157 * 1158 * @return true on success. 1159 */ 1160 bool tox_self_set_name(Tox *tox, const uint8_t *name, size_t length, TOX_ERR_SET_INFO *error); 1161 1162 /** 1163 * Return the length of the current nickname as passed to tox_self_set_name. 1164 * 1165 * If no nickname was set before calling this function, the name is empty, 1166 * and this function returns 0. 1167 * 1168 * @see threading for concurrency implications. 1169 */ 1170 size_t tox_self_get_name_size(const Tox *tox); 1171 1172 /** 1173 * Write the nickname set by tox_self_set_name to a byte array. 1174 * 1175 * If no nickname was set before calling this function, the name is empty, 1176 * and this function has no effect. 1177 * 1178 * Call tox_self_get_name_size to find out how much memory to allocate for 1179 * the result. 1180 * 1181 * @param name A valid memory location large enough to hold the nickname. 1182 * If this parameter is NULL, the function has no effect. 1183 */ 1184 void tox_self_get_name(const Tox *tox, uint8_t *name); 1185 1186 /** 1187 * Set the client's status message. 1188 * 1189 * Status message length cannot exceed TOX_MAX_STATUS_MESSAGE_LENGTH. If 1190 * length is 0, the status parameter is ignored (it can be NULL), and the 1191 * user status is set back to empty. 1192 */ 1193 bool tox_self_set_status_message(Tox *tox, const uint8_t *status_message, size_t length, TOX_ERR_SET_INFO *error); 1194 1195 /** 1196 * Return the length of the current status message as passed to tox_self_set_status_message. 1197 * 1198 * If no status message was set before calling this function, the status 1199 * is empty, and this function returns 0. 1200 * 1201 * @see threading for concurrency implications. 1202 */ 1203 size_t tox_self_get_status_message_size(const Tox *tox); 1204 1205 /** 1206 * Write the status message set by tox_self_set_status_message to a byte array. 1207 * 1208 * If no status message was set before calling this function, the status is 1209 * empty, and this function has no effect. 1210 * 1211 * Call tox_self_get_status_message_size to find out how much memory to allocate for 1212 * the result. 1213 * 1214 * @param status_message A valid memory location large enough to hold the 1215 * status message. If this parameter is NULL, the function has no effect. 1216 */ 1217 void tox_self_get_status_message(const Tox *tox, uint8_t *status_message); 1218 1219 /** 1220 * Set the client's user status. 1221 * 1222 * @param status One of the user statuses listed in the enumeration above. 1223 */ 1224 void tox_self_set_status(Tox *tox, TOX_USER_STATUS status); 1225 1226 /** 1227 * Returns the client's user status. 1228 */ 1229 TOX_USER_STATUS tox_self_get_status(const Tox *tox); 1230 1231 1232 /******************************************************************************* 1233 * 1234 * :: Friend list management 1235 * 1236 ******************************************************************************/ 1237 1238 1239 1240 typedef enum TOX_ERR_FRIEND_ADD { 1241 1242 /** 1243 * The function returned successfully. 1244 */ 1245 TOX_ERR_FRIEND_ADD_OK, 1246 1247 /** 1248 * One of the arguments to the function was NULL when it was not expected. 1249 */ 1250 TOX_ERR_FRIEND_ADD_NULL, 1251 1252 /** 1253 * The length of the friend request message exceeded 1254 * TOX_MAX_FRIEND_REQUEST_LENGTH. 1255 */ 1256 TOX_ERR_FRIEND_ADD_TOO_LONG, 1257 1258 /** 1259 * The friend request message was empty. This, and the TOO_LONG code will 1260 * never be returned from tox_friend_add_norequest. 1261 */ 1262 TOX_ERR_FRIEND_ADD_NO_MESSAGE, 1263 1264 /** 1265 * The friend address belongs to the sending client. 1266 */ 1267 TOX_ERR_FRIEND_ADD_OWN_KEY, 1268 1269 /** 1270 * A friend request has already been sent, or the address belongs to a friend 1271 * that is already on the friend list. 1272 */ 1273 TOX_ERR_FRIEND_ADD_ALREADY_SENT, 1274 1275 /** 1276 * The friend address checksum failed. 1277 */ 1278 TOX_ERR_FRIEND_ADD_BAD_CHECKSUM, 1279 1280 /** 1281 * The friend was already there, but the nospam value was different. 1282 */ 1283 TOX_ERR_FRIEND_ADD_SET_NEW_NOSPAM, 1284 1285 /** 1286 * A memory allocation failed when trying to increase the friend list size. 1287 */ 1288 TOX_ERR_FRIEND_ADD_MALLOC, 1289 1290 } TOX_ERR_FRIEND_ADD; 1291 1292 1293 /** 1294 * Add a friend to the friend list and send a friend request. 1295 * 1296 * A friend request message must be at least 1 byte long and at most 1297 * TOX_MAX_FRIEND_REQUEST_LENGTH. 1298 * 1299 * Friend numbers are unique identifiers used in all functions that operate on 1300 * friends. Once added, a friend number is stable for the lifetime of the Tox 1301 * object. After saving the state and reloading it, the friend numbers may not 1302 * be the same as before. Deleting a friend creates a gap in the friend number 1303 * set, which is filled by the next adding of a friend. Any pattern in friend 1304 * numbers should not be relied on. 1305 * 1306 * If more than INT32_MAX friends are added, this function causes undefined 1307 * behaviour. 1308 * 1309 * @param address The address of the friend (returned by tox_self_get_address of 1310 * the friend you wish to add) it must be TOX_ADDRESS_SIZE bytes. 1311 * @param message The message that will be sent along with the friend request. 1312 * @param length The length of the data byte array. 1313 * 1314 * @return the friend number on success, an unspecified value on failure. 1315 */ 1316 uint32_t tox_friend_add(Tox *tox, const uint8_t *address, const uint8_t *message, size_t length, 1317 TOX_ERR_FRIEND_ADD *error); 1318 1319 /** 1320 * Add a friend without sending a friend request. 1321 * 1322 * This function is used to add a friend in response to a friend request. If the 1323 * client receives a friend request, it can be reasonably sure that the other 1324 * client added this client as a friend, eliminating the need for a friend 1325 * request. 1326 * 1327 * This function is also useful in a situation where both instances are 1328 * controlled by the same entity, so that this entity can perform the mutual 1329 * friend adding. In this case, there is no need for a friend request, either. 1330 * 1331 * @param public_key A byte array of length TOX_PUBLIC_KEY_SIZE containing the 1332 * Public Key (not the Address) of the friend to add. 1333 * 1334 * @return the friend number on success, an unspecified value on failure. 1335 * @see tox_friend_add for a more detailed description of friend numbers. 1336 */ 1337 uint32_t tox_friend_add_norequest(Tox *tox, const uint8_t *public_key, TOX_ERR_FRIEND_ADD *error); 1338 1339 typedef enum TOX_ERR_FRIEND_DELETE { 1340 1341 /** 1342 * The function returned successfully. 1343 */ 1344 TOX_ERR_FRIEND_DELETE_OK, 1345 1346 /** 1347 * There was no friend with the given friend number. No friends were deleted. 1348 */ 1349 TOX_ERR_FRIEND_DELETE_FRIEND_NOT_FOUND, 1350 1351 } TOX_ERR_FRIEND_DELETE; 1352 1353 1354 /** 1355 * Remove a friend from the friend list. 1356 * 1357 * This does not notify the friend of their deletion. After calling this 1358 * function, this client will appear offline to the friend and no communication 1359 * can occur between the two. 1360 * 1361 * @param friend_number Friend number for the friend to be deleted. 1362 * 1363 * @return true on success. 1364 */ 1365 bool tox_friend_delete(Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_DELETE *error); 1366 1367 1368 /******************************************************************************* 1369 * 1370 * :: Friend list queries 1371 * 1372 ******************************************************************************/ 1373 1374 1375 1376 typedef enum TOX_ERR_FRIEND_BY_PUBLIC_KEY { 1377 1378 /** 1379 * The function returned successfully. 1380 */ 1381 TOX_ERR_FRIEND_BY_PUBLIC_KEY_OK, 1382 1383 /** 1384 * One of the arguments to the function was NULL when it was not expected. 1385 */ 1386 TOX_ERR_FRIEND_BY_PUBLIC_KEY_NULL, 1387 1388 /** 1389 * No friend with the given Public Key exists on the friend list. 1390 */ 1391 TOX_ERR_FRIEND_BY_PUBLIC_KEY_NOT_FOUND, 1392 1393 } TOX_ERR_FRIEND_BY_PUBLIC_KEY; 1394 1395 1396 /** 1397 * Return the friend number associated with that Public Key. 1398 * 1399 * @return the friend number on success, an unspecified value on failure. 1400 * @param public_key A byte array containing the Public Key. 1401 */ 1402 uint32_t tox_friend_by_public_key(const Tox *tox, const uint8_t *public_key, TOX_ERR_FRIEND_BY_PUBLIC_KEY *error); 1403 1404 /** 1405 * Checks if a friend with the given friend number exists and returns true if 1406 * it does. 1407 */ 1408 bool tox_friend_exists(const Tox *tox, uint32_t friend_number); 1409 1410 /** 1411 * Return the number of friends on the friend list. 1412 * 1413 * This function can be used to determine how much memory to allocate for 1414 * tox_self_get_friend_list. 1415 */ 1416 size_t tox_self_get_friend_list_size(const Tox *tox); 1417 1418 /** 1419 * Copy a list of valid friend numbers into an array. 1420 * 1421 * Call tox_self_get_friend_list_size to determine the number of elements to allocate. 1422 * 1423 * @param friend_list A memory region with enough space to hold the friend 1424 * list. If this parameter is NULL, this function has no effect. 1425 */ 1426 void tox_self_get_friend_list(const Tox *tox, uint32_t *friend_list); 1427 1428 typedef enum TOX_ERR_FRIEND_GET_PUBLIC_KEY { 1429 1430 /** 1431 * The function returned successfully. 1432 */ 1433 TOX_ERR_FRIEND_GET_PUBLIC_KEY_OK, 1434 1435 /** 1436 * No friend with the given number exists on the friend list. 1437 */ 1438 TOX_ERR_FRIEND_GET_PUBLIC_KEY_FRIEND_NOT_FOUND, 1439 1440 } TOX_ERR_FRIEND_GET_PUBLIC_KEY; 1441 1442 1443 /** 1444 * Copies the Public Key associated with a given friend number to a byte array. 1445 * 1446 * @param friend_number The friend number you want the Public Key of. 1447 * @param public_key A memory region of at least TOX_PUBLIC_KEY_SIZE bytes. If 1448 * this parameter is NULL, this function has no effect. 1449 * 1450 * @return true on success. 1451 */ 1452 bool tox_friend_get_public_key(const Tox *tox, uint32_t friend_number, uint8_t *public_key, 1453 TOX_ERR_FRIEND_GET_PUBLIC_KEY *error); 1454 1455 typedef enum TOX_ERR_FRIEND_GET_LAST_ONLINE { 1456 1457 /** 1458 * The function returned successfully. 1459 */ 1460 TOX_ERR_FRIEND_GET_LAST_ONLINE_OK, 1461 1462 /** 1463 * No friend with the given number exists on the friend list. 1464 */ 1465 TOX_ERR_FRIEND_GET_LAST_ONLINE_FRIEND_NOT_FOUND, 1466 1467 } TOX_ERR_FRIEND_GET_LAST_ONLINE; 1468 1469 1470 /** 1471 * Return a unix-time timestamp of the last time the friend associated with a given 1472 * friend number was seen online. This function will return UINT64_MAX on error. 1473 * 1474 * @param friend_number The friend number you want to query. 1475 */ 1476 uint64_t tox_friend_get_last_online(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_GET_LAST_ONLINE *error); 1477 1478 1479 /******************************************************************************* 1480 * 1481 * :: Friend-specific state queries (can also be received through callbacks) 1482 * 1483 ******************************************************************************/ 1484 1485 1486 1487 /** 1488 * Common error codes for friend state query functions. 1489 */ 1490 typedef enum TOX_ERR_FRIEND_QUERY { 1491 1492 /** 1493 * The function returned successfully. 1494 */ 1495 TOX_ERR_FRIEND_QUERY_OK, 1496 1497 /** 1498 * The pointer parameter for storing the query result (name, message) was 1499 * NULL. Unlike the `_self_` variants of these functions, which have no effect 1500 * when a parameter is NULL, these functions return an error in that case. 1501 */ 1502 TOX_ERR_FRIEND_QUERY_NULL, 1503 1504 /** 1505 * The friend_number did not designate a valid friend. 1506 */ 1507 TOX_ERR_FRIEND_QUERY_FRIEND_NOT_FOUND, 1508 1509 } TOX_ERR_FRIEND_QUERY; 1510 1511 1512 /** 1513 * Return the length of the friend's name. If the friend number is invalid, the 1514 * return value is unspecified. 1515 * 1516 * The return value is equal to the `length` argument received by the last 1517 * `friend_name` callback. 1518 */ 1519 size_t tox_friend_get_name_size(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); 1520 1521 /** 1522 * Write the name of the friend designated by the given friend number to a byte 1523 * array. 1524 * 1525 * Call tox_friend_get_name_size to determine the allocation size for the `name` 1526 * parameter. 1527 * 1528 * The data written to `name` is equal to the data received by the last 1529 * `friend_name` callback. 1530 * 1531 * @param name A valid memory region large enough to store the friend's name. 1532 * 1533 * @return true on success. 1534 */ 1535 bool tox_friend_get_name(const Tox *tox, uint32_t friend_number, uint8_t *name, TOX_ERR_FRIEND_QUERY *error); 1536 1537 /** 1538 * @param friend_number The friend number of the friend whose name changed. 1539 * @param name A byte array containing the same data as 1540 * tox_friend_get_name would write to its `name` parameter. 1541 * @param length A value equal to the return value of 1542 * tox_friend_get_name_size. 1543 */ 1544 typedef void tox_friend_name_cb(Tox *tox, uint32_t friend_number, const uint8_t *name, size_t length, void *user_data); 1545 1546 1547 /** 1548 * Set the callback for the `friend_name` event. Pass NULL to unset. 1549 * 1550 * This event is triggered when a friend changes their name. 1551 */ 1552 void tox_callback_friend_name(Tox *tox, tox_friend_name_cb *callback); 1553 1554 /** 1555 * Return the length of the friend's status message. If the friend number is 1556 * invalid, the return value is SIZE_MAX. 1557 */ 1558 size_t tox_friend_get_status_message_size(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); 1559 1560 /** 1561 * Write the status message of the friend designated by the given friend number to a byte 1562 * array. 1563 * 1564 * Call tox_friend_get_status_message_size to determine the allocation size for the `status_message` 1565 * parameter. 1566 * 1567 * The data written to `status_message` is equal to the data received by the last 1568 * `friend_status_message` callback. 1569 * 1570 * @param status_message A valid memory region large enough to store the friend's status message. 1571 */ 1572 bool tox_friend_get_status_message(const Tox *tox, uint32_t friend_number, uint8_t *status_message, 1573 TOX_ERR_FRIEND_QUERY *error); 1574 1575 /** 1576 * @param friend_number The friend number of the friend whose status message 1577 * changed. 1578 * @param message A byte array containing the same data as 1579 * tox_friend_get_status_message would write to its `status_message` parameter. 1580 * @param length A value equal to the return value of 1581 * tox_friend_get_status_message_size. 1582 */ 1583 typedef void tox_friend_status_message_cb(Tox *tox, uint32_t friend_number, const uint8_t *message, size_t length, 1584 void *user_data); 1585 1586 1587 /** 1588 * Set the callback for the `friend_status_message` event. Pass NULL to unset. 1589 * 1590 * This event is triggered when a friend changes their status message. 1591 */ 1592 void tox_callback_friend_status_message(Tox *tox, tox_friend_status_message_cb *callback); 1593 1594 /** 1595 * Return the friend's user status (away/busy/...). If the friend number is 1596 * invalid, the return value is unspecified. 1597 * 1598 * The status returned is equal to the last status received through the 1599 * `friend_status` callback. 1600 * 1601 * @deprecated This getter is deprecated. Use the event and store the status 1602 * in the client state. 1603 */ 1604 TOX_USER_STATUS tox_friend_get_status(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); 1605 1606 /** 1607 * @param friend_number The friend number of the friend whose user status 1608 * changed. 1609 * @param status The new user status. 1610 */ 1611 typedef void tox_friend_status_cb(Tox *tox, uint32_t friend_number, TOX_USER_STATUS status, void *user_data); 1612 1613 1614 /** 1615 * Set the callback for the `friend_status` event. Pass NULL to unset. 1616 * 1617 * This event is triggered when a friend changes their user status. 1618 */ 1619 void tox_callback_friend_status(Tox *tox, tox_friend_status_cb *callback); 1620 1621 /** 1622 * Check whether a friend is currently connected to this client. 1623 * 1624 * The result of this function is equal to the last value received by the 1625 * `friend_connection_status` callback. 1626 * 1627 * @param friend_number The friend number for which to query the connection 1628 * status. 1629 * 1630 * @return the friend's connection status as it was received through the 1631 * `friend_connection_status` event. 1632 * 1633 * @deprecated This getter is deprecated. Use the event and store the status 1634 * in the client state. 1635 */ 1636 TOX_CONNECTION tox_friend_get_connection_status(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); 1637 1638 /** 1639 * @param friend_number The friend number of the friend whose connection status 1640 * changed. 1641 * @param connection_status The result of calling 1642 * tox_friend_get_connection_status on the passed friend_number. 1643 */ 1644 typedef void tox_friend_connection_status_cb(Tox *tox, uint32_t friend_number, TOX_CONNECTION connection_status, 1645 void *user_data); 1646 1647 1648 /** 1649 * Set the callback for the `friend_connection_status` event. Pass NULL to unset. 1650 * 1651 * This event is triggered when a friend goes offline after having been online, 1652 * or when a friend goes online. 1653 * 1654 * This callback is not called when adding friends. It is assumed that when 1655 * adding friends, their connection status is initially offline. 1656 */ 1657 void tox_callback_friend_connection_status(Tox *tox, tox_friend_connection_status_cb *callback); 1658 1659 /** 1660 * Check whether a friend is currently typing a message. 1661 * 1662 * @param friend_number The friend number for which to query the typing status. 1663 * 1664 * @return true if the friend is typing. 1665 * @return false if the friend is not typing, or the friend number was 1666 * invalid. Inspect the error code to determine which case it is. 1667 * 1668 * @deprecated This getter is deprecated. Use the event and store the status 1669 * in the client state. 1670 */ 1671 bool tox_friend_get_typing(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); 1672 1673 /** 1674 * @param friend_number The friend number of the friend who started or stopped 1675 * typing. 1676 * @param is_typing The result of calling tox_friend_get_typing on the passed 1677 * friend_number. 1678 */ 1679 typedef void tox_friend_typing_cb(Tox *tox, uint32_t friend_number, bool is_typing, void *user_data); 1680 1681 1682 /** 1683 * Set the callback for the `friend_typing` event. Pass NULL to unset. 1684 * 1685 * This event is triggered when a friend starts or stops typing. 1686 */ 1687 void tox_callback_friend_typing(Tox *tox, tox_friend_typing_cb *callback); 1688 1689 1690 /******************************************************************************* 1691 * 1692 * :: Sending private messages 1693 * 1694 ******************************************************************************/ 1695 1696 1697 1698 typedef enum TOX_ERR_SET_TYPING { 1699 1700 /** 1701 * The function returned successfully. 1702 */ 1703 TOX_ERR_SET_TYPING_OK, 1704 1705 /** 1706 * The friend number did not designate a valid friend. 1707 */ 1708 TOX_ERR_SET_TYPING_FRIEND_NOT_FOUND, 1709 1710 } TOX_ERR_SET_TYPING; 1711 1712 1713 /** 1714 * Set the client's typing status for a friend. 1715 * 1716 * The client is responsible for turning it on or off. 1717 * 1718 * @param friend_number The friend to which the client is typing a message. 1719 * @param typing The typing status. True means the client is typing. 1720 * 1721 * @return true on success. 1722 */ 1723 bool tox_self_set_typing(Tox *tox, uint32_t friend_number, bool typing, TOX_ERR_SET_TYPING *error); 1724 1725 typedef enum TOX_ERR_FRIEND_SEND_MESSAGE { 1726 1727 /** 1728 * The function returned successfully. 1729 */ 1730 TOX_ERR_FRIEND_SEND_MESSAGE_OK, 1731 1732 /** 1733 * One of the arguments to the function was NULL when it was not expected. 1734 */ 1735 TOX_ERR_FRIEND_SEND_MESSAGE_NULL, 1736 1737 /** 1738 * The friend number did not designate a valid friend. 1739 */ 1740 TOX_ERR_FRIEND_SEND_MESSAGE_FRIEND_NOT_FOUND, 1741 1742 /** 1743 * This client is currently not connected to the friend. 1744 */ 1745 TOX_ERR_FRIEND_SEND_MESSAGE_FRIEND_NOT_CONNECTED, 1746 1747 /** 1748 * An allocation error occurred while increasing the send queue size. 1749 */ 1750 TOX_ERR_FRIEND_SEND_MESSAGE_SENDQ, 1751 1752 /** 1753 * Message length exceeded TOX_MAX_MESSAGE_LENGTH. 1754 */ 1755 TOX_ERR_FRIEND_SEND_MESSAGE_TOO_LONG, 1756 1757 /** 1758 * Attempted to send a zero-length message. 1759 */ 1760 TOX_ERR_FRIEND_SEND_MESSAGE_EMPTY, 1761 1762 } TOX_ERR_FRIEND_SEND_MESSAGE; 1763 1764 1765 /** 1766 * Send a text chat message to an online friend. 1767 * 1768 * This function creates a chat message packet and pushes it into the send 1769 * queue. 1770 * 1771 * The message length may not exceed TOX_MAX_MESSAGE_LENGTH. Larger messages 1772 * must be split by the client and sent as separate messages. Other clients can 1773 * then reassemble the fragments. Messages may not be empty. 1774 * 1775 * The return value of this function is the message ID. If a read receipt is 1776 * received, the triggered `friend_read_receipt` event will be passed this message ID. 1777 * 1778 * Message IDs are unique per friend. The first message ID is 0. Message IDs are 1779 * incremented by 1 each time a message is sent. If UINT32_MAX messages were 1780 * sent, the next message ID is 0. 1781 * 1782 * @param type Message type (normal, action, ...). 1783 * @param friend_number The friend number of the friend to send the message to. 1784 * @param message A non-NULL pointer to the first element of a byte array 1785 * containing the message text. 1786 * @param length Length of the message to be sent. 1787 */ 1788 uint32_t tox_friend_send_message(Tox *tox, uint32_t friend_number, TOX_MESSAGE_TYPE type, const uint8_t *message, 1789 size_t length, TOX_ERR_FRIEND_SEND_MESSAGE *error); 1790 1791 /** 1792 * @param friend_number The friend number of the friend who received the message. 1793 * @param message_id The message ID as returned from tox_friend_send_message 1794 * corresponding to the message sent. 1795 */ 1796 typedef void tox_friend_read_receipt_cb(Tox *tox, uint32_t friend_number, uint32_t message_id, void *user_data); 1797 1798 1799 /** 1800 * Set the callback for the `friend_read_receipt` event. Pass NULL to unset. 1801 * 1802 * This event is triggered when the friend receives the message sent with 1803 * tox_friend_send_message with the corresponding message ID. 1804 */ 1805 void tox_callback_friend_read_receipt(Tox *tox, tox_friend_read_receipt_cb *callback); 1806 1807 1808 /******************************************************************************* 1809 * 1810 * :: Receiving private messages and friend requests 1811 * 1812 ******************************************************************************/ 1813 1814 1815 1816 /** 1817 * @param public_key The Public Key of the user who sent the friend request. 1818 * @param message The message they sent along with the request. 1819 * @param length The size of the message byte array. 1820 */ 1821 typedef void tox_friend_request_cb(Tox *tox, const uint8_t *public_key, const uint8_t *message, size_t length, 1822 void *user_data); 1823 1824 1825 /** 1826 * Set the callback for the `friend_request` event. Pass NULL to unset. 1827 * 1828 * This event is triggered when a friend request is received. 1829 */ 1830 void tox_callback_friend_request(Tox *tox, tox_friend_request_cb *callback); 1831 1832 /** 1833 * @param friend_number The friend number of the friend who sent the message. 1834 * @param message The message data they sent. 1835 * @param length The size of the message byte array. 1836 */ 1837 typedef void tox_friend_message_cb(Tox *tox, uint32_t friend_number, TOX_MESSAGE_TYPE type, const uint8_t *message, 1838 size_t length, void *user_data); 1839 1840 1841 /** 1842 * Set the callback for the `friend_message` event. Pass NULL to unset. 1843 * 1844 * This event is triggered when a message from a friend is received. 1845 */ 1846 void tox_callback_friend_message(Tox *tox, tox_friend_message_cb *callback); 1847 1848 1849 /******************************************************************************* 1850 * 1851 * :: File transmission: common between sending and receiving 1852 * 1853 ******************************************************************************/ 1854 1855 1856 1857 /** 1858 * Generates a cryptographic hash of the given data. 1859 * 1860 * This function may be used by clients for any purpose, but is provided 1861 * primarily for validating cached avatars. This use is highly recommended to 1862 * avoid unnecessary avatar updates. 1863 * 1864 * If hash is NULL or data is NULL while length is not 0 the function returns false, 1865 * otherwise it returns true. 1866 * 1867 * This function is a wrapper to internal message-digest functions. 1868 * 1869 * @param hash A valid memory location the hash data. It must be at least 1870 * TOX_HASH_LENGTH bytes in size. 1871 * @param data Data to be hashed or NULL. 1872 * @param length Size of the data array or 0. 1873 * 1874 * @return true if hash was not NULL. 1875 */ 1876 bool tox_hash(uint8_t *hash, const uint8_t *data, size_t length); 1877 1878 /** 1879 * A list of pre-defined file kinds. Toxcore itself does not behave 1880 * differently for different file kinds. These are a hint to the client 1881 * telling it what use the sender intended for the file. The `kind` parameter 1882 * in the send function and recv callback are `uint32_t`, not TOX_FILE_KIND, because 1883 * clients can invent their own file kind. Unknown file kinds should be 1884 * treated as TOX_FILE_KIND_DATA. 1885 */ 1886 enum TOX_FILE_KIND { 1887 1888 /** 1889 * Arbitrary file data. Clients can choose to handle it based on the file name 1890 * or magic or any other way they choose. 1891 */ 1892 TOX_FILE_KIND_DATA, 1893 1894 /** 1895 * Avatar file_id. This consists of tox_hash(image). 1896 * Avatar data. This consists of the image data. 1897 * 1898 * Avatars can be sent at any time the client wishes. Generally, a client will 1899 * send the avatar to a friend when that friend comes online, and to all 1900 * friends when the avatar changed. A client can save some traffic by 1901 * remembering which friend received the updated avatar already and only send 1902 * it if the friend has an out of date avatar. 1903 * 1904 * Clients who receive avatar send requests can reject it (by sending 1905 * TOX_FILE_CONTROL_CANCEL before any other controls), or accept it (by 1906 * sending TOX_FILE_CONTROL_RESUME). The file_id of length TOX_HASH_LENGTH bytes 1907 * (same length as TOX_FILE_ID_LENGTH) will contain the hash. A client can compare 1908 * this hash with a saved hash and send TOX_FILE_CONTROL_CANCEL to terminate the avatar 1909 * transfer if it matches. 1910 * 1911 * When file_size is set to 0 in the transfer request it means that the client 1912 * has no avatar. 1913 */ 1914 TOX_FILE_KIND_AVATAR, 1915 1916 }; 1917 1918 1919 typedef enum TOX_FILE_CONTROL { 1920 1921 /** 1922 * Sent by the receiving side to accept a file send request. Also sent after a 1923 * TOX_FILE_CONTROL_PAUSE command to continue sending or receiving. 1924 */ 1925 TOX_FILE_CONTROL_RESUME, 1926 1927 /** 1928 * Sent by clients to pause the file transfer. The initial state of a file 1929 * transfer is always paused on the receiving side and running on the sending 1930 * side. If both the sending and receiving side pause the transfer, then both 1931 * need to send TOX_FILE_CONTROL_RESUME for the transfer to resume. 1932 */ 1933 TOX_FILE_CONTROL_PAUSE, 1934 1935 /** 1936 * Sent by the receiving side to reject a file send request before any other 1937 * commands are sent. Also sent by either side to terminate a file transfer. 1938 */ 1939 TOX_FILE_CONTROL_CANCEL, 1940 1941 } TOX_FILE_CONTROL; 1942 1943 1944 typedef enum TOX_ERR_FILE_CONTROL { 1945 1946 /** 1947 * The function returned successfully. 1948 */ 1949 TOX_ERR_FILE_CONTROL_OK, 1950 1951 /** 1952 * The friend_number passed did not designate a valid friend. 1953 */ 1954 TOX_ERR_FILE_CONTROL_FRIEND_NOT_FOUND, 1955 1956 /** 1957 * This client is currently not connected to the friend. 1958 */ 1959 TOX_ERR_FILE_CONTROL_FRIEND_NOT_CONNECTED, 1960 1961 /** 1962 * No file transfer with the given file number was found for the given friend. 1963 */ 1964 TOX_ERR_FILE_CONTROL_NOT_FOUND, 1965 1966 /** 1967 * A RESUME control was sent, but the file transfer is running normally. 1968 */ 1969 TOX_ERR_FILE_CONTROL_NOT_PAUSED, 1970 1971 /** 1972 * A RESUME control was sent, but the file transfer was paused by the other 1973 * party. Only the party that paused the transfer can resume it. 1974 */ 1975 TOX_ERR_FILE_CONTROL_DENIED, 1976 1977 /** 1978 * A PAUSE control was sent, but the file transfer was already paused. 1979 */ 1980 TOX_ERR_FILE_CONTROL_ALREADY_PAUSED, 1981 1982 /** 1983 * Packet queue is full. 1984 */ 1985 TOX_ERR_FILE_CONTROL_SENDQ, 1986 1987 } TOX_ERR_FILE_CONTROL; 1988 1989 1990 /** 1991 * Sends a file control command to a friend for a given file transfer. 1992 * 1993 * @param friend_number The friend number of the friend the file is being 1994 * transferred to or received from. 1995 * @param file_number The friend-specific identifier for the file transfer. 1996 * @param control The control command to send. 1997 * 1998 * @return true on success. 1999 */ 2000 bool tox_file_control(Tox *tox, uint32_t friend_number, uint32_t file_number, TOX_FILE_CONTROL control, 2001 TOX_ERR_FILE_CONTROL *error); 2002 2003 /** 2004 * When receiving TOX_FILE_CONTROL_CANCEL, the client should release the 2005 * resources associated with the file number and consider the transfer failed. 2006 * 2007 * @param friend_number The friend number of the friend who is sending the file. 2008 * @param file_number The friend-specific file number the data received is 2009 * associated with. 2010 * @param control The file control command received. 2011 */ 2012 typedef void tox_file_recv_control_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, TOX_FILE_CONTROL control, 2013 void *user_data); 2014 2015 2016 /** 2017 * Set the callback for the `file_recv_control` event. Pass NULL to unset. 2018 * 2019 * This event is triggered when a file control command is received from a 2020 * friend. 2021 */ 2022 void tox_callback_file_recv_control(Tox *tox, tox_file_recv_control_cb *callback); 2023 2024 typedef enum TOX_ERR_FILE_SEEK { 2025 2026 /** 2027 * The function returned successfully. 2028 */ 2029 TOX_ERR_FILE_SEEK_OK, 2030 2031 /** 2032 * The friend_number passed did not designate a valid friend. 2033 */ 2034 TOX_ERR_FILE_SEEK_FRIEND_NOT_FOUND, 2035 2036 /** 2037 * This client is currently not connected to the friend. 2038 */ 2039 TOX_ERR_FILE_SEEK_FRIEND_NOT_CONNECTED, 2040 2041 /** 2042 * No file transfer with the given file number was found for the given friend. 2043 */ 2044 TOX_ERR_FILE_SEEK_NOT_FOUND, 2045 2046 /** 2047 * File was not in a state where it could be seeked. 2048 */ 2049 TOX_ERR_FILE_SEEK_DENIED, 2050 2051 /** 2052 * Seek position was invalid 2053 */ 2054 TOX_ERR_FILE_SEEK_INVALID_POSITION, 2055 2056 /** 2057 * Packet queue is full. 2058 */ 2059 TOX_ERR_FILE_SEEK_SENDQ, 2060 2061 } TOX_ERR_FILE_SEEK; 2062 2063 2064 /** 2065 * Sends a file seek control command to a friend for a given file transfer. 2066 * 2067 * This function can only be called to resume a file transfer right before 2068 * TOX_FILE_CONTROL_RESUME is sent. 2069 * 2070 * @param friend_number The friend number of the friend the file is being 2071 * received from. 2072 * @param file_number The friend-specific identifier for the file transfer. 2073 * @param position The position that the file should be seeked to. 2074 */ 2075 bool tox_file_seek(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, TOX_ERR_FILE_SEEK *error); 2076 2077 typedef enum TOX_ERR_FILE_GET { 2078 2079 /** 2080 * The function returned successfully. 2081 */ 2082 TOX_ERR_FILE_GET_OK, 2083 2084 /** 2085 * One of the arguments to the function was NULL when it was not expected. 2086 */ 2087 TOX_ERR_FILE_GET_NULL, 2088 2089 /** 2090 * The friend_number passed did not designate a valid friend. 2091 */ 2092 TOX_ERR_FILE_GET_FRIEND_NOT_FOUND, 2093 2094 /** 2095 * No file transfer with the given file number was found for the given friend. 2096 */ 2097 TOX_ERR_FILE_GET_NOT_FOUND, 2098 2099 } TOX_ERR_FILE_GET; 2100 2101 2102 /** 2103 * Copy the file id associated to the file transfer to a byte array. 2104 * 2105 * @param friend_number The friend number of the friend the file is being 2106 * transferred to or received from. 2107 * @param file_number The friend-specific identifier for the file transfer. 2108 * @param file_id A memory region of at least TOX_FILE_ID_LENGTH bytes. If 2109 * this parameter is NULL, this function has no effect. 2110 * 2111 * @return true on success. 2112 */ 2113 bool tox_file_get_file_id(const Tox *tox, uint32_t friend_number, uint32_t file_number, uint8_t *file_id, 2114 TOX_ERR_FILE_GET *error); 2115 2116 2117 /******************************************************************************* 2118 * 2119 * :: File transmission: sending 2120 * 2121 ******************************************************************************/ 2122 2123 2124 2125 typedef enum TOX_ERR_FILE_SEND { 2126 2127 /** 2128 * The function returned successfully. 2129 */ 2130 TOX_ERR_FILE_SEND_OK, 2131 2132 /** 2133 * One of the arguments to the function was NULL when it was not expected. 2134 */ 2135 TOX_ERR_FILE_SEND_NULL, 2136 2137 /** 2138 * The friend_number passed did not designate a valid friend. 2139 */ 2140 TOX_ERR_FILE_SEND_FRIEND_NOT_FOUND, 2141 2142 /** 2143 * This client is currently not connected to the friend. 2144 */ 2145 TOX_ERR_FILE_SEND_FRIEND_NOT_CONNECTED, 2146 2147 /** 2148 * Filename length exceeded TOX_MAX_FILENAME_LENGTH bytes. 2149 */ 2150 TOX_ERR_FILE_SEND_NAME_TOO_LONG, 2151 2152 /** 2153 * Too many ongoing transfers. The maximum number of concurrent file transfers 2154 * is 256 per friend per direction (sending and receiving). 2155 */ 2156 TOX_ERR_FILE_SEND_TOO_MANY, 2157 2158 } TOX_ERR_FILE_SEND; 2159 2160 2161 /** 2162 * Send a file transmission request. 2163 * 2164 * Maximum filename length is TOX_MAX_FILENAME_LENGTH bytes. The filename 2165 * should generally just be a file name, not a path with directory names. 2166 * 2167 * If a non-UINT64_MAX file size is provided, it can be used by both sides to 2168 * determine the sending progress. File size can be set to UINT64_MAX for streaming 2169 * data of unknown size. 2170 * 2171 * File transmission occurs in chunks, which are requested through the 2172 * `file_chunk_request` event. 2173 * 2174 * When a friend goes offline, all file transfers associated with the friend are 2175 * purged from core. 2176 * 2177 * If the file contents change during a transfer, the behaviour is unspecified 2178 * in general. What will actually happen depends on the mode in which the file 2179 * was modified and how the client determines the file size. 2180 * 2181 * - If the file size was increased 2182 * - and sending mode was streaming (file_size = UINT64_MAX), the behaviour 2183 * will be as expected. 2184 * - and sending mode was file (file_size != UINT64_MAX), the 2185 * file_chunk_request callback will receive length = 0 when Core thinks 2186 * the file transfer has finished. If the client remembers the file size as 2187 * it was when sending the request, it will terminate the transfer normally. 2188 * If the client re-reads the size, it will think the friend cancelled the 2189 * transfer. 2190 * - If the file size was decreased 2191 * - and sending mode was streaming, the behaviour is as expected. 2192 * - and sending mode was file, the callback will return 0 at the new 2193 * (earlier) end-of-file, signalling to the friend that the transfer was 2194 * cancelled. 2195 * - If the file contents were modified 2196 * - at a position before the current read, the two files (local and remote) 2197 * will differ after the transfer terminates. 2198 * - at a position after the current read, the file transfer will succeed as 2199 * expected. 2200 * - In either case, both sides will regard the transfer as complete and 2201 * successful. 2202 * 2203 * @param friend_number The friend number of the friend the file send request 2204 * should be sent to. 2205 * @param kind The meaning of the file to be sent. 2206 * @param file_size Size in bytes of the file the client wants to send, UINT64_MAX if 2207 * unknown or streaming. 2208 * @param file_id A file identifier of length TOX_FILE_ID_LENGTH that can be used to 2209 * uniquely identify file transfers across core restarts. If NULL, a random one will 2210 * be generated by core. It can then be obtained by using tox_file_get_file_id(). 2211 * @param filename Name of the file. Does not need to be the actual name. This 2212 * name will be sent along with the file send request. 2213 * @param filename_length Size in bytes of the filename. 2214 * 2215 * @return A file number used as an identifier in subsequent callbacks. This 2216 * number is per friend. File numbers are reused after a transfer terminates. 2217 * On failure, this function returns an unspecified value. Any pattern in file numbers 2218 * should not be relied on. 2219 */ 2220 uint32_t tox_file_send(Tox *tox, uint32_t friend_number, uint32_t kind, uint64_t file_size, const uint8_t *file_id, 2221 const uint8_t *filename, size_t filename_length, TOX_ERR_FILE_SEND *error); 2222 2223 typedef enum TOX_ERR_FILE_SEND_CHUNK { 2224 2225 /** 2226 * The function returned successfully. 2227 */ 2228 TOX_ERR_FILE_SEND_CHUNK_OK, 2229 2230 /** 2231 * The length parameter was non-zero, but data was NULL. 2232 */ 2233 TOX_ERR_FILE_SEND_CHUNK_NULL, 2234 2235 /** 2236 * The friend_number passed did not designate a valid friend. 2237 */ 2238 TOX_ERR_FILE_SEND_CHUNK_FRIEND_NOT_FOUND, 2239 2240 /** 2241 * This client is currently not connected to the friend. 2242 */ 2243 TOX_ERR_FILE_SEND_CHUNK_FRIEND_NOT_CONNECTED, 2244 2245 /** 2246 * No file transfer with the given file number was found for the given friend. 2247 */ 2248 TOX_ERR_FILE_SEND_CHUNK_NOT_FOUND, 2249 2250 /** 2251 * File transfer was found but isn't in a transferring state: (paused, done, 2252 * broken, etc...) (happens only when not called from the request chunk callback). 2253 */ 2254 TOX_ERR_FILE_SEND_CHUNK_NOT_TRANSFERRING, 2255 2256 /** 2257 * Attempted to send more or less data than requested. The requested data size is 2258 * adjusted according to maximum transmission unit and the expected end of 2259 * the file. Trying to send less or more than requested will return this error. 2260 */ 2261 TOX_ERR_FILE_SEND_CHUNK_INVALID_LENGTH, 2262 2263 /** 2264 * Packet queue is full. 2265 */ 2266 TOX_ERR_FILE_SEND_CHUNK_SENDQ, 2267 2268 /** 2269 * Position parameter was wrong. 2270 */ 2271 TOX_ERR_FILE_SEND_CHUNK_WRONG_POSITION, 2272 2273 } TOX_ERR_FILE_SEND_CHUNK; 2274 2275 2276 /** 2277 * Send a chunk of file data to a friend. 2278 * 2279 * This function is called in response to the `file_chunk_request` callback. The 2280 * length parameter should be equal to the one received though the callback. 2281 * If it is zero, the transfer is assumed complete. For files with known size, 2282 * Core will know that the transfer is complete after the last byte has been 2283 * received, so it is not necessary (though not harmful) to send a zero-length 2284 * chunk to terminate. For streams, core will know that the transfer is finished 2285 * if a chunk with length less than the length requested in the callback is sent. 2286 * 2287 * @param friend_number The friend number of the receiving friend for this file. 2288 * @param file_number The file transfer identifier returned by tox_file_send. 2289 * @param position The file or stream position from which to continue reading. 2290 * @return true on success. 2291 */ 2292 bool tox_file_send_chunk(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, const uint8_t *data, 2293 size_t length, TOX_ERR_FILE_SEND_CHUNK *error); 2294 2295 /** 2296 * If the length parameter is 0, the file transfer is finished, and the client's 2297 * resources associated with the file number should be released. After a call 2298 * with zero length, the file number can be reused for future file transfers. 2299 * 2300 * If the requested position is not equal to the client's idea of the current 2301 * file or stream position, it will need to seek. In case of read-once streams, 2302 * the client should keep the last read chunk so that a seek back can be 2303 * supported. A seek-back only ever needs to read from the last requested chunk. 2304 * This happens when a chunk was requested, but the send failed. A seek-back 2305 * request can occur an arbitrary number of times for any given chunk. 2306 * 2307 * In response to receiving this callback, the client should call the function 2308 * `tox_file_send_chunk` with the requested chunk. If the number of bytes sent 2309 * through that function is zero, the file transfer is assumed complete. A 2310 * client must send the full length of data requested with this callback. 2311 * 2312 * @param friend_number The friend number of the receiving friend for this file. 2313 * @param file_number The file transfer identifier returned by tox_file_send. 2314 * @param position The file or stream position from which to continue reading. 2315 * @param length The number of bytes requested for the current chunk. 2316 */ 2317 typedef void tox_file_chunk_request_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, 2318 size_t length, void *user_data); 2319 2320 2321 /** 2322 * Set the callback for the `file_chunk_request` event. Pass NULL to unset. 2323 * 2324 * This event is triggered when Core is ready to send more file data. 2325 */ 2326 void tox_callback_file_chunk_request(Tox *tox, tox_file_chunk_request_cb *callback); 2327 2328 2329 /******************************************************************************* 2330 * 2331 * :: File transmission: receiving 2332 * 2333 ******************************************************************************/ 2334 2335 2336 2337 /** 2338 * The client should acquire resources to be associated with the file transfer. 2339 * Incoming file transfers start in the PAUSED state. After this callback 2340 * returns, a transfer can be rejected by sending a TOX_FILE_CONTROL_CANCEL 2341 * control command before any other control commands. It can be accepted by 2342 * sending TOX_FILE_CONTROL_RESUME. 2343 * 2344 * @param friend_number The friend number of the friend who is sending the file 2345 * transfer request. 2346 * @param file_number The friend-specific file number the data received is 2347 * associated with. 2348 * @param kind The meaning of the file that was sent. 2349 * @param file_size Size in bytes of the file the client wants to send, 2350 * UINT64_MAX if unknown or streaming. 2351 * @param filename Name of the file. Does not need to be the actual name. This 2352 * name will be sent along with the file send request. 2353 * @param filename_length Size in bytes of the filename. 2354 */ 2355 typedef void tox_file_recv_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, uint32_t kind, uint64_t file_size, 2356 const uint8_t *filename, size_t filename_length, void *user_data); 2357 2358 2359 /** 2360 * Set the callback for the `file_recv` event. Pass NULL to unset. 2361 * 2362 * This event is triggered when a file transfer request is received. 2363 */ 2364 void tox_callback_file_recv(Tox *tox, tox_file_recv_cb *callback); 2365 2366 /** 2367 * When length is 0, the transfer is finished and the client should release the 2368 * resources it acquired for the transfer. After a call with length = 0, the 2369 * file number can be reused for new file transfers. 2370 * 2371 * If position is equal to file_size (received in the file_receive callback) 2372 * when the transfer finishes, the file was received completely. Otherwise, if 2373 * file_size was UINT64_MAX, streaming ended successfully when length is 0. 2374 * 2375 * @param friend_number The friend number of the friend who is sending the file. 2376 * @param file_number The friend-specific file number the data received is 2377 * associated with. 2378 * @param position The file position of the first byte in data. 2379 * @param data A byte array containing the received chunk. 2380 * @param length The length of the received chunk. 2381 */ 2382 typedef void tox_file_recv_chunk_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, 2383 const uint8_t *data, size_t length, void *user_data); 2384 2385 2386 /** 2387 * Set the callback for the `file_recv_chunk` event. Pass NULL to unset. 2388 * 2389 * This event is first triggered when a file transfer request is received, and 2390 * subsequently when a chunk of file data for an accepted request was received. 2391 */ 2392 void tox_callback_file_recv_chunk(Tox *tox, tox_file_recv_chunk_cb *callback); 2393 2394 2395 /******************************************************************************* 2396 * 2397 * :: Conference management 2398 * 2399 ******************************************************************************/ 2400 2401 2402 2403 /** 2404 * Conference types for the conference_invite event. 2405 * 2406 * @deprecated All UPPER_CASE enum type names are deprecated. Use the 2407 * Camel_Snake_Case versions, instead. 2408 */ 2409 typedef enum TOX_CONFERENCE_TYPE { 2410 2411 /** 2412 * Text-only conferences that must be accepted with the tox_conference_join function. 2413 */ 2414 TOX_CONFERENCE_TYPE_TEXT, 2415 2416 /** 2417 * Video conference. The function to accept these is in toxav. 2418 */ 2419 TOX_CONFERENCE_TYPE_AV, 2420 2421 } TOX_CONFERENCE_TYPE; 2422 2423 2424 /** 2425 * The invitation will remain valid until the inviting friend goes offline 2426 * or exits the conference. 2427 * 2428 * @param friend_number The friend who invited us. 2429 * @param type The conference type (text only or audio/video). 2430 * @param cookie A piece of data of variable length required to join the 2431 * conference. 2432 * @param length The length of the cookie. 2433 */ 2434 typedef void tox_conference_invite_cb(Tox *tox, uint32_t friend_number, TOX_CONFERENCE_TYPE type, const uint8_t *cookie, 2435 size_t length, void *user_data); 2436 2437 2438 /** 2439 * Set the callback for the `conference_invite` event. Pass NULL to unset. 2440 * 2441 * This event is triggered when the client is invited to join a conference. 2442 */ 2443 void tox_callback_conference_invite(Tox *tox, tox_conference_invite_cb *callback); 2444 2445 /** 2446 * @param conference_number The conference number of the conference to which we have connected. 2447 */ 2448 typedef void tox_conference_connected_cb(Tox *tox, uint32_t conference_number, void *user_data); 2449 2450 2451 /** 2452 * Set the callback for the `conference_connected` event. Pass NULL to unset. 2453 * 2454 * This event is triggered when the client successfully connects to a 2455 * conference after joining it with the tox_conference_join function. 2456 */ 2457 void tox_callback_conference_connected(Tox *tox, tox_conference_connected_cb *callback); 2458 2459 /** 2460 * @param conference_number The conference number of the conference the message is intended for. 2461 * @param peer_number The ID of the peer who sent the message. 2462 * @param type The type of message (normal, action, ...). 2463 * @param message The message data. 2464 * @param length The length of the message. 2465 */ 2466 typedef void tox_conference_message_cb(Tox *tox, uint32_t conference_number, uint32_t peer_number, 2467 TOX_MESSAGE_TYPE type, const uint8_t *message, size_t length, void *user_data); 2468 2469 2470 /** 2471 * Set the callback for the `conference_message` event. Pass NULL to unset. 2472 * 2473 * This event is triggered when the client receives a conference message. 2474 */ 2475 void tox_callback_conference_message(Tox *tox, tox_conference_message_cb *callback); 2476 2477 /** 2478 * @param conference_number The conference number of the conference the title change is intended for. 2479 * @param peer_number The ID of the peer who changed the title. 2480 * @param title The title data. 2481 * @param length The title length. 2482 */ 2483 typedef void tox_conference_title_cb(Tox *tox, uint32_t conference_number, uint32_t peer_number, const uint8_t *title, 2484 size_t length, void *user_data); 2485 2486 2487 /** 2488 * Set the callback for the `conference_title` event. Pass NULL to unset. 2489 * 2490 * This event is triggered when a peer changes the conference title. 2491 * 2492 * If peer_number == UINT32_MAX, then author is unknown (e.g. initial joining the conference). 2493 */ 2494 void tox_callback_conference_title(Tox *tox, tox_conference_title_cb *callback); 2495 2496 /** 2497 * @param conference_number The conference number of the conference the 2498 * peer is in. 2499 * @param peer_number The ID of the peer who changed their nickname. 2500 * @param name A byte array containing the new nickname. 2501 * @param length The size of the name byte array. 2502 */ 2503 typedef void tox_conference_peer_name_cb(Tox *tox, uint32_t conference_number, uint32_t peer_number, 2504 const uint8_t *name, size_t length, void *user_data); 2505 2506 2507 /** 2508 * Set the callback for the `conference_peer_name` event. Pass NULL to unset. 2509 * 2510 * This event is triggered when a peer changes their name. 2511 */ 2512 void tox_callback_conference_peer_name(Tox *tox, tox_conference_peer_name_cb *callback); 2513 2514 /** 2515 * @param conference_number The conference number of the conference the 2516 * peer is in. 2517 */ 2518 typedef void tox_conference_peer_list_changed_cb(Tox *tox, uint32_t conference_number, void *user_data); 2519 2520 2521 /** 2522 * Set the callback for the `conference_peer_list_changed` event. Pass NULL to unset. 2523 * 2524 * This event is triggered when a peer joins or leaves the conference. 2525 */ 2526 void tox_callback_conference_peer_list_changed(Tox *tox, tox_conference_peer_list_changed_cb *callback); 2527 2528 typedef enum TOX_ERR_CONFERENCE_NEW { 2529 2530 /** 2531 * The function returned successfully. 2532 */ 2533 TOX_ERR_CONFERENCE_NEW_OK, 2534 2535 /** 2536 * The conference instance failed to initialize. 2537 */ 2538 TOX_ERR_CONFERENCE_NEW_INIT, 2539 2540 } TOX_ERR_CONFERENCE_NEW; 2541 2542 2543 /** 2544 * Creates a new conference. 2545 * 2546 * This function creates and connects to a new text conference. 2547 * 2548 * @return conference number on success, or an unspecified value on failure. 2549 */ 2550 uint32_t tox_conference_new(Tox *tox, TOX_ERR_CONFERENCE_NEW *error); 2551 2552 typedef enum TOX_ERR_CONFERENCE_DELETE { 2553 2554 /** 2555 * The function returned successfully. 2556 */ 2557 TOX_ERR_CONFERENCE_DELETE_OK, 2558 2559 /** 2560 * The conference number passed did not designate a valid conference. 2561 */ 2562 TOX_ERR_CONFERENCE_DELETE_CONFERENCE_NOT_FOUND, 2563 2564 } TOX_ERR_CONFERENCE_DELETE; 2565 2566 2567 /** 2568 * This function deletes a conference. 2569 * 2570 * @param conference_number The conference number of the conference to be deleted. 2571 * 2572 * @return true on success. 2573 */ 2574 bool tox_conference_delete(Tox *tox, uint32_t conference_number, TOX_ERR_CONFERENCE_DELETE *error); 2575 2576 /** 2577 * Error codes for peer info queries. 2578 */ 2579 typedef enum TOX_ERR_CONFERENCE_PEER_QUERY { 2580 2581 /** 2582 * The function returned successfully. 2583 */ 2584 TOX_ERR_CONFERENCE_PEER_QUERY_OK, 2585 2586 /** 2587 * The conference number passed did not designate a valid conference. 2588 */ 2589 TOX_ERR_CONFERENCE_PEER_QUERY_CONFERENCE_NOT_FOUND, 2590 2591 /** 2592 * The peer number passed did not designate a valid peer. 2593 */ 2594 TOX_ERR_CONFERENCE_PEER_QUERY_PEER_NOT_FOUND, 2595 2596 /** 2597 * The client is not connected to the conference. 2598 */ 2599 TOX_ERR_CONFERENCE_PEER_QUERY_NO_CONNECTION, 2600 2601 } TOX_ERR_CONFERENCE_PEER_QUERY; 2602 2603 2604 /** 2605 * Return the number of online peers in the conference. The unsigned 2606 * integers less than this number are the valid values of peer_number for 2607 * the functions querying these peers. Return value is unspecified on 2608 * failure. 2609 */ 2610 uint32_t tox_conference_peer_count(const Tox *tox, uint32_t conference_number, TOX_ERR_CONFERENCE_PEER_QUERY *error); 2611 2612 /** 2613 * Return the length of the peer's name. Return value is unspecified on failure. 2614 */ 2615 size_t tox_conference_peer_get_name_size(const Tox *tox, uint32_t conference_number, uint32_t peer_number, 2616 TOX_ERR_CONFERENCE_PEER_QUERY *error); 2617 2618 /** 2619 * Copy the name of peer_number who is in conference_number to name. 2620 * 2621 * Call tox_conference_peer_get_name_size to determine the allocation size for the `name` parameter. 2622 * 2623 * @param name A valid memory region large enough to store the peer's name. 2624 * 2625 * @return true on success. 2626 */ 2627 bool tox_conference_peer_get_name(const Tox *tox, uint32_t conference_number, uint32_t peer_number, uint8_t *name, 2628 TOX_ERR_CONFERENCE_PEER_QUERY *error); 2629 2630 /** 2631 * Copy the public key of peer_number who is in conference_number to public_key. 2632 * public_key must be TOX_PUBLIC_KEY_SIZE long. 2633 * 2634 * @return true on success. 2635 */ 2636 bool tox_conference_peer_get_public_key(const Tox *tox, uint32_t conference_number, uint32_t peer_number, 2637 uint8_t *public_key, TOX_ERR_CONFERENCE_PEER_QUERY *error); 2638 2639 /** 2640 * Return true if passed peer_number corresponds to our own. 2641 */ 2642 bool tox_conference_peer_number_is_ours(const Tox *tox, uint32_t conference_number, uint32_t peer_number, 2643 TOX_ERR_CONFERENCE_PEER_QUERY *error); 2644 2645 /** 2646 * Return the number of offline peers in the conference. The unsigned 2647 * integers less than this number are the valid values of offline_peer_number for 2648 * the functions querying these peers. Return value is unspecified on failure. 2649 */ 2650 uint32_t tox_conference_offline_peer_count(const Tox *tox, uint32_t conference_number, 2651 TOX_ERR_CONFERENCE_PEER_QUERY *error); 2652 2653 /** 2654 * Return the length of the offline peer's name. Return value is unspecified on failure. 2655 */ 2656 size_t tox_conference_offline_peer_get_name_size(const Tox *tox, uint32_t conference_number, 2657 uint32_t offline_peer_number, TOX_ERR_CONFERENCE_PEER_QUERY *error); 2658 2659 /** 2660 * Copy the name of offline_peer_number who is in conference_number to name. 2661 * 2662 * Call tox_conference_offline_peer_get_name_size to determine the allocation size for the `name` parameter. 2663 * 2664 * @param name A valid memory region large enough to store the peer's name. 2665 * 2666 * @return true on success. 2667 */ 2668 bool tox_conference_offline_peer_get_name(const Tox *tox, uint32_t conference_number, uint32_t offline_peer_number, 2669 uint8_t *name, TOX_ERR_CONFERENCE_PEER_QUERY *error); 2670 2671 /** 2672 * Copy the public key of offline_peer_number who is in conference_number to public_key. 2673 * public_key must be TOX_PUBLIC_KEY_SIZE long. 2674 * 2675 * @return true on success. 2676 */ 2677 bool tox_conference_offline_peer_get_public_key(const Tox *tox, uint32_t conference_number, 2678 uint32_t offline_peer_number, uint8_t *public_key, TOX_ERR_CONFERENCE_PEER_QUERY *error); 2679 2680 /** 2681 * Return a unix-time timestamp of the last time offline_peer_number was seen to be active. 2682 */ 2683 uint64_t tox_conference_offline_peer_get_last_active(const Tox *tox, uint32_t conference_number, 2684 uint32_t offline_peer_number, TOX_ERR_CONFERENCE_PEER_QUERY *error); 2685 2686 typedef enum TOX_ERR_CONFERENCE_SET_MAX_OFFLINE { 2687 2688 /** 2689 * The function returned successfully. 2690 */ 2691 TOX_ERR_CONFERENCE_SET_MAX_OFFLINE_OK, 2692 2693 /** 2694 * The conference number passed did not designate a valid conference. 2695 */ 2696 TOX_ERR_CONFERENCE_SET_MAX_OFFLINE_CONFERENCE_NOT_FOUND, 2697 2698 } TOX_ERR_CONFERENCE_SET_MAX_OFFLINE; 2699 2700 2701 /** 2702 * Set maximum number of offline peers to store, overriding the default. 2703 */ 2704 bool tox_conference_set_max_offline(Tox *tox, uint32_t conference_number, uint32_t max_offline_peers, 2705 TOX_ERR_CONFERENCE_SET_MAX_OFFLINE *error); 2706 2707 typedef enum TOX_ERR_CONFERENCE_INVITE { 2708 2709 /** 2710 * The function returned successfully. 2711 */ 2712 TOX_ERR_CONFERENCE_INVITE_OK, 2713 2714 /** 2715 * The conference number passed did not designate a valid conference. 2716 */ 2717 TOX_ERR_CONFERENCE_INVITE_CONFERENCE_NOT_FOUND, 2718 2719 /** 2720 * The invite packet failed to send. 2721 */ 2722 TOX_ERR_CONFERENCE_INVITE_FAIL_SEND, 2723 2724 /** 2725 * The client is not connected to the conference. 2726 */ 2727 TOX_ERR_CONFERENCE_INVITE_NO_CONNECTION, 2728 2729 } TOX_ERR_CONFERENCE_INVITE; 2730 2731 2732 /** 2733 * Invites a friend to a conference. 2734 * 2735 * @param friend_number The friend number of the friend we want to invite. 2736 * @param conference_number The conference number of the conference we want to invite the friend to. 2737 * 2738 * @return true on success. 2739 */ 2740 bool tox_conference_invite(Tox *tox, uint32_t friend_number, uint32_t conference_number, 2741 TOX_ERR_CONFERENCE_INVITE *error); 2742 2743 typedef enum TOX_ERR_CONFERENCE_JOIN { 2744 2745 /** 2746 * The function returned successfully. 2747 */ 2748 TOX_ERR_CONFERENCE_JOIN_OK, 2749 2750 /** 2751 * The cookie passed has an invalid length. 2752 */ 2753 TOX_ERR_CONFERENCE_JOIN_INVALID_LENGTH, 2754 2755 /** 2756 * The conference is not the expected type. This indicates an invalid cookie. 2757 */ 2758 TOX_ERR_CONFERENCE_JOIN_WRONG_TYPE, 2759 2760 /** 2761 * The friend number passed does not designate a valid friend. 2762 */ 2763 TOX_ERR_CONFERENCE_JOIN_FRIEND_NOT_FOUND, 2764 2765 /** 2766 * Client is already in this conference. 2767 */ 2768 TOX_ERR_CONFERENCE_JOIN_DUPLICATE, 2769 2770 /** 2771 * Conference instance failed to initialize. 2772 */ 2773 TOX_ERR_CONFERENCE_JOIN_INIT_FAIL, 2774 2775 /** 2776 * The join packet failed to send. 2777 */ 2778 TOX_ERR_CONFERENCE_JOIN_FAIL_SEND, 2779 2780 } TOX_ERR_CONFERENCE_JOIN; 2781 2782 2783 /** 2784 * Joins a conference that the client has been invited to. 2785 * 2786 * After successfully joining the conference, the client will not be "connected" 2787 * to it until a handshaking procedure has been completed. A 2788 * `conference_connected` event will then occur for the conference. The client 2789 * will then remain connected to the conference until the conference is deleted, 2790 * even across core restarts. Many operations on a conference will fail with a 2791 * corresponding error if attempted on a conference to which the client is not 2792 * yet connected. 2793 * 2794 * @param friend_number The friend number of the friend who sent the invite. 2795 * @param cookie Received via the `conference_invite` event. 2796 * @param length The size of cookie. 2797 * 2798 * @return conference number on success, an unspecified value on failure. 2799 */ 2800 uint32_t tox_conference_join(Tox *tox, uint32_t friend_number, const uint8_t *cookie, size_t length, 2801 TOX_ERR_CONFERENCE_JOIN *error); 2802 2803 typedef enum TOX_ERR_CONFERENCE_SEND_MESSAGE { 2804 2805 /** 2806 * The function returned successfully. 2807 */ 2808 TOX_ERR_CONFERENCE_SEND_MESSAGE_OK, 2809 2810 /** 2811 * The conference number passed did not designate a valid conference. 2812 */ 2813 TOX_ERR_CONFERENCE_SEND_MESSAGE_CONFERENCE_NOT_FOUND, 2814 2815 /** 2816 * The message is too long. 2817 */ 2818 TOX_ERR_CONFERENCE_SEND_MESSAGE_TOO_LONG, 2819 2820 /** 2821 * The client is not connected to the conference. 2822 */ 2823 TOX_ERR_CONFERENCE_SEND_MESSAGE_NO_CONNECTION, 2824 2825 /** 2826 * The message packet failed to send. 2827 */ 2828 TOX_ERR_CONFERENCE_SEND_MESSAGE_FAIL_SEND, 2829 2830 } TOX_ERR_CONFERENCE_SEND_MESSAGE; 2831 2832 2833 /** 2834 * Send a text chat message to the conference. 2835 * 2836 * This function creates a conference message packet and pushes it into the send 2837 * queue. 2838 * 2839 * The message length may not exceed TOX_MAX_MESSAGE_LENGTH. Larger messages 2840 * must be split by the client and sent as separate messages. Other clients can 2841 * then reassemble the fragments. 2842 * 2843 * @param conference_number The conference number of the conference the message is intended for. 2844 * @param type Message type (normal, action, ...). 2845 * @param message A non-NULL pointer to the first element of a byte array 2846 * containing the message text. 2847 * @param length Length of the message to be sent. 2848 * 2849 * @return true on success. 2850 */ 2851 bool tox_conference_send_message(Tox *tox, uint32_t conference_number, TOX_MESSAGE_TYPE type, const uint8_t *message, 2852 size_t length, TOX_ERR_CONFERENCE_SEND_MESSAGE *error); 2853 2854 typedef enum TOX_ERR_CONFERENCE_TITLE { 2855 2856 /** 2857 * The function returned successfully. 2858 */ 2859 TOX_ERR_CONFERENCE_TITLE_OK, 2860 2861 /** 2862 * The conference number passed did not designate a valid conference. 2863 */ 2864 TOX_ERR_CONFERENCE_TITLE_CONFERENCE_NOT_FOUND, 2865 2866 /** 2867 * The title is too long or empty. 2868 */ 2869 TOX_ERR_CONFERENCE_TITLE_INVALID_LENGTH, 2870 2871 /** 2872 * The title packet failed to send. 2873 */ 2874 TOX_ERR_CONFERENCE_TITLE_FAIL_SEND, 2875 2876 } TOX_ERR_CONFERENCE_TITLE; 2877 2878 2879 /** 2880 * Return the length of the conference title. Return value is unspecified on failure. 2881 * 2882 * The return value is equal to the `length` argument received by the last 2883 * `conference_title` callback. 2884 */ 2885 size_t tox_conference_get_title_size(const Tox *tox, uint32_t conference_number, TOX_ERR_CONFERENCE_TITLE *error); 2886 2887 /** 2888 * Write the title designated by the given conference number to a byte array. 2889 * 2890 * Call tox_conference_get_title_size to determine the allocation size for the `title` parameter. 2891 * 2892 * The data written to `title` is equal to the data received by the last 2893 * `conference_title` callback. 2894 * 2895 * @param title A valid memory region large enough to store the title. 2896 * If this parameter is NULL, this function has no effect. 2897 * 2898 * @return true on success. 2899 */ 2900 bool tox_conference_get_title(const Tox *tox, uint32_t conference_number, uint8_t *title, 2901 TOX_ERR_CONFERENCE_TITLE *error); 2902 2903 /** 2904 * Set the conference title and broadcast it to the rest of the conference. 2905 * 2906 * Title length cannot be longer than TOX_MAX_NAME_LENGTH. 2907 * 2908 * @return true on success. 2909 */ 2910 bool tox_conference_set_title(Tox *tox, uint32_t conference_number, const uint8_t *title, size_t length, 2911 TOX_ERR_CONFERENCE_TITLE *error); 2912 2913 /** 2914 * Return the number of conferences in the Tox instance. 2915 * This should be used to determine how much memory to allocate for `tox_conference_get_chatlist`. 2916 */ 2917 size_t tox_conference_get_chatlist_size(const Tox *tox); 2918 2919 /** 2920 * Copy a list of valid conference numbers into the array chatlist. Determine 2921 * how much space to allocate for the array with the `tox_conference_get_chatlist_size` function. 2922 * 2923 * Note that `tox_get_savedata` saves all connected conferences; 2924 * when toxcore is created from savedata in which conferences were saved, those 2925 * conferences will be connected at startup, and will be listed by 2926 * `tox_conference_get_chatlist`. 2927 * 2928 * The conference number of a loaded conference may differ from the conference 2929 * number it had when it was saved. 2930 */ 2931 void tox_conference_get_chatlist(const Tox *tox, uint32_t *chatlist); 2932 2933 /** 2934 * Returns the type of conference (TOX_CONFERENCE_TYPE) that conference_number is. Return value is 2935 * unspecified on failure. 2936 */ 2937 typedef enum TOX_ERR_CONFERENCE_GET_TYPE { 2938 2939 /** 2940 * The function returned successfully. 2941 */ 2942 TOX_ERR_CONFERENCE_GET_TYPE_OK, 2943 2944 /** 2945 * The conference number passed did not designate a valid conference. 2946 */ 2947 TOX_ERR_CONFERENCE_GET_TYPE_CONFERENCE_NOT_FOUND, 2948 2949 } TOX_ERR_CONFERENCE_GET_TYPE; 2950 2951 2952 TOX_CONFERENCE_TYPE tox_conference_get_type(const Tox *tox, uint32_t conference_number, 2953 TOX_ERR_CONFERENCE_GET_TYPE *error); 2954 2955 /** 2956 * Get the conference unique ID. 2957 * 2958 * If id is NULL, this function has no effect. 2959 * 2960 * @param id A memory region large enough to store TOX_CONFERENCE_ID_SIZE bytes. 2961 * 2962 * @return true on success. 2963 */ 2964 bool tox_conference_get_id(const Tox *tox, uint32_t conference_number, uint8_t *id); 2965 2966 typedef enum TOX_ERR_CONFERENCE_BY_ID { 2967 2968 /** 2969 * The function returned successfully. 2970 */ 2971 TOX_ERR_CONFERENCE_BY_ID_OK, 2972 2973 /** 2974 * One of the arguments to the function was NULL when it was not expected. 2975 */ 2976 TOX_ERR_CONFERENCE_BY_ID_NULL, 2977 2978 /** 2979 * No conference with the given id exists on the conference list. 2980 */ 2981 TOX_ERR_CONFERENCE_BY_ID_NOT_FOUND, 2982 2983 } TOX_ERR_CONFERENCE_BY_ID; 2984 2985 2986 /** 2987 * Return the conference number associated with the specified id. 2988 * 2989 * @param id A byte array containing the conference id (TOX_CONFERENCE_ID_SIZE). 2990 * 2991 * @return the conference number on success, an unspecified value on failure. 2992 */ 2993 uint32_t tox_conference_by_id(const Tox *tox, const uint8_t *id, TOX_ERR_CONFERENCE_BY_ID *error); 2994 2995 /** 2996 * Get the conference unique ID. 2997 * 2998 * If uid is NULL, this function has no effect. 2999 * 3000 * @param uid A memory region large enough to store TOX_CONFERENCE_UID_SIZE bytes. 3001 * 3002 * @return true on success. 3003 * @deprecated use tox_conference_get_id instead (exactly the same function, just renamed). 3004 */ 3005 bool tox_conference_get_uid(const Tox *tox, uint32_t conference_number, uint8_t *uid); 3006 3007 typedef enum TOX_ERR_CONFERENCE_BY_UID { 3008 3009 /** 3010 * The function returned successfully. 3011 */ 3012 TOX_ERR_CONFERENCE_BY_UID_OK, 3013 3014 /** 3015 * One of the arguments to the function was NULL when it was not expected. 3016 */ 3017 TOX_ERR_CONFERENCE_BY_UID_NULL, 3018 3019 /** 3020 * No conference with the given uid exists on the conference list. 3021 */ 3022 TOX_ERR_CONFERENCE_BY_UID_NOT_FOUND, 3023 3024 } TOX_ERR_CONFERENCE_BY_UID; 3025 3026 3027 /** 3028 * Return the conference number associated with the specified uid. 3029 * 3030 * @param uid A byte array containing the conference id (TOX_CONFERENCE_UID_SIZE). 3031 * 3032 * @return the conference number on success, an unspecified value on failure. 3033 * @deprecated use tox_conference_by_id instead (exactly the same function, just renamed). 3034 */ 3035 uint32_t tox_conference_by_uid(const Tox *tox, const uint8_t *uid, TOX_ERR_CONFERENCE_BY_UID *error); 3036 3037 3038 /******************************************************************************* 3039 * 3040 * :: Low-level custom packet sending and receiving 3041 * 3042 ******************************************************************************/ 3043 3044 3045 3046 typedef enum TOX_ERR_FRIEND_CUSTOM_PACKET { 3047 3048 /** 3049 * The function returned successfully. 3050 */ 3051 TOX_ERR_FRIEND_CUSTOM_PACKET_OK, 3052 3053 /** 3054 * One of the arguments to the function was NULL when it was not expected. 3055 */ 3056 TOX_ERR_FRIEND_CUSTOM_PACKET_NULL, 3057 3058 /** 3059 * The friend number did not designate a valid friend. 3060 */ 3061 TOX_ERR_FRIEND_CUSTOM_PACKET_FRIEND_NOT_FOUND, 3062 3063 /** 3064 * This client is currently not connected to the friend. 3065 */ 3066 TOX_ERR_FRIEND_CUSTOM_PACKET_FRIEND_NOT_CONNECTED, 3067 3068 /** 3069 * The first byte of data was not in the specified range for the packet type. 3070 * This range is 192-254 for lossy, and 69, 160-191 for lossless packets. 3071 */ 3072 TOX_ERR_FRIEND_CUSTOM_PACKET_INVALID, 3073 3074 /** 3075 * Attempted to send an empty packet. 3076 */ 3077 TOX_ERR_FRIEND_CUSTOM_PACKET_EMPTY, 3078 3079 /** 3080 * Packet data length exceeded TOX_MAX_CUSTOM_PACKET_SIZE. 3081 */ 3082 TOX_ERR_FRIEND_CUSTOM_PACKET_TOO_LONG, 3083 3084 /** 3085 * Packet queue is full. 3086 */ 3087 TOX_ERR_FRIEND_CUSTOM_PACKET_SENDQ, 3088 3089 } TOX_ERR_FRIEND_CUSTOM_PACKET; 3090 3091 3092 /** 3093 * Send a custom lossy packet to a friend. 3094 * 3095 * The first byte of data must be in the range 192-254. Maximum length of a 3096 * custom packet is TOX_MAX_CUSTOM_PACKET_SIZE. 3097 * 3098 * Lossy packets behave like UDP packets, meaning they might never reach the 3099 * other side or might arrive more than once (if someone is messing with the 3100 * connection) or might arrive in the wrong order. 3101 * 3102 * Unless latency is an issue, it is recommended that you use lossless custom 3103 * packets instead. 3104 * 3105 * @param friend_number The friend number of the friend this lossy packet 3106 * should be sent to. 3107 * @param data A byte array containing the packet data. 3108 * @param length The length of the packet data byte array. 3109 * 3110 * @return true on success. 3111 */ 3112 bool tox_friend_send_lossy_packet(Tox *tox, uint32_t friend_number, const uint8_t *data, size_t length, 3113 TOX_ERR_FRIEND_CUSTOM_PACKET *error); 3114 3115 /** 3116 * Send a custom lossless packet to a friend. 3117 * 3118 * The first byte of data must be in the range 69, 160-191. Maximum length of a 3119 * custom packet is TOX_MAX_CUSTOM_PACKET_SIZE. 3120 * 3121 * Lossless packet behaviour is comparable to TCP (reliability, arrive in order) 3122 * but with packets instead of a stream. 3123 * 3124 * @param friend_number The friend number of the friend this lossless packet 3125 * should be sent to. 3126 * @param data A byte array containing the packet data. 3127 * @param length The length of the packet data byte array. 3128 * 3129 * @return true on success. 3130 */ 3131 bool tox_friend_send_lossless_packet(Tox *tox, uint32_t friend_number, const uint8_t *data, size_t length, 3132 TOX_ERR_FRIEND_CUSTOM_PACKET *error); 3133 3134 /** 3135 * @param friend_number The friend number of the friend who sent a lossy packet. 3136 * @param data A byte array containing the received packet data. 3137 * @param length The length of the packet data byte array. 3138 */ 3139 typedef void tox_friend_lossy_packet_cb(Tox *tox, uint32_t friend_number, const uint8_t *data, size_t length, 3140 void *user_data); 3141 3142 3143 /** 3144 * Set the callback for the `friend_lossy_packet` event. Pass NULL to unset. 3145 * 3146 */ 3147 void tox_callback_friend_lossy_packet(Tox *tox, tox_friend_lossy_packet_cb *callback); 3148 3149 /** 3150 * @param friend_number The friend number of the friend who sent the packet. 3151 * @param data A byte array containing the received packet data. 3152 * @param length The length of the packet data byte array. 3153 */ 3154 typedef void tox_friend_lossless_packet_cb(Tox *tox, uint32_t friend_number, const uint8_t *data, size_t length, 3155 void *user_data); 3156 3157 3158 /** 3159 * Set the callback for the `friend_lossless_packet` event. Pass NULL to unset. 3160 * 3161 */ 3162 void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb *callback); 3163 3164 3165 /******************************************************************************* 3166 * 3167 * :: Low-level network information 3168 * 3169 ******************************************************************************/ 3170 3171 3172 3173 typedef enum TOX_ERR_GET_PORT { 3174 3175 /** 3176 * The function returned successfully. 3177 */ 3178 TOX_ERR_GET_PORT_OK, 3179 3180 /** 3181 * The instance was not bound to any port. 3182 */ 3183 TOX_ERR_GET_PORT_NOT_BOUND, 3184 3185 } TOX_ERR_GET_PORT; 3186 3187 3188 /** 3189 * Writes the temporary DHT public key of this instance to a byte array. 3190 * 3191 * This can be used in combination with an externally accessible IP address and 3192 * the bound port (from tox_self_get_udp_port) to run a temporary bootstrap node. 3193 * 3194 * Be aware that every time a new instance is created, the DHT public key 3195 * changes, meaning this cannot be used to run a permanent bootstrap node. 3196 * 3197 * @param dht_id A memory region of at least TOX_PUBLIC_KEY_SIZE bytes. If this 3198 * parameter is NULL, this function has no effect. 3199 */ 3200 void tox_self_get_dht_id(const Tox *tox, uint8_t *dht_id); 3201 3202 /** 3203 * Return the UDP port this Tox instance is bound to. 3204 */ 3205 uint16_t tox_self_get_udp_port(const Tox *tox, TOX_ERR_GET_PORT *error); 3206 3207 /** 3208 * Return the TCP port this Tox instance is bound to. This is only relevant if 3209 * the instance is acting as a TCP relay. 3210 */ 3211 uint16_t tox_self_get_tcp_port(const Tox *tox, TOX_ERR_GET_PORT *error); 3212 3213 #ifdef __cplusplus 3214 } 3215 #endif 3216 3217 typedef TOX_ERR_OPTIONS_NEW Tox_Err_Options_New; 3218 typedef TOX_ERR_NEW Tox_Err_New; 3219 typedef TOX_ERR_BOOTSTRAP Tox_Err_Bootstrap; 3220 typedef TOX_ERR_SET_INFO Tox_Err_Set_Info; 3221 typedef TOX_ERR_FRIEND_ADD Tox_Err_Friend_Add; 3222 typedef TOX_ERR_FRIEND_DELETE Tox_Err_Friend_Delete; 3223 typedef TOX_ERR_FRIEND_BY_PUBLIC_KEY Tox_Err_Friend_By_Public_Key; 3224 typedef TOX_ERR_FRIEND_GET_PUBLIC_KEY Tox_Err_Friend_Get_Public_Key; 3225 typedef TOX_ERR_FRIEND_GET_LAST_ONLINE Tox_Err_Friend_Get_Last_Online; 3226 typedef TOX_ERR_FRIEND_QUERY Tox_Err_Friend_Query; 3227 typedef TOX_ERR_SET_TYPING Tox_Err_Set_Typing; 3228 typedef TOX_ERR_FRIEND_SEND_MESSAGE Tox_Err_Friend_Send_Message; 3229 typedef TOX_ERR_FILE_CONTROL Tox_Err_File_Control; 3230 typedef TOX_ERR_FILE_SEEK Tox_Err_File_Seek; 3231 typedef TOX_ERR_FILE_GET Tox_Err_File_Get; 3232 typedef TOX_ERR_FILE_SEND Tox_Err_File_Send; 3233 typedef TOX_ERR_FILE_SEND_CHUNK Tox_Err_File_Send_Chunk; 3234 typedef TOX_ERR_CONFERENCE_NEW Tox_Err_Conference_New; 3235 typedef TOX_ERR_CONFERENCE_DELETE Tox_Err_Conference_Delete; 3236 typedef TOX_ERR_CONFERENCE_PEER_QUERY Tox_Err_Conference_Peer_Query; 3237 typedef TOX_ERR_CONFERENCE_SET_MAX_OFFLINE Tox_Err_Conference_Set_Max_Offline; 3238 typedef TOX_ERR_CONFERENCE_BY_ID Tox_Err_Conference_By_Id; 3239 typedef TOX_ERR_CONFERENCE_BY_UID Tox_Err_Conference_By_Uid; 3240 typedef TOX_ERR_CONFERENCE_INVITE Tox_Err_Conference_Invite; 3241 typedef TOX_ERR_CONFERENCE_JOIN Tox_Err_Conference_Join; 3242 typedef TOX_ERR_CONFERENCE_SEND_MESSAGE Tox_Err_Conference_Send_Message; 3243 typedef TOX_ERR_CONFERENCE_TITLE Tox_Err_Conference_Title; 3244 typedef TOX_ERR_CONFERENCE_GET_TYPE Tox_Err_Conference_Get_Type; 3245 typedef TOX_ERR_FRIEND_CUSTOM_PACKET Tox_Err_Friend_Custom_Packet; 3246 typedef TOX_ERR_GET_PORT Tox_Err_Get_Port; 3247 typedef TOX_USER_STATUS Tox_User_Status; 3248 typedef TOX_MESSAGE_TYPE Tox_Message_Type; 3249 typedef TOX_PROXY_TYPE Tox_Proxy_Type; 3250 typedef TOX_SAVEDATA_TYPE Tox_Savedata_Type; 3251 typedef TOX_LOG_LEVEL Tox_Log_Level; 3252 typedef TOX_CONNECTION Tox_Connection; 3253 typedef TOX_FILE_CONTROL Tox_File_Control; 3254 typedef TOX_CONFERENCE_TYPE Tox_Conference_Type; 3255 3256 //!TOKSTYLE+ 3257 3258 #endif // C_TOXCORE_TOXCORE_TOX_H 3259