summaryrefslogtreecommitdiff
path: root/toxcore/tox.h
diff options
context:
space:
mode:
Diffstat (limited to 'toxcore/tox.h')
-rw-r--r--toxcore/tox.h2212
1 files changed, 1579 insertions, 633 deletions
diff --git a/toxcore/tox.h b/toxcore/tox.h
index ee678cc1..8dab7002 100644
--- a/toxcore/tox.h
+++ b/toxcore/tox.h
@@ -24,928 +24,1874 @@
24#ifndef TOX_H 24#ifndef TOX_H
25#define TOX_H 25#define TOX_H
26 26
27#include <stdbool.h>
28#include <stddef.h>
27#include <stdint.h> 29#include <stdint.h>
28 30
29
30#ifdef __cplusplus 31#ifdef __cplusplus
31extern "C" { 32extern "C" {
32#endif 33#endif
33 34
34#define TOX_MAX_NAME_LENGTH 128 35/** \page core Public core API for Tox clients.
36 *
37 * Every function that can fail takes a function-specific error code pointer
38 * that can be used to diagnose problems with the Tox state or the function
39 * arguments. The error code pointer can be NULL, which does not influence the
40 * function's behaviour, but can be done if the reason for failure is irrelevant
41 * to the client.
42 *
43 * The exception to this rule are simple allocation functions whose only failure
44 * mode is allocation failure. They return NULL in that case, and do not set an
45 * error code.
46 *
47 * Every error code type has an OK value to which functions will set their error
48 * code value on success. Clients can keep their error code uninitialised before
49 * passing it to a function. The library guarantees that after returning, the
50 * value pointed to by the error code pointer has been initialised.
51 *
52 * Functions with pointer parameters often have a NULL error code, meaning they
53 * could not perform any operation, because one of the required parameters was
54 * NULL. Some functions operate correctly or are defined as effectless on NULL.
55 *
56 * Some functions additionally return a value outside their
57 * return type domain, or a bool containing true on success and false on
58 * failure.
59 *
60 * All functions that take a Tox instance pointer will cause undefined behaviour
61 * when passed a NULL Tox pointer.
62 *
63 * All integer values are expected in host byte order.
64 *
65 * Functions with parameters with enum types cause unspecified behaviour if the
66 * enumeration value is outside the valid range of the type. If possible, the
67 * function will try to use a sane default, but there will be no error code,
68 * and one possible action for the function to take is to have no effect.
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 */
35 80
36/* Maximum length of single messages after which they should be split. */ 81/** \subsection threading Threading implications
37#define TOX_MAX_MESSAGE_LENGTH 1368 82 *
38#define TOX_MAX_STATUSMESSAGE_LENGTH 1007 83 * It is possible to run multiple concurrent threads with a Tox instance for
39#define TOX_MAX_FRIENDREQUEST_LENGTH 1016 84 * each thread. It is also possible to run all Tox instances in the same thread.
85 * A common way to run Tox (multiple or single instance) is to have one thread
86 * running a simple tox_iteration loop, sleeping for tox_iteration_time
87 * milliseconds on each iteration.
88 *
89 * If you want to access a single Tox instance from multiple threads, access
90 * to the instance must be synchronised. While multiple threads can concurrently
91 * access multiple different Tox instances, no more than one API function can
92 * operate on a single instance at any given time.
93 *
94 * Functions that write to variable length byte arrays will always have a size
95 * function associated with them. The result of this size function is only valid
96 * until another mutating function (one that takes a pointer to non-const Tox)
97 * is called. Thus, clients must ensure that no other thread calls a mutating
98 * function between the call to the size function and the call to the retrieval
99 * function.
100 *
101 * E.g. to get the current nickname, one would write
102 *
103 * \code
104 * size_t length = tox_self_get_name_size(tox);
105 * uint8_t *name = malloc(length);
106 * if (!name) abort();
107 * tox_self_get_name(tox, name);
108 * \endcode
109 *
110 * If any other thread calls tox_self_set_name while this thread is allocating
111 * memory, the length will have become invalid, and the call to
112 * tox_self_get_name may cause undefined behaviour.
113 */
40 114
41#define TOX_PUBLIC_KEY_SIZE 32 115#ifndef TOX_DEFINED
42/* TODO: remove */ 116#define TOX_DEFINED
43#define TOX_CLIENT_ID_SIZE TOX_PUBLIC_KEY_SIZE 117/**
118 * The Tox instance type. All the state associated with a connection is held
119 * within the instance. Multiple instances can exist and operate concurrently.
120 * The maximum number of Tox instances that can exist on a single network
121 * device is limited. Note that this is not just a per-process limit, since the
122 * limiting factor is the number of usable ports on a device.
123 */
124typedef struct Tox Tox;
125#endif
44 126
45#define TOX_AVATAR_MAX_DATA_LENGTH 16384
46#define TOX_HASH_LENGTH /*crypto_hash_sha256_BYTES*/ 32
47 127
48#define TOX_FRIEND_ADDRESS_SIZE (TOX_PUBLIC_KEY_SIZE + sizeof(uint32_t) + sizeof(uint16_t)) 128/*******************************************************************************
129 *
130 * :: API version
131 *
132 ******************************************************************************/
49 133
50#define TOX_ENABLE_IPV6_DEFAULT 1
51 134
52#define TOX_ENC_SAVE_MAGIC_NUMBER "toxEsave" 135/**
53#define TOX_ENC_SAVE_MAGIC_LENGTH 8 136 * The major version number. Incremented when the API or ABI changes in an
137 * incompatible way.
138 */
139#define TOX_VERSION_MAJOR 0u
140/**
141 * The minor version number. Incremented when functionality is added without
142 * breaking the API or ABI. Set to 0 when the major version number is
143 * incremented.
144 */
145#define TOX_VERSION_MINOR 0u
146/**
147 * The patch or revision number. Incremented when bugfixes are applied without
148 * changing any functionality or API or ABI.
149 */
150#define TOX_VERSION_PATCH 0u
54 151
55/* Errors for m_addfriend 152/**
56 * FAERR - Friend Add Error 153 * A macro to check at preprocessing time whether the client code is compatible
154 * with the installed version of Tox.
57 */ 155 */
58enum { 156#define TOX_VERSION_IS_API_COMPATIBLE(MAJOR, MINOR, PATCH) \
59 TOX_FAERR_TOOLONG = -1, 157 (TOX_VERSION_MAJOR == MAJOR && \
60 TOX_FAERR_NOMESSAGE = -2, 158 (TOX_VERSION_MINOR > MINOR || \
61 TOX_FAERR_OWNKEY = -3, 159 (TOX_VERSION_MINOR == MINOR && \
62 TOX_FAERR_ALREADYSENT = -4, 160 TOX_VERSION_PATCH >= PATCH)))
63 TOX_FAERR_UNKNOWN = -5,
64 TOX_FAERR_BADCHECKSUM = -6,
65 TOX_FAERR_SETNEWNOSPAM = -7,
66 TOX_FAERR_NOMEM = -8
67};
68 161
69/* USERSTATUS - 162/**
70 * Represents userstatuses someone can have. 163 * A macro to make compilation fail if the client code is not compatible with
164 * the installed version of Tox.
71 */ 165 */
72typedef enum { 166#define TOX_VERSION_REQUIRE(MAJOR, MINOR, PATCH) \
73 TOX_USERSTATUS_NONE, 167 typedef char tox_required_version[TOX_IS_COMPATIBLE(MAJOR, MINOR, PATCH) ? 1 : -1]
74 TOX_USERSTATUS_AWAY,
75 TOX_USERSTATUS_BUSY,
76 TOX_USERSTATUS_INVALID
77}
78TOX_USERSTATUS;
79 168
80 169
81/* AVATAR_FORMAT - 170/**
82 * Data formats for user avatar images 171 * Return the major version number of the library. Can be used to display the
172 * Tox library version or to check whether the client is compatible with the
173 * dynamically linked version of Tox.
83 */ 174 */
84typedef enum { 175uint32_t tox_version_major(void);
85 TOX_AVATAR_FORMAT_NONE = 0,
86 TOX_AVATAR_FORMAT_PNG
87}
88TOX_AVATAR_FORMAT;
89 176
90#ifndef __TOX_DEFINED__ 177/**
91#define __TOX_DEFINED__ 178 * Return the minor version number of the library.
92typedef struct Tox Tox; 179 */
93#endif 180uint32_t tox_version_minor(void);
181
182/**
183 * Return the patch number of the library.
184 */
185uint32_t tox_version_patch(void);
186
187/**
188 * Return whether the compiled library version is compatible with the passed
189 * version numbers.
190 */
191bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch);
192
193/**
194 * A convenience macro to call tox_version_is_compatible with the currently
195 * compiling API version.
196 */
197#define TOX_VERSION_IS_ABI_COMPATIBLE() \
198 tox_version_is_compatible(TOX_VERSION_MAJOR, TOX_VERSION_MINOR, TOX_VERSION_PATCH)
94 199
95/* NOTE: Strings in Tox are all UTF-8, (This means that there is no terminating NULL character.) 200
201/*******************************************************************************
96 * 202 *
97 * The exact buffer you send will be received at the other end without modification. 203 * :: Numeric constants
98 * 204 *
99 * Do not treat Tox strings as C strings. 205 ******************************************************************************/
100 */
101 206
102/* return TOX_FRIEND_ADDRESS_SIZE byte address to give to others. 207
103 * format: [public_key (32 bytes)][nospam number (4 bytes)][checksum (2 bytes)] 208/**
209 * The size of a Tox Public Key in bytes.
104 */ 210 */
105void tox_get_address(const Tox *tox, uint8_t *address); 211#define TOX_PUBLIC_KEY_SIZE 32
106 212
107/* Add a friend. 213/**
108 * Set the data that will be sent along with friend request. 214 * The size of a Tox address in bytes. Tox addresses are in the format
109 * address is the address of the friend (returned by getaddress of the friend you wish to add) it must be TOX_FRIEND_ADDRESS_SIZE bytes. TODO: add checksum. 215 * [Public Key (TOX_PUBLIC_KEY_SIZE bytes)][nospam (4 bytes)][checksum (2 bytes)].
110 * data is the data and length is the length (maximum length of data is TOX_MAX_FRIENDREQUEST_LENGTH).
111 * 216 *
112 * return the friend number if success. 217 * The checksum is computed over the Public Key and the nospam value. The first
113 * return TOX_FAERR_TOOLONG if message length is too long. 218 * byte is an XOR of all the even bytes (0, 2, 4, ...), the second byte is an
114 * return TOX_FAERR_NOMESSAGE if no message (message length must be >= 1 byte). 219 * XOR of all the odd bytes (1, 3, 5, ...) of the Public Key and nospam.
115 * return TOX_FAERR_OWNKEY if user's own key.
116 * return TOX_FAERR_ALREADYSENT if friend request already sent or already a friend.
117 * return TOX_FAERR_UNKNOWN for unknown error.
118 * return TOX_FAERR_BADCHECKSUM if bad checksum in address.
119 * return TOX_FAERR_SETNEWNOSPAM if the friend was already there but the nospam was different.
120 * (the nospam for that friend was set to the new one).
121 * return TOX_FAERR_NOMEM if increasing the friend list size fails.
122 */ 220 */
123int32_t tox_add_friend(Tox *tox, const uint8_t *address, const uint8_t *data, uint16_t length); 221#define TOX_ADDRESS_SIZE (TOX_PUBLIC_KEY_SIZE + sizeof(uint32_t) + sizeof(uint16_t))
124 222
223/**
224 * Maximum length of a nickname in bytes.
225 */
226#define TOX_MAX_NAME_LENGTH 128
125 227
126/* Add a friend without sending a friendrequest. 228/**
127 * return the friend number if success. 229 * Maximum length of a status message in bytes.
128 * return -1 if failure.
129 */ 230 */
130int32_t tox_add_friend_norequest(Tox *tox, const uint8_t *public_key); 231#define TOX_MAX_STATUS_MESSAGE_LENGTH 1007
131 232
132/* return the friend number associated to that client id. 233/**
133 return -1 if no such friend */ 234 * Maximum length of a friend request message in bytes.
134int32_t tox_get_friend_number(const Tox *tox, const uint8_t *public_key); 235 */
236#define TOX_MAX_FRIEND_REQUEST_LENGTH 1016
135 237
136/* Copies the public key associated to that friend id into public_key buffer. 238/**
137 * Make sure that public_key is of size TOX_PUBLIC_KEY_SIZE. 239 * Maximum length of a single message after which it should be split.
138 * return 0 if success.
139 * return -1 if failure.
140 */ 240 */
141int tox_get_client_id(const Tox *tox, int32_t friendnumber, uint8_t *public_key); 241#define TOX_MAX_MESSAGE_LENGTH 1368
142 242
143/* Remove a friend. 243/**
144 * 244 * Maximum size of custom packets. TODO: should be LENGTH?
145 * return 0 if success.
146 * return -1 if failure.
147 */ 245 */
148int tox_del_friend(Tox *tox, int32_t friendnumber); 246#define TOX_MAX_CUSTOM_PACKET_SIZE 1373
149 247
150/* Checks friend's connecting status. 248/**
151 * 249 * The number of bytes in a hash generated by tox_hash.
152 * return 1 if friend is connected to us (Online).
153 * return 0 if friend is not connected to us (Offline).
154 * return -1 on failure.
155 */ 250 */
156int tox_get_friend_connection_status(const Tox *tox, int32_t friendnumber); 251#define TOX_HASH_LENGTH /*crypto_hash_sha256_BYTES*/ 32
157 252
158/* Checks if there exists a friend with given friendnumber. 253/*******************************************************************************
254 *
255 * :: Global enumerations
159 * 256 *
160 * return 1 if friend exists. 257 ******************************************************************************/
161 * return 0 if friend doesn't exist. 258
259
260/**
261 * Represents the possible statuses a client can have.
162 */ 262 */
163int tox_friend_exists(const Tox *tox, int32_t friendnumber); 263typedef enum TOX_STATUS {
264 /**
265 * User is online and available.
266 */
267 TOX_STATUS_NONE,
268 /**
269 * User is away. Clients can set this e.g. after a user defined
270 * inactivity time.
271 */
272 TOX_STATUS_AWAY,
273 /**
274 * User is busy. Signals to other clients that this client does not
275 * currently wish to communicate.
276 */
277 TOX_STATUS_BUSY
278} TOX_STATUS;
164 279
165/* Send a text chat message to an online friend. 280
281/*******************************************************************************
166 * 282 *
167 * return the message id if packet was successfully put into the send queue. 283 * :: Startup options
168 * return 0 if it was not.
169 * 284 *
170 * maximum length of messages is TOX_MAX_MESSAGE_LENGTH, your client must split larger messages 285 ******************************************************************************/
171 * or else sending them will not work. No the core will not split messages for you because that 286
172 * requires me to parse UTF-8. 287
288typedef enum TOX_PROXY_TYPE {
289 /**
290 * Don't use a proxy.
291 */
292 TOX_PROXY_TYPE_NONE,
293 /**
294 * HTTP proxy using CONNECT.
295 */
296 TOX_PROXY_TYPE_HTTP,
297 /**
298 * SOCKS proxy for simple socket pipes.
299 */
300 TOX_PROXY_TYPE_SOCKS5
301} TOX_PROXY_TYPE;
302
303
304/**
305 * This struct contains all the startup options for Tox. You can either allocate
306 * this object yourself, and pass it to tox_options_default, or call
307 * tox_options_new to get a new default options object.
308 */
309struct Tox_Options {
310 /**
311 * The type of socket to create.
312 *
313 * If this is set to false, an IPv4 socket is created, which subsequently
314 * only allows IPv4 communication.
315 * If it is set to true, an IPv6 socket is created, allowing both IPv4 and
316 * IPv6 communication.
317 */
318 bool ipv6_enabled;
319
320 /**
321 * Enable the use of UDP communication when available.
322 *
323 * Setting this to false will force Tox to use TCP only. Communications will
324 * need to be relayed through a TCP relay node, potentially slowing them down.
325 * Disabling UDP support is necessary when using anonymous proxies or Tor.
326 */
327 bool udp_enabled;
328
329 /**
330 * Pass communications through a proxy.
331 */
332 TOX_PROXY_TYPE proxy_type;
333
334 /**
335 * The IP address or DNS name of the proxy to be used.
336 *
337 * If used, this must be non-NULL and be a valid DNS name. The name must not
338 * exceed 255 characters, and be in a NUL-terminated C string format
339 * (255 chars + 1 NUL byte).
340 *
341 * This member is ignored (it can be NULL) if proxy_enabled is false.
342 */
343 char const *proxy_address;
344
345 /**
346 * The port to use to connect to the proxy server.
347 *
348 * Ports must be in the range (1, 65535). The value is ignored if
349 * proxy_enabled is false.
350 */
351 uint16_t proxy_port;
352};
353
354
355/**
356 * Initialises a Tox_Options object with the default options.
357 *
358 * The result of this function is independent of the original options. All
359 * values will be overwritten, no values will be read (so it is permissible
360 * to pass an uninitialised object).
173 * 361 *
174 * You will want to retain the return value, it will be passed to your read_receipt callback 362 * If options is NULL, this function has no effect.
175 * if one is received. 363 *
364 * @param options An options object to be filled with default options.
176 */ 365 */
177uint32_t tox_send_message(Tox *tox, int32_t friendnumber, const uint8_t *message, uint32_t length); 366void tox_options_default(struct Tox_Options *options);
367
368
369typedef enum TOX_ERR_OPTIONS_NEW {
370 TOX_ERR_OPTIONS_NEW_OK,
371 /**
372 * The function failed to allocate enough memory for the options struct.
373 */
374 TOX_ERR_OPTIONS_NEW_MALLOC
375} TOX_ERR_OPTIONS_NEW;
178 376
179/* Send an action to an online friend. 377/**
378 * Allocates a new Tox_Options object and initialises it with the default
379 * options. This function can be used to preserve long term ABI compatibility by
380 * giving the responsibility of allocation and deallocation to the Tox library.
180 * 381 *
181 * return the message id if packet was successfully put into the send queue. 382 * Objects returned from this function must be freed using the tox_options_free
182 * return 0 if it was not. 383 * function.
183 * 384 *
184 * maximum length of actions is TOX_MAX_MESSAGE_LENGTH, your client must split larger actions 385 * @return A new Tox_Options object with default options or NULL on failure.
185 * or else sending them will not work. No the core will not split actions for you because that 386 */
186 * requires me to parse UTF-8. 387struct Tox_Options *tox_options_new(TOX_ERR_OPTIONS_NEW *error);
388
389
390/**
391 * Releases all resources associated with an options objects.
187 * 392 *
188 * You will want to retain the return value, it will be passed to your read_receipt callback 393 * Passing a pointer that was not returned by tox_options_new results in
189 * if one is received. 394 * undefined behaviour.
190 */ 395 */
191uint32_t tox_send_action(Tox *tox, int32_t friendnumber, const uint8_t *action, uint32_t length); 396void tox_options_free(struct Tox_Options *options);
397
398
399/*******************************************************************************
400 *
401 * :: Creation and destruction
402 *
403 ******************************************************************************/
404
192 405
193/* Set our nickname. 406typedef enum TOX_ERR_NEW {
194 * name must be a string of maximum MAX_NAME_LENGTH length. 407 TOX_ERR_NEW_OK,
195 * length must be at least 1 byte. 408 TOX_ERR_NEW_NULL,
196 * length is the length of name. 409 /**
410 * The function was unable to allocate enough memory to store the internal
411 * structures for the Tox object.
412 */
413 TOX_ERR_NEW_MALLOC,
414 /**
415 * The function was unable to bind to a port. This may mean that all ports
416 * have already been bound, e.g. by other Tox instances, or it may mean
417 * a permission error. You may be able to gather more information from errno.
418 */
419 TOX_ERR_NEW_PORT_ALLOC,
420 /**
421 * proxy_enabled was true, but the proxy_address passed had an invalid format
422 * or was NULL.
423 */
424 TOX_ERR_NEW_PROXY_BAD_HOST,
425 /**
426 * proxy_enabled was true, but the proxy_port was invalid.
427 */
428 TOX_ERR_NEW_PROXY_BAD_PORT,
429 /**
430 * The proxy address passed could not be resolved.
431 */
432 TOX_ERR_NEW_PROXY_NOT_FOUND,
433 /**
434 * The byte array to be loaded contained an encrypted save.
435 */
436 TOX_ERR_NEW_LOAD_ENCRYPTED,
437 /**
438 * The data format was invalid. This can happen when loading data that was
439 * saved by an older version of Tox, or when the data has been corrupted.
440 * When loading from badly formatted data, some data may have been loaded,
441 * and the rest is discarded. Passing an invalid length parameter also
442 * causes this error.
443 */
444 TOX_ERR_NEW_LOAD_BAD_FORMAT
445} TOX_ERR_NEW;
446
447
448/**
449 * @brief Creates and initialises a new Tox instance with the options passed.
450 *
451 * This function will bring the instance into a valid state. Running the event
452 * loop with a new instance will operate correctly.
453 *
454 * If the data parameter is not NULL, this function will load the Tox instance
455 * from a byte array previously filled by tox_save.
456 *
457 * If loading failed or succeeded only partially, the new or partially loaded
458 * instance is returned and an error code is set.
459 *
460 * @param options An options object as described above. If this parameter is
461 * NULL, the default options are used.
462 * @param data A byte array containing data previously stored by tox_save.
463 * @param length The length of the byte array data. If this parameter is 0, the
464 * data parameter is ignored.
465 *
466 * @see tox_iteration for the event loop.
467 */
468Tox *tox_new(struct Tox_Options const *options, uint8_t const *data, size_t length, TOX_ERR_NEW *error);
469
470
471/**
472 * Releases all resources associated with the Tox instance and disconnects from
473 * the network.
197 * 474 *
198 * return 0 if success. 475 * After calling this function, the Tox pointer becomes invalid. No other
199 * return -1 if failure. 476 * functions can be called, and the pointer value can no longer be read.
200 */ 477 */
201int tox_set_name(Tox *tox, const uint8_t *name, uint16_t length); 478void tox_kill(Tox *tox);
479
202 480
203/* 481/**
204 * Get your nickname. 482 * Calculates the number of bytes required to store the tox instance with
205 * m - The messenger context to use. 483 * tox_save. This function cannot fail. The result is always greater than 0.
206 * name - needs to be a valid memory location with a size of at least MAX_NAME_LENGTH (128) bytes.
207 * 484 *
208 * return length of name. 485 * @see threading for concurrency implications.
209 * return 0 on error.
210 */ 486 */
211uint16_t tox_get_self_name(const Tox *tox, uint8_t *name); 487size_t tox_save_size(Tox const *tox);
212 488
213/* Get name of friendnumber and put it in name. 489/**
214 * name needs to be a valid memory location with a size of at least MAX_NAME_LENGTH (128) bytes. 490 * Store all information associated with the tox instance to a byte array.
215 * 491 *
216 * return length of name if success. 492 * @param data A memory region large enough to store the tox instance data.
217 * return -1 if failure. 493 * Call tox_save_size to find the number of bytes required. If this parameter
494 * is NULL, this function has no effect.
218 */ 495 */
219int tox_get_name(const Tox *tox, int32_t friendnumber, uint8_t *name); 496void tox_save(Tox const *tox, uint8_t *data);
497
498
499/*******************************************************************************
500 *
501 * :: Connection lifecycle and event loop
502 *
503 ******************************************************************************/
504
505
506typedef enum TOX_ERR_BOOTSTRAP {
507 TOX_ERR_BOOTSTRAP_OK,
508 TOX_ERR_BOOTSTRAP_NULL,
509 /**
510 * The address could not be resolved to an IP address, or the IP address
511 * passed was invalid.
512 */
513 TOX_ERR_BOOTSTRAP_BAD_ADDRESS,
514 /**
515 * The port passed was invalid. The valid port range is (1, 65535).
516 */
517 TOX_ERR_BOOTSTRAP_BAD_PORT
518} TOX_ERR_BOOTSTRAP;
220 519
221/* returns the length of name on success. 520/**
222 * returns -1 on failure. 521 * Sends a "get nodes" request to the given bootstrap node with IP, port, and
522 * public key to setup connections.
523 *
524 * This function will attempt to connect to the node using UDP and TCP at the
525 * same time.
526 *
527 * Tox will use the node as a TCP relay in case Tox_Options.udp_enabled was
528 * false, and also to connect to friends that are in TCP-only mode. Tox will
529 * also use the TCP connection when NAT hole punching is slow, and later switch
530 * to UDP if hole punching succeeds.
531 *
532 * @param address The hostname or IP address (IPv4 or IPv6) of the node.
533 * @param port The port on the host on which the bootstrap Tox instance is
534 * listening.
535 * @param public_key The long term public key of the bootstrap node
536 * (TOX_PUBLIC_KEY_SIZE bytes).
537 * @return true on success.
223 */ 538 */
224int tox_get_name_size(const Tox *tox, int32_t friendnumber); 539bool tox_bootstrap(Tox *tox, char const *address, uint16_t port, uint8_t const *public_key, TOX_ERR_BOOTSTRAP *error);
225int tox_get_self_name_size(const Tox *tox); 540
226 541
227/* Set our user status. 542/**
543 * Adds additional host:port pair as TCP relay.
228 * 544 *
229 * userstatus must be one of TOX_USERSTATUS values. 545 * This function can be used to initiate TCP connections to different ports on
230 * max length of the status is TOX_MAX_STATUSMESSAGE_LENGTH. 546 * the same bootstrap node, or to add TCP relays without using them as
547 * bootstrap nodes.
231 * 548 *
232 * returns 0 on success. 549 * @param address The hostname or IP address (IPv4 or IPv6) of the TCP relay.
233 * returns -1 on failure. 550 * @param port The port on the host on which the TCP relay is listening.
551 * @param public_key The long term public key of the TCP relay
552 * (TOX_PUBLIC_KEY_SIZE bytes).
553 * @return true on success.
234 */ 554 */
235int tox_set_status_message(Tox *tox, const uint8_t *status, uint16_t length); 555bool tox_add_tcp_relay(Tox *tox, char const *address, uint16_t port, uint8_t const *public_key,
236int tox_set_user_status(Tox *tox, uint8_t userstatus); 556 TOX_ERR_BOOTSTRAP *error);
557
558
559typedef enum TOX_CONNECTION {
560 /**
561 * There is no connection. This instance, or the friend the state change is
562 * about, is now offline.
563 */
564 TOX_CONNECTION_NONE,
565 /**
566 * A TCP connection has been established. For the own instance, this means it
567 * is connected through a TCP relay, only. For a friend, this means that the
568 * connection to that particular friend goes through a TCP relay.
569 */
570 TOX_CONNECTION_TCP4,
571 TOX_CONNECTION_TCP6,
572 /**
573 * A UDP connection has been established. For the own instance, this means it
574 * is able to send UDP packets to DHT nodes, but may still be connected to
575 * a TCP relay. For a friend, this means that the connection to that
576 * particular friend was built using direct UDP packets.
577 */
578 TOX_CONNECTION_UDP4,
579 TOX_CONNECTION_UDP6
580} TOX_CONNECTION;
581
237 582
238/* returns the length of status message on success. 583/**
239 * returns -1 on failure. 584 * Return whether we are connected to the DHT. The return value is equal to the
585 * last value received through the `connection_status` callback.
240 */ 586 */
241int tox_get_status_message_size(const Tox *tox, int32_t friendnumber); 587TOX_CONNECTION tox_get_connection_status(Tox const *tox);
242int tox_get_self_status_message_size(const Tox *tox);
243 588
244/* Copy friendnumber's status message into buf, truncating if size is over maxlen. 589/**
245 * Get the size you need to allocate from m_get_statusmessage_size. 590 * The function type for the `connection_status` callback.
246 * The self variant will copy our own status message.
247 * 591 *
248 * returns the length of the copied data on success 592 * @param connection_status Equal to the return value of
249 * retruns -1 on failure. 593 * tox_get_connection_status.
250 */ 594 */
251int tox_get_status_message(const Tox *tox, int32_t friendnumber, uint8_t *buf, uint32_t maxlen); 595typedef void tox_connection_status_cb(Tox *tox, TOX_CONNECTION connection_status, void *user_data);
252int tox_get_self_status_message(const Tox *tox, uint8_t *buf, uint32_t maxlen);
253 596
254/* return one of TOX_USERSTATUS values. 597/**
255 * Values unknown to your application should be represented as TOX_USERSTATUS_NONE. 598 * Set the callback for the `connection_status` event. Pass NULL to unset.
256 * As above, the self variant will return our own TOX_USERSTATUS. 599 *
257 * If friendnumber is invalid, this shall return TOX_USERSTATUS_INVALID. 600 * This event is triggered whenever there is a change in the DHT connection
601 * state. When disconnected, a client may choose to call tox_bootstrap again, to
602 * reconnect to the DHT. Note that this state may frequently change for short
603 * amounts of time. Clients should therefore not immediately bootstrap on
604 * receiving a disconnect.
605 *
606 * TODO: how long should a client wait before bootstrapping again?
607 */
608void tox_callback_connection_status(Tox *tox, tox_connection_status_cb *function, void *user_data);
609
610
611/**
612 * Return the time in milliseconds before tox_iteration() should be called again
613 * for optimal performance.
258 */ 614 */
259uint8_t tox_get_user_status(const Tox *tox, int32_t friendnumber); 615uint32_t tox_iteration_interval(Tox const *tox);
260uint8_t tox_get_self_user_status(const Tox *tox);
261 616
262/* returns timestamp of last time friendnumber was seen online, or 0 if never seen. 617
263 * returns -1 on error. 618/**
619 * The main loop that needs to be run in intervals of tox_iteration_interval()
620 * milliseconds.
264 */ 621 */
265uint64_t tox_get_last_online(const Tox *tox, int32_t friendnumber); 622void tox_iteration(Tox *tox);
623
266 624
267/* Set our typing status for a friend. 625/*******************************************************************************
268 * You are responsible for turning it on or off.
269 * 626 *
270 * returns 0 on success. 627 * :: Internal client information (Tox address/id)
271 * returns -1 on failure. 628 *
272 */ 629 ******************************************************************************/
273int tox_set_user_is_typing(Tox *tox, int32_t friendnumber, uint8_t is_typing);
274 630
275/* Get the typing status of a friend. 631
632/**
633 * Writes the Tox friend address of the client to a byte array. The address is
634 * not in human-readable format. If a client wants to display the address,
635 * formatting is required.
276 * 636 *
277 * returns 0 if friend is not typing. 637 * @param address A memory region of at least TOX_ADDRESS_SIZE bytes. If this
278 * returns 1 if friend is typing. 638 * parameter is NULL, this function has no effect.
639 * @see TOX_ADDRESS_SIZE for the address format.
279 */ 640 */
280uint8_t tox_get_is_typing(const Tox *tox, int32_t friendnumber); 641void tox_self_get_address(Tox const *tox, uint8_t *address);
281 642
282/* Return the number of friends in the instance m.
283 * You should use this to determine how much memory to allocate
284 * for copy_friendlist. */
285uint32_t tox_count_friendlist(const Tox *tox);
286 643
287/* Return the number of online friends in the instance m. */ 644/**
288uint32_t tox_get_num_online_friends(const Tox *tox); 645 * Set the 4-byte nospam part of the address.
646 *
647 * @param nospam Any 32 bit unsigned integer.
648 */
649void tox_self_set_nospam(Tox *tox, uint32_t nospam);
289 650
290/* Copy a list of valid friend IDs into the array out_list. 651/**
291 * If out_list is NULL, returns 0. 652 * Get the 4-byte nospam part of the address.
292 * Otherwise, returns the number of elements copied. 653 */
293 * If the array was too small, the contents 654uint32_t tox_self_get_nospam(Tox const *tox);
294 * of out_list will be truncated to list_size. */
295uint32_t tox_get_friendlist(const Tox *tox, int32_t *out_list, uint32_t list_size);
296 655
297/* Set the function that will be executed when a friend request is received. 656/**
298 * Function format is function(Tox *tox, const uint8_t * public_key, const uint8_t * data, uint16_t length, void *userdata) 657 * Copy the Tox Public Key (long term public key) from the Tox object.
658 *
659 * @param public_key A memory region of at least TOX_PUBLIC_KEY_SIZE bytes. If
660 * this parameter is NULL, this function has no effect.
299 */ 661 */
300void tox_callback_friend_request(Tox *tox, void (*function)(Tox *tox, const uint8_t *, const uint8_t *, uint16_t, 662void tox_self_get_public_key(Tox const *tox, uint8_t *public_key);
301 void *), void *userdata);
302 663
303/* Set the function that will be executed when a message from a friend is received. 664/**
304 * Function format is: function(Tox *tox, int32_t friendnumber, const uint8_t * message, uint16_t length, void *userdata) 665 * Copy the private key from the Tox object.
666 *
667 * @param private_key A memory region of at least TOX_PUBLIC_KEY_SIZE bytes. If
668 * this parameter is NULL, this function has no effect.
305 */ 669 */
306void tox_callback_friend_message(Tox *tox, void (*function)(Tox *tox, int32_t, const uint8_t *, uint16_t, void *), 670void tox_self_get_private_key(Tox const *tox, uint8_t *private_key);
307 void *userdata); 671
672
673/*******************************************************************************
674 *
675 * :: User-visible client information (nickname/status)
676 *
677 ******************************************************************************/
308 678
309/* Set the function that will be executed when an action from a friend is received. 679
310 * Function format is: function(Tox *tox, int32_t friendnumber, const uint8_t * action, uint16_t length, void *userdata) 680/**
681 * Common error codes for all functions that set a piece of user-visible
682 * client information.
311 */ 683 */
312void tox_callback_friend_action(Tox *tox, void (*function)(Tox *tox, int32_t, const uint8_t *, uint16_t, void *), 684typedef enum TOX_ERR_SET_INFO {
313 void *userdata); 685 TOX_ERR_SET_INFO_OK,
686 TOX_ERR_SET_INFO_NULL,
687 /**
688 * Information length exceeded maximum permissible size.
689 */
690 TOX_ERR_SET_INFO_TOO_LONG
691} TOX_ERR_SET_INFO;
692
314 693
315/* Set the callback for name changes. 694/**
316 * function(Tox *tox, int32_t friendnumber, const uint8_t *newname, uint16_t length, void *userdata) 695 * Set the nickname for the Tox client.
317 * You are not responsible for freeing newname 696 *
697 * Nickname length cannot exceed TOX_MAX_NAME_LENGTH. If length is 0, the name
698 * parameter is ignored (it can be NULL), and the nickname is set back to empty.
699 *
700 * @param name A byte array containing the new nickname.
701 * @param length The size of the name byte array.
702 *
703 * @return true on success.
318 */ 704 */
319void tox_callback_name_change(Tox *tox, void (*function)(Tox *tox, int32_t, const uint8_t *, uint16_t, void *), 705bool tox_self_set_name(Tox *tox, uint8_t const *name, size_t length, TOX_ERR_SET_INFO *error);
320 void *userdata);
321 706
322/* Set the callback for status message changes. 707/**
323 * function(Tox *tox, int32_t friendnumber, const uint8_t *newstatus, uint16_t length, void *userdata) 708 * Return the length of the current nickname as passed to tox_self_set_name.
324 * You are not responsible for freeing newstatus. 709 *
710 * If no nickname was set before calling this function, the name is empty,
711 * and this function returns 0.
712 *
713 * @see threading for concurrency implications.
325 */ 714 */
326void tox_callback_status_message(Tox *tox, void (*function)(Tox *tox, int32_t, const uint8_t *, uint16_t, void *), 715size_t tox_self_get_name_size(Tox const *tox);
327 void *userdata);
328 716
329/* Set the callback for status type changes. 717/**
330 * function(Tox *tox, int32_t friendnumber, uint8_t TOX_USERSTATUS, void *userdata) 718 * Write the nickname set by tox_self_set_name to a byte array.
719 *
720 * If no nickname was set before calling this function, the name is empty,
721 * and this function has no effect.
722 *
723 * Call tox_self_get_name_size to find out how much memory to allocate for
724 * the result.
725 *
726 * @param name A valid memory location large enough to hold the nickname.
727 * If this parameter is NULL, the function has no effect.
331 */ 728 */
332void tox_callback_user_status(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, void *), void *userdata); 729void tox_self_get_name(Tox const *tox, uint8_t *name);
333 730
334/* Set the callback for typing changes. 731
335 * function (Tox *tox, int32_t friendnumber, uint8_t is_typing, void *userdata) 732/**
733 * Set the client's status message.
734 *
735 * Status message length cannot exceed TOX_MAX_STATUS_MESSAGE_LENGTH. If
736 * length is 0, the status parameter is ignored (it can be NULL), and the
737 * user status is set back to empty.
336 */ 738 */
337void tox_callback_typing_change(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, void *), void *userdata); 739bool tox_self_set_status_message(Tox *tox, uint8_t const *status, size_t length, TOX_ERR_SET_INFO *error);
338 740
339/* Set the callback for read receipts. 741/**
340 * function(Tox *tox, int32_t friendnumber, uint32_t receipt, void *userdata) 742 * Return the length of the current status message as passed to
743 * tox_self_set_status_message.
341 * 744 *
342 * If you are keeping a record of returns from m_sendmessage; 745 * If no status message was set before calling this function, the status
343 * receipt might be one of those values, meaning the message 746 * is empty, and this function returns 0.
344 * has been received on the other side. 747 *
345 * Since core doesn't track ids for you, receipt may not correspond to any message. 748 * @see threading for concurrency implications.
346 * In that case, you should discard it.
347 */ 749 */
348void tox_callback_read_receipt(Tox *tox, void (*function)(Tox *tox, int32_t, uint32_t, void *), void *userdata); 750size_t tox_self_get_status_message_size(Tox const *tox);
349 751
350/* Set the callback for connection status changes. 752/**
351 * function(Tox *tox, int32_t friendnumber, uint8_t status, void *userdata) 753 * Write the status message set by tox_self_set_status_message to a byte array.
754 *
755 * If no status message was set before calling this function, the status is
756 * empty, and this function has no effect.
352 * 757 *
353 * Status: 758 * Call tox_self_status_message_size to find out how much memory to allocate for
354 * 0 -- friend went offline after being previously online 759 * the result.
355 * 1 -- friend went online
356 * 760 *
357 * NOTE: This callback is not called when adding friends, thus the "after 761 * @param name A valid memory location large enough to hold the status message.
358 * being previously online" part. it's assumed that when adding friends, 762 * If this parameter is NULL, the function has no effect.
359 * their connection status is offline.
360 */ 763 */
361void tox_callback_connection_status(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, void *), void *userdata); 764void tox_self_get_status_message(Tox const *tox, uint8_t *status);
362 765
363 766
364/**********ADVANCED FUNCTIONS (If you don't know what they do you can safely ignore them.) ************/ 767/**
768 * Set the client's user status.
769 *
770 * @param user_status One of the user statuses listed in the enumeration above.
771 */
772void tox_self_set_status(Tox *tox, TOX_STATUS user_status);
365 773
366/* Functions to get/set the nospam part of the id. 774/**
775 * Returns the client's user status.
367 */ 776 */
368uint32_t tox_get_nospam(const Tox *tox); 777TOX_STATUS tox_self_get_status(Tox const *tox);
369void tox_set_nospam(Tox *tox, uint32_t nospam); 778
779
780/*******************************************************************************
781 *
782 * :: Friend list management
783 *
784 ******************************************************************************/
370 785
371/* Copy the public and secret key from the Tox object.
372 public_key and secret_key must be 32 bytes big.
373 if the pointer is NULL, no data will be copied to it.*/
374void tox_get_keys(Tox *tox, uint8_t *public_key, uint8_t *secret_key);
375 786
376/* Maximum size of custom packets. */ 787typedef enum TOX_ERR_FRIEND_ADD {
377#define TOX_MAX_CUSTOM_PACKET_SIZE 1373 788 TOX_ERR_FRIEND_ADD_OK,
789 TOX_ERR_FRIEND_ADD_NULL,
790 /**
791 * The length of the friend request message exceeded
792 * TOX_MAX_FRIEND_REQUEST_LENGTH.
793 */
794 TOX_ERR_FRIEND_ADD_TOO_LONG,
795 /**
796 * The friend request message was empty. This, and the TOO_LONG code will
797 * never be returned from tox_friend_add_norequest.
798 */
799 TOX_ERR_FRIEND_ADD_NO_MESSAGE,
800 /**
801 * The friend address belongs to the sending client.
802 */
803 TOX_ERR_FRIEND_ADD_OWN_KEY,
804 /**
805 * A friend request has already been sent, or the address belongs to a friend
806 * that is already on the friend list.
807 */
808 TOX_ERR_FRIEND_ADD_ALREADY_SENT,
809 /**
810 * The friend address checksum failed.
811 */
812 TOX_ERR_FRIEND_ADD_BAD_CHECKSUM,
813 /**
814 * The friend was already there, but the nospam value was different.
815 */
816 TOX_ERR_FRIEND_ADD_SET_NEW_NOSPAM,
817 /**
818 * A memory allocation failed when trying to increase the friend list size.
819 */
820 TOX_ERR_FRIEND_ADD_MALLOC
821} TOX_ERR_FRIEND_ADD;
378 822
379/* Set handlers for custom lossy packets. 823/**
380 * Set the function to be called when friend sends us a lossy packet starting with byte. 824 * Add a friend to the friend list and send a friend request.
381 * byte must be in the 200-254 range. 825 *
826 * A friend request message must be at least 1 byte long and at most
827 * TOX_MAX_FRIEND_REQUEST_LENGTH.
382 * 828 *
383 * NOTE: lossy packets behave like UDP packets meaning they might never reach the other side 829 * Friend numbers are unique identifiers used in all functions that operate on
384 * or might arrive more than once (if someone is messing with the connection) or might arrive 830 * friends. Once added, a friend number is stable for the lifetime of the Tox
385 * in the wrong order. 831 * object. After saving the state and reloading it, the friend numbers may not
832 * be the same as before. Deleting a friend creates a gap in the friend number
833 * set, which is filled by the next adding of a friend.
386 * 834 *
387 * Unless latency is an issue, it is recommended that you use lossless packets instead. 835 * If more than UINT32_MAX friends are added, this function causes undefined
836 * behaviour.
388 * 837 *
389 * return -1 on failure. 838 * @param address The address of the friend (returned by tox_self_get_address of
390 * return 0 on success. 839 * the friend you wish to add) it must be TOX_ADDRESS_SIZE bytes.
840 * @param message The message that will be sent along with the friend request.
841 * @param length The length of the data byte array.
842 *
843 * @return the friend number.
391 */ 844 */
392int tox_lossy_packet_registerhandler(Tox *tox, int32_t friendnumber, uint8_t byte, 845uint32_t tox_friend_add(Tox *tox, uint8_t const *address, uint8_t const *message, size_t length,
393 int (*packet_handler_callback)(Tox *tox, int32_t friendnumber, const uint8_t *data, uint32_t len, void *object), 846 TOX_ERR_FRIEND_ADD *error);
394 void *object); 847
395 848
396/* Function to send custom lossy packets. 849/**
397 * First byte of data must be in the range: 200-254. 850 * Add a friend without sending a friend request.
398 * 851 *
399 * return -1 on failure. 852 * This function is used to add a friend in response to a friend request. If the
400 * return 0 on success. 853 * client receives a friend request, it can be reasonably sure that the other
854 * client added this client as a friend, eliminating the need for a friend
855 * request.
856 *
857 * This function is also useful in a situation where both instances are
858 * controlled by the same entity, so that this entity can perform the mutual
859 * friend adding. In this case, there is no need for a friend request, either.
860 *
861 * @param public_key A byte array of length TOX_PUBLIC_KEY_SIZE containing the
862 * Public Key (not the Address) of the friend to add.
863 *
864 * @return the friend number.
865 * @see tox_friend_add for a more detailed description of friend numbers.
401 */ 866 */
402int tox_send_lossy_packet(const Tox *tox, int32_t friendnumber, const uint8_t *data, uint32_t length); 867uint32_t tox_friend_add_norequest(Tox *tox, uint8_t const *public_key, TOX_ERR_FRIEND_ADD *error);
868
403 869
404/* Set handlers for custom lossless packets. 870typedef enum TOX_ERR_FRIEND_DELETE {
405 * Set the function to be called when friend sends us a lossless packet starting with byte. 871 TOX_ERR_FRIEND_DELETE_OK,
406 * byte must be in the 160-191 range. 872 /**
873 * There was no friend with the given friend number. No friends were deleted.
874 */
875 TOX_ERR_FRIEND_DELETE_FRIEND_NOT_FOUND
876} TOX_ERR_FRIEND_DELETE;
877
878/**
879 * Remove a friend from the friend list.
880 *
881 * This does not notify the friend of their deletion. After calling this
882 * function, this client will appear offline to the friend and no communication
883 * can occur between the two.
407 * 884 *
408 * Lossless packets behave kind of like TCP (reliability, arrive in order.) but with packets instead of a stream. 885 * @friend_number Friend number for the friend to be deleted.
409 * 886 *
410 * return -1 on failure. 887 * @return true on success.
411 * return 0 on success.
412 */ 888 */
413int tox_lossless_packet_registerhandler(Tox *tox, int32_t friendnumber, uint8_t byte, 889bool tox_friend_delete(Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_DELETE *error);
414 int (*packet_handler_callback)(Tox *tox, int32_t friendnumber, const uint8_t *data, uint32_t len, void *object),
415 void *object);
416 890
417/* Function to send custom lossless packets. 891
418 * First byte of data must be in the range: 160-191. 892/*******************************************************************************
419 * 893 *
420 * return -1 on failure. 894 * :: Friend list queries
421 * return 0 on success. 895 *
422 */ 896 ******************************************************************************/
423int tox_send_lossless_packet(const Tox *tox, int32_t friendnumber, const uint8_t *data, uint32_t length); 897
424 898
425/**********GROUP CHAT FUNCTIONS: WARNING Group chats will be rewritten so this might change ************/ 899typedef enum TOX_ERR_FRIEND_BY_PUBLIC_KEY {
900 TOX_ERR_FRIEND_BY_PUBLIC_KEY_OK,
901 TOX_ERR_FRIEND_BY_PUBLIC_KEY_NULL,
902 /**
903 * No friend with the given Public Key exists on the friend list.
904 */
905 TOX_ERR_FRIEND_BY_PUBLIC_KEY_NOT_FOUND
906} TOX_ERR_FRIEND_BY_PUBLIC_KEY;
426 907
427/* Group chat types for tox_callback_group_invite function. 908/**
909 * Return the friend number associated with that Public Key.
428 * 910 *
429 * TOX_GROUPCHAT_TYPE_TEXT groupchats must be accepted with the tox_join_groupchat() function. 911 * @param public_key A byte array containing the Public Key.
430 * The function to accept TOX_GROUPCHAT_TYPE_AV is in toxav.
431 */ 912 */
432enum { 913uint32_t tox_friend_by_public_key(Tox const *tox, uint8_t const *public_key, TOX_ERR_FRIEND_BY_PUBLIC_KEY *error);
433 TOX_GROUPCHAT_TYPE_TEXT,
434 TOX_GROUPCHAT_TYPE_AV
435};
436 914
437/* Set the callback for group invites. 915
438 * 916typedef enum TOX_ERR_FRIEND_GET_PUBLIC_KEY {
439 * Function(Tox *tox, int32_t friendnumber, uint8_t type, const uint8_t *data, uint16_t length, void *userdata) 917 TOX_ERR_FRIEND_GET_PUBLIC_KEY_OK,
918 /**
919 * No friend with the given number exists on the friend list.
920 */
921 TOX_ERR_FRIEND_GET_PUBLIC_KEY_FRIEND_NOT_FOUND
922} TOX_ERR_FRIEND_GET_PUBLIC_KEY;
923
924/**
925 * Copies the Public Key associated with a given friend number to a byte array.
440 * 926 *
441 * data of length is what needs to be passed to join_groupchat(). 927 * @param friend_number The friend number you want the Public Key of.
928 * @param public_key A memory region of at least TOX_PUBLIC_KEY_SIZE bytes. If
929 * this parameter is NULL, this function has no effect.
442 * 930 *
443 * for what type means see the enum right above this comment. 931 * @return true on success.
444 */ 932 */
445void tox_callback_group_invite(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, const uint8_t *, uint16_t, 933bool tox_friend_get_public_key(Tox const *tox, uint32_t friend_number, uint8_t *public_key,
446 void *), void *userdata); 934 TOX_ERR_FRIEND_GET_PUBLIC_KEY *error);
447 935
448/* Set the callback for group messages. 936
449 * 937/**
450 * Function(Tox *tox, int groupnumber, int peernumber, const uint8_t * message, uint16_t length, void *userdata) 938 * Checks if a friend with the given friend number exists and returns true if
939 * it does.
451 */ 940 */
452void tox_callback_group_message(Tox *tox, void (*function)(Tox *tox, int, int, const uint8_t *, uint16_t, void *), 941bool tox_friend_exists(Tox const *tox, uint32_t friend_number);
453 void *userdata);
454 942
455/* Set the callback for group actions. 943
944/**
945 * Return the number of friends on the friend list.
456 * 946 *
457 * Function(Tox *tox, int groupnumber, int peernumber, const uint8_t * action, uint16_t length, void *userdata) 947 * This function can be used to determine how much memory to allocate for
948 * tox_friend_list.
458 */ 949 */
459void tox_callback_group_action(Tox *tox, void (*function)(Tox *tox, int, int, const uint8_t *, uint16_t, void *), 950size_t tox_friend_list_size(Tox const *tox);
460 void *userdata); 951
461 952
462/* Set callback function for title changes. 953/**
954 * Copy a list of valid friend numbers into an array.
463 * 955 *
464 * Function(Tox *tox, int groupnumber, int peernumber, uint8_t * title, uint8_t length, void *userdata) 956 * Call tox_friend_list_size to determine the number of elements to allocate.
465 * if peernumber == -1, then author is unknown (e.g. initial joining the group) 957 *
958 * @param list A memory region with enough space to hold the friend list. If
959 * this parameter is NULL, this function has no effect.
466 */ 960 */
467void tox_callback_group_title(Tox *tox, void (*function)(Tox *tox, int, int, const uint8_t *, uint8_t, 961void tox_friend_list(Tox const *tox, uint32_t *list);
468 void *), void *userdata); 962
469 963
470/* Set callback function for peer name list changes. 964
965/*******************************************************************************
966 *
967 * :: Friend-specific state queries (can also be received through callbacks)
471 * 968 *
472 * It gets called every time the name list changes(new peer/name, deleted peer) 969 ******************************************************************************/
473 * Function(Tox *tox, int groupnumber, int peernumber, TOX_CHAT_CHANGE change, void *userdata) 970
971
972/**
973 * Common error codes for friend state query functions.
474 */ 974 */
475typedef enum { 975typedef enum TOX_ERR_FRIEND_QUERY {
476 TOX_CHAT_CHANGE_PEER_ADD, 976 TOX_ERR_FRIEND_QUERY_OK,
477 TOX_CHAT_CHANGE_PEER_DEL, 977 /**
478 TOX_CHAT_CHANGE_PEER_NAME, 978 * The pointer parameter for storing the query result (name, message) was
479} TOX_CHAT_CHANGE; 979 * NULL. Unlike the `_self_` variants of these functions, which have no effect
980 * when a parameter is NULL, these functions return an error in that case.
981 */
982 TOX_ERR_FRIEND_QUERY_NULL,
983 /**
984 * The friend_number did not designate a valid friend.
985 */
986 TOX_ERR_FRIEND_QUERY_FRIEND_NOT_FOUND
987} TOX_ERR_FRIEND_QUERY;
480 988
481void tox_callback_group_namelist_change(Tox *tox, void (*function)(Tox *tox, int, int, uint8_t, void *),
482 void *userdata);
483 989
484/* Creates a new groupchat and puts it in the chats array. 990/**
991 * Return the length of the friend's name. If the friend number is invalid, the
992 * return value is unspecified.
485 * 993 *
486 * return group number on success. 994 * The return value is equal to the `length` argument received by the last
487 * return -1 on failure. 995 * `friend_name` callback.
488 */ 996 */
489int tox_add_groupchat(Tox *tox); 997size_t tox_friend_get_name_size(Tox const *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error);
490 998
491/* Delete a groupchat from the chats array. 999/**
1000 * Write the name of the friend designated by the given friend number to a byte
1001 * array.
1002 *
1003 * Call tox_friend_get_name_size to determine the allocation size for the `name`
1004 * parameter.
1005 *
1006 * The data written to `name` is equal to the data received by the last
1007 * `friend_name` callback.
1008 *
1009 * @param name A valid memory region large enough to store the friend's name.
492 * 1010 *
493 * return 0 on success. 1011 * @return true on success.
494 * return -1 if failure.
495 */ 1012 */
496int tox_del_groupchat(Tox *tox, int groupnumber); 1013bool tox_friend_get_name(Tox const *tox, uint32_t friend_number, uint8_t *name, TOX_ERR_FRIEND_QUERY *error);
497 1014
498/* Copy the name of peernumber who is in groupnumber to name. 1015/**
499 * name must be at least TOX_MAX_NAME_LENGTH long. 1016 * The function type for the `friend_name` callback.
500 * 1017 *
501 * return length of name if success 1018 * @param friend_number The friend number of the friend whose name changed.
502 * return -1 if failure 1019 * @param name A byte array containing the same data as
1020 * tox_friend_get_name would write to its `name` parameter.
1021 * @param length A value equal to the return value of
1022 * tox_friend_get_name_size.
503 */ 1023 */
504int tox_group_peername(const Tox *tox, int groupnumber, int peernumber, uint8_t *name); 1024typedef void tox_friend_name_cb(Tox *tox, uint32_t friend_number, uint8_t const *name, size_t length, void *user_data);
505 1025
506/* Copy the public key of peernumber who is in groupnumber to public_key. 1026/**
507 * public_key must be TOX_PUBLIC_KEY_SIZE long. 1027 * Set the callback for the `friend_name` event. Pass NULL to unset.
508 * 1028 *
509 * returns 0 on success 1029 * This event is triggered when a friend changes their name.
510 * returns -1 on failure
511 */ 1030 */
512int tox_group_peer_pubkey(const Tox *tox, int groupnumber, int peernumber, uint8_t *public_key); 1031void tox_callback_friend_name(Tox *tox, tox_friend_name_cb *function, void *user_data);
513 1032
514/* invite friendnumber to groupnumber 1033
515 * return 0 on success 1034/**
516 * return -1 on failure 1035 * Return the length of the friend's status message. If the friend number is
1036 * invalid, the return value is unspecified.
517 */ 1037 */
518int tox_invite_friend(Tox *tox, int32_t friendnumber, int groupnumber); 1038size_t tox_friend_get_status_message_size(Tox const *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error);
519 1039
520/* Join a group (you need to have been invited first.) using data of length obtained 1040/**
521 * in the group invite callback. 1041 * Write the name of the friend designated by the given friend number to a byte
1042 * array.
1043 *
1044 * Call tox_friend_get_name_size to determine the allocation size for the `name`
1045 * parameter.
522 * 1046 *
523 * returns group number on success 1047 * The data written to `message` is equal to the data received by the last
524 * returns -1 on failure. 1048 * `friend_status_message` callback.
1049 *
1050 * @param name A valid memory region large enough to store the friend's name.
525 */ 1051 */
526int tox_join_groupchat(Tox *tox, int32_t friendnumber, const uint8_t *data, uint16_t length); 1052bool tox_friend_get_status_message(Tox const *tox, uint32_t friend_number, uint8_t *message,
1053 TOX_ERR_FRIEND_QUERY *error);
527 1054
528/* send a group message 1055/**
529 * return 0 on success 1056 * The function type for the `friend_status_message` callback.
530 * return -1 on failure 1057 *
1058 * @param friend_number The friend number of the friend whose status message
1059 * changed.
1060 * @param message A byte array containing the same data as
1061 * tox_friend_get_status_message would write to its `message` parameter.
1062 * @param length A value equal to the return value of
1063 * tox_friend_get_status_message_size.
531 */ 1064 */
532int tox_group_message_send(Tox *tox, int groupnumber, const uint8_t *message, uint16_t length); 1065typedef void tox_friend_status_message_cb(Tox *tox, uint32_t friend_number, uint8_t const *message, size_t length,
1066 void *user_data);
533 1067
534/* send a group action 1068/**
535 * return 0 on success 1069 * Set the callback for the `friend_status_message` event. Pass NULL to unset.
536 * return -1 on failure 1070 *
1071 * This event is triggered when a friend changes their name.
537 */ 1072 */
538int tox_group_action_send(Tox *tox, int groupnumber, const uint8_t *action, uint16_t length); 1073void tox_callback_friend_status_message(Tox *tox, tox_friend_status_message_cb *function, void *user_data);
539 1074
540/* set the group's title, limited to MAX_NAME_LENGTH
541 * return 0 on success
542 * return -1 on failure
543 */
544int tox_group_set_title(Tox *tox, int groupnumber, const uint8_t *title, uint8_t length);
545 1075
546/* Get group title from groupnumber and put it in title. 1076/**
547 * title needs to be a valid memory location with a max_length size of at least MAX_NAME_LENGTH (128) bytes. 1077 * Return the friend's user status (away/busy/...). If the friend number is
1078 * invalid, the return value is unspecified.
548 * 1079 *
549 * return length of copied title if success. 1080 * The status returned is equal to the last status received through the
550 * return -1 if failure. 1081 * `friend_status` callback.
551 */ 1082 */
552int tox_group_get_title(Tox *tox, int groupnumber, uint8_t *title, uint32_t max_length); 1083TOX_STATUS tox_friend_get_status(Tox const *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error);
553 1084
554/* Check if the current peernumber corresponds to ours. 1085/**
1086 * The function type for the `friend_status` callback.
555 * 1087 *
556 * return 1 if the peernumber corresponds to ours. 1088 * @param friend_number The friend number of the friend whose user status
557 * return 0 on failure. 1089 * changed.
1090 * @param status The new user status.
558 */ 1091 */
559unsigned int tox_group_peernumber_is_ours(const Tox *tox, int groupnumber, int peernumber); 1092typedef void tox_friend_status_cb(Tox *tox, uint32_t friend_number, TOX_STATUS status, void *user_data);
560 1093
561/* Return the number of peers in the group chat on success. 1094/**
562 * return -1 on failure 1095 * Set the callback for the `friend_status` event. Pass NULL to unset.
1096 *
1097 * This event is triggered when a friend changes their user status.
563 */ 1098 */
564int tox_group_number_peers(const Tox *tox, int groupnumber); 1099void tox_callback_friend_status(Tox *tox, tox_friend_status_cb *function, void *user_data);
1100
565 1101
566/* List all the peers in the group chat. 1102/**
1103 * Check whether a friend is currently connected to this client.
567 * 1104 *
568 * Copies the names of the peers to the name[length][TOX_MAX_NAME_LENGTH] array. 1105 * The result of this function is equal to the last value received by the
1106 * `friend_connection_status` callback.
569 * 1107 *
570 * Copies the lengths of the names to lengths[length] 1108 * @param friend_number The friend number for which to query the connection
1109 * status.
571 * 1110 *
572 * returns the number of peers on success. 1111 * @return the friend's connection status as it was received through the
1112 * `friend_connection_status` event.
1113 */
1114TOX_CONNECTION tox_friend_get_connection_status(Tox const *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error);
1115
1116/**
1117 * The function type for the `friend_connection_status` callback.
573 * 1118 *
574 * return -1 on failure. 1119 * @param friend_number The friend number of the friend whose connection status
1120 * changed.
1121 * @param connection_status The result of calling
1122 * tox_friend_get_connection_status on the passed friend_number.
575 */ 1123 */
576int tox_group_get_names(const Tox *tox, int groupnumber, uint8_t names[][TOX_MAX_NAME_LENGTH], uint16_t lengths[], 1124typedef void tox_friend_connection_status_cb(Tox *tox, uint32_t friend_number, TOX_CONNECTION connection_status,
577 uint16_t length); 1125 void *user_data);
578 1126
579/* Return the number of chats in the instance m. 1127/**
580 * You should use this to determine how much memory to allocate 1128 * Set the callback for the `friend_connection_status` event. Pass NULL to
581 * for copy_chatlist. */ 1129 * unset.
582uint32_t tox_count_chatlist(const Tox *tox); 1130 *
1131 * This event is triggered when a friend goes offline after having been online,
1132 * or when a friend goes online.
1133 *
1134 * This callback is not called when adding friends. It is assumed that when
1135 * adding friends, their connection status is offline.
1136 */
1137void tox_callback_friend_connection_status(Tox *tox, tox_friend_connection_status_cb *function, void *user_data);
583 1138
584/* Copy a list of valid chat IDs into the array out_list.
585 * If out_list is NULL, returns 0.
586 * Otherwise, returns the number of elements copied.
587 * If the array was too small, the contents
588 * of out_list will be truncated to list_size. */
589uint32_t tox_get_chatlist(const Tox *tox, int32_t *out_list, uint32_t list_size);
590 1139
591/* return the type of groupchat (TOX_GROUPCHAT_TYPE_) that groupnumber is. 1140/**
1141 * Check whether a friend is currently typing a message.
1142 *
1143 * @param friend_number The friend number for which to query the typing status.
592 * 1144 *
593 * return -1 on failure. 1145 * @return true if the friend is typing.
594 * return type on success. 1146 * @return false if the friend is not typing, or the friend number was
1147 * invalid. Inspect the error code to determine which case it is.
595 */ 1148 */
596int tox_group_get_type(const Tox *tox, int groupnumber); 1149bool tox_friend_get_typing(Tox const *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error);
597 1150
598/****************AVATAR FUNCTIONS*****************/ 1151/**
1152 * The function type for the `friend_typing` callback.
1153 *
1154 * @param friend_number The friend number of the friend who started or stopped
1155 * typing.
1156 * @param is_typing The result of calling tox_friend_get_typing on the passed
1157 * friend_number.
1158 */
1159typedef void tox_friend_typing_cb(Tox *tox, uint32_t friend_number, bool is_typing, void *user_data);
599 1160
600/* Set the callback function for avatar information. 1161/**
601 * This callback will be called when avatar information are received from friends. These events 1162 * Set the callback for the `friend_typing` event. Pass NULL to unset.
602 * can arrive at anytime, but are usually received uppon connection and in reply of avatar
603 * information requests.
604 * 1163 *
605 * Function format is: 1164 * This event is triggered when a friend starts or stops typing.
606 * function(Tox *tox, int32_t friendnumber, uint8_t format, uint8_t *hash, void *userdata) 1165 */
1166void tox_callback_friend_typing(Tox *tox, tox_friend_typing_cb *function, void *user_data);
1167
1168
1169/*******************************************************************************
607 * 1170 *
608 * where 'format' is the avatar image format (see TOX_AVATAR_FORMAT) and 'hash' is the hash of 1171 * :: Sending private messages
609 * the avatar data for caching purposes and it is exactly TOX_HASH_LENGTH long. If the image
610 * format is NONE, the hash is zeroed.
611 * 1172 *
1173 ******************************************************************************/
1174
1175
1176typedef enum TOX_ERR_SET_TYPING {
1177 TOX_ERR_SET_TYPING_OK,
1178 /**
1179 * The friend number did not designate a valid friend.
1180 */
1181 TOX_ERR_SET_TYPING_FRIEND_NOT_FOUND
1182} TOX_ERR_SET_TYPING;
1183
1184/**
1185 * Set the client's typing status for a friend.
1186 *
1187 * The client is responsible for turning it on or off.
1188 *
1189 * @param friend_number The friend to which the client is typing a message.
1190 * @param is_typing The typing status. True means the client is typing.
1191 *
1192 * @return true on success.
612 */ 1193 */
613void tox_callback_avatar_info(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, uint8_t *, void *), 1194bool tox_self_set_typing(Tox *tox, uint32_t friend_number, bool is_typing, TOX_ERR_SET_TYPING *error);
614 void *userdata); 1195
615 1196
1197typedef enum TOX_ERR_SEND_MESSAGE {
1198 TOX_ERR_SEND_MESSAGE_OK,
1199 TOX_ERR_SEND_MESSAGE_NULL,
1200 /**
1201 * The friend number did not designate a valid friend.
1202 */
1203 TOX_ERR_SEND_MESSAGE_FRIEND_NOT_FOUND,
1204 /**
1205 * This client is currently not connected to the friend.
1206 */
1207 TOX_ERR_SEND_MESSAGE_FRIEND_NOT_CONNECTED,
1208 /**
1209 * An allocation error occurred while increasing the send queue size.
1210 */
1211 TOX_ERR_SEND_MESSAGE_SENDQ,
1212 /**
1213 * Message length exceeded TOX_MAX_MESSAGE_LENGTH.
1214 */
1215 TOX_ERR_SEND_MESSAGE_TOO_LONG,
1216 /**
1217 * Attempted to send a zero-length message.
1218 */
1219 TOX_ERR_SEND_MESSAGE_EMPTY
1220} TOX_ERR_SEND_MESSAGE;
616 1221
617/* Set the callback function for avatar data. 1222/**
618 * This callback will be called when the complete avatar data was correctly received from a 1223 * Send a text chat message to an online friend.
619 * friend. This only happens in reply of a avatar data request (see tox_request_avatar_data);
620 * 1224 *
621 * Function format is: 1225 * This function creates a chat message packet and pushes it into the send
622 * function(Tox *tox, int32_t friendnumber, uint8_t format, uint8_t *hash, uint8_t *data, uint32_t datalen, void *userdata) 1226 * queue.
623 * 1227 *
624 * where 'format' is the avatar image format (see TOX_AVATAR_FORMAT); 'hash' is the 1228 * The message length may not exceed TOX_MAX_MESSAGE_LENGTH. Larger messages
625 * locally-calculated cryptographic hash of the avatar data and it is exactly 1229 * must be split by the client and sent as separate messages. Other clients can
626 * TOX_HASH_LENGTH long; 'data' is the avatar image data and 'datalen' is the length 1230 * then reassemble the fragments. Messages may not be empty.
627 * of such data.
628 * 1231 *
629 * If format is NONE, 'data' is NULL, 'datalen' is zero, and the hash is zeroed. The hash is 1232 * The return value of this function is the message ID. If a read receipt is
630 * always validated locally with the function tox_hash and ensured to match the image data, 1233 * received, the triggered `read_receipt` event will be passed this message ID.
631 * so this value can be safely used to compare with cached avatars.
632 * 1234 *
633 * WARNING: users MUST treat all avatar image data received from another peer as untrusted and 1235 * Message IDs are unique per friend. The first message ID is 0. Message IDs are
634 * potentially malicious. The library only ensures that the data which arrived is the same the 1236 * incremented by 1 each time a message is sent. If UINT32_MAX messages were
635 * other user sent, and does not interpret or validate any image data. 1237 * sent, the next message ID is 0.
636 */ 1238 */
637void tox_callback_avatar_data(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, uint8_t *, uint8_t *, uint32_t, 1239uint32_t tox_send_message(Tox *tox, uint32_t friend_number, uint8_t const *message, size_t length,
638 void *), void *userdata); 1240 TOX_ERR_SEND_MESSAGE *error);
1241
639 1242
640/* Set the user avatar image data. 1243/**
641 * This should be made before connecting, so we will not announce that the user have no avatar 1244 * Send an action to an online friend.
642 * before setting and announcing a new one, forcing the peers to re-download it.
643 * 1245 *
644 * Notice that the library treats the image as raw data and does not interpret it by any way. 1246 * This is similar to /me (CTCP ACTION) on IRC.
645 * 1247 *
646 * Arguments: 1248 * Message ID space is shared between tox_send_message and tox_send_action. This
647 * format - Avatar image format or NONE for user with no avatar (see TOX_AVATAR_FORMAT); 1249 * means that sending a message will cause the next message ID from sending an
648 * data - pointer to the avatar data (may be NULL it the format is NONE); 1250 * action will be incremented.
649 * length - length of image data. Must be <= TOX_AVATAR_MAX_DATA_LENGTH.
650 * 1251 *
651 * returns 0 on success 1252 * @see tox_send_message for more details.
652 * returns -1 on failure.
653 */ 1253 */
654int tox_set_avatar(Tox *tox, uint8_t format, const uint8_t *data, uint32_t length); 1254uint32_t tox_send_action(Tox *tox, uint32_t friend_number, uint8_t const *action, size_t length,
1255 TOX_ERR_SEND_MESSAGE *error);
655 1256
656/* Unsets the user avatar.
657 1257
658 returns 0 on success (currently always returns 0) */ 1258/**
659int tox_unset_avatar(Tox *tox); 1259 * The function type for the `read_receipt` callback.
1260 *
1261 * @param friend_number The friend number of the friend who received the message.
1262 * @param message_id The message ID as returned from tox_send_message or
1263 * tox_send_action corresponding to the message sent.
1264 */
1265typedef void tox_read_receipt_cb(Tox *tox, uint32_t friend_number, uint32_t message_id, void *user_data);
660 1266
661/* Get avatar data from the current user. 1267/**
662 * Copies the current user avatar data to the destination buffer and sets the image format 1268 * Set the callback for the `read_receipt` event. Pass NULL to unset.
663 * accordingly.
664 * 1269 *
665 * If the avatar format is NONE, the buffer 'buf' isleft uninitialized, 'hash' is zeroed, and 1270 * This event is triggered when a read receipt is received from a friend. This
666 * 'length' is set to zero. 1271 * normally means that the message has been received by the friend, however a
1272 * friend can send a read receipt with any message ID in it, so the number
1273 * received here may not correspond to any message sent through tox_send_message
1274 * or tox_send_action. In that case, the receipt should be discarded.
1275 */
1276void tox_callback_read_receipt(Tox *tox, tox_read_receipt_cb *function, void *user_data);
1277
1278
1279/*******************************************************************************
667 * 1280 *
668 * If any of the pointers format, buf, length, and hash are NULL, that particular field will be ignored. 1281 * :: Receiving private messages and friend requests
669 * 1282 *
670 * Arguments: 1283 ******************************************************************************/
671 * format - destination pointer to the avatar image format (see TOX_AVATAR_FORMAT); 1284
672 * buf - destination buffer to the image data. Must have at least 'maxlen' bytes; 1285
673 * length - destination pointer to the image data length; 1286/**
674 * maxlen - length of the destination buffer 'buf'; 1287 * The function type for the `friend_request` callback.
675 * hash - destination pointer to the avatar hash (it must be exactly TOX_HASH_LENGTH bytes long).
676 * 1288 *
677 * returns 0 on success; 1289 * @param public_key The Public Key of the user who sent the friend request.
678 * returns -1 on failure. 1290 * @param time_delta A delta in seconds between when the message was composed
1291 * and when it is being transmitted. For messages that are sent immediately,
1292 * it will be 0. If a message was written and couldn't be sent immediately
1293 * (due to a connection failure, for example), the time_delta is an
1294 * approximation of when it was composed.
1295 * @param message The message they sent along with the request.
1296 * @param length The size of the message byte array.
1297 */
1298typedef void tox_friend_request_cb(Tox *tox, uint8_t const *public_key, /*uint32_t time_delta, */uint8_t const *message,
1299 size_t length, void *user_data);
1300
1301/**
1302 * Set the callback for the `friend_request` event. Pass NULL to unset.
679 * 1303 *
1304 * This event is triggered when a friend request is received.
680 */ 1305 */
681int tox_get_self_avatar(const Tox *tox, uint8_t *format, uint8_t *buf, uint32_t *length, uint32_t maxlen, 1306void tox_callback_friend_request(Tox *tox, tox_friend_request_cb *function, void *user_data);
682 uint8_t *hash);
683 1307
684 1308
685/* Generates a cryptographic hash of the given data. 1309/**
686 * This function may be used by clients for any purpose, but is provided primarily for 1310 * The function type for the `friend_message` callback.
687 * validating cached avatars. This use is highly recommended to avoid unnecessary avatar
688 * updates.
689 * This function is a wrapper to internal message-digest functions.
690 * 1311 *
691 * Arguments: 1312 * @param friend_number The friend number of the friend who sent the message.
692 * hash - destination buffer for the hash data, it must be exactly TOX_HASH_LENGTH bytes long. 1313 * @param time_delta Time between composition and sending.
693 * data - data to be hashed; 1314 * @param message The message data they sent.
694 * datalen - length of the data; for avatars, should be TOX_AVATAR_MAX_DATA_LENGTH 1315 * @param length The size of the message byte array.
695 * 1316 *
696 * returns 0 on success 1317 * @see tox_friend_request_cb for more information on time_delta.
697 * returns -1 on failure.
698 */ 1318 */
699int tox_hash(uint8_t *hash, const uint8_t *data, const uint32_t datalen); 1319typedef void tox_friend_message_cb(Tox *tox, uint32_t friend_number, /*uint32_t time_delta, */uint8_t const *message,
1320 size_t length, void *user_data);
700 1321
701/* Request avatar information from a friend. 1322/**
702 * Asks a friend to provide their avatar information (image format and hash). The friend may 1323 * Set the callback for the `friend_message` event. Pass NULL to unset.
703 * or may not answer this request and, if answered, the information will be provided through
704 * the callback 'avatar_info'.
705 * 1324 *
706 * returns 0 on success 1325 * This event is triggered when a message from a friend is received.
707 * returns -1 on failure.
708 */ 1326 */
709int tox_request_avatar_info(const Tox *tox, const int32_t friendnumber); 1327void tox_callback_friend_message(Tox *tox, tox_friend_message_cb *function, void *user_data);
710 1328
711 1329
712/* Send an unrequested avatar information to a friend. 1330/**
713 * Sends our avatar format and hash to a friend; he/she can use this information to validate 1331 * The function type for the `friend_action` callback.
714 * an avatar from the cache and may (or not) reply with an avatar data request.
715 * 1332 *
716 * Notice: it is NOT necessary to send these notification after changing the avatar or 1333 * @param friend_number The friend number of the friend who sent the action.
717 * connecting. The library already does this. 1334 * @param time_delta Time between composition and sending.
1335 * @param action The action message data they sent.
1336 * @param length The size of the action byte array.
718 * 1337 *
719 * returns 0 on success 1338 * @see tox_friend_request_cb for more information on time_delta.
720 * returns -1 on failure.
721 */ 1339 */
722int tox_send_avatar_info(Tox *tox, const int32_t friendnumber); 1340typedef void tox_friend_action_cb(Tox *tox, uint32_t friend_number, /*uint32_t time_delta, */uint8_t const *action,
1341 size_t length, void *user_data);
723 1342
724 1343/**
725/* Request the avatar data from a friend. 1344 * Set the callback for the `friend_action` event. Pass NULL to unset.
726 * Ask a friend to send their avatar data. The friend may or may not answer this request and,
727 * if answered, the information will be provided in callback 'avatar_data'.
728 * 1345 *
729 * returns 0 on sucess 1346 * This event is triggered when an action from a friend is received.
730 * returns -1 on failure.
731 */ 1347 */
732int tox_request_avatar_data(const Tox *tox, const int32_t friendnumber); 1348void tox_callback_friend_action(Tox *tox, tox_friend_action_cb *function, void *user_data);
1349
733 1350
734/****************FILE SENDING FUNCTIONS*****************/ 1351
735/* NOTE: This how to will be updated. 1352/*******************************************************************************
736 * 1353 *
737 * HOW TO SEND FILES CORRECTLY: 1354 * :: File transmission: common between sending and receiving
738 * 1. Use tox_new_file_sender(...) to create a new file sender.
739 * 2. Wait for the callback set with tox_callback_file_control(...) to be called with receive_send == 1 and control_type == TOX_FILECONTROL_ACCEPT
740 * 3. Send the data with tox_file_send_data(...) with chunk size tox_file_data_size(...)
741 * 4. When sending is done, send a tox_file_send_control(...) with send_receive = 0 and message_id = TOX_FILECONTROL_FINISHED
742 * 5. when the callback set with tox_callback_file_control(...) is called with receive_send == 1 and control_type == TOX_FILECONTROL_FINISHED
743 * the other person has received the file correctly.
744 * 1355 *
745 * HOW TO RECEIVE FILES CORRECTLY: 1356 ******************************************************************************/
746 * 1. wait for the callback set with tox_callback_file_send_request(...) 1357
747 * 2. accept or refuse the connection with tox_file_send_control(...) with send_receive = 1 and message_id = TOX_FILECONTROL_ACCEPT or TOX_FILECONTROL_KILL 1358
748 * 3. save all the data received with the callback set with tox_callback_file_data(...) to a file. 1359typedef enum TOX_FILE_KIND {
749 * 4. when the callback set with tox_callback_file_control(...) is called with receive_send == 0 and control_type == TOX_FILECONTROL_FINISHED 1360 /**
750 * the file is done transferring. 1361 * Arbitrary file data. Clients can choose to handle it based on the file name
751 * 5. send a tox_file_send_control(...) with send_receive = 1 and message_id = TOX_FILECONTROL_FINISHED to confirm that we did receive the file. 1362 * or magic or any other way they choose.
1363 */
1364 TOX_FILE_KIND_DATA,
1365 /**
1366 * Avatar data. This consists of tox_hash(image) + image.
1367 *
1368 * Avatars can be sent at any time the client wishes. Generally, a client will
1369 * send the avatar to a friend when that friend comes online, and to all
1370 * friends when the avatar changed. A client can save some traffic by
1371 * remembering which friend received the updated avatar already and only send
1372 * it if the friend has an out of date avatar.
1373 *
1374 * Clients who receive avatar send requests can reject it (by sending
1375 * TOX_FILE_CONTROL_CANCEL before any other controls), or accept it (by
1376 * sending TOX_FILE_CONTROL_RESUME). The first chunk will contain the hash in
1377 * its first TOX_HASH_LENGTH bytes. A client can compare this hash with a
1378 * saved hash and send TOX_FILE_CONTROL_CANCEL to terminate the avatar
1379 * transfer if it matches.
1380 */
1381 TOX_FILE_KIND_AVATAR
1382} TOX_FILE_KIND;
1383
1384
1385/**
1386 * Generates a cryptographic hash of the given data.
752 * 1387 *
753 * tox_file_data_remaining(...) can be used to know how many bytes are left to send/receive. 1388 * This function may be used by clients for any purpose, but is provided
1389 * primarily for validating cached avatars. This use is highly recommended to
1390 * avoid unnecessary avatar updates.
754 * 1391 *
755 * If the connection breaks during file sending (The other person goes offline without pausing the sending and then comes back) 1392 * If length is zero or data is NULL, the hash will contain all zero. If hash is
756 * the receiver must send a control packet with send_receive == 1 message_id = TOX_FILECONTROL_RESUME_BROKEN and the data being 1393 * NULL, the function returns false, otherwise it returns true.
757 * a uint64_t (in host byte order) containing the number of bytes received.
758 * 1394 *
759 * If the sender receives this packet, he must send a control packet with send_receive == 0 and control_type == TOX_FILECONTROL_ACCEPT 1395 * This function is a wrapper to internal message-digest functions.
760 * then he must start sending file data from the position (data , uint64_t in host byte order) received in the TOX_FILECONTROL_RESUME_BROKEN packet.
761 * 1396 *
762 * To pause a file transfer send a control packet with control_type == TOX_FILECONTROL_PAUSE. 1397 * @param hash A valid memory location the hash data. It must be at least
763 * To unpause a file transfer send a control packet with control_type == TOX_FILECONTROL_ACCEPT. 1398 * TOX_HASH_LENGTH bytes in size.
1399 * @param data Data to be hashed or NULL.
1400 * @param length Size of the data array or 0.
1401 *
1402 * @return true if hash was not NULL.
1403 */
1404bool tox_hash(uint8_t *hash, uint8_t const *data, size_t length);
1405
1406
1407typedef enum TOX_FILE_CONTROL {
1408 /**
1409 * Sent by the receiving side to accept a file send request. Also sent after a
1410 * TOX_FILE_CONTROL_PAUSE command to continue sending or receiving.
1411 */
1412 TOX_FILE_CONTROL_RESUME,
1413 /**
1414 * Sent by clients to pause the file transfer. The initial state of a file
1415 * transfer is always paused on the receiving side and running on the sending
1416 * side. If both the sending and receiving side pause the transfer, then both
1417 * need to send TOX_FILE_CONTROL_RESUME for the transfer to resume.
1418 */
1419 TOX_FILE_CONTROL_PAUSE,
1420 /**
1421 * Sent by the receiving side to reject a file send request before any other
1422 * commands are sent. Also sent by either side to terminate a file transfer.
1423 */
1424 TOX_FILE_CONTROL_CANCEL
1425} TOX_FILE_CONTROL;
1426
1427
1428typedef enum TOX_ERR_FILE_CONTROL {
1429 TOX_ERR_FILE_CONTROL_OK,
1430 /**
1431 * The friend_number passed did not designate a valid friend.
1432 */
1433 TOX_ERR_FILE_CONTROL_FRIEND_NOT_FOUND,
1434 /**
1435 * This client is currently not connected to the friend.
1436 */
1437 TOX_ERR_FILE_CONTROL_FRIEND_NOT_CONNECTED,
1438 /**
1439 * No file transfer with the given file number was found for the given friend.
1440 */
1441 TOX_ERR_FILE_CONTROL_NOT_FOUND,
1442 /**
1443 * A RESUME control was sent, but the file transfer is running normally.
1444 */
1445 TOX_ERR_FILE_CONTROL_NOT_PAUSED,
1446 /**
1447 * A RESUME control was sent, but the file transfer was paused by the other
1448 * party. Only the party that paused the transfer can resume it.
1449 */
1450 TOX_ERR_FILE_CONTROL_DENIED,
1451 /**
1452 * A PAUSE control was sent, but the file transfer was already paused.
1453 */
1454 TOX_ERR_FILE_CONTROL_ALREADY_PAUSED
1455} TOX_ERR_FILE_CONTROL;
1456
1457/**
1458 * Sends a file control command to a friend for a given file transfer.
1459 *
1460 * @param friend_number The friend number of the friend the file is being
1461 * transferred to.
1462 * @param file_number The friend-specific identifier for the file transfer.
1463 * @param control The control command to send.
1464 *
1465 * @return true on success.
1466 */
1467bool tox_file_control(Tox *tox, uint32_t friend_number, uint32_t file_number, TOX_FILE_CONTROL control,
1468 TOX_ERR_FILE_CONTROL *error);
1469
1470
1471/**
1472 * The function type for the `file_control` callback.
1473 *
1474 * When receiving TOX_FILE_CONTROL_CANCEL, the client should release the
1475 * resources associated with the file number and consider the transfer failed.
1476 *
1477 * @param friend_number The friend number of the friend who is sending the file.
1478 * @param file_number The friend-specific file number the data received is
1479 * associated with.
1480 * @param control The file control command received.
1481 */
1482typedef void tox_file_control_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, TOX_FILE_CONTROL control,
1483 void *user_data);
1484
1485/**
1486 * Set the callback for the `file_control` event. Pass NULL to unset.
1487 *
1488 * This event is triggered when a file control command is received from a
1489 * friend.
1490 */
1491void tox_callback_file_control(Tox *tox, tox_file_control_cb *function, void *user_data);
1492
1493
1494/*******************************************************************************
1495 *
1496 * :: File transmission: sending
1497 *
1498 ******************************************************************************/
1499
1500
1501typedef enum TOX_ERR_FILE_SEND {
1502 TOX_ERR_FILE_SEND_OK,
1503 TOX_ERR_FILE_SEND_NULL,
1504 /**
1505 * The friend_number passed did not designate a valid friend.
1506 */
1507 TOX_ERR_FILE_SEND_FRIEND_NOT_FOUND,
1508 /**
1509 * This client is currently not connected to the friend.
1510 */
1511 TOX_ERR_FILE_SEND_FRIEND_NOT_CONNECTED,
1512 /**
1513 * Filename length was 0.
1514 */
1515 TOX_ERR_FILE_SEND_NAME_EMPTY,
1516 /**
1517 * Filename length exceeded 255 bytes.
1518 */
1519 TOX_ERR_FILE_SEND_NAME_TOO_LONG,
1520 /**
1521 * Too many ongoing transfers. The maximum number of concurrent file transfers
1522 * is 256 per friend per direction (sending and receiving).
1523 */
1524 TOX_ERR_FILE_SEND_TOO_MANY
1525} TOX_ERR_FILE_SEND;
1526
1527/**
1528 * Send a file transmission request.
1529 *
1530 * Maximum filename length is 255 bytes. The filename should generally just be
1531 * a file name, not a path with directory names.
1532 *
1533 * If a non-zero file size is provided, this can be used by both sides to
1534 * determine the sending progress. File size can be set to zero for streaming
1535 * data of unknown size.
1536 *
1537 * File transmission occurs in chunks, which are requested through the
1538 * `file_request_chunk` event.
1539 *
1540 * File numbers are stable across tox_save/tox_load cycles, so that file
1541 * transfers can be resumed when a client restarts. The client needs to
1542 * associate (friend Public Key, file number) with the local path of the file and
1543 * persist this information to support resuming of transfers across restarts.
1544 *
1545 * If the file contents change during a transfer, the behaviour is unspecified
1546 * in general. What will actually happen depends on the mode in which the file
1547 * was modified and how the client determines the file size.
1548 *
1549 * - If the file size was increased
1550 * - and sending mode was streaming (file_size = 0), the behaviour will be as
1551 * expected.
1552 * - and sending mode was file (file_size != 0), the file_request_chunk
1553 * callback will receive length = 0 when Core thinks the file transfer has
1554 * finished. If the client remembers the file size as it was when sending
1555 * the request, it will terminate the transfer normally. If the client
1556 * re-reads the size, it will think the friend cancelled the transfer.
1557 * - If the file size was decreased
1558 * - and sending mode was streaming, the behaviour is as expected.
1559 * - and sending mode was file, the callback will return 0 at the new
1560 * (earlier) end-of-file, signalling to the friend that the transfer was
1561 * cancelled.
1562 * - If the file contents were modified
1563 * - at a position before the current read, the two files (local and remote)
1564 * will differ after the transfer terminates.
1565 * - at a position after the current read, the file transfer will succeed as
1566 * expected.
1567 * - In either case, both sides will regard the transfer as complete and
1568 * successful.
1569 *
1570 * @param friend_number The friend number of the friend the file send request
1571 * should be sent to.
1572 * @param kind The meaning of the file to be sent.
1573 * @param file_size Size in bytes of the file the client wants to send, 0 if
1574 * unknown or streaming.
1575 * @param filename Name of the file. Does not need to be the actual name. This
1576 * name will be sent along with the file send request.
1577 * @param filename_length Size in bytes of the filename.
1578 *
1579 * @return A file number used as an identifier in subsequent callbacks. This
1580 * number is per friend. File numbers are reused after a transfer terminates.
1581 */
1582uint32_t tox_file_send(Tox *tox, uint32_t friend_number, TOX_FILE_KIND kind, uint64_t file_size,
1583 uint8_t const *filename, size_t filename_length, TOX_ERR_FILE_SEND *error);
1584
1585
1586typedef enum TOX_ERR_FILE_SEND_CHUNK {
1587 TOX_ERR_FILE_SEND_CHUNK_OK,
1588 /**
1589 * The length parameter was non-zero, but data was NULL.
1590 */
1591 TOX_ERR_FILE_SEND_CHUNK_NULL,
1592 /**
1593 * The friend_number passed did not designate a valid friend.
1594 */
1595 TOX_ERR_FILE_SEND_CHUNK_FRIEND_NOT_FOUND,
1596 /**
1597 * This client is currently not connected to the friend.
1598 */
1599 TOX_ERR_FILE_SEND_CHUNK_FRIEND_NOT_CONNECTED,
1600 /**
1601 * No file transfer with the given file number was found for the given friend.
1602 */
1603 TOX_ERR_FILE_SEND_CHUNK_NOT_FOUND,
1604 /**
1605 * Attempted to send more data than requested. The requested data size is
1606 * adjusted according to maximum transmission unit and the expected end of
1607 * the file. Trying to send more will result in no data being sent.
1608 */
1609 TOX_ERR_FILE_SEND_CHUNK_TOO_LARGE
1610} TOX_ERR_FILE_SEND_CHUNK;
1611
1612/**
1613 * Send a chunk of file data to a friend.
1614 *
1615 * This function is called in response to the `file_request_chunk` callback. The
1616 * length parameter should be equal to or less than the one received though the
1617 * callback. If it is zero, the transfer is assumed complete. For files with
1618 * known size, Core will know that the transfer is complete after the last byte
1619 * has been received, so it is not necessary (though not harmful) to send a
1620 * zero-length chunk to terminate. For streams, it is necessary for the last
1621 * chunk sent to be zero-length.
1622 *
1623 * @return true on success.
1624 */
1625bool tox_file_send_chunk(Tox *tox, uint32_t friend_number, uint32_t file_number, uint8_t const *data, size_t length,
1626 TOX_ERR_FILE_SEND_CHUNK *error);
1627
1628
1629/**
1630 * The function type for the `file_request_chunk` callback.
1631 *
1632 * If the length parameter is 0, the file transfer is finished, and the client's
1633 * resources associated with the file number should be released. After a call
1634 * with zero length, the file number can be reused for future file transfers.
764 * 1635 *
765 * If you receive a control packet with receive_send == 1 and control_type == TOX_FILECONTROL_PAUSE, you must stop sending filenumber until the other 1636 * If the requested position is not equal to the client's idea of the current
766 * person sends a control packet with send_receive == 0 and control_type == TOX_FILECONTROL_ACCEPT with the filenumber being a paused filenumber. 1637 * file or stream position, it will need to seek. In case of read-once streams,
1638 * the client should keep the last read chunk so that a seek back can be
1639 * supported. A seek-back only ever needs to read from the last requested chunk.
1640 * This happens when a chunk was requested, but the send failed. A seek-back
1641 * request can occur an arbitrary number of times for any given chunk.
767 * 1642 *
768 * If you receive a control packet with receive_send == 0 and control_type == TOX_FILECONTROL_PAUSE, it means the sender of filenumber has paused the 1643 * In response to receiving this callback, the client should call the function
769 * transfer and will resume it later with a control packet with send_receive == 1 and control_type == TOX_FILECONTROL_ACCEPT for that file number. 1644 * `tox_file_send_chunk` with the requested chunk. If the number of bytes sent
1645 * through that function is zero, the file transfer is assumed complete. A
1646 * client may choose to send less than requested, if it is reading from a
1647 * stream that doesn't have more data, yet, and it still wants to send some
1648 * data to the other side. However, this will generally be less efficient than
1649 * waiting for a full chunk size of data to be ready.
770 * 1650 *
771 * More to come... 1651 * @param friend_number The friend number of the receiving friend for this file.
1652 * @param file_number The file transfer identifier returned by tox_file_send.
1653 * @param position The file or stream position from which to continue reading.
1654 * @param length The number of bytes requested for the current chunk.
772 */ 1655 */
1656typedef void tox_file_request_chunk_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position,
1657 size_t length, void *user_data);
773 1658
774enum { 1659/**
775 TOX_FILECONTROL_ACCEPT, 1660 * Set the callback for the `file_request_chunk` event. Pass NULL to unset.
776 TOX_FILECONTROL_PAUSE,
777 TOX_FILECONTROL_KILL,
778 TOX_FILECONTROL_FINISHED,
779 TOX_FILECONTROL_RESUME_BROKEN
780};
781/* Set the callback for file send requests.
782 *
783 * Function(Tox *tox, int32_t friendnumber, uint8_t filenumber, uint64_t filesize, const uint8_t *filename, uint16_t filename_length, void *userdata)
784 */ 1661 */
785void tox_callback_file_send_request(Tox *tox, void (*function)(Tox *m, int32_t, uint8_t, uint64_t, const uint8_t *, 1662void tox_callback_file_request_chunk(Tox *tox, tox_file_request_chunk_cb *function, void *user_data);
786 uint16_t, void *), void *userdata);
787 1663
788/* Set the callback for file control requests. 1664
1665/*******************************************************************************
1666 *
1667 * :: File transmission: receiving
789 * 1668 *
790 * receive_send is 1 if the message is for a slot on which we are currently sending a file and 0 if the message 1669 ******************************************************************************/
791 * is for a slot on which we are receiving the file 1670
1671
1672/**
1673 * The function type for the `file_receive` callback.
792 * 1674 *
793 * Function(Tox *tox, int32_t friendnumber, uint8_t receive_send, uint8_t filenumber, uint8_t control_type, const uint8_t *data, uint16_t length, void *userdata) 1675 * The client should acquire resources to be associated with the file transfer.
1676 * Incoming file transfers start in the PAUSED state. After this callback
1677 * returns, a transfer can be rejected by sending a TOX_FILE_CONTROL_CANCEL
1678 * control command before any other control commands. It can be accepted by
1679 * sending TOX_FILE_CONTROL_RESUME.
794 * 1680 *
1681 * @param friend_number The friend number of the friend who is sending the file
1682 * transfer request.
1683 * @param file_number The friend-specific file number the data received is
1684 * associated with.
795 */ 1685 */
796void tox_callback_file_control(Tox *tox, void (*function)(Tox *m, int32_t, uint8_t, uint8_t, uint8_t, const uint8_t *, 1686typedef void tox_file_receive_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, TOX_FILE_KIND kind,
797 uint16_t, void *), void *userdata); 1687 uint64_t file_size, uint8_t const *filename, size_t filename_length, void *user_data);
798 1688
799/* Set the callback for file data. 1689/**
800 * 1690 * Set the callback for the `file_receive` event. Pass NULL to unset.
801 * Function(Tox *tox, int32_t friendnumber, uint8_t filenumber, const uint8_t *data, uint16_t length, void *userdata)
802 * 1691 *
1692 * This event is triggered when a file transfer request is received.
803 */ 1693 */
804void tox_callback_file_data(Tox *tox, void (*function)(Tox *m, int32_t, uint8_t, const uint8_t *, uint16_t length, 1694void tox_callback_file_receive(Tox *tox, tox_file_receive_cb *function, void *user_data);
805 void *), void *userdata); 1695
806 1696
1697/**
1698 * The function type for the `file_receive_chunk` callback.
1699 *
1700 * This function is first called when a file transfer request is received, and
1701 * subsequently when a chunk of file data for an accepted request was received.
1702 *
1703 * When length is 0, the transfer is finished and the client should release the
1704 * resources it acquired for the transfer. After a call with length = 0, the
1705 * file number can be reused for new file transfers.
1706 *
1707 * If position is equal to file_size (received in the file_receive callback)
1708 * when the transfer finishes, the file was received completely. Otherwise, if
1709 * file_size was 0, streaming ended successfully when length is 0.
1710 *
1711 * @param friend_number The friend number of the friend who is sending the file.
1712 * @param file_number The friend-specific file number the data received is
1713 * associated with.
1714 * @param position The file position of the first byte in data.
1715 * @param data A byte array containing the received chunk.
1716 * @param length The length of the received chunk.
1717 */
1718typedef void tox_file_receive_chunk_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position,
1719 uint8_t const *data, size_t length, void *user_data);
807 1720
808/* Send a file send request. 1721/**
809 * Maximum filename length is 255 bytes. 1722 * Set the callback for the `file_receive_chunk` event. Pass NULL to unset.
810 * return file number on success
811 * return -1 on failure
812 */ 1723 */
813int tox_new_file_sender(Tox *tox, int32_t friendnumber, uint64_t filesize, const uint8_t *filename, 1724void tox_callback_file_receive_chunk(Tox *tox, tox_file_receive_chunk_cb *function, void *user_data);
814 uint16_t filename_length);
815 1725
816/* Send a file control request. 1726
1727/*******************************************************************************
817 * 1728 *
818 * send_receive is 0 if we want the control packet to target a file we are currently sending, 1729 * :: Group chat management
819 * 1 if it targets a file we are currently receiving.
820 * 1730 *
821 * return 0 on success 1731 ******************************************************************************/
822 * return -1 on failure
823 */
824int tox_file_send_control(Tox *tox, int32_t friendnumber, uint8_t send_receive, uint8_t filenumber, uint8_t message_id,
825 const uint8_t *data, uint16_t length);
826 1732
827/* Send file data. 1733
1734/******************************************************************************
828 * 1735 *
829 * return 0 on success 1736 * :: Group chat message sending and receiving
830 * return -1 on failure 1737 *
831 */ 1738 ******************************************************************************/
832int tox_file_send_data(Tox *tox, int32_t friendnumber, uint8_t filenumber, const uint8_t *data, uint16_t length); 1739
833 1740
834/* Returns the recommended/maximum size of the filedata you send with tox_file_send_data() 1741/*******************************************************************************
835 * 1742 *
836 * return size on success 1743 * :: Low-level custom packet sending and receiving
837 * return -1 on failure (currently will never return -1) 1744 *
838 */ 1745 ******************************************************************************/
839int tox_file_data_size(const Tox *tox, int32_t friendnumber);
840 1746
841/* Give the number of bytes left to be sent/received. 1747
1748typedef enum TOX_ERR_SEND_CUSTOM_PACKET {
1749 TOX_ERR_SEND_CUSTOM_PACKET_OK,
1750 TOX_ERR_SEND_CUSTOM_PACKET_NULL,
1751 /**
1752 * The friend number did not designate a valid friend.
1753 */
1754 TOX_ERR_SEND_CUSTOM_PACKET_FRIEND_NOT_FOUND,
1755 /**
1756 * This client is currently not connected to the friend.
1757 */
1758 TOX_ERR_SEND_CUSTOM_PACKET_FRIEND_NOT_CONNECTED,
1759 /**
1760 * The first byte of data was not in the specified range for the packet type.
1761 * This range is 200-254 for lossy, and 160-191 for lossless packets.
1762 */
1763 TOX_ERR_SEND_CUSTOM_PACKET_INVALID,
1764 /**
1765 * Attempted to send an empty packet.
1766 */
1767 TOX_ERR_SEND_CUSTOM_PACKET_EMPTY,
1768 /**
1769 * Packet data length exceeded TOX_MAX_CUSTOM_PACKET_SIZE.
1770 */
1771 TOX_ERR_SEND_CUSTOM_PACKET_TOO_LONG,
1772 /**
1773 * Send queue size exceeded.
1774 */
1775 TOX_ERR_SEND_CUSTOM_PACKET_SENDQ
1776} TOX_ERR_SEND_CUSTOM_PACKET;
1777
1778
1779/**
1780 * Send a custom lossy packet to a friend.
1781 *
1782 * The first byte of data must be in the range 200-254. Maximum length of a
1783 * custom packet is TOX_MAX_CUSTOM_PACKET_SIZE.
842 * 1784 *
843 * send_receive is 0 if we want the sending files, 1 if we want the receiving. 1785 * Lossy packets behave like UDP packets, meaning they might never reach the
1786 * other side or might arrive more than once (if someone is messing with the
1787 * connection) or might arrive in the wrong order.
844 * 1788 *
845 * return number of bytes remaining to be sent/received on success 1789 * Unless latency is an issue, it is recommended that you use lossless custom
846 * return 0 on failure 1790 * packets instead.
1791 *
1792 * @param friend_number The friend number of the friend this lossy packet
1793 * should be sent to.
1794 * @param data A byte array containing the packet data.
1795 * @param length The length of the packet data byte array.
1796 *
1797 * @return true on success.
847 */ 1798 */
848uint64_t tox_file_data_remaining(const Tox *tox, int32_t friendnumber, uint8_t filenumber, uint8_t send_receive); 1799bool tox_send_lossy_packet(Tox *tox, uint32_t friend_number, uint8_t const *data, size_t length,
1800 TOX_ERR_SEND_CUSTOM_PACKET *error);
849 1801
850/***************END OF FILE SENDING FUNCTIONS******************/ 1802/**
1803 * The function type for the `friend_lossy_packet` callback.
1804 *
1805 * @param friend_number The friend number of the friend who sent a lossy packet.
1806 * @param data A byte array containing the received packet data.
1807 * @param length The length of the packet data byte array.
1808 */
1809typedef void tox_friend_lossy_packet_cb(Tox *tox, uint32_t friend_number, uint8_t const *data, size_t length,
1810 void *user_data);
851 1811
852/* 1812/**
853 * Use this function to bootstrap the client. 1813 * Set the callback for the `friend_lossy_packet` event. Pass NULL to unset.
854 */ 1814 */
1815void tox_callback_friend_lossy_packet(Tox *tox, tox_friend_lossy_packet_cb *function, void *user_data);
855 1816
856/* Resolves address into an IP address. If successful, sends a "get nodes" 1817
857 * request to the given node with ip, port (in host byte order). 1818/**
858 * and public_key to setup connections 1819 * Send a custom lossless packet to a friend.
1820 *
1821 * The first byte of data must be in the range 160-191. Maximum length of a
1822 * custom packet is TOX_MAX_CUSTOM_PACKET_SIZE.
859 * 1823 *
860 * address can be a hostname or an IP address (IPv4 or IPv6). 1824 * Lossless packet behaviour is comparable to TCP (reliability, arrive in order)
1825 * but with packets instead of a stream.
861 * 1826 *
862 * returns 1 if the address could be converted into an IP address 1827 * @param friend_number The friend number of the friend this lossless packet
863 * returns 0 otherwise 1828 * should be sent to.
1829 * @param data A byte array containing the packet data.
1830 * @param length The length of the packet data byte array.
1831 *
1832 * @return true on success.
864 */ 1833 */
865int tox_bootstrap_from_address(Tox *tox, const char *address, uint16_t port, const uint8_t *public_key); 1834bool tox_send_lossless_packet(Tox *tox, uint32_t friend_number, uint8_t const *data, size_t length,
1835 TOX_ERR_SEND_CUSTOM_PACKET *error);
866 1836
867/* Like tox_bootstrap_from_address but for TCP relays only. 1837/**
1838 * The function type for the `friend_lossless_packet` callback.
868 * 1839 *
869 * return 0 on failure. 1840 * @param friend_number The friend number of the friend who sent the packet.
870 * return 1 on success. 1841 * @param data A byte array containing the received packet data.
1842 * @param length The length of the packet data byte array.
871 */ 1843 */
872int tox_add_tcp_relay(Tox *tox, const char *address, uint16_t port, const uint8_t *public_key); 1844typedef void tox_friend_lossless_packet_cb(Tox *tox, uint32_t friend_number, uint8_t const *data, size_t length,
1845 void *user_data);
873 1846
874/* return 0 if we are not connected to the DHT. 1847/**
875 * return 1 if we are. 1848 * Set the callback for the `friend_lossless_packet` event. Pass NULL to unset.
876 */ 1849 */
877int tox_isconnected(const Tox *tox); 1850void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb *function, void *user_data);
878
879typedef enum {
880 TOX_PROXY_NONE,
881 TOX_PROXY_SOCKS5,
882 TOX_PROXY_HTTP
883} TOX_PROXY_TYPE;
884 1851
885typedef struct {
886 /*
887 * The type of UDP socket created depends on ipv6enabled:
888 * If set to 0 (zero), creates an IPv4 socket which subsequently only allows
889 * IPv4 communication
890 * If set to anything else (default), creates an IPv6 socket which allows both IPv4 AND
891 * IPv6 communication
892 */
893 uint8_t ipv6enabled;
894 1852
895 /* Set to 1 to disable udp support. (default: 0)
896 This will force Tox to use TCP only which may slow things down.
897 Disabling udp support is necessary when using proxies or Tor.*/
898 uint8_t udp_disabled;
899 uint8_t proxy_type; /* a value from TOX_PROXY_TYPE */
900 char proxy_address[256]; /* Proxy ip or domain in NULL terminated string format. */
901 uint16_t proxy_port; /* Proxy port in host byte order. */
902} Tox_Options;
903 1853
904/* 1854/*******************************************************************************
905 * Run this function at startup.
906 *
907 * Options are some options that can be passed to the Tox instance (see above struct).
908 * 1855 *
909 * If options is NULL, tox_new() will use default settings. 1856 * :: Low-level network information
910 * 1857 *
911 * Initializes a tox structure 1858 ******************************************************************************/
912 * return allocated instance of tox on success.
913 * return NULL on failure.
914 */
915Tox *tox_new(Tox_Options *options);
916 1859
917/* Run this before closing shop.
918 * Free all datastructures. */
919void tox_kill(Tox *tox);
920 1860
921/* Return the time in milliseconds before tox_do() should be called again 1861/**
922 * for optimal performance. 1862 * Writes the temporary DHT public key of this instance to a byte array.
1863 *
1864 * This can be used in combination with an externally accessible IP address and
1865 * the bound port (from tox_get_udp_port) to run a temporary bootstrap node.
923 * 1866 *
924 * returns time (in ms) before the next tox_do() needs to be run on success. 1867 * Be aware that every time a new instance is created, the DHT public key
1868 * changes, meaning this cannot be used to run a permanent bootstrap node.
1869 *
1870 * @param dht_id A memory region of at least TOX_PUBLIC_KEY_SIZE bytes. If this
1871 * parameter is NULL, this function has no effect.
925 */ 1872 */
926uint32_t tox_do_interval(Tox *tox); 1873void tox_get_dht_id(Tox const *tox, uint8_t *dht_id);
927
928/* The main loop that needs to be run in intervals of tox_do_interval() ms. */
929void tox_do(Tox *tox);
930 1874
931/* SAVING AND LOADING FUNCTIONS: */
932 1875
933/* return size of messenger data (for saving). */ 1876typedef enum TOX_ERR_GET_PORT {
934uint32_t tox_size(const Tox *tox); 1877 TOX_ERR_GET_PORT_OK,
1878 /**
1879 * The instance was not bound to any port.
1880 */
1881 TOX_ERR_GET_PORT_NOT_BOUND
1882} TOX_ERR_GET_PORT;
935 1883
936/* Save the messenger in data (must be allocated memory of size Messenger_size()). */ 1884/**
937void tox_save(const Tox *tox, uint8_t *data); 1885 * Return the UDP port this Tox instance is bound to.
1886 */
1887uint16_t tox_get_udp_port(Tox const *tox, TOX_ERR_GET_PORT *error);
938 1888
939/* Load the messenger from data of size length. 1889/**
940 * NOTE: The Tox save format isn't stable yet meaning this function sometimes 1890 * Return the TCP port this Tox instance is bound to. This is only relevant if
941 * returns -1 when loading older saves. This however does not mean nothing was 1891 * the instance is acting as a TCP relay.
942 * loaded from the save.
943 *
944 * returns 0 on success
945 * returns -1 on failure
946 * returns +1 on finding encrypted save data
947 */ 1892 */
948int tox_load(Tox *tox, const uint8_t *data, uint32_t length); 1893uint16_t tox_get_tcp_port(Tox const *tox, TOX_ERR_GET_PORT *error);
1894
949 1895
950#ifdef __cplusplus 1896#ifdef __cplusplus
951} 1897}