summaryrefslogtreecommitdiff
path: root/other/apidsl
diff options
context:
space:
mode:
Diffstat (limited to 'other/apidsl')
-rw-r--r--other/apidsl/README.md11
-rw-r--r--other/apidsl/tox.in.h2076
2 files changed, 2087 insertions, 0 deletions
diff --git a/other/apidsl/README.md b/other/apidsl/README.md
new file mode 100644
index 00000000..c8241eb8
--- /dev/null
+++ b/other/apidsl/README.md
@@ -0,0 +1,11 @@
1This folder contains the input file that can be used to generate the tox.h api
2with: https://github.com/iphydf/apidsl
3
4You can also use the following command if you can't install it:
5
6```
7cat tox.in.h | curl -X POST --data-binary @- https://criticism.herokuapp.com/apidsl > tox.h
8```
9
10Note that the output must be passed through astyle with the config in
11other/astyle/astylerc to generate the exact same file.
diff --git a/other/apidsl/tox.in.h b/other/apidsl/tox.in.h
new file mode 100644
index 00000000..84a4a03e
--- /dev/null
+++ b/other/apidsl/tox.in.h
@@ -0,0 +1,2076 @@
1%{
2/* tox.h
3 *
4 * The Tox public API.
5 *
6 * Copyright (C) 2013 Tox project All Rights Reserved.
7 *
8 * This file is part of Tox.
9 *
10 * Tox is free software: you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation, either version 3 of the License, or
13 * (at your option) any later version.
14 *
15 * Tox is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
19 *
20 * You should have received a copy of the GNU General Public License
21 * along with Tox. If not, see <http://www.gnu.org/licenses/>.
22 *
23 */
24
25#ifndef TOX_H
26#define TOX_H
27
28#include <stdbool.h>
29#include <stddef.h>
30#include <stdint.h>
31
32#ifdef __cplusplus
33extern "C" {
34#endif
35%}
36
37/** \page core Public core API for Tox clients.
38 *
39 * Every function that can fail takes a function-specific error code pointer
40 * that can be used to diagnose problems with the Tox state or the function
41 * arguments. The error code pointer can be NULL, which does not influence the
42 * function's behaviour, but can be done if the reason for failure is irrelevant
43 * to the client.
44 *
45 * The exception to this rule are simple allocation functions whose only failure
46 * mode is allocation failure. They return NULL in that case, and do not set an
47 * error code.
48 *
49 * Every error code type has an OK value to which functions will set their error
50 * code value on success. Clients can keep their error code uninitialised before
51 * passing it to a function. The library guarantees that after returning, the
52 * value pointed to by the error code pointer has been initialised.
53 *
54 * Functions with pointer parameters often have a NULL error code, meaning they
55 * could not perform any operation, because one of the required parameters was
56 * NULL. Some functions operate correctly or are defined as effectless on NULL.
57 *
58 * Some functions additionally return a value outside their
59 * return type domain, or a bool containing true on success and false on
60 * failure.
61 *
62 * All functions that take a Tox instance pointer will cause undefined behaviour
63 * when passed a NULL Tox pointer.
64 *
65 * All integer values are expected in host byte order.
66 *
67 * Functions with parameters with enum types cause unspecified behaviour if the
68 * enumeration value is outside the valid range of the type. If possible, the
69 * function will try to use a sane default, but there will be no error code,
70 * and one possible action for the function to take is to have no effect.
71 */
72
73/** \subsection events Events and callbacks
74 *
75 * Events are handled by callbacks. One callback can be registered per event.
76 * All events have a callback function type named `tox_{event}_cb` and a
77 * function to register it named `tox_callback_{event}`. Passing a NULL
78 * callback will result in no callback being registered for that event. Only
79 * one callback per event can be registered, so if a client needs multiple
80 * event listeners, it needs to implement the dispatch functionality itself.
81 */
82
83/** \subsection threading Threading implications
84 *
85 * It is possible to run multiple concurrent threads with a Tox instance for
86 * each thread. It is also possible to run all Tox instances in the same thread.
87 * A common way to run Tox (multiple or single instance) is to have one thread
88 * running a simple ${tox.iterate} loop, sleeping for ${tox.iteration_interval}
89 * milliseconds on each iteration.
90 *
91 * If you want to access a single Tox instance from multiple threads, access
92 * to the instance must be synchronised. While multiple threads can concurrently
93 * access multiple different Tox instances, no more than one API function can
94 * operate on a single instance at any given time.
95 *
96 * Functions that write to variable length byte arrays will always have a size
97 * function associated with them. The result of this size function is only valid
98 * until another mutating function (one that takes a pointer to non-const Tox)
99 * is called. Thus, clients must ensure that no other thread calls a mutating
100 * function between the call to the size function and the call to the retrieval
101 * function.
102 *
103 * E.g. to get the current nickname, one would write
104 *
105 * \code
106 * size_t length = ${tox.self.name.size}(tox);
107 * uint8_t *name = malloc(length);
108 * if (!name) abort();
109 * ${tox.self.name.get}(tox, name);
110 * \endcode
111 *
112 * If any other thread calls ${tox.self.name.set} while this thread is allocating
113 * memory, the length may have become invalid, and the call to
114 * ${tox.self.name.get} may cause undefined behaviour.
115 */
116
117// The rest of this file is in class tox.
118class tox {
119
120/**
121 * The Tox instance type. All the state associated with a connection is held
122 * within the instance. Multiple instances can exist and operate concurrently.
123 * The maximum number of Tox instances that can exist on a single network
124 * device is limited. Note that this is not just a per-process limit, since the
125 * limiting factor is the number of usable ports on a device.
126 */
127struct this;
128
129
130/*******************************************************************************
131 *
132 * :: API version
133 *
134 ******************************************************************************/
135
136
137/**
138 * The major version number. Incremented when the API or ABI changes in an
139 * incompatible way.
140 */
141#define TOX_VERSION_MAJOR 0u
142/**
143 * The minor version number. Incremented when functionality is added without
144 * breaking the API or ABI. Set to 0 when the major version number is
145 * incremented.
146 */
147#define TOX_VERSION_MINOR 0u
148/**
149 * The patch or revision number. Incremented when bugfixes are applied without
150 * changing any functionality or API or ABI.
151 */
152#define TOX_VERSION_PATCH 0u
153
154/**
155 * A macro to check at preprocessing time whether the client code is compatible
156 * with the installed version of Tox.
157 */
158#define TOX_VERSION_IS_API_COMPATIBLE(MAJOR, MINOR, PATCH) \
159 (TOX_VERSION_MAJOR == MAJOR && \
160 (TOX_VERSION_MINOR > MINOR || \
161 (TOX_VERSION_MINOR == MINOR && \
162 TOX_VERSION_PATCH >= PATCH)))
163
164/**
165 * A macro to make compilation fail if the client code is not compatible with
166 * the installed version of Tox.
167 */
168#define TOX_VERSION_REQUIRE(MAJOR, MINOR, PATCH) \
169 typedef char tox_required_version[TOX_IS_COMPATIBLE(MAJOR, MINOR, PATCH) ? 1 : -1]
170
171static namespace version {
172
173 /**
174 * Return the major version number of the library. Can be used to display the
175 * Tox library version or to check whether the client is compatible with the
176 * dynamically linked version of Tox.
177 */
178 uint32_t major();
179
180 /**
181 * Return the minor version number of the library.
182 */
183 uint32_t minor();
184
185 /**
186 * Return the patch number of the library.
187 */
188 uint32_t patch();
189
190 /**
191 * Return whether the compiled library version is compatible with the passed
192 * version numbers.
193 */
194 bool is_compatible(uint32_t major, uint32_t minor, uint32_t patch);
195
196}
197
198/**
199 * A convenience macro to call tox_version_is_compatible with the currently
200 * compiling API version.
201 */
202#define TOX_VERSION_IS_ABI_COMPATIBLE() \
203 tox_version_is_compatible(TOX_VERSION_MAJOR, TOX_VERSION_MINOR, TOX_VERSION_PATCH)
204
205/*******************************************************************************
206 *
207 * :: Numeric constants
208 *
209 ******************************************************************************/
210
211
212/**
213 * The size of a Tox Public Key in bytes.
214 */
215const PUBLIC_KEY_SIZE = 32;
216
217/**
218 * The size of a Tox Secret Key in bytes.
219 */
220const SECRET_KEY_SIZE = 32;
221
222/**
223 * The size of a Tox address in bytes. Tox addresses are in the format
224 * [Public Key ($PUBLIC_KEY_SIZE bytes)][nospam (4 bytes)][checksum (2 bytes)].
225 *
226 * The checksum is computed over the Public Key and the nospam value. The first
227 * byte is an XOR of all the even bytes (0, 2, 4, ...), the second byte is an
228 * XOR of all the odd bytes (1, 3, 5, ...) of the Public Key and nospam.
229 */
230const ADDRESS_SIZE = PUBLIC_KEY_SIZE + sizeof(uint32_t) + sizeof(uint16_t);
231
232/**
233 * Maximum length of a nickname in bytes.
234 */
235const MAX_NAME_LENGTH = 128;
236
237/**
238 * Maximum length of a status message in bytes.
239 */
240const MAX_STATUS_MESSAGE_LENGTH = 1007;
241
242/**
243 * Maximum length of a friend request message in bytes.
244 */
245const MAX_FRIEND_REQUEST_LENGTH = 1016;
246
247/**
248 * Maximum length of a single message after which it should be split.
249 */
250const MAX_MESSAGE_LENGTH = 1372;
251
252/**
253 * Maximum size of custom packets. TODO: should be LENGTH?
254 */
255const MAX_CUSTOM_PACKET_SIZE = 1373;
256
257/**
258 * The number of bytes in a hash generated by $hash.
259 */
260const HASH_LENGTH = 32;
261
262/**
263 * The number of bytes in a file id.
264 */
265const FILE_ID_LENGTH = 32;
266
267/**
268 * Maximum file name length for file transfers.
269 */
270const MAX_FILENAME_LENGTH = 255;
271
272
273/*******************************************************************************
274 *
275 * :: Global enumerations
276 *
277 ******************************************************************************/
278
279
280/**
281 * Represents the possible statuses a client can have.
282 */
283enum class USER_STATUS {
284 /**
285 * User is online and available.
286 */
287 NONE,
288 /**
289 * User is away. Clients can set this e.g. after a user defined
290 * inactivity time.
291 */
292 AWAY,
293 /**
294 * User is busy. Signals to other clients that this client does not
295 * currently wish to communicate.
296 */
297 BUSY,
298}
299
300
301/**
302 * Represents message types for ${tox.friend.send.message} and group chat
303 * messages.
304 */
305enum class MESSAGE_TYPE {
306 /**
307 * Normal text message. Similar to PRIVMSG on IRC.
308 */
309 NORMAL,
310 /**
311 * A message describing an user action. This is similar to /me (CTCP ACTION)
312 * on IRC.
313 */
314 ACTION,
315}
316
317
318/*******************************************************************************
319 *
320 * :: Startup options
321 *
322 ******************************************************************************/
323
324
325/**
326 * Type of proxy used to connect to TCP relays.
327 */
328enum class PROXY_TYPE {
329 /**
330 * Don't use a proxy.
331 */
332 NONE,
333 /**
334 * HTTP proxy using CONNECT.
335 */
336 HTTP,
337 /**
338 * SOCKS proxy for simple socket pipes.
339 */
340 SOCKS5,
341}
342
343
344static class options {
345 /**
346 * This struct contains all the startup options for Tox. You can either allocate
347 * this object yourself, and pass it to $default, or call
348 * $new to get a new default options object.
349 */
350 struct this {
351 /**
352 * The type of socket to create.
353 *
354 * If this is set to false, an IPv4 socket is created, which subsequently
355 * only allows IPv4 communication.
356 * If it is set to true, an IPv6 socket is created, allowing both IPv4 and
357 * IPv6 communication.
358 */
359 bool ipv6_enabled;
360
361 /**
362 * Enable the use of UDP communication when available.
363 *
364 * Setting this to false will force Tox to use TCP only. Communications will
365 * need to be relayed through a TCP relay node, potentially slowing them down.
366 * Disabling UDP support is necessary when using anonymous proxies or Tor.
367 */
368 bool udp_enabled;
369
370 namespace proxy {
371 /**
372 * Pass communications through a proxy.
373 */
374 PROXY_TYPE type;
375
376 /**
377 * The IP address or DNS name of the proxy to be used.
378 *
379 * If used, this must be non-NULL and be a valid DNS name. The name must not
380 * exceed 255 characters, and be in a NUL-terminated C string format
381 * (255 chars + 1 NUL byte).
382 *
383 * This member is ignored (it can be NULL) if proxy_type is TOX_PROXY_TYPE_NONE.
384 */
385 string host;
386
387 /**
388 * The port to use to connect to the proxy server.
389 *
390 * Ports must be in the range (1, 65535). The value is ignored if
391 * proxy_type is TOX_PROXY_TYPE_NONE.
392 */
393 uint16_t port;
394 }
395
396 /**
397 * The start port of the inclusive port range to attempt to use.
398 *
399 * If both start_port and end_port are 0, the default port range will be
400 * used: [33445, 33545].
401 *
402 * If either start_port or end_port is 0 while the other is non-zero, the
403 * non-zero port will be the only port in the range.
404 *
405 * Having start_port > end_port will yield the same behavior as if start_port
406 * and end_port were swapped.
407 */
408 uint16_t start_port;
409
410 /**
411 * The end port of the inclusive port range to attempt to use.
412 */
413 uint16_t end_port;
414 }
415
416
417 /**
418 * Initialises a $this object with the default options.
419 *
420 * The result of this function is independent of the original options. All
421 * values will be overwritten, no values will be read (so it is permissible
422 * to pass an uninitialised object).
423 *
424 * If options is NULL, this function has no effect.
425 *
426 * @param options An options object to be filled with default options.
427 */
428 void default();
429
430
431 /**
432 * Allocates a new $this object and initialises it with the default
433 * options. This function can be used to preserve long term ABI compatibility by
434 * giving the responsibility of allocation and deallocation to the Tox library.
435 *
436 * Objects returned from this function must be freed using the $free
437 * function.
438 *
439 * @return A new $this object with default options or NULL on failure.
440 */
441 static this new() {
442 /**
443 * The function failed to allocate enough memory for the options struct.
444 */
445 MALLOC,
446 }
447
448
449 /**
450 * Releases all resources associated with an options objects.
451 *
452 * Passing a pointer that was not returned by $new results in
453 * undefined behaviour.
454 */
455 void free();
456}
457
458
459/*******************************************************************************
460 *
461 * :: Creation and destruction
462 *
463 ******************************************************************************/
464
465
466/**
467 * @brief Creates and initialises a new Tox instance with the options passed.
468 *
469 * This function will bring the instance into a valid state. Running the event
470 * loop with a new instance will operate correctly.
471 *
472 * If the data parameter is not NULL, this function will load the Tox instance
473 * from a byte array previously filled by ${savedata.get}.
474 *
475 * If loading failed or succeeded only partially, the new or partially loaded
476 * instance is returned and an error code is set.
477 *
478 * @param options An options object as described above. If this parameter is
479 * NULL, the default options are used.
480 * @param data A byte array containing data previously stored by ${savedata.get}.
481 * @param length The length of the byte array data. If this parameter is 0, the
482 * data parameter is ignored.
483 *
484 * @see $iterate for the event loop.
485 */
486static this new(const options_t *options, const uint8_t[length] data) {
487 NULL,
488 /**
489 * The function was unable to allocate enough memory to store the internal
490 * structures for the Tox object.
491 */
492 MALLOC,
493 /**
494 * The function was unable to bind to a port. This may mean that all ports
495 * have already been bound, e.g. by other Tox instances, or it may mean
496 * a permission error. You may be able to gather more information from errno.
497 */
498 PORT_ALLOC,
499
500 namespace PROXY {
501 /**
502 * proxy_type was invalid.
503 */
504 BAD_TYPE,
505 /**
506 * proxy_type was valid but the proxy_host passed had an invalid format
507 * or was NULL.
508 */
509 BAD_HOST,
510 /**
511 * proxy_type was valid, but the proxy_port was invalid.
512 */
513 BAD_PORT,
514 /**
515 * The proxy address passed could not be resolved.
516 */
517 NOT_FOUND,
518 }
519
520 namespace LOAD {
521 /**
522 * The byte array to be loaded contained an encrypted save.
523 */
524 ENCRYPTED,
525 /**
526 * The data format was invalid. This can happen when loading data that was
527 * saved by an older version of Tox, or when the data has been corrupted.
528 * When loading from badly formatted data, some data may have been loaded,
529 * and the rest is discarded. Passing an invalid length parameter also
530 * causes this error.
531 */
532 BAD_FORMAT,
533 }
534}
535
536
537/**
538 * Releases all resources associated with the Tox instance and disconnects from
539 * the network.
540 *
541 * After calling this function, the Tox pointer becomes invalid. No other
542 * functions can be called, and the pointer value can no longer be read.
543 */
544void kill();
545
546
547uint8_t[size] savedata {
548 /**
549 * Calculates the number of bytes required to store the tox instance with
550 * $get. This function cannot fail. The result is always greater than 0.
551 *
552 * @see threading for concurrency implications.
553 */
554 size();
555
556 /**
557 * Store all information associated with the tox instance to a byte array.
558 *
559 * @param data A memory region large enough to store the tox instance data.
560 * Call $size to find the number of bytes required. If this parameter
561 * is NULL, this function has no effect.
562 */
563 get();
564}
565
566
567/*******************************************************************************
568 *
569 * :: Connection lifecycle and event loop
570 *
571 ******************************************************************************/
572
573
574/**
575 * Sends a "get nodes" request to the given bootstrap node with IP, port, and
576 * public key to setup connections.
577 *
578 * This function will attempt to connect to the node using UDP and TCP at the
579 * same time.
580 *
581 * Tox will use the node as a TCP relay in case ${options.this.udp_enabled} was
582 * false, and also to connect to friends that are in TCP-only mode. Tox will
583 * also use the TCP connection when NAT hole punching is slow, and later switch
584 * to UDP if hole punching succeeds.
585 *
586 * @param address The hostname or IP address (IPv4 or IPv6) of the node.
587 * @param port The port on the host on which the bootstrap Tox instance is
588 * listening.
589 * @param public_key The long term public key of the bootstrap node
590 * ($PUBLIC_KEY_SIZE bytes).
591 * @return true on success.
592 */
593bool bootstrap(string address, uint16_t port, const uint8_t[PUBLIC_KEY_SIZE] public_key) {
594 NULL,
595 /**
596 * The address could not be resolved to an IP address, or the IP address
597 * passed was invalid.
598 */
599 BAD_HOST,
600 /**
601 * The port passed was invalid. The valid port range is (1, 65535).
602 */
603 BAD_PORT,
604}
605
606
607/**
608 * Adds additional host:port pair as TCP relay.
609 *
610 * This function can be used to initiate TCP connections to different ports on
611 * the same bootstrap node, or to add TCP relays without using them as
612 * bootstrap nodes.
613 *
614 * @param address The hostname or IP address (IPv4 or IPv6) of the TCP relay.
615 * @param port The port on the host on which the TCP relay is listening.
616 * @param public_key The long term public key of the TCP relay
617 * ($PUBLIC_KEY_SIZE bytes).
618 * @return true on success.
619 */
620bool add_tcp_relay(string address, uint16_t port, const uint8_t[PUBLIC_KEY_SIZE] public_key)
621 with error for bootstrap;
622
623
624/**
625 * Protocols that can be used to connect to the network or friends.
626 */
627enum class CONNECTION {
628 /**
629 * There is no connection. This instance, or the friend the state change is
630 * about, is now offline.
631 */
632 NONE,
633 /**
634 * A TCP connection has been established. For the own instance, this means it
635 * is connected through a TCP relay, only. For a friend, this means that the
636 * connection to that particular friend goes through a TCP relay.
637 */
638 TCP,
639 /**
640 * A UDP connection has been established. For the own instance, this means it
641 * is able to send UDP packets to DHT nodes, but may still be connected to
642 * a TCP relay. For a friend, this means that the connection to that
643 * particular friend was built using direct UDP packets.
644 */
645 UDP,
646}
647
648
649inline namespace self {
650
651 CONNECTION connection_status {
652 /**
653 * Return whether we are connected to the DHT. The return value is equal to the
654 * last value received through the `${event connection_status}` callback.
655 */
656 get();
657 }
658
659
660 /**
661 * This event is triggered whenever there is a change in the DHT connection
662 * state. When disconnected, a client may choose to call $bootstrap again, to
663 * reconnect to the DHT. Note that this state may frequently change for short
664 * amounts of time. Clients should therefore not immediately bootstrap on
665 * receiving a disconnect.
666 *
667 * TODO: how long should a client wait before bootstrapping again?
668 */
669 event connection_status {
670 /**
671 * @param connection_status Whether we are connected to the DHT.
672 */
673 typedef void(CONNECTION connection_status);
674 }
675
676}
677
678
679/**
680 * Return the time in milliseconds before $iterate() should be called again
681 * for optimal performance.
682 */
683const uint32_t iteration_interval();
684
685
686/**
687 * The main loop that needs to be run in intervals of $iteration_interval()
688 * milliseconds.
689 */
690void iterate();
691
692
693/*******************************************************************************
694 *
695 * :: Internal client information (Tox address/id)
696 *
697 ******************************************************************************/
698
699
700inline namespace self {
701
702 uint8_t[ADDRESS_SIZE] address {
703 /**
704 * Writes the Tox friend address of the client to a byte array. The address is
705 * not in human-readable format. If a client wants to display the address,
706 * formatting is required.
707 *
708 * @param address A memory region of at least $ADDRESS_SIZE bytes. If this
709 * parameter is NULL, this function has no effect.
710 * @see $ADDRESS_SIZE for the address format.
711 */
712 get();
713 }
714
715
716 uint32_t nospam {
717 /**
718 * Set the 4-byte nospam part of the address.
719 *
720 * @param nospam Any 32 bit unsigned integer.
721 */
722 set();
723
724 /**
725 * Get the 4-byte nospam part of the address.
726 */
727 get();
728 }
729
730
731 uint8_t[PUBLIC_KEY_SIZE] public_key {
732 /**
733 * Copy the Tox Public Key (long term) from the Tox object.
734 *
735 * @param public_key A memory region of at least $PUBLIC_KEY_SIZE bytes. If
736 * this parameter is NULL, this function has no effect.
737 */
738 get();
739 }
740
741
742 uint8_t[SECRET_KEY_SIZE] secret_key {
743 /**
744 * Copy the Tox Secret Key from the Tox object.
745 *
746 * @param secret_key A memory region of at least $SECRET_KEY_SIZE bytes. If
747 * this parameter is NULL, this function has no effect.
748 */
749 get();
750 }
751
752}
753
754
755/*******************************************************************************
756 *
757 * :: User-visible client information (nickname/status)
758 *
759 ******************************************************************************/
760
761
762/**
763 * Common error codes for all functions that set a piece of user-visible
764 * client information.
765 */
766error for set_info {
767 NULL,
768 /**
769 * Information length exceeded maximum permissible size.
770 */
771 TOO_LONG,
772}
773
774
775inline namespace self {
776
777 uint8_t[length <= MAX_NAME_LENGTH] name {
778 /**
779 * Set the nickname for the Tox client.
780 *
781 * Nickname length cannot exceed $MAX_NAME_LENGTH. If length is 0, the name
782 * parameter is ignored (it can be NULL), and the nickname is set back to empty.
783 *
784 * @param name A byte array containing the new nickname.
785 * @param length The size of the name byte array.
786 *
787 * @return true on success.
788 */
789 set() with error for set_info;
790
791 /**
792 * Return the length of the current nickname as passed to $set.
793 *
794 * If no nickname was set before calling this function, the name is empty,
795 * and this function returns 0.
796 *
797 * @see threading for concurrency implications.
798 */
799 size();
800
801 /**
802 * Write the nickname set by $set to a byte array.
803 *
804 * If no nickname was set before calling this function, the name is empty,
805 * and this function has no effect.
806 *
807 * Call $size to find out how much memory to allocate for
808 * the result.
809 *
810 * @param name A valid memory location large enough to hold the nickname.
811 * If this parameter is NULL, the function has no effect.
812 */
813 get();
814
815 }
816
817
818 uint8_t[length <= MAX_STATUS_MESSAGE_LENGTH] status_message {
819 /**
820 * Set the client's status message.
821 *
822 * Status message length cannot exceed $MAX_STATUS_MESSAGE_LENGTH. If
823 * length is 0, the status parameter is ignored (it can be NULL), and the
824 * user status is set back to empty.
825 */
826 set() with error for set_info;
827
828 /**
829 * Return the length of the current status message as passed to $set.
830 *
831 * If no status message was set before calling this function, the status
832 * is empty, and this function returns 0.
833 *
834 * @see threading for concurrency implications.
835 */
836 size();
837
838 /**
839 * Write the status message set by $set to a byte array.
840 *
841 * If no status message was set before calling this function, the status is
842 * empty, and this function has no effect.
843 *
844 * Call $size to find out how much memory to allocate for
845 * the result.
846 *
847 * @param status A valid memory location large enough to hold the status message.
848 * If this parameter is NULL, the function has no effect.
849 */
850 get();
851 }
852
853
854 USER_STATUS status {
855 /**
856 * Set the client's user status.
857 *
858 * @param user_status One of the user statuses listed in the enumeration above.
859 */
860 set();
861
862 /**
863 * Returns the client's user status.
864 */
865 get();
866 }
867
868}
869
870
871/*******************************************************************************
872 *
873 * :: Friend list management
874 *
875 ******************************************************************************/
876
877
878namespace friend {
879
880 /**
881 * Add a friend to the friend list and send a friend request.
882 *
883 * A friend request message must be at least 1 byte long and at most
884 * $MAX_FRIEND_REQUEST_LENGTH.
885 *
886 * Friend numbers are unique identifiers used in all functions that operate on
887 * friends. Once added, a friend number is stable for the lifetime of the Tox
888 * object. After saving the state and reloading it, the friend numbers may not
889 * be the same as before. Deleting a friend creates a gap in the friend number
890 * set, which is filled by the next adding of a friend. Any pattern in friend
891 * numbers should not be relied on.
892 *
893 * If more than INT32_MAX friends are added, this function causes undefined
894 * behaviour.
895 *
896 * @param address The address of the friend (returned by ${self.address.get} of
897 * the friend you wish to add) it must be $ADDRESS_SIZE bytes.
898 * @param message The message that will be sent along with the friend request.
899 * @param length The length of the data byte array.
900 *
901 * @return the friend number on success, UINT32_MAX on failure.
902 */
903 uint32_t add(
904 const uint8_t[ADDRESS_SIZE] address,
905 const uint8_t[length <= MAX_FRIEND_REQUEST_LENGTH] message
906 ) {
907 NULL,
908 /**
909 * The length of the friend request message exceeded
910 * $MAX_FRIEND_REQUEST_LENGTH.
911 */
912 TOO_LONG,
913 /**
914 * The friend request message was empty. This, and the TOO_LONG code will
915 * never be returned from $add_norequest.
916 */
917 NO_MESSAGE,
918 /**
919 * The friend address belongs to the sending client.
920 */
921 OWN_KEY,
922 /**
923 * A friend request has already been sent, or the address belongs to a friend
924 * that is already on the friend list.
925 */
926 ALREADY_SENT,
927 /**
928 * The friend address checksum failed.
929 */
930 BAD_CHECKSUM,
931 /**
932 * The friend was already there, but the nospam value was different.
933 */
934 SET_NEW_NOSPAM,
935 /**
936 * A memory allocation failed when trying to increase the friend list size.
937 */
938 MALLOC,
939 }
940
941
942 /**
943 * Add a friend without sending a friend request.
944 *
945 * This function is used to add a friend in response to a friend request. If the
946 * client receives a friend request, it can be reasonably sure that the other
947 * client added this client as a friend, eliminating the need for a friend
948 * request.
949 *
950 * This function is also useful in a situation where both instances are
951 * controlled by the same entity, so that this entity can perform the mutual
952 * friend adding. In this case, there is no need for a friend request, either.
953 *
954 * @param public_key A byte array of length $PUBLIC_KEY_SIZE containing the
955 * Public Key (not the Address) of the friend to add.
956 *
957 * @return the friend number on success, UINT32_MAX on failure.
958 * @see $add for a more detailed description of friend numbers.
959 */
960 uint32_t add_norequest(const uint8_t[PUBLIC_KEY_SIZE] public_key)
961 with error for add;
962
963
964 /**
965 * Remove a friend from the friend list.
966 *
967 * This does not notify the friend of their deletion. After calling this
968 * function, this client will appear offline to the friend and no communication
969 * can occur between the two.
970 *
971 * @param friend_number Friend number for the friend to be deleted.
972 *
973 * @return true on success.
974 */
975 bool delete(uint32_t friend_number) {
976 /**
977 * There was no friend with the given friend number. No friends were deleted.
978 */
979 FRIEND_NOT_FOUND,
980 }
981
982}
983
984
985/*******************************************************************************
986 *
987 * :: Friend list queries
988 *
989 ******************************************************************************/
990
991namespace friend {
992
993 /**
994 * Return the friend number associated with that Public Key.
995 *
996 * @return the friend number on success, UINT32_MAX on failure.
997 * @param public_key A byte array containing the Public Key.
998 */
999 const uint32_t by_public_key(const uint8_t[PUBLIC_KEY_SIZE] public_key) {
1000 NULL,
1001 /**
1002 * No friend with the given Public Key exists on the friend list.
1003 */
1004 NOT_FOUND,
1005 }
1006
1007
1008 /**
1009 * Checks if a friend with the given friend number exists and returns true if
1010 * it does.
1011 */
1012 const bool exists(uint32_t friend_number);
1013
1014
1015}
1016
1017inline namespace self {
1018
1019 uint32_t[size] friend_list {
1020 /**
1021 * Return the number of friends on the friend list.
1022 *
1023 * This function can be used to determine how much memory to allocate for
1024 * $get.
1025 */
1026 size();
1027
1028
1029 /**
1030 * Copy a list of valid friend numbers into an array.
1031 *
1032 * Call $size to determine the number of elements to allocate.
1033 *
1034 * @param list A memory region with enough space to hold the friend list. If
1035 * this parameter is NULL, this function has no effect.
1036 */
1037 get();
1038 }
1039
1040}
1041
1042
1043
1044namespace friend {
1045
1046 uint8_t[PUBLIC_KEY_SIZE] public_key {
1047 /**
1048 * Copies the Public Key associated with a given friend number to a byte array.
1049 *
1050 * @param friend_number The friend number you want the Public Key of.
1051 * @param public_key A memory region of at least $PUBLIC_KEY_SIZE bytes. If
1052 * this parameter is NULL, this function has no effect.
1053 *
1054 * @return true on success.
1055 */
1056 get(uint32_t friend_number) {
1057 /**
1058 * No friend with the given number exists on the friend list.
1059 */
1060 FRIEND_NOT_FOUND,
1061 }
1062 }
1063
1064}
1065
1066namespace friend {
1067
1068 uint64_t last_online {
1069 /**
1070 * Return a unix-time timestamp of the last time the friend associated with a given
1071 * friend number was seen online. This function will return UINT64_MAX on error.
1072 *
1073 * @param friend_number The friend number you want to query.
1074 */
1075 get(uint32_t friend_number) {
1076 /**
1077 * No friend with the given number exists on the friend list.
1078 */
1079 FRIEND_NOT_FOUND,
1080 }
1081 }
1082
1083}
1084
1085/*******************************************************************************
1086 *
1087 * :: Friend-specific state queries (can also be received through callbacks)
1088 *
1089 ******************************************************************************/
1090
1091
1092namespace friend {
1093
1094 /**
1095 * Common error codes for friend state query functions.
1096 */
1097 error for query {
1098 /**
1099 * The pointer parameter for storing the query result (name, message) was
1100 * NULL. Unlike the `_self_` variants of these functions, which have no effect
1101 * when a parameter is NULL, these functions return an error in that case.
1102 */
1103 NULL,
1104 /**
1105 * The friend_number did not designate a valid friend.
1106 */
1107 FRIEND_NOT_FOUND,
1108 }
1109
1110
1111 uint8_t[length <= MAX_NAME_LENGTH] name {
1112 /**
1113 * Return the length of the friend's name. If the friend number is invalid, the
1114 * return value is unspecified.
1115 *
1116 * The return value is equal to the `length` argument received by the last
1117 * `${event name}` callback.
1118 */
1119 size(uint32_t friend_number)
1120 with error for query;
1121
1122 /**
1123 * Write the name of the friend designated by the given friend number to a byte
1124 * array.
1125 *
1126 * Call $size to determine the allocation size for the `name`
1127 * parameter.
1128 *
1129 * The data written to `name` is equal to the data received by the last
1130 * `${event name}` callback.
1131 *
1132 * @param name A valid memory region large enough to store the friend's name.
1133 *
1134 * @return true on success.
1135 */
1136 get(uint32_t friend_number)
1137 with error for query;
1138 }
1139
1140
1141 /**
1142 * This event is triggered when a friend changes their name.
1143 */
1144 event name {
1145 /**
1146 * @param friend_number The friend number of the friend whose name changed.
1147 * @param name A byte array containing the same data as
1148 * ${name.get} would write to its `name` parameter.
1149 * @param length A value equal to the return value of
1150 * ${name.size}.
1151 */
1152 typedef void(uint32_t friend_number, const uint8_t[length <= MAX_NAME_LENGTH] name);
1153 }
1154
1155
1156 uint8_t[length <= MAX_STATUS_MESSAGE_LENGTH] status_message {
1157 /**
1158 * Return the length of the friend's status message. If the friend number is
1159 * invalid, the return value is SIZE_MAX.
1160 */
1161 size(uint32_t friend_number)
1162 with error for query;
1163
1164 /**
1165 * Write the name of the friend designated by the given friend number to a byte
1166 * array.
1167 *
1168 * Call $size to determine the allocation size for the `status_name`
1169 * parameter.
1170 *
1171 * The data written to `status_message` is equal to the data received by the last
1172 * `${event status_message}` callback.
1173 *
1174 * @param name A valid memory region large enough to store the friend's name.
1175 */
1176 get(uint32_t friend_number)
1177 with error for query;
1178
1179 }
1180
1181
1182 /**
1183 * This event is triggered when a friend changes their status message.
1184 */
1185 event status_message {
1186 /**
1187 * @param friend_number The friend number of the friend whose status message
1188 * changed.
1189 * @param message A byte array containing the same data as
1190 * ${status_message.get} would write to its `status_message` parameter.
1191 * @param length A value equal to the return value of
1192 * ${status_message.size}.
1193 */
1194 typedef void(uint32_t friend_number, const uint8_t[length <= MAX_STATUS_MESSAGE_LENGTH] message);
1195 }
1196
1197
1198 USER_STATUS status {
1199 /**
1200 * Return the friend's user status (away/busy/...). If the friend number is
1201 * invalid, the return value is unspecified.
1202 *
1203 * The status returned is equal to the last status received through the
1204 * `${event status}` callback.
1205 */
1206 get(uint32_t friend_number)
1207 with error for query;
1208 }
1209
1210
1211 /**
1212 * This event is triggered when a friend changes their user status.
1213 */
1214 event status {
1215 /**
1216 * @param friend_number The friend number of the friend whose user status
1217 * changed.
1218 * @param status The new user status.
1219 */
1220 typedef void(uint32_t friend_number, USER_STATUS status);
1221 }
1222
1223
1224 CONNECTION connection_status {
1225 /**
1226 * Check whether a friend is currently connected to this client.
1227 *
1228 * The result of this function is equal to the last value received by the
1229 * `${event connection_status}` callback.
1230 *
1231 * @param friend_number The friend number for which to query the connection
1232 * status.
1233 *
1234 * @return the friend's connection status as it was received through the
1235 * `${event connection_status}` event.
1236 */
1237 get(uint32_t friend_number)
1238 with error for query;
1239 }
1240
1241
1242 /**
1243 * This event is triggered when a friend goes offline after having been online,
1244 * or when a friend goes online.
1245 *
1246 * This callback is not called when adding friends. It is assumed that when
1247 * adding friends, their connection status is initially offline.
1248 */
1249 event connection_status {
1250 /**
1251 * @param friend_number The friend number of the friend whose connection status
1252 * changed.
1253 * @param connection_status The result of calling
1254 * ${connection_status.get} on the passed friend_number.
1255 */
1256 typedef void(uint32_t friend_number, CONNECTION connection_status);
1257 }
1258
1259
1260 bool typing {
1261 /**
1262 * Check whether a friend is currently typing a message.
1263 *
1264 * @param friend_number The friend number for which to query the typing status.
1265 *
1266 * @return true if the friend is typing.
1267 * @return false if the friend is not typing, or the friend number was
1268 * invalid. Inspect the error code to determine which case it is.
1269 */
1270 get(uint32_t friend_number)
1271 with error for query;
1272 }
1273
1274
1275 /**
1276 * This event is triggered when a friend starts or stops typing.
1277 */
1278 event typing {
1279 /**
1280 * @param friend_number The friend number of the friend who started or stopped
1281 * typing.
1282 * @param is_typing The result of calling ${typing.get} on the passed
1283 * friend_number.
1284 */
1285 typedef void(uint32_t friend_number, bool is_typing);
1286 }
1287
1288}
1289
1290
1291/*******************************************************************************
1292 *
1293 * :: Sending private messages
1294 *
1295 ******************************************************************************/
1296
1297
1298inline namespace self {
1299
1300 bool typing {
1301 /**
1302 * Set the client's typing status for a friend.
1303 *
1304 * The client is responsible for turning it on or off.
1305 *
1306 * @param friend_number The friend to which the client is typing a message.
1307 * @param typing The typing status. True means the client is typing.
1308 *
1309 * @return true on success.
1310 */
1311 set(uint32_t friend_number) {
1312 /**
1313 * The friend number did not designate a valid friend.
1314 */
1315 FRIEND_NOT_FOUND,
1316 }
1317 }
1318
1319}
1320
1321
1322namespace friend {
1323
1324 namespace send {
1325
1326 /**
1327 * Send a text chat message to an online friend.
1328 *
1329 * This function creates a chat message packet and pushes it into the send
1330 * queue.
1331 *
1332 * The message length may not exceed $MAX_MESSAGE_LENGTH. Larger messages
1333 * must be split by the client and sent as separate messages. Other clients can
1334 * then reassemble the fragments. Messages may not be empty.
1335 *
1336 * The return value of this function is the message ID. If a read receipt is
1337 * received, the triggered `${event read_receipt}` event will be passed this message ID.
1338 *
1339 * Message IDs are unique per friend. The first message ID is 0. Message IDs are
1340 * incremented by 1 each time a message is sent. If UINT32_MAX messages were
1341 * sent, the next message ID is 0.
1342 *
1343 * @param type Message type (normal, action, ...).
1344 * @param friend_number The friend number of the friend to send the message to.
1345 * @param message A non-NULL pointer to the first element of a byte array
1346 * containing the message text.
1347 * @param length Length of the message to be sent.
1348 */
1349 uint32_t message(uint32_t friend_number, MESSAGE_TYPE type, const uint8_t[length <= MAX_MESSAGE_LENGTH] message) {
1350 NULL,
1351 /**
1352 * The friend number did not designate a valid friend.
1353 */
1354 FRIEND_NOT_FOUND,
1355 /**
1356 * This client is currently not connected to the friend.
1357 */
1358 FRIEND_NOT_CONNECTED,
1359 /**
1360 * An allocation error occurred while increasing the send queue size.
1361 */
1362 SENDQ,
1363 /**
1364 * Message length exceeded $MAX_MESSAGE_LENGTH.
1365 */
1366 TOO_LONG,
1367 /**
1368 * Attempted to send a zero-length message.
1369 */
1370 EMPTY,
1371 }
1372
1373 }
1374
1375
1376 /**
1377 * This event is triggered when the friend receives the message sent with
1378 * ${send.message} with the corresponding message ID.
1379 */
1380 event read_receipt {
1381 /**
1382 * @param friend_number The friend number of the friend who received the message.
1383 * @param message_id The message ID as returned from ${send.message}
1384 * corresponding to the message sent.
1385 */
1386 typedef void(uint32_t friend_number, uint32_t message_id);
1387 }
1388
1389}
1390
1391
1392/*******************************************************************************
1393 *
1394 * :: Receiving private messages and friend requests
1395 *
1396 ******************************************************************************/
1397
1398
1399namespace friend {
1400
1401 /**
1402 * This event is triggered when a friend request is received.
1403 */
1404 event request {
1405 /**
1406 * @param public_key The Public Key of the user who sent the friend request.
1407 * @param time_delta A delta in seconds between when the message was composed
1408 * and when it is being transmitted. For messages that are sent immediately,
1409 * it will be 0. If a message was written and couldn't be sent immediately
1410 * (due to a connection failure, for example), the time_delta is an
1411 * approximation of when it was composed.
1412 * @param message The message they sent along with the request.
1413 * @param length The size of the message byte array.
1414 */
1415 typedef void(const uint8_t[PUBLIC_KEY_SIZE] public_key
1416 //, uint32_t time_delta
1417 , const uint8_t[length <= MAX_MESSAGE_LENGTH] message);
1418 }
1419
1420
1421 /**
1422 * This event is triggered when a message from a friend is received.
1423 */
1424 event message {
1425 /**
1426 * @param friend_number The friend number of the friend who sent the message.
1427 * @param time_delta Time between composition and sending.
1428 * @param message The message data they sent.
1429 * @param length The size of the message byte array.
1430 *
1431 * @see ${event request} for more information on time_delta.
1432 */
1433 typedef void(uint32_t friend_number
1434 //, uint32_t time_delta
1435 , MESSAGE_TYPE type, const uint8_t[length <= MAX_MESSAGE_LENGTH] message);
1436 }
1437
1438}
1439
1440
1441/*******************************************************************************
1442 *
1443 * :: File transmission: common between sending and receiving
1444 *
1445 ******************************************************************************/
1446
1447
1448/**
1449 * Generates a cryptographic hash of the given data.
1450 *
1451 * This function may be used by clients for any purpose, but is provided
1452 * primarily for validating cached avatars. This use is highly recommended to
1453 * avoid unnecessary avatar updates.
1454 *
1455 * If hash is NULL or data is NULL while length is not 0 the function returns false,
1456 * otherwise it returns true.
1457 *
1458 * This function is a wrapper to internal message-digest functions.
1459 *
1460 * @param hash A valid memory location the hash data. It must be at least
1461 * TOX_HASH_LENGTH bytes in size.
1462 * @param data Data to be hashed or NULL.
1463 * @param length Size of the data array or 0.
1464 *
1465 * @return true if hash was not NULL.
1466 */
1467static bool hash(uint8_t[HASH_LENGTH] hash, const uint8_t[length] data);
1468
1469
1470namespace file {
1471
1472 enum KIND {
1473 /**
1474 * Arbitrary file data. Clients can choose to handle it based on the file name
1475 * or magic or any other way they choose.
1476 */
1477 DATA,
1478 /**
1479 * Avatar filename. This consists of $hash(image).
1480 * Avatar data. This consists of the image data.
1481 *
1482 * Avatars can be sent at any time the client wishes. Generally, a client will
1483 * send the avatar to a friend when that friend comes online, and to all
1484 * friends when the avatar changed. A client can save some traffic by
1485 * remembering which friend received the updated avatar already and only send
1486 * it if the friend has an out of date avatar.
1487 *
1488 * Clients who receive avatar send requests can reject it (by sending
1489 * ${CONTROL.CANCEL} before any other controls), or accept it (by
1490 * sending ${CONTROL.RESUME}). The file_id of length $HASH_LENGTH bytes
1491 * (same length as $FILE_ID_LENGTH) will contain the hash. A client can compare
1492 * this hash with a saved hash and send ${CONTROL.CANCEL} to terminate the avatar
1493 * transfer if it matches.
1494 *
1495 * When file_size is set to 0 in the transfer request it means that the client
1496 * has no avatar.
1497 */
1498 AVATAR,
1499 }
1500
1501
1502 enum class CONTROL {
1503 /**
1504 * Sent by the receiving side to accept a file send request. Also sent after a
1505 * $PAUSE command to continue sending or receiving.
1506 */
1507 RESUME,
1508 /**
1509 * Sent by clients to pause the file transfer. The initial state of a file
1510 * transfer is always paused on the receiving side and running on the sending
1511 * side. If both the sending and receiving side pause the transfer, then both
1512 * need to send $RESUME for the transfer to resume.
1513 */
1514 PAUSE,
1515 /**
1516 * Sent by the receiving side to reject a file send request before any other
1517 * commands are sent. Also sent by either side to terminate a file transfer.
1518 */
1519 CANCEL,
1520 }
1521
1522
1523 /**
1524 * Sends a file control command to a friend for a given file transfer.
1525 *
1526 * @param friend_number The friend number of the friend the file is being
1527 * transferred to or received from.
1528 * @param file_number The friend-specific identifier for the file transfer.
1529 * @param control The control command to send.
1530 *
1531 * @return true on success.
1532 */
1533 bool control(uint32_t friend_number, uint32_t file_number, CONTROL control) {
1534 /**
1535 * The friend_number passed did not designate a valid friend.
1536 */
1537 FRIEND_NOT_FOUND,
1538 /**
1539 * This client is currently not connected to the friend.
1540 */
1541 FRIEND_NOT_CONNECTED,
1542 /**
1543 * No file transfer with the given file number was found for the given friend.
1544 */
1545 NOT_FOUND,
1546 /**
1547 * A RESUME control was sent, but the file transfer is running normally.
1548 */
1549 NOT_PAUSED,
1550 /**
1551 * A RESUME control was sent, but the file transfer was paused by the other
1552 * party. Only the party that paused the transfer can resume it.
1553 */
1554 DENIED,
1555 /**
1556 * A PAUSE control was sent, but the file transfer was already paused.
1557 */
1558 ALREADY_PAUSED,
1559 /**
1560 * Packet queue is full.
1561 */
1562 SENDQ,
1563 }
1564
1565
1566 /**
1567 * This event is triggered when a file control command is received from a
1568 * friend.
1569 */
1570 event recv_control {
1571 /**
1572 * When receiving ${CONTROL.CANCEL}, the client should release the
1573 * resources associated with the file number and consider the transfer failed.
1574 *
1575 * @param friend_number The friend number of the friend who is sending the file.
1576 * @param file_number The friend-specific file number the data received is
1577 * associated with.
1578 * @param control The file control command received.
1579 */
1580 typedef void(uint32_t friend_number, uint32_t file_number, CONTROL control);
1581 }
1582
1583 /**
1584 * Sends a file seek control command to a friend for a given file transfer.
1585 *
1586 * This function can only be called to resume a file transfer right before
1587 * ${CONTROL.RESUME} is sent.
1588 *
1589 * @param friend_number The friend number of the friend the file is being
1590 * received from.
1591 * @param file_number The friend-specific identifier for the file transfer.
1592 * @param position The position that the file should be seeked to.
1593 */
1594 bool seek(uint32_t friend_number, uint32_t file_number, uint64_t position) {
1595 /**
1596 * The friend_number passed did not designate a valid friend.
1597 */
1598 FRIEND_NOT_FOUND,
1599 /**
1600 * This client is currently not connected to the friend.
1601 */
1602 FRIEND_NOT_CONNECTED,
1603 /**
1604 * No file transfer with the given file number was found for the given friend.
1605 */
1606 NOT_FOUND,
1607 /**
1608 * File was not in a state where it could be seeked.
1609 */
1610 DENIED,
1611 /**
1612 * Seek position was invalid
1613 */
1614 INVALID_POSITION,
1615 /**
1616 * Packet queue is full.
1617 */
1618 SENDQ,
1619 }
1620
1621
1622 error for get {
1623 /**
1624 * The friend_number passed did not designate a valid friend.
1625 */
1626 FRIEND_NOT_FOUND,
1627 /**
1628 * No file transfer with the given file number was found for the given friend.
1629 */
1630 NOT_FOUND,
1631 }
1632
1633 /**
1634 * Copy the file id associated to the file transfer to a byte array.
1635 *
1636 * @param friend_number The friend number of the friend the file is being
1637 * transferred to or received from.
1638 * @param file_number The friend-specific identifier for the file transfer.
1639 * @param file_id A memory region of at least $FILE_ID_LENGTH bytes. If
1640 * this parameter is NULL, this function has no effect.
1641 *
1642 * @return true on success.
1643 */
1644 const bool get_file_id(uint32_t friend_number, uint32_t file_number, uint8_t[FILE_ID_LENGTH] file_id)
1645 with error for get;
1646
1647}
1648
1649
1650/*******************************************************************************
1651 *
1652 * :: File transmission: sending
1653 *
1654 ******************************************************************************/
1655
1656
1657namespace file {
1658
1659 /**
1660 * Send a file transmission request.
1661 *
1662 * Maximum filename length is $MAX_FILENAME_LENGTH bytes. The filename
1663 * should generally just be a file name, not a path with directory names.
1664 *
1665 * If a non-UINT64_MAX file size is provided, it can be used by both sides to
1666 * determine the sending progress. File size can be set to UINT64_MAX for streaming
1667 * data of unknown size.
1668 *
1669 * File transmission occurs in chunks, which are requested through the
1670 * `${event chunk_request}` event.
1671 *
1672 * When a friend goes offline, all file transfers associated with the friend are
1673 * purged from core.
1674 *
1675 * If the file contents change during a transfer, the behaviour is unspecified
1676 * in general. What will actually happen depends on the mode in which the file
1677 * was modified and how the client determines the file size.
1678 *
1679 * - If the file size was increased
1680 * - and sending mode was streaming (file_size = UINT64_MAX), the behaviour
1681 * will be as expected.
1682 * - and sending mode was file (file_size != UINT64_MAX), the
1683 * ${event chunk_request} callback will receive length = 0 when Core thinks
1684 * the file transfer has finished. If the client remembers the file size as
1685 * it was when sending the request, it will terminate the transfer normally.
1686 * If the client re-reads the size, it will think the friend cancelled the
1687 * transfer.
1688 * - If the file size was decreased
1689 * - and sending mode was streaming, the behaviour is as expected.
1690 * - and sending mode was file, the callback will return 0 at the new
1691 * (earlier) end-of-file, signalling to the friend that the transfer was
1692 * cancelled.
1693 * - If the file contents were modified
1694 * - at a position before the current read, the two files (local and remote)
1695 * will differ after the transfer terminates.
1696 * - at a position after the current read, the file transfer will succeed as
1697 * expected.
1698 * - In either case, both sides will regard the transfer as complete and
1699 * successful.
1700 *
1701 * @param friend_number The friend number of the friend the file send request
1702 * should be sent to.
1703 * @param kind The meaning of the file to be sent.
1704 * @param file_size Size in bytes of the file the client wants to send, UINT64_MAX if
1705 * unknown or streaming.
1706 * @param file_id A file identifier of length $FILE_ID_LENGTH that can be used to
1707 * uniquely identify file transfers across core restarts. If NULL, a random one will
1708 * be generated by core. It can then be obtained by using $get_file_id().
1709 * @param filename Name of the file. Does not need to be the actual name. This
1710 * name will be sent along with the file send request.
1711 * @param filename_length Size in bytes of the filename.
1712 *
1713 * @return A file number used as an identifier in subsequent callbacks. This
1714 * number is per friend. File numbers are reused after a transfer terminates.
1715 * On failure, this function returns UINT32_MAX. Any pattern in file numbers
1716 * should not be relied on.
1717 */
1718 uint32_t send(uint32_t friend_number, uint32_t kind, uint64_t file_size, const uint8_t[FILE_ID_LENGTH] file_id, const uint8_t[filename_length <= MAX_FILENAME_LENGTH] filename) {
1719 NULL,
1720 /**
1721 * The friend_number passed did not designate a valid friend.
1722 */
1723 FRIEND_NOT_FOUND,
1724 /**
1725 * This client is currently not connected to the friend.
1726 */
1727 FRIEND_NOT_CONNECTED,
1728 /**
1729 * Filename length exceeded $MAX_FILENAME_LENGTH bytes.
1730 */
1731 NAME_TOO_LONG,
1732 /**
1733 * Too many ongoing transfers. The maximum number of concurrent file transfers
1734 * is 256 per friend per direction (sending and receiving).
1735 */
1736 TOO_MANY,
1737 }
1738
1739
1740 /**
1741 * Send a chunk of file data to a friend.
1742 *
1743 * This function is called in response to the `${event chunk_request}` callback. The
1744 * length parameter should be equal to the one received though the callback.
1745 * If it is zero, the transfer is assumed complete. For files with known size,
1746 * Core will know that the transfer is complete after the last byte has been
1747 * received, so it is not necessary (though not harmful) to send a zero-length
1748 * chunk to terminate. For streams, core will know that the transfer is finished
1749 * if a chunk with length less than the length requested in the callback is sent.
1750 *
1751 * @param friend_number The friend number of the receiving friend for this file.
1752 * @param file_number The file transfer identifier returned by tox_file_send.
1753 * @param position The file or stream position from which to continue reading.
1754 * @return true on success.
1755 */
1756 bool send_chunk(uint32_t friend_number, uint32_t file_number, uint64_t position, const uint8_t[length] data) {
1757 /**
1758 * The length parameter was non-zero, but data was NULL.
1759 */
1760 NULL,
1761 /**
1762 * The friend_number passed did not designate a valid friend.
1763 */
1764 FRIEND_NOT_FOUND,
1765 /**
1766 * This client is currently not connected to the friend.
1767 */
1768 FRIEND_NOT_CONNECTED,
1769 /**
1770 * No file transfer with the given file number was found for the given friend.
1771 */
1772 NOT_FOUND,
1773 /**
1774 * File transfer was found but isn't in a transferring state: (paused, done,
1775 * broken, etc...) (happens only when not called from the request chunk callback).
1776 */
1777 NOT_TRANSFERRING,
1778 /**
1779 * Attempted to send more or less data than requested. The requested data size is
1780 * adjusted according to maximum transmission unit and the expected end of
1781 * the file. Trying to send less or more than requested will return this error.
1782 */
1783 INVALID_LENGTH,
1784 /**
1785 * Packet queue is full.
1786 */
1787 SENDQ,
1788 /**
1789 * Position parameter was wrong.
1790 */
1791 WRONG_POSITION,
1792 }
1793
1794
1795 /**
1796 * This event is triggered when Core is ready to send more file data.
1797 */
1798 event chunk_request {
1799 /**
1800 * If the length parameter is 0, the file transfer is finished, and the client's
1801 * resources associated with the file number should be released. After a call
1802 * with zero length, the file number can be reused for future file transfers.
1803 *
1804 * If the requested position is not equal to the client's idea of the current
1805 * file or stream position, it will need to seek. In case of read-once streams,
1806 * the client should keep the last read chunk so that a seek back can be
1807 * supported. A seek-back only ever needs to read from the last requested chunk.
1808 * This happens when a chunk was requested, but the send failed. A seek-back
1809 * request can occur an arbitrary number of times for any given chunk.
1810 *
1811 * In response to receiving this callback, the client should call the function
1812 * `$send_chunk` with the requested chunk. If the number of bytes sent
1813 * through that function is zero, the file transfer is assumed complete. A
1814 * client must send the full length of data requested with this callback.
1815 *
1816 * @param friend_number The friend number of the receiving friend for this file.
1817 * @param file_number The file transfer identifier returned by $send.
1818 * @param position The file or stream position from which to continue reading.
1819 * @param length The number of bytes requested for the current chunk.
1820 */
1821 typedef void(uint32_t friend_number, uint32_t file_number, uint64_t position, size_t length);
1822 }
1823
1824}
1825
1826
1827/*******************************************************************************
1828 *
1829 * :: File transmission: receiving
1830 *
1831 ******************************************************************************/
1832
1833
1834namespace file {
1835
1836 /**
1837 * This event is triggered when a file transfer request is received.
1838 */
1839 event recv {
1840 /**
1841 * The client should acquire resources to be associated with the file transfer.
1842 * Incoming file transfers start in the PAUSED state. After this callback
1843 * returns, a transfer can be rejected by sending a ${CONTROL.CANCEL}
1844 * control command before any other control commands. It can be accepted by
1845 * sending ${CONTROL.RESUME}.
1846 *
1847 * @param friend_number The friend number of the friend who is sending the file
1848 * transfer request.
1849 * @param file_number The friend-specific file number the data received is
1850 * associated with.
1851 * @param kind The meaning of the file to be sent.
1852 * @param file_size Size in bytes of the file the client wants to send,
1853 * UINT64_MAX if unknown or streaming.
1854 * @param filename Name of the file. Does not need to be the actual name. This
1855 * name will be sent along with the file send request.
1856 * @param filename_length Size in bytes of the filename.
1857 */
1858 typedef void(uint32_t friend_number, uint32_t file_number, uint32_t kind,
1859 uint64_t file_size, const uint8_t[filename_length <= MAX_FILENAME_LENGTH] filename);
1860 }
1861
1862
1863 /**
1864 * This event is first triggered when a file transfer request is received, and
1865 * subsequently when a chunk of file data for an accepted request was received.
1866 */
1867 event recv_chunk {
1868 /**
1869 * When length is 0, the transfer is finished and the client should release the
1870 * resources it acquired for the transfer. After a call with length = 0, the
1871 * file number can be reused for new file transfers.
1872 *
1873 * If position is equal to file_size (received in the file_receive callback)
1874 * when the transfer finishes, the file was received completely. Otherwise, if
1875 * file_size was UINT64_MAX, streaming ended successfully when length is 0.
1876 *
1877 * @param friend_number The friend number of the friend who is sending the file.
1878 * @param file_number The friend-specific file number the data received is
1879 * associated with.
1880 * @param position The file position of the first byte in data.
1881 * @param data A byte array containing the received chunk.
1882 * @param length The length of the received chunk.
1883 */
1884 typedef void(uint32_t friend_number, uint32_t file_number, uint64_t position,
1885 const uint8_t[length] data);
1886 }
1887
1888}
1889
1890
1891/*******************************************************************************
1892 *
1893 * :: Group chat management
1894 *
1895 ******************************************************************************/
1896
1897
1898/******************************************************************************
1899 *
1900 * :: Group chat message sending and receiving
1901 *
1902 ******************************************************************************/
1903
1904
1905/*******************************************************************************
1906 *
1907 * :: Low-level custom packet sending and receiving
1908 *
1909 ******************************************************************************/
1910
1911
1912namespace friend {
1913
1914 inline namespace send {
1915
1916 error for custom_packet {
1917 NULL,
1918 /**
1919 * The friend number did not designate a valid friend.
1920 */
1921 FRIEND_NOT_FOUND,
1922 /**
1923 * This client is currently not connected to the friend.
1924 */
1925 FRIEND_NOT_CONNECTED,
1926 /**
1927 * The first byte of data was not in the specified range for the packet type.
1928 * This range is 200-254 for lossy, and 160-191 for lossless packets.
1929 */
1930 INVALID,
1931 /**
1932 * Attempted to send an empty packet.
1933 */
1934 EMPTY,
1935 /**
1936 * Packet data length exceeded $MAX_CUSTOM_PACKET_SIZE.
1937 */
1938 TOO_LONG,
1939 /**
1940 * Packet queue is full.
1941 */
1942 SENDQ,
1943 }
1944
1945 /**
1946 * Send a custom lossy packet to a friend.
1947 *
1948 * The first byte of data must be in the range 200-254. Maximum length of a
1949 * custom packet is $MAX_CUSTOM_PACKET_SIZE.
1950 *
1951 * Lossy packets behave like UDP packets, meaning they might never reach the
1952 * other side or might arrive more than once (if someone is messing with the
1953 * connection) or might arrive in the wrong order.
1954 *
1955 * Unless latency is an issue, it is recommended that you use lossless custom
1956 * packets instead.
1957 *
1958 * @param friend_number The friend number of the friend this lossy packet
1959 * should be sent to.
1960 * @param data A byte array containing the packet data.
1961 * @param length The length of the packet data byte array.
1962 *
1963 * @return true on success.
1964 */
1965 bool lossy_packet(uint32_t friend_number, const uint8_t[length <= MAX_CUSTOM_PACKET_SIZE] data)
1966 with error for custom_packet;
1967
1968
1969 /**
1970 * Send a custom lossless packet to a friend.
1971 *
1972 * The first byte of data must be in the range 160-191. Maximum length of a
1973 * custom packet is $MAX_CUSTOM_PACKET_SIZE.
1974 *
1975 * Lossless packet behaviour is comparable to TCP (reliability, arrive in order)
1976 * but with packets instead of a stream.
1977 *
1978 * @param friend_number The friend number of the friend this lossless packet
1979 * should be sent to.
1980 * @param data A byte array containing the packet data.
1981 * @param length The length of the packet data byte array.
1982 *
1983 * @return true on success.
1984 */
1985 bool lossless_packet(uint32_t friend_number, const uint8_t[length <= MAX_CUSTOM_PACKET_SIZE] data)
1986 with error for custom_packet;
1987
1988 }
1989
1990
1991 event lossy_packet {
1992 /**
1993 * @param friend_number The friend number of the friend who sent a lossy packet.
1994 * @param data A byte array containing the received packet data.
1995 * @param length The length of the packet data byte array.
1996 */
1997 typedef void(uint32_t friend_number, const uint8_t[length <= MAX_CUSTOM_PACKET_SIZE] data);
1998 }
1999
2000
2001 event lossless_packet {
2002 /**
2003 * @param friend_number The friend number of the friend who sent the packet.
2004 * @param data A byte array containing the received packet data.
2005 * @param length The length of the packet data byte array.
2006 */
2007 typedef void(uint32_t friend_number, const uint8_t[length <= MAX_CUSTOM_PACKET_SIZE] data);
2008 }
2009
2010}
2011
2012
2013
2014/*******************************************************************************
2015 *
2016 * :: Low-level network information
2017 *
2018 ******************************************************************************/
2019
2020
2021inline namespace self {
2022
2023 uint8_t[PUBLIC_KEY_SIZE] dht_id {
2024 /**
2025 * Writes the temporary DHT public key of this instance to a byte array.
2026 *
2027 * This can be used in combination with an externally accessible IP address and
2028 * the bound port (from ${udp_port.get}) to run a temporary bootstrap node.
2029 *
2030 * Be aware that every time a new instance is created, the DHT public key
2031 * changes, meaning this cannot be used to run a permanent bootstrap node.
2032 *
2033 * @param dht_id A memory region of at least $PUBLIC_KEY_SIZE bytes. If this
2034 * parameter is NULL, this function has no effect.
2035 */
2036 get();
2037 }
2038
2039
2040 error for get_port {
2041 /**
2042 * The instance was not bound to any port.
2043 */
2044 NOT_BOUND,
2045 }
2046
2047
2048 uint16_t udp_port {
2049 /**
2050 * Return the UDP port this Tox instance is bound to.
2051 */
2052 get() with error for get_port;
2053 }
2054
2055
2056 uint16_t tcp_port {
2057 /**
2058 * Return the TCP port this Tox instance is bound to. This is only relevant if
2059 * the instance is acting as a TCP relay.
2060 */
2061 get() with error for get_port;
2062 }
2063
2064}
2065
2066} // class tox
2067
2068%{
2069#include "tox_old.h"
2070
2071#ifdef __cplusplus
2072}
2073#endif
2074
2075#endif
2076%}