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