Tox is a peer to peer (serverless) instant messenger aimed at making security and privacy easy to obtain for regular users. It uses NaCl for its encryption and authentication.
Every function that can fail takes a function-specific error code pointer that can be used to diagnose problems with the Tox state or the function arguments. The error code pointer can be NULL, which does not influence the function's behaviour, but can be done if the reason for failure is irrelevant to the client.
The exception to this rule are simple allocation functions whose only failure mode is allocation failure. They return NULL in that case, and do not set an error code.
Every error code type has an OK value to which functions will set their error code value on success. Clients can keep their error code uninitialised before passing it to a function. The library guarantees that after returning, the value pointed to by the error code pointer has been initialised.
Functions with pointer parameters often have a NULL error code, meaning they could not perform any operation, because one of the required parameters was NULL. Some functions operate correctly or are defined as effectless on NULL.
Some functions additionally return a value outside their return type domain, or a bool containing true on success and false on failure.
All functions that take a Tox instance pointer will cause undefined behaviour when passed a NULL Tox pointer.
All integer values are expected in host byte order.
Functions with parameters with enum types cause unspecified behaviour if the enumeration value is outside the valid range of the type. If possible, the function will try to use a sane default, but there will be no error code, and one possible action for the function to take is to have no effect.
Integer constants and the memory layout of publicly exposed structs are not part of the ABI.
Events are handled by callbacks. One callback can be registered per event. All events have a callback function type named `tox_{event} _cb` and a function to register it named `tox_callback_{event}`. Passing a NULL callback will result in no callback being registered for that event. Only one callback per event can be registered, so if a client needs multiple event listeners, it needs to implement the dispatch functionality itself.
The last argument to a callback is the user data pointer. It is passed from tox_iterate to each callback in sequence.
The user data pointer is never stored or dereferenced by any library code, so can be any pointer, including NULL. Callbacks must all operate on the same object type. In the apidsl code (tox.in.h), this is denoted with `any`. The `any` in tox_iterate must be the same `any` as in all callbacks. In C, lacking parametric polymorphism, this is a pointer to void.
Old style callbacks that are registered together with a user data pointer receive that pointer as argument when they are called. They can each have their own user data pointer of their own type.
It is possible to run multiple concurrent threads with a Tox instance for each thread. It is also possible to run all Tox instances in the same thread. A common way to run Tox (multiple or single instance) is to have one thread running a simple tox_iterate loop, sleeping for tox_iteration_interval milliseconds on each iteration.
If you want to access a single Tox instance from multiple threads, access to the instance must be synchronised. While multiple threads can concurrently access multiple different Tox instances, no more than one API function can operate on a single instance at any given time.
Functions that write to variable length byte arrays will always have a size function associated with them. The result of this size function is only valid until another mutating function (one that takes a pointer to non-const Tox) is called. Thus, clients must ensure that no other thread calls a mutating function between the call to the size function and the call to the retrieval function.
E.g. to get the current nickname, one would write
size_t length = tox_self_get_name_size(tox);
uint8_t *name = malloc(length);
if (!name) abort();
tox_self_get_name(tox, name);If any other thread calls tox_self_set_name while this thread is allocating memory, the length may have become invalid, and the call to tox_self_get_name may cause undefined behaviour.