From 47ad96e2b6c5704872b3615a160cd78d29b46b21 Mon Sep 17 00:00:00 2001 From: Green Sky Date: Thu, 28 Mar 2024 16:13:51 +0100 Subject: [PATCH] Squashed 'external/toxcore/c-toxcore/' changes from 3e05824b80..da438763d5 da438763d5 chore: Release 0.2.19 f90417987c chore: Add cmake flag to disable unit tests. 7df3f99417 docs: Document that group topic lock is default on. 9e9ed77390 docs: Add missing param docs for callbacks. 0ec4978de5 refactor: Don't expose Tox_System in the public API a3d1b8595c docs: Public headers, Core/toxcore -> Tox/the Tox library f78d0f3f39 docs: Public headers, events_alloc -> internal 817518949e docs: Public headers, NULL-terminated -> NUL-terminated be085db191 docs: Public headers, spellcheck 4c902955f3 docs: Public headers, 80 column width comments be8a82a818 docs: Public headers, null -> NULL 419d783d95 docs: Public headers, tox -> Tox 5c8aa65e41 docs: Update user data API explanation ad4921dbaa cleanup: A more descriptive error for group invite accept function git-subtree-dir: external/toxcore/c-toxcore git-subtree-split: da438763d5b8e071de6e061a1dcaddd2177dff7d --- .cirrus.yml | 8 +- CHANGELOG.md | 266 +++++ CMakeLists.txt | 6 +- INSTALL.md | 1 + configure.ac | 2 +- .../docker/tox-bootstrapd.sha256 | 2 +- other/docker/pkgsrc/pkgsrc.Dockerfile | 1 + so.version | 4 +- testing/fuzzing/bootstrap_fuzz_test.cc | 8 +- testing/fuzzing/e2e_fuzz_test.cc | 8 +- testing/fuzzing/fuzz_support.hh | 1 + testing/fuzzing/protodump.cc | 12 +- testing/fuzzing/protodump_reduce.cc | 8 +- testing/fuzzing/toxsave_fuzz_test.cc | 9 +- toxav/toxav.h | 142 +-- toxcore/tox.c | 37 +- toxcore/tox.h | 956 ++++++++++-------- toxcore/tox_api.c | 12 +- toxcore/tox_dispatch.h | 7 + toxcore/tox_events.h | 9 + toxcore/tox_private.h | 92 +- toxencryptsave/toxencryptsave.c | 27 +- toxencryptsave/toxencryptsave.h | 32 +- 23 files changed, 1072 insertions(+), 578 deletions(-) diff --git a/.cirrus.yml b/.cirrus.yml index bb477b26..28c40dcd 100644 --- a/.cirrus.yml +++ b/.cirrus.yml @@ -7,13 +7,14 @@ bazel-opt_task: configure_script: - git submodule update --init --recursive - /src/workspace/tools/inject-repo c-toxcore + - sed -i -e 's/build --config=remote/#&/' /src/workspace/.bazelrc.local test_all_script: - cd /src/workspace && bazel test -k --build_tag_filters=-haskell --test_tag_filters=-haskell -- //c-toxcore/... - -//c-toxcore/auto_tests:tcp_relay_test # TODO(robinlinden): Why does this pass locally but not in Cirrus? + -//c-toxcore/auto_tests:tcp_relay_test # Cirrus doesn't allow external network connections. bazel-dbg_task: container: @@ -30,7 +31,7 @@ bazel-dbg_task: --remote_http_cache=http://$CIRRUS_HTTP_CACHE_HOST -- //c-toxcore/... - -//c-toxcore/auto_tests:tcp_relay_test # TODO(robinlinden): Why does this pass locally but not in Cirrus? + -//c-toxcore/auto_tests:tcp_relay_test # Cirrus doesn't allow external network connections. cimple_task: container: @@ -40,6 +41,7 @@ cimple_task: configure_script: - git submodule update --init --recursive - /src/workspace/tools/inject-repo c-toxcore + - sed -i -e 's/build --config=remote/#&/' /src/workspace/.bazelrc.local test_all_script: - cd /src/workspace && bazel test -k --build_tag_filters=haskell @@ -69,7 +71,7 @@ freebsd_task: cmake . \ -DMIN_LOGGER_LEVEL=TRACE \ -DMUST_BUILD_TOXAV=ON \ - -DNON_HERMETIC_TESTS=ON \ + -DNON_HERMETIC_TESTS=OFF \ -DTEST_TIMEOUT_SECONDS=50 \ -DUSE_IPV6=OFF \ -DAUTOTEST=ON diff --git a/CHANGELOG.md b/CHANGELOG.md index 082b788c..8bb93bc3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,274 @@ +## v0.2.19 + +### Merged PRs: + +- [#2744](https://github.com/TokTok/c-toxcore/pull/2744) docs: Document that group topic lock is default on. +- [#2743](https://github.com/TokTok/c-toxcore/pull/2743) docs: Add missing param docs for callbacks. +- [#2742](https://github.com/TokTok/c-toxcore/pull/2742) chore: Add cmake flag to disable unit tests. +- [#2741](https://github.com/TokTok/c-toxcore/pull/2741) refactor: Don't expose Tox_System in the public API +- [#2736](https://github.com/TokTok/c-toxcore/pull/2736) cleanup: A more descriptive error for group invite accept function +- [#2735](https://github.com/TokTok/c-toxcore/pull/2735) chore: Small API doc fixes +- [#2732](https://github.com/TokTok/c-toxcore/pull/2732) cleanup: event length naming inconsistencies +- [#2731](https://github.com/TokTok/c-toxcore/pull/2731) cleanup: align group send err enum order +- [#2729](https://github.com/TokTok/c-toxcore/pull/2729) cleanup: use typedef for private message ID's in callback +- [#2728](https://github.com/TokTok/c-toxcore/pull/2728) refactor: Observers/ignored peers can now send and receive custom packets +- [#2727](https://github.com/TokTok/c-toxcore/pull/2727) feat: add message IDs to private group messages +- [#2726](https://github.com/TokTok/c-toxcore/pull/2726) refactor: Rename `out` parameters to `out_$something`. +- [#2718](https://github.com/TokTok/c-toxcore/pull/2718) chore: Use a specific non-broken slimcc version. +- [#2713](https://github.com/TokTok/c-toxcore/pull/2713) feat: Update and improve the Windows cross-compilation +- [#2712](https://github.com/TokTok/c-toxcore/pull/2712) chore: Update github actions. +- [#2710](https://github.com/TokTok/c-toxcore/pull/2710) docs: Update the list of CMake options +- [#2709](https://github.com/TokTok/c-toxcore/pull/2709) refactor: Remove "mod" and "founder" from group API naming scheme +- [#2708](https://github.com/TokTok/c-toxcore/pull/2708) docs: add the experimental api build option to INSTALL.md +- [#2705](https://github.com/TokTok/c-toxcore/pull/2705) refactor: Rename Queries to Query to align with other enums. +- [#2704](https://github.com/TokTok/c-toxcore/pull/2704) fix: Correct type for conference offline peer numbers. +- [#2700](https://github.com/TokTok/c-toxcore/pull/2700) test: Add FreeBSD VM action on GitHub. +- [#2699](https://github.com/TokTok/c-toxcore/pull/2699) test: Add pkgsrc build. +- [#2698](https://github.com/TokTok/c-toxcore/pull/2698) chore: Only install tox_private.h on request. +- [#2697](https://github.com/TokTok/c-toxcore/pull/2697) test: Build toxcore on NetBSD (VM). +- [#2696](https://github.com/TokTok/c-toxcore/pull/2696) fix: save_compatibility_test failing on big-endian systems +- [#2695](https://github.com/TokTok/c-toxcore/pull/2695) fix: Don't serve files from websockify. +- [#2689](https://github.com/TokTok/c-toxcore/pull/2689) fix: Correctly pass extended public keys to group moderation code. +- [#2686](https://github.com/TokTok/c-toxcore/pull/2686) chore: Compile libsodium reference implementation with compcert. +- [#2685](https://github.com/TokTok/c-toxcore/pull/2685) cleanup: correct a few nullable annotations +- [#2684](https://github.com/TokTok/c-toxcore/pull/2684) cleanup: Don't use `memcpy` to cast arbitrary `struct`s to `uint8_t[]`. +- [#2683](https://github.com/TokTok/c-toxcore/pull/2683) fix: Pass array, not array pointer, to `memcmp`. +- [#2682](https://github.com/TokTok/c-toxcore/pull/2682) cleanup: Never pass `void*` directly to `memcpy`. +- [#2678](https://github.com/TokTok/c-toxcore/pull/2678) chore: Disable NGC saving by default, enable through Tox_Options. +- [#2675](https://github.com/TokTok/c-toxcore/pull/2675) cleanup: Replace pointer arithmetic with explicit `&arr[i]`. +- [#2672](https://github.com/TokTok/c-toxcore/pull/2672) refactor: Use `structs` for extended public/secret keys. +- [#2671](https://github.com/TokTok/c-toxcore/pull/2671) refactor: Use tox rng to seed the keypair generation. +- [#2666](https://github.com/TokTok/c-toxcore/pull/2666) cleanup: Small improvements found by PVS Studio. +- [#2664](https://github.com/TokTok/c-toxcore/pull/2664) docs: Run prettier-markdown on markdown files. +- [#2662](https://github.com/TokTok/c-toxcore/pull/2662) fix: Correct a few potential null derefs in bootstrap daemon. +- [#2661](https://github.com/TokTok/c-toxcore/pull/2661) fix: Zero out stack-allocated secret key before return. +- [#2660](https://github.com/TokTok/c-toxcore/pull/2660) fix: Add missing memunlock of local variable when it goes out of scope. +- [#2659](https://github.com/TokTok/c-toxcore/pull/2659) cleanup: Simplify custom packet length check in NGC. +- [#2658](https://github.com/TokTok/c-toxcore/pull/2658) refactor: Make prune_gc_sanctions_list more obviously correct. +- [#2657](https://github.com/TokTok/c-toxcore/pull/2657) fix: Fix some false positive from PVS Studio. +- [#2656](https://github.com/TokTok/c-toxcore/pull/2656) docs: Add static analysis tool list to README. +- [#2655](https://github.com/TokTok/c-toxcore/pull/2655) cleanup: Check that WINXP macro exists before comparing it. +- [#2652](https://github.com/TokTok/c-toxcore/pull/2652) refactor: Make tox mutex non-recursive. +- [#2648](https://github.com/TokTok/c-toxcore/pull/2648) docs: Add more documentation to crypto_core. +- [#2647](https://github.com/TokTok/c-toxcore/pull/2647) docs: Fix up doxyfile. +- [#2645](https://github.com/TokTok/c-toxcore/pull/2645) refactor: Remove `Tox *` from `tox_dispatch`. +- [#2644](https://github.com/TokTok/c-toxcore/pull/2644) refactor: Don't rely on tox_dispatch passing tox in tests. +- [#2643](https://github.com/TokTok/c-toxcore/pull/2643) refactor: Use strong typedef for NGC peer id. +- [#2642](https://github.com/TokTok/c-toxcore/pull/2642) chore: Use C++ mode for clang-tidy. +- [#2640](https://github.com/TokTok/c-toxcore/pull/2640) refactor: Use strong `typedef` instead of `struct` for `Socket`. +- [#2637](https://github.com/TokTok/c-toxcore/pull/2637) chore: Check that both gtest and gmock exist for tests. +- [#2634](https://github.com/TokTok/c-toxcore/pull/2634) chore: Add some comments to the astyle config. +- [#2629](https://github.com/TokTok/c-toxcore/pull/2629) chore: Reformat sources with astyle. +- [#2626](https://github.com/TokTok/c-toxcore/pull/2626) chore: Rename C++ headers to .hh suffixes. +- [#2624](https://github.com/TokTok/c-toxcore/pull/2624) test: Add slimcc compiler compatibility test. +- [#2622](https://github.com/TokTok/c-toxcore/pull/2622) cleanup: Add more `const` where possible. +- [#2621](https://github.com/TokTok/c-toxcore/pull/2621) cleanup: Remove implicit bool conversions. +- [#2620](https://github.com/TokTok/c-toxcore/pull/2620) chore: Only check the bootstrap daemon checksum on release. +- [#2617](https://github.com/TokTok/c-toxcore/pull/2617) cleanup: Further `#include` cleanups. +- [#2614](https://github.com/TokTok/c-toxcore/pull/2614) cleanup: Use Bazel modules to enforce proper `#include` hygiene. +- [#2612](https://github.com/TokTok/c-toxcore/pull/2612) refactor: Move pack/unpack `IP_Port` from DHT into network module. +- [#2611](https://github.com/TokTok/c-toxcore/pull/2611) chore: Really fix coverage docker image build. +- [#2610](https://github.com/TokTok/c-toxcore/pull/2610) chore: Fix post-submit coverage image. +- [#2609](https://github.com/TokTok/c-toxcore/pull/2609) fix: partially fix a bug that prevented group part messages from sending +- [#2605](https://github.com/TokTok/c-toxcore/pull/2605) fix: Don't use `memcmp` to compare `IP_Port`s. +- [#2604](https://github.com/TokTok/c-toxcore/pull/2604) chore: Fix rpm build; add a CI check for it. +- [#2603](https://github.com/TokTok/c-toxcore/pull/2603) chore: Speed up docker builds a bit by reducing layer count. +- [#2602](https://github.com/TokTok/c-toxcore/pull/2602) cleanup: Add `const` where possible in auto tests. +- [#2601](https://github.com/TokTok/c-toxcore/pull/2601) fix: a few off by one errors in group autotests +- [#2598](https://github.com/TokTok/c-toxcore/pull/2598) refactor: Rename `system_{memory,...}` to `os_{memory,...}`. +- [#2597](https://github.com/TokTok/c-toxcore/pull/2597) test: Add goblint static analyser. +- [#2594](https://github.com/TokTok/c-toxcore/pull/2594) cleanup: Use `memzero(x, s)` instead of `memset(x, 0, s)`. +- [#2593](https://github.com/TokTok/c-toxcore/pull/2593) cleanup: Use explicit 0 instead of `PACKET_ID_PADDING`. +- [#2592](https://github.com/TokTok/c-toxcore/pull/2592) cleanup: Remove all uses of `SIZEOF_VLA`. +- [#2591](https://github.com/TokTok/c-toxcore/pull/2591) cleanup: Expand the `Tox_Options` accessor macros. +- [#2590](https://github.com/TokTok/c-toxcore/pull/2590) test: Add a simple new/delete test for Tox. +- [#2588](https://github.com/TokTok/c-toxcore/pull/2588) cleanup: Remove plan9 support. +- [#2587](https://github.com/TokTok/c-toxcore/pull/2587) cleanup: Add comment after every `#endif`. +- [#2583](https://github.com/TokTok/c-toxcore/pull/2583) test: Fix comment I broke in the events test PR. +- [#2582](https://github.com/TokTok/c-toxcore/pull/2582) cleanup: Rename group to conference in groupav documentation. +- [#2581](https://github.com/TokTok/c-toxcore/pull/2581) cleanup: Ensure handler params are named after callback params. +- [#2580](https://github.com/TokTok/c-toxcore/pull/2580) cleanup: Minor cleanup of event unpack code. +- [#2578](https://github.com/TokTok/c-toxcore/pull/2578) refactor: Allow NULL pointers for byte arrays in events. +- [#2577](https://github.com/TokTok/c-toxcore/pull/2577) refactor: Add common msgpack array packer with callback. +- [#2576](https://github.com/TokTok/c-toxcore/pull/2576) cleanup: make some improvements to group moderation test +- [#2575](https://github.com/TokTok/c-toxcore/pull/2575) refactor: Pass `this` pointer as first param to s11n callbacks. +- [#2573](https://github.com/TokTok/c-toxcore/pull/2573) cleanup: skip a do_gc iteration before removing peers marked for deletion +- [#2572](https://github.com/TokTok/c-toxcore/pull/2572) cleanup: Remove `bin_pack_{new,free}`. +- [#2568](https://github.com/TokTok/c-toxcore/pull/2568) feat: Add dht_get_nodes_response event to the events system. +- [#2567](https://github.com/TokTok/c-toxcore/pull/2567) refactor: Use enum-specific pack functions for enum values. +- [#2566](https://github.com/TokTok/c-toxcore/pull/2566) cleanup: Remove empty test doing nothing. +- [#2565](https://github.com/TokTok/c-toxcore/pull/2565) refactor: Factor out union pack switch from event packer. +- [#2564](https://github.com/TokTok/c-toxcore/pull/2564) cleanup: Move the 2-element array pack out of individual events. +- [#2563](https://github.com/TokTok/c-toxcore/pull/2563) test: Add printf log statement to group_moderation_test. +- [#2562](https://github.com/TokTok/c-toxcore/pull/2562) chore: add clangd files to .gitignore +- [#2561](https://github.com/TokTok/c-toxcore/pull/2561) refactor: Move file streaming test to its own file. +- [#2560](https://github.com/TokTok/c-toxcore/pull/2560) fix(ci): window builds now build in parallel +- [#2559](https://github.com/TokTok/c-toxcore/pull/2559) refactor: Migrate auto_tests to new events API. +- [#2557](https://github.com/TokTok/c-toxcore/pull/2557) test: Add C++ classes wrapping system interfaces. +- [#2555](https://github.com/TokTok/c-toxcore/pull/2555) fix: Remove fatal error for non-erroneous case +- [#2554](https://github.com/TokTok/c-toxcore/pull/2554) fix: Make all the fuzzers work again, and add a test for protodump. +- [#2552](https://github.com/TokTok/c-toxcore/pull/2552) fix: Make sure there's enough space for CONSUME1 in fuzzers. +- [#2551](https://github.com/TokTok/c-toxcore/pull/2551) chore: Move from gcov to llvm source-based coverage. +- [#2549](https://github.com/TokTok/c-toxcore/pull/2549) fix: issues with packet broadcast error reporting +- [#2547](https://github.com/TokTok/c-toxcore/pull/2547) test: Add fuzz tests to the coverage run. +- [#2545](https://github.com/TokTok/c-toxcore/pull/2545) refactor: Use `operator==` for equality tests of `Node_format`. +- [#2543](https://github.com/TokTok/c-toxcore/pull/2543) refactor(test): Slightly nicer C++ interface to tox Random. +- [#2542](https://github.com/TokTok/c-toxcore/pull/2542) refactor: packet broadcast functions now return errors +- [#2541](https://github.com/TokTok/c-toxcore/pull/2541) fix: don't pass garbage data buffer to packet send functions +- [#2540](https://github.com/TokTok/c-toxcore/pull/2540) cleanup: Make group packet entry creation less error-prone +- [#2539](https://github.com/TokTok/c-toxcore/pull/2539) refactor: Minor refactoring of get_close_nodes functions. +- [#2538](https://github.com/TokTok/c-toxcore/pull/2538) refactor: Factor out malloc+memcpy into memdup. +- [#2536](https://github.com/TokTok/c-toxcore/pull/2536) cleanup: Some more test cleanups, removing overly smart code. +- [#2531](https://github.com/TokTok/c-toxcore/pull/2531) test: Add more unit tests for `add_to_list`. +- [#2530](https://github.com/TokTok/c-toxcore/pull/2530) refactor: Assign malloc return to a local variable first. +- [#2529](https://github.com/TokTok/c-toxcore/pull/2529) test: Add "infer" CI check to github, remove from circle. +- [#2527](https://github.com/TokTok/c-toxcore/pull/2527) cleanup: Add Toxav alias for ToxAV. +- [#2526](https://github.com/TokTok/c-toxcore/pull/2526) cleanup: Make Tox_Options a typedef. +- [#2525](https://github.com/TokTok/c-toxcore/pull/2525) cleanup: Add dynamically derived array sizes to the API. +- [#2524](https://github.com/TokTok/c-toxcore/pull/2524) cleanup: Add explicit array sizes to toxencryptsave. +- [#2523](https://github.com/TokTok/c-toxcore/pull/2523) cleanup: Move `tox_get_system` out of the public API. +- [#2522](https://github.com/TokTok/c-toxcore/pull/2522) cleanup: Make setters take non-const `Tox *`. +- [#2521](https://github.com/TokTok/c-toxcore/pull/2521) cleanup: Make array params in toxav `[]` instead of `*`. +- [#2520](https://github.com/TokTok/c-toxcore/pull/2520) cleanup: Mark arrays in the tox API as `[]` instead of `*`. +- [#2519](https://github.com/TokTok/c-toxcore/pull/2519) refactor: Align group message sending with other send functions. +- [#2518](https://github.com/TokTok/c-toxcore/pull/2518) cleanup: Add typedefs for public API int identifiers. +- [#2517](https://github.com/TokTok/c-toxcore/pull/2517) chore: Spellcheck tox-bootstrapd +- [#2516](https://github.com/TokTok/c-toxcore/pull/2516) chore: Remove settings.yml in favour of hs-github-tools. +- [#2515](https://github.com/TokTok/c-toxcore/pull/2515) chore: Use GPL license with https. +- [#2513](https://github.com/TokTok/c-toxcore/pull/2513) chore: Add fetch-sha256 script to update bootstrap node hash. +- [#2512](https://github.com/TokTok/c-toxcore/pull/2512) cleanup: Move all vptr-to-ptr casts to the beginning of a function. +- [#2510](https://github.com/TokTok/c-toxcore/pull/2510) cleanup: Use github actions matrix to simplify CI. +- [#2509](https://github.com/TokTok/c-toxcore/pull/2509) fix: Use QueryPerformanceCounter on windows for monotonic time. +- [#2508](https://github.com/TokTok/c-toxcore/pull/2508) chore: Add `net_(new|kill)_strerror` to cppcheck's allocators. +- [#2507](https://github.com/TokTok/c-toxcore/pull/2507) cleanup: Run clang-tidy on headers, as well. +- [#2506](https://github.com/TokTok/c-toxcore/pull/2506) cleanup: Make TCP connection failures a warning instead of error. +- [#2505](https://github.com/TokTok/c-toxcore/pull/2505) cleanup: Make all .c files include the headers they need. +- [#2504](https://github.com/TokTok/c-toxcore/pull/2504) cleanup: Upgrade cppcheck, fix some warnings. +- [#2503](https://github.com/TokTok/c-toxcore/pull/2503) cleanup: Upgrade to clang-tidy-17 and fix some warnings. +- [#2502](https://github.com/TokTok/c-toxcore/pull/2502) chore: Use `pkg_search_module` directly in cmake. +- [#2501](https://github.com/TokTok/c-toxcore/pull/2501) chore: Add `IMPORTED_TARGET` to pkg-config packages. +- [#2499](https://github.com/TokTok/c-toxcore/pull/2499) cleanup: Use target_link_libraries directly in cmake. +- [#2498](https://github.com/TokTok/c-toxcore/pull/2498) chore: Simplify msvc build using vcpkg. +- [#2497](https://github.com/TokTok/c-toxcore/pull/2497) cleanup: Remove NaCl support. +- [#2494](https://github.com/TokTok/c-toxcore/pull/2494) fix: unpack enum function names in event impl generator +- [#2493](https://github.com/TokTok/c-toxcore/pull/2493) chore: Disable targets for cross-compilation. +- [#2491](https://github.com/TokTok/c-toxcore/pull/2491) chore: Build a docker image with coverage info in it. +- [#2490](https://github.com/TokTok/c-toxcore/pull/2490) cleanup: Some portability/warning fixes for Windows builds. +- [#2488](https://github.com/TokTok/c-toxcore/pull/2488) fix: Correct a use-after-free and fix some memory leaks. +- [#2487](https://github.com/TokTok/c-toxcore/pull/2487) refactor: Change all enum-like `#define` sequences into enums. +- [#2486](https://github.com/TokTok/c-toxcore/pull/2486) refactor: Change the `TCP_PACKET_*` defines into an enum. +- [#2485](https://github.com/TokTok/c-toxcore/pull/2485) refactor: event generation tool for reorder pr +- [#2484](https://github.com/TokTok/c-toxcore/pull/2484) chore: Fix make_single_file to support core-only. +- [#2481](https://github.com/TokTok/c-toxcore/pull/2481) chore: Update github actions `uses`. +- [#2480](https://github.com/TokTok/c-toxcore/pull/2480) feat: add ngc related unpack functions +- [#2479](https://github.com/TokTok/c-toxcore/pull/2479) feat: Add `to_string` functions for all public enums. +- [#2477](https://github.com/TokTok/c-toxcore/pull/2477) test: add real timeout test +- [#2476](https://github.com/TokTok/c-toxcore/pull/2476) chore: Move s390x build to post-merge. +- [#2475](https://github.com/TokTok/c-toxcore/pull/2475) refactor: Give `enum-from-int` functions the ability to report errors. +- [#2474](https://github.com/TokTok/c-toxcore/pull/2474) cleanup: Remove test net support. +- [#2472](https://github.com/TokTok/c-toxcore/pull/2472) feat: Enable ubsan on bootstrap nodes. +- [#2470](https://github.com/TokTok/c-toxcore/pull/2470) test: Add check-c run to bazel build. +- [#2468](https://github.com/TokTok/c-toxcore/pull/2468) fix(test): tests use ipv6 by default, even with USE_IPV6 set to 0 +- [#2466](https://github.com/TokTok/c-toxcore/pull/2466) cleanup: Make group saving/loading more forgiving with data errors +- [#2465](https://github.com/TokTok/c-toxcore/pull/2465) refactor: replace memset with a loop +- [#2459](https://github.com/TokTok/c-toxcore/pull/2459) fix: Enable debug flag for ubsan. +- [#2458](https://github.com/TokTok/c-toxcore/pull/2458) fix: also Install header for private/experimental API functions with autotools +- [#2456](https://github.com/TokTok/c-toxcore/pull/2456) docs: Remove defunct IRC channel from README.md +- [#2454](https://github.com/TokTok/c-toxcore/pull/2454) fix: memory leaks +- [#2453](https://github.com/TokTok/c-toxcore/pull/2453) refactor: Install header for private/experimental API functions +- [#2452](https://github.com/TokTok/c-toxcore/pull/2452) refactor: replace DEFAULT_TCP_RELAY_PORTS_COUNT with a compile-time calculation +- [#2451](https://github.com/TokTok/c-toxcore/pull/2451) cleanup: clarify disabling of static assert checks +- [#2449](https://github.com/TokTok/c-toxcore/pull/2449) cleanup: replace tabs with spaces +- [#2448](https://github.com/TokTok/c-toxcore/pull/2448) feat: group connection queries now return our own connection type +- [#2447](https://github.com/TokTok/c-toxcore/pull/2447) fix: Docker tox-bootstrapd hash update failing when using BuildKit +- [#2446](https://github.com/TokTok/c-toxcore/pull/2446) feat: Add groupchat API function that returns an IP address string for a peer +- [#2442](https://github.com/TokTok/c-toxcore/pull/2442) perf: Slightly reduce bandwidth usage when there are few nodes. +- [#2439](https://github.com/TokTok/c-toxcore/pull/2439) test: Make esp32 build actually try to instantiate tox. +- [#2438](https://github.com/TokTok/c-toxcore/pull/2438) cleanup: Remove explicit layering_check feature. +- [#2437](https://github.com/TokTok/c-toxcore/pull/2437) chore: Upgrade sonar-scan jvm to java 17. +- [#2436](https://github.com/TokTok/c-toxcore/pull/2436) fix: Add missing `htons` call when adding configured TCP relay. +- [#2434](https://github.com/TokTok/c-toxcore/pull/2434) chore: Cancel old PR builds on docker and sonar-scan workflows. +- [#2432](https://github.com/TokTok/c-toxcore/pull/2432) chore: Use C99 on MSVC instead of C11. +- [#2430](https://github.com/TokTok/c-toxcore/pull/2430) chore: Retry freebsd tests 2 times. +- [#2429](https://github.com/TokTok/c-toxcore/pull/2429) test: Add an s390x build (on alpine) for CI. +- [#2428](https://github.com/TokTok/c-toxcore/pull/2428) chore: Add a compcert docker run script. +- [#2427](https://github.com/TokTok/c-toxcore/pull/2427) cleanup: Use tcc docker image for CI. +- [#2424](https://github.com/TokTok/c-toxcore/pull/2424) fix: Fix memory leak in the error path of loading savedata. +- [#2420](https://github.com/TokTok/c-toxcore/pull/2420) refactor: Use Bin_Pack for packing Node_format. +- [#2416](https://github.com/TokTok/c-toxcore/pull/2416) chore: Add more logging to loading conferences from savedata. +- [#2415](https://github.com/TokTok/c-toxcore/pull/2415) refactor: Add a `bin_unpack_bin_max` for max-length arrays. +- [#2414](https://github.com/TokTok/c-toxcore/pull/2414) fix: inversed return values +- [#2413](https://github.com/TokTok/c-toxcore/pull/2413) cleanup: Fix GCC compatibility. +- [#2408](https://github.com/TokTok/c-toxcore/pull/2408) fix: Ensure we have allocators available for the error paths. +- [#2407](https://github.com/TokTok/c-toxcore/pull/2407) cleanup: Remove redundant `-DSODIUM_EXPORT` from definitions. +- [#2406](https://github.com/TokTok/c-toxcore/pull/2406) cleanup: Fix a few more clang-tidy warnings. +- [#2405](https://github.com/TokTok/c-toxcore/pull/2405) cleanup: Fix a few more clang-tidy warnings. +- [#2404](https://github.com/TokTok/c-toxcore/pull/2404) cleanup: Enforce stricter identifier naming using clang-tidy. +- [#2396](https://github.com/TokTok/c-toxcore/pull/2396) chore: Add devcontainer setup for codespaces. +- [#2393](https://github.com/TokTok/c-toxcore/pull/2393) refactor: Add `mem` module to allow tests to override allocators. +- [#2392](https://github.com/TokTok/c-toxcore/pull/2392) refactor: Make event dispatch ordered by receive time. +- [#2391](https://github.com/TokTok/c-toxcore/pull/2391) docs: Fix doxygen config and remove some redundant comments. +- [#2390](https://github.com/TokTok/c-toxcore/pull/2390) chore: Fix the Android CI job +- [#2389](https://github.com/TokTok/c-toxcore/pull/2389) fix: Add missing `#include `. +- [#2388](https://github.com/TokTok/c-toxcore/pull/2388) chore: Add missing module dependencies. +- [#2384](https://github.com/TokTok/c-toxcore/pull/2384) feat: increase NGC lossy custom packet size +- [#2383](https://github.com/TokTok/c-toxcore/pull/2383) fix: add missing ngc constants getter declarations and definitions +- [#2381](https://github.com/TokTok/c-toxcore/pull/2381) fix: incorrect documentation +- [#2380](https://github.com/TokTok/c-toxcore/pull/2380) feat: allow for larger incoming NGC packets +- [#2371](https://github.com/TokTok/c-toxcore/pull/2371) docs: fix group_peer_exit_cb +- [#2370](https://github.com/TokTok/c-toxcore/pull/2370) fix: behaviour of group api function +- [#2369](https://github.com/TokTok/c-toxcore/pull/2369) fix: flaky tcp test +- [#2367](https://github.com/TokTok/c-toxcore/pull/2367) fix: fuzz support for TCP server +- [#2364](https://github.com/TokTok/c-toxcore/pull/2364) fix: potential endless loop under extremely high load +- [#2362](https://github.com/TokTok/c-toxcore/pull/2362) test: enable tcp relay for bootstrap fuzzing +- [#2361](https://github.com/TokTok/c-toxcore/pull/2361) fix: resolve_bootstrap_node() not checking net_getipport() returned count correctly +- [#2357](https://github.com/TokTok/c-toxcore/pull/2357) feat: get the number of close dht nodes with announce/store support +- [#2355](https://github.com/TokTok/c-toxcore/pull/2355) fix: group custom packet size limits +- [#2354](https://github.com/TokTok/c-toxcore/pull/2354) fix: DHTBootstrap should always respond to version packets with toxcore version +- [#2351](https://github.com/TokTok/c-toxcore/pull/2351) fix: Increase max group message length by four bytes +- [#2348](https://github.com/TokTok/c-toxcore/pull/2348) refactor: Make some improvements to how often/when we announce a group +- [#2341](https://github.com/TokTok/c-toxcore/pull/2341) fix: #1144 by forcing misc_tools to be a static lib +- [#2340](https://github.com/TokTok/c-toxcore/pull/2340) fix: missing net to host conversion of port in logging in group_chat.c +- [#2339](https://github.com/TokTok/c-toxcore/pull/2339) fix: missing net to host conversion of port in logging +- [#2338](https://github.com/TokTok/c-toxcore/pull/2338) fix: bug causing friend group invites to sometimes fail & improve logging +- [#2333](https://github.com/TokTok/c-toxcore/pull/2333) docs: Update README for bootstrap node docker +- [#2329](https://github.com/TokTok/c-toxcore/pull/2329) refactor: extract each case in handle packet in messenger +- [#2327](https://github.com/TokTok/c-toxcore/pull/2327) fix: unlock correct dht_friend +- [#2325](https://github.com/TokTok/c-toxcore/pull/2325) fix: Remove cmake cache files after copying to container build directory +- [#2323](https://github.com/TokTok/c-toxcore/pull/2323) docs: Update README.md to include cmp submodule info +- [#2318](https://github.com/TokTok/c-toxcore/pull/2318) chore: disable warning about pre C99 code +- [#2317](https://github.com/TokTok/c-toxcore/pull/2317) Refactor: Extract shared key cache into separate file +- [#2311](https://github.com/TokTok/c-toxcore/pull/2311) cleanup: make it more clear that assert and uint32_t increment both only exist if NDEBUG is not defined +- [#2291](https://github.com/TokTok/c-toxcore/pull/2291) test: Add a protocol dump test to generate initial fuzzer input. +- [#2271](https://github.com/TokTok/c-toxcore/pull/2271) chore: Migrate from Appveyor to Azure Pipelines +- [#2269](https://github.com/TokTok/c-toxcore/pull/2269) feat: Merge the remainder of the new groupchats implementation +- [#2203](https://github.com/TokTok/c-toxcore/pull/2203) refactor: Store time in Mono_Time in milliseconds. +- [#1944](https://github.com/TokTok/c-toxcore/pull/1944) chore: tox_new() should return null when savedata loading fails + +### Closed issues: + +- [#2739](https://github.com/TokTok/c-toxcore/issues/2739) Tox_Options.operating_system is not clear about it being an experimental option +- [#2734](https://github.com/TokTok/c-toxcore/issues/2734) error compiling on fedora +- [#2649](https://github.com/TokTok/c-toxcore/issues/2649) create_extended_keypair should use Random and be made deterministic for fuzzing +- [#2358](https://github.com/TokTok/c-toxcore/issues/2358) resolve_bootstrap_node assert hit +- [#2352](https://github.com/TokTok/c-toxcore/issues/2352) SEGV after infinite loop retrying proxy_socks5_read_connection_response +- [#2335](https://github.com/TokTok/c-toxcore/issues/2335) ipv6 disabled on kernel cmdline disrupts Tox = most tests fail +- [#2303](https://github.com/TokTok/c-toxcore/issues/2303) Add new group chats events to tox_events and tox_dispatch modules. +- [#2302](https://github.com/TokTok/c-toxcore/issues/2302) Run strong fuzz tests against NGC +- [#2301](https://github.com/TokTok/c-toxcore/issues/2301) Implement NGC save/load in hs-toxcore and run round-trip tests against c-toxcore +- [#2192](https://github.com/TokTok/c-toxcore/issues/2192) Provide official signed release tarballs +- [#2118](https://github.com/TokTok/c-toxcore/issues/2118) Add a private "get mono_time" API to `tox_private.h` and use it in auto_tests. +- [#2029](https://github.com/TokTok/c-toxcore/issues/2029) Migrate all auto tests to the events API. +- [#2014](https://github.com/TokTok/c-toxcore/issues/2014) Add sodium autotools CI build +- [#1144](https://github.com/TokTok/c-toxcore/issues/1144) DHT_bootstrap should not link against misc_tools + ## v0.2.18 ### Merged PRs: +- [#2300](https://github.com/TokTok/c-toxcore/pull/2300) chore: Release 0.2.18 - [#2299](https://github.com/TokTok/c-toxcore/pull/2299) fix: remove the assert because buffer can be larger than UINT16_MAX. - [#2297](https://github.com/TokTok/c-toxcore/pull/2297) cleanup: remove unused field last_seen from Onion_Friend - [#2289](https://github.com/TokTok/c-toxcore/pull/2289) test: Add a Null_System used in toxsave_harness. @@ -107,6 +372,7 @@ ### Closed issues: +- [#2298](https://github.com/TokTok/c-toxcore/issues/2298) assert makes incorrect assumption - [#2256](https://github.com/TokTok/c-toxcore/issues/2256) New Defects reported by Coverity Scan for TokTok/c-toxcore - [#2109](https://github.com/TokTok/c-toxcore/issues/2109) Assimilate `messenger_test.c`: replace with public API test - [#2012](https://github.com/TokTok/c-toxcore/issues/2012) Support building a DLL on Windows diff --git a/CMakeLists.txt b/CMakeLists.txt index 6d779fa0..6f6d37da 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -44,7 +44,7 @@ set_source_files_properties( # versions in a synchronised way. set(PROJECT_VERSION_MAJOR "0") set(PROJECT_VERSION_MINOR "2") -set(PROJECT_VERSION_PATCH "18") +set(PROJECT_VERSION_PATCH "19") set(PROJECT_VERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}") # set .so library version / following libtool scheme @@ -146,6 +146,8 @@ endif() option(BUILD_MISC_TESTS "Build additional tests" OFF) option(BUILD_FUN_UTILS "Build additional just for fun utilities" OFF) +option(UNITTEST "Enable unit tests (disable if you don't have a working gmock or gtest)" ON) + option(AUTOTEST "Enable autotests (mainly for CI)" OFF) if(AUTOTEST) option(NON_HERMETIC_TESTS "Whether to build and run tests that depend on an internet connection" OFF) @@ -534,7 +536,7 @@ endfunction() # The actual unit tests follow. # -if(TARGET GTest::gtest AND TARGET GTest::gmock) +if(UNITTEST AND TARGET GTest::gtest AND TARGET GTest::gmock) unit_test(toxav ring_buffer) unit_test(toxav rtp) unit_test(toxcore DHT) diff --git a/INSTALL.md b/INSTALL.md index 3754faac..67e83717 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -151,6 +151,7 @@ There are some options that are available to configure the build. | `PROXY_TEST` | Enable proxy test (requires `other/proxy/proxy_server.go` to be running). | ON or OFF | OFF | | `STRICT_ABI` | Enforce strict ABI export in dynamic libraries. | ON or OFF | OFF | | `TEST_TIMEOUT_SECONDS` | Limit runtime of each test to the number of seconds specified. | Positive number or nothing (empty string). | Empty string. | +| `UNITTEST` | Enable unit tests (disable if you don't have a working gmock or gtest). | ON or OFF | ON | | `USE_IPV6` | Use IPv6 in tests. | ON or OFF | ON | You can get this list of option using the following commands diff --git a/configure.ac b/configure.ac index 8f9a50bb..76eca6be 100644 --- a/configure.ac +++ b/configure.ac @@ -2,7 +2,7 @@ # Process this file with autoconf to produce a configure script. AC_PREREQ([2.65]) -AC_INIT([tox], [0.2.18]) +AC_INIT([tox], [0.2.19]) AC_CONFIG_AUX_DIR(configure_aux) AC_CONFIG_SRCDIR([toxcore/net_crypto.c]) AM_INIT_AUTOMAKE([foreign 1.10 -Wall -Werror subdir-objects tar-ustar]) diff --git a/other/bootstrap_daemon/docker/tox-bootstrapd.sha256 b/other/bootstrap_daemon/docker/tox-bootstrapd.sha256 index faef8b86..c726f000 100644 --- a/other/bootstrap_daemon/docker/tox-bootstrapd.sha256 +++ b/other/bootstrap_daemon/docker/tox-bootstrapd.sha256 @@ -1 +1 @@ -af58a125e5c80d7a19bc7f32868c1edfdf80f366e3bf778728961a50ce63ee26 /usr/local/bin/tox-bootstrapd +e96f03a89051c5df12c28d0d6941184da2b92742d248bd4c57d31189a0052844 /usr/local/bin/tox-bootstrapd diff --git a/other/docker/pkgsrc/pkgsrc.Dockerfile b/other/docker/pkgsrc/pkgsrc.Dockerfile index 10fb6a6b..c27ed7cb 100644 --- a/other/docker/pkgsrc/pkgsrc.Dockerfile +++ b/other/docker/pkgsrc/pkgsrc.Dockerfile @@ -5,6 +5,7 @@ COPY . /work/c-toxcore-0.2.18 RUN ["tar", "zcf", "c-toxcore.tar.gz", "c-toxcore-0.2.18"] WORKDIR /work/pkgsrc/chat/toxcore +RUN ["sed", "-i", "-e", "s/libtoxcore.so.2.18.0/libtoxcore.so.2.19.0/g", "PLIST"] RUN ["bmake", "clean"] RUN ["bmake", "DISTFILES=c-toxcore.tar.gz", "DISTDIR=/work", "NO_CHECKSUM=yes"] RUN ["bmake", "install"] diff --git a/so.version b/so.version index b2322ccd..26514bca 100644 --- a/so.version +++ b/so.version @@ -11,6 +11,6 @@ # For a full reference see: # https://www.gnu.org/software/libtool/manual/libtool.html#Updating-version-info -CURRENT=20 +CURRENT=21 REVISION=0 -AGE=18 +AGE=19 diff --git a/testing/fuzzing/bootstrap_fuzz_test.cc b/testing/fuzzing/bootstrap_fuzz_test.cc index f25e2431..4a784f84 100644 --- a/testing/fuzzing/bootstrap_fuzz_test.cc +++ b/testing/fuzzing/bootstrap_fuzz_test.cc @@ -104,7 +104,6 @@ void TestBootstrap(Fuzz_Data &input) Ptr opts(tox_options_new(nullptr), tox_options_free); assert(opts != nullptr); - tox_options_set_operating_system(opts.get(), sys.sys.get()); tox_options_set_log_callback(opts.get(), [](Tox *tox, Tox_Log_Level level, const char *file, uint32_t line, const char *func, @@ -134,8 +133,12 @@ void TestBootstrap(Fuzz_Data &input) tox_options_set_tcp_port(opts.get(), 33445); } + Tox_Options_Testing tox_options_testing; + tox_options_testing.operating_system = sys.sys.get(); + Tox_Err_New error_new; - Tox *tox = tox_new(opts.get(), &error_new); + Tox_Err_New_Testing error_new_testing; + Tox *tox = tox_new_testing(opts.get(), &error_new, &tox_options_testing, &error_new_testing); if (tox == nullptr) { // It might fail, because some I/O happens in tox_new, and the fuzzer @@ -144,6 +147,7 @@ void TestBootstrap(Fuzz_Data &input) } assert(error_new == TOX_ERR_NEW_OK); + assert(error_new_testing == TOX_ERR_NEW_TESTING_OK); uint8_t pub_key[TOX_PUBLIC_KEY_SIZE] = {0}; diff --git a/testing/fuzzing/e2e_fuzz_test.cc b/testing/fuzzing/e2e_fuzz_test.cc index 1be228e0..df4e03c6 100644 --- a/testing/fuzzing/e2e_fuzz_test.cc +++ b/testing/fuzzing/e2e_fuzz_test.cc @@ -138,7 +138,6 @@ void TestEndToEnd(Fuzz_Data &input) Ptr opts(tox_options_new(nullptr), tox_options_free); assert(opts != nullptr); - tox_options_set_operating_system(opts.get(), sys.sys.get()); tox_options_set_local_discovery_enabled(opts.get(), false); tox_options_set_log_callback(opts.get(), @@ -151,8 +150,12 @@ void TestEndToEnd(Fuzz_Data &input) } }); + Tox_Options_Testing tox_options_testing; + tox_options_testing.operating_system = sys.sys.get(); + Tox_Err_New error_new; - Tox *tox = tox_new(opts.get(), &error_new); + Tox_Err_New_Testing error_new_testing; + Tox *tox = tox_new_testing(opts.get(), &error_new, &tox_options_testing, &error_new_testing); if (tox == nullptr) { // It might fail, because some I/O happens in tox_new, and the fuzzer @@ -161,6 +164,7 @@ void TestEndToEnd(Fuzz_Data &input) } assert(error_new == TOX_ERR_NEW_OK); + assert(error_new_testing == TOX_ERR_NEW_TESTING_OK); tox_events_init(tox); diff --git a/testing/fuzzing/fuzz_support.hh b/testing/fuzzing/fuzz_support.hh index 7f03d341..6a370f3d 100644 --- a/testing/fuzzing/fuzz_support.hh +++ b/testing/fuzzing/fuzz_support.hh @@ -16,6 +16,7 @@ #include #include "../../toxcore/tox.h" +#include "../../toxcore/tox_private.h" struct Fuzz_Data { static constexpr bool DEBUG = false; diff --git a/testing/fuzzing/protodump.cc b/testing/fuzzing/protodump.cc index 1a3f8c07..28df05a0 100644 --- a/testing/fuzzing/protodump.cc +++ b/testing/fuzzing/protodump.cc @@ -195,13 +195,16 @@ void RecordBootstrap(const char *init, const char *bootstrap) }); Tox_Err_New error_new; + Tox_Err_New_Testing error_new_testing; + Tox_Options_Testing tox_options_testing; Record_System sys1(global, 4, "tox1"); // fair dice roll tox_options_set_log_user_data(opts, &sys1); - tox_options_set_operating_system(opts, sys1.sys.get()); - Tox *tox1 = tox_new(opts, &error_new); + tox_options_testing.operating_system = sys1.sys.get(); + Tox *tox1 = tox_new_testing(opts, &error_new, &tox_options_testing, &error_new_testing); assert(tox1 != nullptr); assert(error_new == TOX_ERR_NEW_OK); + assert(error_new_testing == TOX_ERR_NEW_TESTING_OK); std::array address1; tox_self_get_address(tox1, address1.data()); std::array pk1; @@ -211,10 +214,11 @@ void RecordBootstrap(const char *init, const char *bootstrap) Record_System sys2(global, 5, "tox2"); // unfair dice roll tox_options_set_log_user_data(opts, &sys2); - tox_options_set_operating_system(opts, sys2.sys.get()); - Tox *tox2 = tox_new(opts, &error_new); + tox_options_testing.operating_system = sys2.sys.get(); + Tox *tox2 = tox_new_testing(opts, &error_new, &tox_options_testing, &error_new_testing); assert(tox2 != nullptr); assert(error_new == TOX_ERR_NEW_OK); + assert(error_new_testing == TOX_ERR_NEW_TESTING_OK); std::array address2; tox_self_get_address(tox2, address2.data()); std::array pk2; diff --git a/testing/fuzzing/protodump_reduce.cc b/testing/fuzzing/protodump_reduce.cc index ae9676ca..820a3fc7 100644 --- a/testing/fuzzing/protodump_reduce.cc +++ b/testing/fuzzing/protodump_reduce.cc @@ -142,9 +142,11 @@ void TestEndToEnd(Fuzz_Data &input) Ptr opts(tox_options_new(nullptr), tox_options_free); assert(opts != nullptr); - tox_options_set_operating_system(opts.get(), sys.sys.get()); tox_options_set_local_discovery_enabled(opts.get(), false); + Tox_Options_Testing tox_options_testing; + tox_options_testing.operating_system = sys.sys.get(); + tox_options_set_log_callback(opts.get(), [](Tox *tox, Tox_Log_Level level, const char *file, uint32_t line, const char *func, const char *message, void *user_data) { @@ -156,7 +158,8 @@ void TestEndToEnd(Fuzz_Data &input) }); Tox_Err_New error_new; - Tox *tox = tox_new(opts.get(), &error_new); + Tox_Err_New_Testing error_new_testing; + Tox *tox = tox_new_testing(opts.get(), &error_new, &tox_options_testing, &error_new_testing); if (tox == nullptr) { // It might fail, because some I/O happens in tox_new, and the fuzzer @@ -165,6 +168,7 @@ void TestEndToEnd(Fuzz_Data &input) } assert(error_new == TOX_ERR_NEW_OK); + assert(error_new_testing == TOX_ERR_NEW_TESTING_OK); tox_events_init(tox); diff --git a/testing/fuzzing/toxsave_fuzz_test.cc b/testing/fuzzing/toxsave_fuzz_test.cc index 2cb134cb..f48c2bf0 100644 --- a/testing/fuzzing/toxsave_fuzz_test.cc +++ b/testing/fuzzing/toxsave_fuzz_test.cc @@ -20,14 +20,15 @@ void TestSaveDataLoading(Fuzz_Data &input) const size_t savedata_size = input.size(); CONSUME_OR_RETURN(const uint8_t *savedata, input, savedata_size); - Null_System sys; - tox_options_set_operating_system(tox_options, sys.sys.get()); - // pass test data to Tox tox_options_set_savedata_data(tox_options, savedata, savedata_size); tox_options_set_savedata_type(tox_options, TOX_SAVEDATA_TYPE_TOX_SAVE); - Tox *tox = tox_new(tox_options, nullptr); + Tox_Options_Testing tox_options_testing; + Null_System sys; + tox_options_testing.operating_system = sys.sys.get(); + + Tox *tox = tox_new_testing(tox_options, nullptr, &tox_options_testing, nullptr); tox_options_free(tox_options); if (tox == nullptr) { // Tox save was invalid, we're finished here diff --git a/toxav/toxav.h b/toxav/toxav.h index 07d8d0ee..3b4bd09c 100644 --- a/toxav/toxav.h +++ b/toxav/toxav.h @@ -1,5 +1,5 @@ /* SPDX-License-Identifier: GPL-3.0-or-later - * Copyright © 2016-2018 The TokTok team. + * Copyright © 2016-2024 The TokTok team. * Copyright © 2013-2015 Tox project. */ @@ -7,39 +7,40 @@ * @brief Public audio/video API for Tox clients. * * This API can handle multiple calls. Each call has its state, in very rare - * occasions the library can change the state of the call without apps knowledge. + * occasions the library can change the state of the call without apps + * knowledge. * * @section av_events Events and callbacks * - * As in Core API, events are handled by callbacks. One callback can be + * As in the toxcore API, events are handled by callbacks. One callback can be * registered per event. All events have a callback function type named - * `toxav_{event}_cb` and a function to register it named `toxav_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. Unlike Core API, lack of some event handlers will cause the the - * library to drop calls before they are started. Hanging up call from a - * callback causes undefined behaviour. + * `toxav_{event}_cb` and a function to register it named + * `toxav_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. Unlike the toxcore API, lack of + * some event handlers will cause the the library to drop calls before they are + * started. Hanging up call from a callback causes undefined behaviour. * * @section av_threading Threading implications * * Only toxav_iterate is thread-safe, all other functions must run from the - * tox thread. + * Tox thread. * * Important exceptions are the `*_iterate` and `*_iterate_interval` * functions. You have to choose either the single thread or the multi thread * functions and read their documentation. * * A common way to run ToxAV (multiple or single instance) is to have a thread, - * separate from tox instance thread, running a simple toxav_iterate loop, + * separate from Tox instance thread, running a simple toxav_iterate loop, * sleeping for `toxav_iteration_interval * milliseconds` on each iteration. * - * An important thing to note is that events are triggered from both tox and - * toxav thread (see above). Audio and video receive frame events are triggered - * from toxav thread while all the other events are triggered from tox thread. + * An important thing to note is that events are triggered from both Tox and + * ToxAV thread (see above). Audio and video receive frame events are triggered + * from ToxAV thread while all the other events are triggered from Tox thread. * - * Tox thread has priority with mutex mechanisms. Any api function can - * fail if mutexes are held by tox thread in which case they will set SYNC + * Tox thread has priority with mutex mechanisms. Any API function can + * fail if mutexes are held by Tox thread in which case they will set SYNC * error code. * * @subsection av_multi_threading Separate audio and video threads @@ -77,9 +78,9 @@ typedef struct Tox Tox; * * Each ToxAV instance can be bound to only one Tox instance, and Tox instance * can have only one ToxAV instance. One must make sure to close ToxAV instance - * prior closing Tox instance otherwise undefined behaviour occurs. Upon - * closing of ToxAV instance, all active calls will be forcibly terminated - * without notifying peers. + * prior closing Tox instance otherwise undefined behaviour occurs. Upon closing + * of ToxAV instance, all active calls will be forcibly terminated without + * notifying peers. */ typedef struct ToxAV ToxAV; @@ -100,8 +101,8 @@ typedef enum Toxav_Err_New { TOXAV_ERR_NEW_NULL, /** - * Memory allocation failure while trying to allocate structures required for - * the A/V session. + * Memory allocation failure while trying to allocate structures required + * for the A/V session. */ TOXAV_ERR_NEW_MALLOC, @@ -203,8 +204,8 @@ typedef enum Toxav_Err_Call { TOXAV_ERR_CALL_OK, /** - * A resource allocation error occurred while trying to create the structures - * required for the call. + * A resource allocation error occurred while trying to create the + * structures required for the call. */ TOXAV_ERR_CALL_MALLOC, @@ -246,9 +247,9 @@ typedef enum Toxav_Err_Call { * * @param friend_number The friend number of the friend that should be called. * @param audio_bit_rate Audio bit rate in Kb/sec. Set this to 0 to disable - * audio sending. + * audio sending. * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable - * video sending. + * video sending. */ bool toxav_call(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, Toxav_Err_Call *error); @@ -293,8 +294,9 @@ typedef enum Toxav_Err_Answer { TOXAV_ERR_ANSWER_FRIEND_NOT_FOUND, /** - * The friend was valid, but they are not currently trying to initiate a call. - * This is also returned if this client is already in a call with the friend. + * The friend was valid, but they are not currently trying to initiate a + * call. This is also returned if this client is already in a call with the + * friend. */ TOXAV_ERR_ANSWER_FRIEND_NOT_CALLING, @@ -314,9 +316,9 @@ typedef enum Toxav_Err_Answer { * * @param friend_number The friend number of the friend that is calling. * @param audio_bit_rate Audio bit rate in Kb/sec. Set this to 0 to disable - * audio sending. + * audio sending. * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable - * video sending. + * video sending. */ bool toxav_answer(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate, Toxav_Err_Answer *error); @@ -337,8 +339,8 @@ enum Toxav_Friend_Call_State { /** * Set by the AV core if an error occurred on the remote end or if friend * timed out. This is the final state after which no more state - * transitions can occur for the call. This call state will never be triggered - * in combination with other call states. + * transitions can occur for the call. This call state will never be + * triggered in combination with other call states. */ TOXAV_FRIEND_CALL_STATE_ERROR = 1, @@ -376,9 +378,9 @@ enum Toxav_Friend_Call_State { * * @param friend_number The friend number for which the call state changed. * @param state The bitmask of the new call state which is guaranteed to be - * different than the previous state. The state is set to 0 when the call is - * paused. The bitmask represents all the activities currently performed by the - * friend. + * different than the previous state. The state is set to 0 when the call is + * paused. The bitmask represents all the activities currently performed by + * the friend. */ typedef void toxav_call_state_cb(ToxAV *av, uint32_t friend_number, uint32_t state, void *user_data); @@ -397,8 +399,9 @@ void toxav_callback_call_state(ToxAV *av, toxav_call_state_cb *callback, void *u typedef enum Toxav_Call_Control { /** - * Resume a previously paused call. Only valid if the pause was caused by this - * client, if not, this control is ignored. Not valid before the call is accepted. + * Resume a previously paused call. Only valid if the pause was caused by + * this client, if not, this control is ignored. Not valid before the call + * is accepted. */ TOXAV_CALL_CONTROL_RESUME, @@ -457,8 +460,8 @@ typedef enum Toxav_Err_Call_Control { TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_FOUND, /** - * This client is currently not in a call with the friend. Before the call is - * answered, only CANCEL is a valid control. + * This client is currently not in a call with the friend. Before the call + * is answered, only CANCEL is a valid control. */ TOXAV_ERR_CALL_CONTROL_FRIEND_NOT_IN_CALL, @@ -474,7 +477,7 @@ typedef enum Toxav_Err_Call_Control { * Sends a call control command to a friend. * * @param friend_number The friend number of the friend this client is in a call - * with. + * with. * @param control The control command to send. * * @return true on success. @@ -530,8 +533,8 @@ typedef enum Toxav_Err_Send_Frame { TOXAV_ERR_SEND_FRAME_OK, /** - * In case of video, one of Y, U, or V was NULL. In case of audio, the samples - * data pointer was NULL. + * In case of video, one of Y, U, or V was NULL. In case of audio, the + * samples data pointer was NULL. */ TOXAV_ERR_SEND_FRAME_NULL, @@ -557,13 +560,13 @@ typedef enum Toxav_Err_Send_Frame { TOXAV_ERR_SEND_FRAME_INVALID, /** - * Either friend turned off audio or video receiving or we turned off sending - * for the said payload. + * Either friend turned off audio or video receiving or we turned off + * sending for the said payload. */ TOXAV_ERR_SEND_FRAME_PAYLOAD_TYPE_DISABLED, /** - * Failed to push frame through rtp interface. + * Failed to push frame through RTP interface. */ TOXAV_ERR_SEND_FRAME_RTP_FAILED, @@ -572,7 +575,8 @@ typedef enum Toxav_Err_Send_Frame { /** * Send an audio frame to a friend. * - * The expected format of the PCM data is: `[s1c1][s1c2][...][s2c1][s2c2][...]...` + * The expected format of the PCM data is: + * `[s1c1][s1c2][...][s2c1][s2c2][...]...` * Meaning: sample 1 for channel 1, sample 1 for channel 2, ... * For mono audio, this has no meaning, every sample is subsequent. For stereo, * this means the expected format is LRLRLR... with samples for left and right @@ -584,10 +588,10 @@ typedef enum Toxav_Err_Send_Frame { * `sample_count * channels`. * @param sample_count Number of samples in this frame. Valid numbers here are * `((sample rate) * (audio length) / 1000)`, where audio length can be - * 2.5, 5, 10, 20, 40 or 60 millseconds. + * 2.5, 5, 10, 20, 40 or 60 milliseconds. * @param channels Number of audio channels. Supported values are 1 and 2. * @param sampling_rate Audio sampling rate used in this frame. Valid sampling - * rates are 8000, 12000, 16000, 24000, or 48000. + * rates are 8000, 12000, 16000, 24000, or 48000. */ bool toxav_audio_send_frame(ToxAV *av, uint32_t friend_number, const int16_t pcm[], size_t sample_count, uint8_t channels, uint32_t sampling_rate, Toxav_Err_Send_Frame *error); @@ -596,7 +600,7 @@ bool toxav_audio_send_frame(ToxAV *av, uint32_t friend_number, const int16_t pcm * Set the bit rate to be used in subsequent video frames. * * @param friend_number The friend number of the friend for which to set the - * bit rate. + * bit rate. * @param bit_rate The new audio bit rate in Kb/sec. Set to 0 to disable. * * @return true on success. @@ -605,11 +609,11 @@ bool toxav_audio_set_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t bit_ra /** * The function type for the audio_bit_rate callback. The event is triggered - * when the network becomes too saturated for current bit rates at which - * point core suggests new bit rates. + * when the network becomes too saturated for current bit rates at which point + * ToxAV suggests new bit rates. * * @param friend_number The friend number of the friend for which to set the - * bit rate. + * bit rate. * @param audio_bit_rate Suggested maximum audio bit rate in Kb/sec. */ typedef void toxav_audio_bit_rate_cb(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, void *user_data); @@ -628,7 +632,7 @@ void toxav_callback_audio_bit_rate(ToxAV *av, toxav_audio_bit_rate_cb *callback, * V - plane should be of size: `(height/2) * (width/2)` * * @param friend_number The friend number of the friend to which to send a video - * frame. + * frame. * @param width Width of the frame in pixels. * @param height Height of the frame in pixels. * @param y Y (Luminance) plane data. @@ -646,7 +650,7 @@ bool toxav_video_send_frame( * Set the bit rate to be used in subsequent video frames. * * @param friend_number The friend number of the friend for which to set the - * bit rate. + * bit rate. * @param bit_rate The new video bit rate in Kb/sec. Set to 0 to disable. * * @return true on success. @@ -655,11 +659,11 @@ bool toxav_video_set_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t bit_ra /** * The function type for the video_bit_rate callback. The event is triggered - * when the network becomes too saturated for current bit rates at which - * point core suggests new bit rates. + * when the network becomes too saturated for current bit rates at which point + * ToxAV suggests new bit rates. * * @param friend_number The friend number of the friend for which to set the - * bit rate. + * bit rate. * @param video_bit_rate Suggested maximum video bit rate in Kb/sec. */ typedef void toxav_video_bit_rate_cb(ToxAV *av, uint32_t friend_number, uint32_t video_bit_rate, void *user_data); @@ -714,7 +718,6 @@ void toxav_callback_audio_receive_frame(ToxAV *av, toxav_audio_receive_frame_cb * @param y Luminosity plane. `Size = MAX(width, abs(ystride)) * height`. * @param u U chroma plane. `Size = MAX(width/2, abs(ustride)) * (height/2)`. * @param v V chroma plane. `Size = MAX(width/2, abs(vstride)) * (height/2)`. - * * @param ystride Luminosity plane stride. * @param ustride U chroma plane stride. * @param vstride V chroma plane stride. @@ -737,26 +740,28 @@ void toxav_callback_video_receive_frame(ToxAV *av, toxav_video_receive_frame_cb #ifndef APIGEN_IGNORE /*** - * NOTE Compatibility with old toxav group calls. TODO(iphydf): remove + * NOTE Compatibility with old ToxAV group calls. TODO(iphydf): remove * * TODO(iphydf): Use proper new API guidelines for these. E.g. don't use inline * function types, don't have per-callback userdata, especially don't have one * userdata per group. */ -// TODO(iphydf): Use this better typed one instead of the void-pointer one below. +// TODO(iphydf): Use this better typed one instead of the void-pointer one +// below. typedef void toxav_group_audio_cb(Tox *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t pcm[], uint32_t samples, uint8_t channels, uint32_t sample_rate, void *user_data); typedef void toxav_audio_data_cb(void *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t pcm[], uint32_t samples, uint8_t channels, uint32_t sample_rate, void *userdata); -/** @brief Create a new toxav group. +/** @brief Create a new ToxAV group. * * @return group number on success. * @retval -1 on failure. * - * Note that total size of pcm in bytes is equal to `samples * channels * sizeof(int16_t)`. + * Note that total size of pcm in bytes is equal to + * `samples * channels * sizeof(int16_t)`. */ int32_t toxav_add_av_groupchat(Tox *tox, toxav_audio_data_cb *audio_callback, void *userdata); @@ -765,7 +770,8 @@ int32_t toxav_add_av_groupchat(Tox *tox, toxav_audio_data_cb *audio_callback, vo * @return group number on success. * @retval -1 on failure. * - * Note that total size of pcm in bytes is equal to `samples * channels * sizeof(int16_t)`. + * Note that total size of pcm in bytes is equal to + * `samples * channels * sizeof(int16_t)`. */ int32_t toxav_join_av_groupchat( Tox *tox, uint32_t friendnumber, const uint8_t data[], uint16_t length, @@ -776,7 +782,8 @@ int32_t toxav_join_av_groupchat( * @retval 0 on success. * @retval -1 on failure. * - * Note that total size of pcm in bytes is equal to `samples * channels * sizeof(int16_t)`. + * Note that total size of pcm in bytes is equal to + * `samples * channels * sizeof(int16_t)`. * * Valid number of samples are `(sample rate) * (audio length) / 1000` * (Valid values for audio length are: 2.5, 5, 10, 20, 40 or 60 ms) @@ -794,15 +801,16 @@ int32_t toxav_group_send_audio( * A/V must be enabled on a groupchat for audio to be sent to it and for * received audio to be handled. * - * An A/V group created with `toxav_add_av_groupchat` or `toxav_join_av_groupchat` - * will start with A/V enabled. + * An A/V group created with `toxav_add_av_groupchat` or + * `toxav_join_av_groupchat` will start with A/V enabled. * * An A/V group loaded from a savefile will start with A/V disabled. * * @retval 0 on success. * @retval -1 on failure. * - * Note that total size of pcm in bytes is equal to `samples * channels * sizeof(int16_t)`. + * Note that total size of pcm in bytes is equal to + * `samples * channels * sizeof(int16_t)`. */ int32_t toxav_groupchat_enable_av( Tox *tox, uint32_t groupnumber, diff --git a/toxcore/tox.c b/toxcore/tox.c index ebcb53bb..03e34414 100644 --- a/toxcore/tox.c +++ b/toxcore/tox.c @@ -712,7 +712,8 @@ static int tox_load(Tox *tox, const uint8_t *data, uint32_t length) length - cookie_len, STATE_COOKIE_TYPE); } -Tox *tox_new(const struct Tox_Options *options, Tox_Err_New *error) +nullable(1, 2, 3) +static Tox *tox_new_system(const struct Tox_Options *options, Tox_Err_New *error, const Tox_System *sys) { struct Tox_Options *default_options = nullptr; @@ -736,7 +737,6 @@ Tox *tox_new(const struct Tox_Options *options, Tox_Err_New *error) const struct Tox_Options *const opts = options != nullptr ? options : default_options; assert(opts != nullptr); - const Tox_System *sys = tox_options_get_operating_system(opts); const Tox_System default_system = tox_default_system(); if (sys == nullptr) { @@ -1020,6 +1020,37 @@ Tox *tox_new(const struct Tox_Options *options, Tox_Err_New *error) return tox; } +Tox *tox_new(const struct Tox_Options *options, Tox_Err_New *error) +{ + return tox_new_system(options, error, nullptr); +} + +Tox *tox_new_testing(const Tox_Options *options, Tox_Err_New *error, const Tox_Options_Testing *testing, Tox_Err_New_Testing *testing_error) +{ + if (testing == nullptr) { + SET_ERROR_PARAMETER(error, TOX_ERR_NEW_NULL); + SET_ERROR_PARAMETER(testing_error, TOX_ERR_NEW_TESTING_NULL); + return nullptr; + } + + if (testing->operating_system == nullptr) { + SET_ERROR_PARAMETER(error, TOX_ERR_NEW_NULL); + SET_ERROR_PARAMETER(testing_error, TOX_ERR_NEW_TESTING_NULL); + return nullptr; + } + + const Tox_System *sys = testing->operating_system; + + if (sys->rng == nullptr || sys->ns == nullptr || sys->mem == nullptr) { + SET_ERROR_PARAMETER(error, TOX_ERR_NEW_NULL); + SET_ERROR_PARAMETER(testing_error, TOX_ERR_NEW_TESTING_NULL); + return nullptr; + } + + SET_ERROR_PARAMETER(testing_error, TOX_ERR_NEW_TESTING_OK); + return tox_new_system(options, error, sys); +} + void tox_kill(Tox *tox) { if (tox == nullptr) { @@ -4269,7 +4300,7 @@ uint32_t tox_group_invite_accept(Tox *tox, uint32_t friend_number, const uint8_t } case -6: { - SET_ERROR_PARAMETER(error, TOX_ERR_GROUP_INVITE_ACCEPT_CORE); + SET_ERROR_PARAMETER(error, TOX_ERR_GROUP_INVITE_ACCEPT_FRIEND_NOT_FOUND); return UINT32_MAX; } diff --git a/toxcore/tox.h b/toxcore/tox.h index 7aca21ea..aea2db0e 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -1,5 +1,5 @@ /* SPDX-License-Identifier: GPL-3.0-or-later - * Copyright © 2016-2018 The TokTok team. + * Copyright © 2016-2024 The TokTok team. * Copyright © 2013 Tox project. */ @@ -25,9 +25,8 @@ * 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. + * 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. @@ -52,17 +51,9 @@ * 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. + * 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. * * @section threading Threading implications * @@ -157,7 +148,7 @@ uint32_t tox_version_minor(void); * Incremented when bugfixes are applied without changing any functionality or * API or ABI. */ -#define TOX_VERSION_PATCH 18 +#define TOX_VERSION_PATCH 19 uint32_t tox_version_patch(void); @@ -206,7 +197,7 @@ bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch); * * The values of these are not part of the ABI. Prefer to use the function * versions of them for code that should remain compatible with future versions - * of toxcore. + * of the Tox library. */ /** @@ -468,12 +459,12 @@ typedef enum Tox_Log_Level { TOX_LOG_LEVEL_INFO, /** - * Warnings about events_alloc inconsistency or logic errors. + * Warnings about internal inconsistency or logic errors. */ TOX_LOG_LEVEL_WARNING, /** - * Severe unexpected errors caused by external or events_alloc inconsistency. + * Severe unexpected errors caused by external or internal inconsistency. */ TOX_LOG_LEVEL_ERROR, @@ -482,7 +473,7 @@ typedef enum Tox_Log_Level { const char *tox_log_level_to_string(Tox_Log_Level value); /** - * @brief This event is triggered when the toxcore library logs an events_alloc message. + * @brief This event is triggered when Tox logs an internal message. * * This is mostly useful for debugging. This callback can be called from any * function, not just tox_iterate. This means the user data lifetime must at @@ -505,15 +496,6 @@ const char *tox_log_level_to_string(Tox_Log_Level value); typedef void tox_log_cb(Tox *tox, Tox_Log_Level level, const char *file, uint32_t line, const char *func, const char *message, void *user_data); -/** - * @brief Operating system functions used by Tox. - * - * This struct is opaque and generally shouldn't be used in clients, but in - * combination with tox_private.h, it allows tests to inject non-IO (hermetic) - * versions of low level network, RNG, and time keeping functions. - */ -typedef struct Tox_System Tox_System; - /** * @brief This struct contains all the startup options for Tox. * @@ -546,10 +528,11 @@ struct Tox_Options { * Enable the use of UDP communication when available. * * Setting this to false will force Tox to use TCP only. Communications will - * need to be relayed through a TCP relay node, potentially slowing them down. + * need to be relayed through a TCP relay node, potentially slowing them + * down. * - * If a proxy is enabled, UDP will be disabled if either toxcore or the - * proxy don't support proxying UDP messages. + * If a proxy is enabled, UDP will be disabled if either the Tox library or + * the proxy don't support proxying UDP messages. */ bool udp_enabled; @@ -576,10 +559,11 @@ struct Tox_Options { * The IP address or DNS name of the proxy to be used. * * If used, this must be non-NULL and be a valid DNS name. The name must not - * exceed TOX_MAX_HOSTNAME_LENGTH characters, and be in a NUL-terminated C string - * format (TOX_MAX_HOSTNAME_LENGTH includes the NUL byte). + * exceed TOX_MAX_HOSTNAME_LENGTH characters, and be in a NUL-terminated C + * string format (TOX_MAX_HOSTNAME_LENGTH includes the NUL byte). * - * This member is ignored (it can be NULL) if proxy_type is TOX_PROXY_TYPE_NONE. + * This member is ignored (it can be NULL) if proxy_type is + * TOX_PROXY_TYPE_NONE. * * The data pointed at by this member is owned by the user, so must * outlive the options object. @@ -603,8 +587,8 @@ struct Tox_Options { * If either start_port or end_port is 0 while the other is non-zero, the * non-zero port will be the only port in the range. * - * Having start_port > end_port will yield the same behavior as if start_port - * and end_port were swapped. + * Having start_port > end_port will yield the same behavior as if + * start_port and end_port were swapped. */ uint16_t start_port; @@ -627,7 +611,7 @@ struct Tox_Options { uint16_t tcp_port; /** - * Enables or disables UDP hole-punching in toxcore. (Default: enabled). + * Enables or disables UDP hole-punching. (Default: enabled). */ bool hole_punching_enabled; @@ -639,8 +623,8 @@ struct Tox_Options { /** * The savedata. * - * The data pointed at by this member is owned by the user, so must - * outlive the options object. + * The data pointed at by this member is owned by the user, so must outlive + * the options object. */ const uint8_t *savedata_data; @@ -650,7 +634,7 @@ struct Tox_Options { size_t savedata_length; /** - * Logging callback for the new tox instance. + * Logging callback for the new Tox instance. */ tox_log_cb *log_callback; @@ -673,14 +657,9 @@ struct Tox_Options { bool experimental_thread_safety; /** - * Low level operating system functionality such as send/recv, random - * number generation, and memory allocation. - */ - const Tox_System *operating_system; - - /** - * Enable saving DHT-based group chats to Tox save data (via `tox_get_savedata`). - * This format will change in the future, so don't rely on it. + * Enable saving DHT-based group chats to Tox save data (via + * `tox_get_savedata`). This format will change in the future, so don't rely + * on it. * * As an alternative, clients can save the group chat ID in client-owned * savedata. Then, when the client starts, it can use `tox_group_join` @@ -759,10 +738,6 @@ bool tox_options_get_experimental_thread_safety(const Tox_Options *options); void tox_options_set_experimental_thread_safety(Tox_Options *options, bool experimental_thread_safety); -const Tox_System *tox_options_get_operating_system(const Tox_Options *options); - -void tox_options_set_operating_system(Tox_Options *options, const Tox_System *operating_system); - bool tox_options_get_experimental_groups_persistence(const Tox_Options *options); void tox_options_set_experimental_groups_persistence(Tox_Options *options, bool experimental_groups_persistence); @@ -837,15 +812,16 @@ typedef enum Tox_Err_New { TOX_ERR_NEW_NULL, /** - * The function was unable to allocate enough memory to store the events_alloc - * structures for the Tox object. + * The function was unable to allocate enough memory to store the + * internal structures for the Tox object. */ TOX_ERR_NEW_MALLOC, /** * The function was unable to bind to a port. This may mean that all ports * have already been bound, e.g. by other Tox instances, or it may mean - * a permission error. You may be able to gather more information from errno. + * a permission error. You may be able to gather more information from + * errno. */ TOX_ERR_NEW_PORT_ALLOC, @@ -913,7 +889,7 @@ Tox *tox_new(const Tox_Options *options, Tox_Err_New *error); void tox_kill(Tox *tox); /** - * @brief Calculates the number of bytes required to store the tox instance with + * @brief Calculates the number of bytes required to store the Tox instance with * tox_get_savedata. * * This function cannot fail. The result is always greater than 0. @@ -923,11 +899,12 @@ void tox_kill(Tox *tox); size_t tox_get_savedata_size(const Tox *tox); /** - * @brief Store all information associated with the tox instance to a byte array. + * @brief Store all information associated with the Tox instance to a byte + * array. * - * @param savedata A memory region large enough to store the tox instance - * data. Call tox_get_savedata_size to find the number of bytes required. If this parameter - * is NULL, this function has no effect. + * @param savedata A memory region large enough to store the Tox instance + * data. Call tox_get_savedata_size to find the number of bytes required. If + * this parameter is NULL, this function has no effect. */ void tox_get_savedata(const Tox *tox, uint8_t savedata[]); @@ -1065,14 +1042,16 @@ typedef void tox_self_connection_status_cb(Tox *tox, Tox_Connection connection_s void tox_callback_self_connection_status(Tox *tox, tox_self_connection_status_cb *callback); /** - * @brief Return the time in milliseconds before `tox_iterate()` should be called again - * for optimal performance. + * @brief Return the time in milliseconds before `tox_iterate()` should be + * called again for optimal performance. */ uint32_t tox_iteration_interval(const Tox *tox); /** - * @brief The main loop that needs to be run in intervals of `tox_iteration_interval()` - * milliseconds. + * @brief The main loop that needs to be run in intervals of + * `tox_iteration_interval()` milliseconds. + * @param user_data Any pointer a client wishes the Tox instance to pass into + * the event callbacks, including NULL. */ void tox_iterate(Tox *tox, void *user_data); @@ -1172,7 +1151,8 @@ const char *tox_err_set_info_to_string(Tox_Err_Set_Info value); bool tox_self_set_name(Tox *tox, const uint8_t name[], size_t length, Tox_Err_Set_Info *error); /** - * @brief Return the length of the current nickname as passed to tox_self_set_name. + * @brief Return the length of the current nickname as passed to + * tox_self_set_name. * * If no nickname was set before calling this function, the name is empty, * and this function returns 0. @@ -1206,7 +1186,8 @@ bool tox_self_set_status_message( Tox *tox, const uint8_t status_message[], size_t length, Tox_Err_Set_Info *error); /** - * @brief Return the length of the current status message as passed to tox_self_set_status_message. + * @brief Return the length of the current status message as passed to + * tox_self_set_status_message. * * If no status message was set before calling this function, the status * is empty, and this function returns 0. @@ -1216,13 +1197,14 @@ bool tox_self_set_status_message( size_t tox_self_get_status_message_size(const Tox *tox); /** - * @brief Write the status message set by tox_self_set_status_message to a byte array. + * @brief Write the status message set by tox_self_set_status_message to a byte + * array. * * If no status message was set before calling this function, the status is * empty, and this function has no effect. * - * Call tox_self_get_status_message_size to find out how much memory to allocate for - * the result. + * Call tox_self_get_status_message_size to find out how much memory to allocate + * for the result. * * @param status_message A valid memory location large enough to hold the * status message. If this parameter is NULL, the function has no effect. @@ -1279,8 +1261,8 @@ typedef enum Tox_Err_Friend_Add { TOX_ERR_FRIEND_ADD_OWN_KEY, /** - * A friend request has already been sent, or the address belongs to a friend - * that is already on the friend list. + * A friend request has already been sent, or the address belongs to a + * friend that is already on the friend list. */ TOX_ERR_FRIEND_ADD_ALREADY_SENT, @@ -1360,7 +1342,8 @@ typedef enum Tox_Err_Friend_Delete { TOX_ERR_FRIEND_DELETE_OK, /** - * There was no friend with the given friend number. No friends were deleted. + * There was no friend with the given friend number. No friends were + * deleted. */ TOX_ERR_FRIEND_DELETE_FRIEND_NOT_FOUND, @@ -1411,14 +1394,15 @@ const char *tox_err_friend_by_public_key_to_string(Tox_Err_Friend_By_Public_Key /** * @brief Return the friend number associated with that Public Key. * - * @return the friend number on success, an unspecified value on failure. * @param public_key A byte array containing the Public Key. + * + * @return the friend number on success, an unspecified value on failure. */ Tox_Friend_Number tox_friend_by_public_key(const Tox *tox, const uint8_t public_key[TOX_PUBLIC_KEY_SIZE], Tox_Err_Friend_By_Public_Key *error); /** - * @brief Checks if a friend with the given friend number exists and returns true if - * it does. + * @brief Checks if a friend with the given friend number exists and returns + * true if it does. */ bool tox_friend_exists(const Tox *tox, Tox_Friend_Number friend_number); @@ -1433,7 +1417,8 @@ size_t tox_self_get_friend_list_size(const Tox *tox); /** * @brief Copy a list of valid friend numbers into an array. * - * Call tox_self_get_friend_list_size to determine the number of elements to allocate. + * Call tox_self_get_friend_list_size to determine the number of elements to + * allocate. * * @param friend_list A memory region with enough space to hold the friend * list. If this parameter is NULL, this function has no effect. @@ -1457,7 +1442,8 @@ typedef enum Tox_Err_Friend_Get_Public_Key { const char *tox_err_friend_get_public_key_to_string(Tox_Err_Friend_Get_Public_Key value); /** - * @brief Copies the Public Key associated with a given friend number to a byte array. + * @brief Copies the Public Key associated with a given friend number to a byte + * array. * * @param friend_number The friend number you want the Public Key of. * @param public_key A memory region of at least TOX_PUBLIC_KEY_SIZE bytes. If @@ -1486,8 +1472,8 @@ typedef enum Tox_Err_Friend_Get_Last_Online { const char *tox_err_friend_get_last_online_to_string(Tox_Err_Friend_Get_Last_Online value); /** - * @brief Return a unix-time timestamp of the last time the friend associated with a given - * friend number was seen online. + * @brief Return a unix-time timestamp of the last time the friend associated + * with a given friend number was seen online. * * This function will return UINT64_MAX on error. * @@ -1514,8 +1500,9 @@ typedef enum Tox_Err_Friend_Query { /** * The pointer parameter for storing the query result (name, message) was - * NULL. Unlike the `_self_` variants of these functions, which have no effect - * when a parameter is NULL, these functions return an error in that case. + * NULL. Unlike the `_self_` variants of these functions, which have no + * effect when a parameter is NULL, these functions return an error in that + * case. */ TOX_ERR_FRIEND_QUERY_NULL, @@ -1540,8 +1527,8 @@ size_t tox_friend_get_name_size( const Tox *tox, Tox_Friend_Number friend_number, Tox_Err_Friend_Query *error); /** - * @brief Write the name of the friend designated by the given friend number to a byte - * array. + * @brief Write the name of the friend designated by the given friend number to + * a byte array. * * Call tox_friend_get_name_size to determine the allocation size for the `name` * parameter. @@ -1579,22 +1566,23 @@ void tox_callback_friend_name(Tox *tox, tox_friend_name_cb *callback); /** * @brief Return the length of the friend's status message. * - * If the friend number isinvalid, the return value is SIZE_MAX. + * If the friend number is invalid, the return value is SIZE_MAX. */ size_t tox_friend_get_status_message_size( const Tox *tox, Tox_Friend_Number friend_number, Tox_Err_Friend_Query *error); /** - * @brief Write the status message of the friend designated by the given friend number to a byte - * array. + * @brief Write the status message of the friend designated by the given friend + * number to a byte array. * - * Call tox_friend_get_status_message_size to determine the allocation size for the `status_message` - * parameter. + * Call tox_friend_get_status_message_size to determine the allocation size for + * the `status_message` parameter. * - * The data written to `status_message` is equal to the data received by the last - * `friend_status_message` callback. + * The data written to `status_message` is equal to the data received by the + * last `friend_status_message` callback. * - * @param status_message A valid memory region large enough to store the friend's status message. + * @param status_message A valid memory region large enough to store the + * friend's status message. */ bool tox_friend_get_status_message( const Tox *tox, Tox_Friend_Number friend_number, uint8_t status_message[], @@ -1604,7 +1592,8 @@ bool tox_friend_get_status_message( * @param friend_number The friend number of the friend whose status message * changed. * @param message A byte array containing the same data as - * tox_friend_get_status_message would write to its `status_message` parameter. + * tox_friend_get_status_message would write to its `status_message` + * parameter. * @param length A value equal to the return value of * tox_friend_get_status_message_size. */ @@ -1814,7 +1803,8 @@ typedef uint32_t Tox_Friend_Message_Id; * then reassemble the fragments. Messages may not be empty. * * The return value of this function is the message ID. If a read receipt is - * received, the triggered `friend_read_receipt` event will be passed this message ID. + * received, the triggered `friend_read_receipt` event will be passed this + * message ID. * * Message IDs are unique per friend. The first message ID is 0. Message IDs are * incremented by 1 each time a message is sent. If UINT32_MAX messages were @@ -1831,7 +1821,8 @@ Tox_Friend_Message_Id tox_friend_send_message( const uint8_t message[], size_t length, Tox_Err_Friend_Send_Message *error); /** - * @param friend_number The friend number of the friend who received the message. + * @param friend_number The friend number of the friend who received the + * message. * @param message_id The message ID as returned from tox_friend_send_message * corresponding to the message sent. */ @@ -1875,6 +1866,7 @@ void tox_callback_friend_request(Tox *tox, tox_friend_request_cb *callback); /** * @param friend_number The friend number of the friend who sent the message. + * @param type The type of the message (normal, action, ...). * @param message The message data they sent. * @param length The size of the message byte array. */ @@ -1906,10 +1898,10 @@ typedef uint32_t Tox_File_Number; * primarily for validating cached avatars. This use is highly recommended to * avoid unnecessary avatar updates. * - * If hash is NULL or data is NULL while length is not 0 the function returns false, - * otherwise it returns true. + * If hash is NULL or data is NULL while length is not 0 the function returns + * false, otherwise it returns true. * - * This function is a wrapper to events_alloc message-digest functions. + * This function is a wrapper to internal message-digest functions. * * @param hash A valid memory location the hash data. It must be at least * TOX_HASH_LENGTH bytes in size. @@ -1923,17 +1915,17 @@ bool tox_hash(uint8_t hash[TOX_HASH_LENGTH], const uint8_t data[], size_t length /** * @brief A list of pre-defined file kinds. * - * Toxcore itself does not behave differently for different file kinds. These - * are a hint to the client telling it what use the sender intended for the - * file. The `kind` parameter in the send function and recv callback are + * The Tox library itself does not behave differently for different file kinds. + * These are a hint to the client telling it what use the sender intended for + * the file. The `kind` parameter in the send function and recv callback are * `uint32_t`, not Tox_File_Kind, because clients can invent their own file * kind. Unknown file kinds should be treated as TOX_FILE_KIND_DATA. */ enum Tox_File_Kind { /** - * Arbitrary file data. Clients can choose to handle it based on the file name - * or magic or any other way they choose. + * Arbitrary file data. Clients can choose to handle it based on the file + * name or magic or any other way they choose. */ TOX_FILE_KIND_DATA, @@ -1941,21 +1933,21 @@ enum Tox_File_Kind { * Avatar file_id. This consists of tox_hash(image). * Avatar data. This consists of the image data. * - * Avatars can be sent at any time the client wishes. Generally, a client will - * send the avatar to a friend when that friend comes online, and to all - * friends when the avatar changed. A client can save some traffic by - * remembering which friend received the updated avatar already and only send - * it if the friend has an out of date avatar. + * Avatars can be sent at any time the client wishes. Generally, a client + * will send the avatar to a friend when that friend comes online, and to + * all friends when the avatar changed. A client can save some traffic by + * remembering which friend received the updated avatar already and only + * send it if the friend has an out of date avatar. * * Clients who receive avatar send requests can reject it (by sending * TOX_FILE_CONTROL_CANCEL before any other controls), or accept it (by - * sending TOX_FILE_CONTROL_RESUME). The file_id of length TOX_HASH_LENGTH bytes - * (same length as TOX_FILE_ID_LENGTH) will contain the hash. A client can compare - * this hash with a saved hash and send TOX_FILE_CONTROL_CANCEL to terminate the avatar - * transfer if it matches. + * sending TOX_FILE_CONTROL_RESUME). The file_id of length TOX_HASH_LENGTH + * bytes (same length as TOX_FILE_ID_LENGTH) will contain the hash. A client + * can compare this hash with a saved hash and send TOX_FILE_CONTROL_CANCEL + * to terminate the avatar transfer if it matches. * - * When file_size is set to 0 in the transfer request it means that the client - * has no avatar. + * When file_size is set to 0 in the transfer request it means that the + * client has no avatar. */ TOX_FILE_KIND_AVATAR, @@ -1964,16 +1956,17 @@ enum Tox_File_Kind { typedef enum Tox_File_Control { /** - * Sent by the receiving side to accept a file send request. Also sent after a - * TOX_FILE_CONTROL_PAUSE command to continue sending or receiving. + * Sent by the receiving side to accept a file send request. Also sent after + * a TOX_FILE_CONTROL_PAUSE command to continue sending or receiving. */ TOX_FILE_CONTROL_RESUME, /** * Sent by clients to pause the file transfer. The initial state of a file - * transfer is always paused on the receiving side and running on the sending - * side. If both the sending and receiving side pause the transfer, then both - * need to send TOX_FILE_CONTROL_RESUME for the transfer to resume. + * transfer is always paused on the receiving side and running on the + * sending side. If both the sending and receiving side pause the transfer, + * then both need to send TOX_FILE_CONTROL_RESUME for the transfer to + * resume. */ TOX_FILE_CONTROL_PAUSE, @@ -2005,7 +1998,8 @@ typedef enum Tox_Err_File_Control { TOX_ERR_FILE_CONTROL_FRIEND_NOT_CONNECTED, /** - * No file transfer with the given file number was found for the given friend. + * No file transfer with the given file number was found for the given + * friend. */ TOX_ERR_FILE_CONTROL_NOT_FOUND, @@ -2089,7 +2083,8 @@ typedef enum Tox_Err_File_Seek { TOX_ERR_FILE_SEEK_FRIEND_NOT_CONNECTED, /** - * No file transfer with the given file number was found for the given friend. + * No file transfer with the given file number was found for the given + * friend. */ TOX_ERR_FILE_SEEK_NOT_FOUND, @@ -2113,7 +2108,8 @@ typedef enum Tox_Err_File_Seek { const char *tox_err_file_seek_to_string(Tox_Err_File_Seek value); /** - * @brief Sends a file seek control command to a friend for a given file transfer. + * @brief Sends a file seek control command to a friend for a given file + * transfer. * * This function can only be called to resume a file transfer right before * TOX_FILE_CONTROL_RESUME is sent. @@ -2144,7 +2140,8 @@ typedef enum Tox_Err_File_Get { TOX_ERR_FILE_GET_FRIEND_NOT_FOUND, /** - * No file transfer with the given file number was found for the given friend. + * No file transfer with the given file number was found for the given + * friend. */ TOX_ERR_FILE_GET_NOT_FOUND, @@ -2158,8 +2155,8 @@ const char *tox_err_file_get_to_string(Tox_Err_File_Get value); * @param friend_number The friend number of the friend the file is being * transferred to or received from. * @param file_number The friend-specific identifier for the file transfer. - * @param file_id A memory region of at least TOX_FILE_ID_LENGTH bytes. If - * this parameter is NULL, this function has no effect. + * @param file_id A memory region of at least TOX_FILE_ID_LENGTH bytes. If this + * parameter is NULL, this function has no effect. * * @return true on success. */ @@ -2202,8 +2199,8 @@ typedef enum Tox_Err_File_Send { TOX_ERR_FILE_SEND_NAME_TOO_LONG, /** - * Too many ongoing transfers. The maximum number of concurrent file transfers - * is 256 per friend per direction (sending and receiving). + * Too many ongoing transfers. The maximum number of concurrent file + * transfers is 256 per friend per direction (sending and receiving). */ TOX_ERR_FILE_SEND_TOO_MANY, @@ -2214,8 +2211,8 @@ const char *tox_err_file_send_to_string(Tox_Err_File_Send value); /** * @brief Send a file transmission request. * - * Maximum filename length is TOX_MAX_FILENAME_LENGTH bytes. The filename - * should generally just be a file name, not a path with directory names. + * Maximum filename length is TOX_MAX_FILENAME_LENGTH bytes. The filename should + * generally just be a file name, not a path with directory names. * * If a non-UINT64_MAX file size is provided, it can be used by both sides to * determine the sending progress. File size can be set to UINT64_MAX for @@ -2224,8 +2221,8 @@ const char *tox_err_file_send_to_string(Tox_Err_File_Send value); * File transmission occurs in chunks, which are requested through the * `file_chunk_request` event. * - * When a friend goes offline, all file transfers associated with the friend are - * purged from core. + * When a friend goes offline, all file transfers associated with the friend get + * purged. * * If the file contents change during a transfer, the behaviour is unspecified * in general. What will actually happen depends on the mode in which the file @@ -2234,15 +2231,16 @@ const char *tox_err_file_send_to_string(Tox_Err_File_Send value); * - If the file size was increased * - and sending mode was streaming (file_size = UINT64_MAX), the behaviour * will be as expected. - * - and sending mode was file (file_size != UINT64_MAX), the file_chunk_request - * callback will receive length = 0 when Core thinks the file transfer has - * finished. If the client remembers the file size as it was when sending the - * request, it will terminate the transfer normally. If the client re-reads the - * size, it will think the friend cancelled the transfer. + * - and sending mode was file (file_size != UINT64_MAX), the + * file_chunk_request callback will receive length = 0 when Tox thinks the + * file transfer has finished. If the client remembers the file size as it + * was when sending the request, it will terminate the transfer normally. If + * the client re-reads the size, it will think the friend cancelled the + * transfer. * - If the file size was decreased * - and sending mode was streaming, the behaviour is as expected. * - and sending mode was file, the callback will return 0 at the new - * (earlier) end-of-file, signalling to the friend that the transfer was + * (earlier) end-of-file, signaling to the friend that the transfer was * cancelled. * - If the file contents were modified * - at a position before the current read, the two files (local and remote) @@ -2255,19 +2253,20 @@ const char *tox_err_file_send_to_string(Tox_Err_File_Send value); * @param friend_number The friend number of the friend the file send request * should be sent to. * @param kind The meaning of the file to be sent. - * @param file_size Size in bytes of the file the client wants to send, UINT64_MAX if - * unknown or streaming. - * @param file_id A file identifier of length TOX_FILE_ID_LENGTH that can be used to - * uniquely identify file transfers across core restarts. If NULL, a random one will - * be generated by core. It can then be obtained by using `tox_file_get_file_id()`. + * @param file_size Size in bytes of the file the client wants to send, + * UINT64_MAX if unknown or streaming. + * @param file_id A file identifier of length TOX_FILE_ID_LENGTH that can be + * used to uniquely identify file transfers across Tox restarts. If NULL, a + * random one will be generated by the library. It can then be obtained by + * using `tox_file_get_file_id()`. * @param filename Name of the file. Does not need to be the actual name. This * name will be sent along with the file send request. * @param filename_length Size in bytes of the filename. * * @return A file number used as an identifier in subsequent callbacks. This * number is per friend. File numbers are reused after a transfer terminates. - * On failure, this function returns an unspecified value. Any pattern in file numbers - * should not be relied on. + * On failure, this function returns an unspecified value. Any pattern in file + * numbers should not be relied on. */ Tox_File_Number tox_file_send( Tox *tox, Tox_Friend_Number friend_number, uint32_t kind, uint64_t file_size, @@ -2297,20 +2296,23 @@ typedef enum Tox_Err_File_Send_Chunk { TOX_ERR_FILE_SEND_CHUNK_FRIEND_NOT_CONNECTED, /** - * No file transfer with the given file number was found for the given friend. + * No file transfer with the given file number was found for the given + * friend. */ TOX_ERR_FILE_SEND_CHUNK_NOT_FOUND, /** * File transfer was found but isn't in a transferring state: (paused, done, - * broken, etc...) (happens only when not called from the request chunk callback). + * broken, etc...) (happens only when not called from the request chunk + * callback). */ TOX_ERR_FILE_SEND_CHUNK_NOT_TRANSFERRING, /** - * Attempted to send more or less data than requested. The requested data size is - * adjusted according to maximum transmission unit and the expected end of - * the file. Trying to send less or more than requested will return this error. + * Attempted to send more or less data than requested. The requested data + * size is adjusted according to maximum transmission unit and the expected + * end of the file. Trying to send less or more than requested will return + * this error. */ TOX_ERR_FILE_SEND_CHUNK_INVALID_LENGTH, @@ -2334,10 +2336,11 @@ const char *tox_err_file_send_chunk_to_string(Tox_Err_File_Send_Chunk value); * This function is called in response to the `file_chunk_request` callback. The * length parameter should be equal to the one received though the callback. * If it is zero, the transfer is assumed complete. For files with known size, - * Core will know that the transfer is complete after the last byte has been + * Tox will know that the transfer is complete after the last byte has been * received, so it is not necessary (though not harmful) to send a zero-length - * chunk to terminate. For streams, core will know that the transfer is finished - * if a chunk with length less than the length requested in the callback is sent. + * chunk to terminate. For streams, Tox will know that the transfer is finished + * if a chunk with length less than the length requested in the callback is + * sent. * * @param friend_number The friend number of the receiving friend for this file. * @param file_number The file transfer identifier returned by tox_file_send. @@ -2379,7 +2382,7 @@ typedef void tox_file_chunk_request_cb( * * Pass NULL to unset. * - * This event is triggered when Core is ready to send more file data. + * This event is triggered when Tox is ready to send more file data. */ void tox_callback_file_chunk_request(Tox *tox, tox_file_chunk_request_cb *callback); @@ -2466,7 +2469,8 @@ typedef uint32_t Tox_Conference_Offline_Peer_Number; typedef enum Tox_Conference_Type { /** - * Text-only conferences that must be accepted with the tox_conference_join function. + * Text-only conferences that must be accepted with the tox_conference_join + * function. */ TOX_CONFERENCE_TYPE_TEXT, @@ -2503,7 +2507,8 @@ typedef void tox_conference_invite_cb( void tox_callback_conference_invite(Tox *tox, tox_conference_invite_cb *callback); /** - * @param conference_number The conference number of the conference to which we have connected. + * @param conference_number The conference number of the conference to which we + * have connected. */ typedef void tox_conference_connected_cb(Tox *tox, Tox_Conference_Number conference_number, void *user_data); @@ -2556,7 +2561,8 @@ typedef void tox_conference_title_cb( * * This event is triggered when a peer changes the conference title. * - * If peer_number == UINT32_MAX, then author is unknown (e.g. initial joining the conference). + * If peer_number == UINT32_MAX, then author is unknown (e.g. initial joining + * the conference). */ void tox_callback_conference_title(Tox *tox, tox_conference_title_cb *callback); @@ -2641,7 +2647,8 @@ const char *tox_err_conference_delete_to_string(Tox_Err_Conference_Delete value) /** * @brief This function deletes a conference. * - * @param conference_number The conference number of the conference to be deleted. + * @param conference_number The conference number of the conference to be + * deleted. * * @return true on success. */ @@ -2698,7 +2705,8 @@ size_t tox_conference_peer_get_name_size( /** * @brief Copy the name of peer_number who is in conference_number to name. * - * Call tox_conference_peer_get_name_size to determine the allocation size for the `name` parameter. + * Call tox_conference_peer_get_name_size to determine the allocation size for + * the `name` parameter. * * @param name A valid memory region large enough to store the peer's name. * @@ -2709,7 +2717,8 @@ bool tox_conference_peer_get_name( uint8_t name[], Tox_Err_Conference_Peer_Query *error); /** - * @brief Copy the public key of peer_number who is in conference_number to public_key. + * @brief Copy the public key of peer_number who is in conference_number to + * public_key. * * public_key must be TOX_PUBLIC_KEY_SIZE long. * @@ -2748,7 +2757,8 @@ size_t tox_conference_offline_peer_get_name_size( Tox_Conference_Offline_Peer_Number offline_peer_number, Tox_Err_Conference_Peer_Query *error); /** - * @brief Copy the name of offline_peer_number who is in conference_number to name. + * @brief Copy the name of offline_peer_number who is in conference_number to + * name. * * Call tox_conference_offline_peer_get_name_size to determine the allocation * size for the `name` parameter. @@ -2762,7 +2772,8 @@ bool tox_conference_offline_peer_get_name( uint8_t name[], Tox_Err_Conference_Peer_Query *error); /** - * @brief Copy the public key of offline_peer_number who is in conference_number to public_key. + * @brief Copy the public key of offline_peer_number who is in conference_number + * to public_key. * * public_key must be TOX_PUBLIC_KEY_SIZE long. * @@ -2773,7 +2784,8 @@ bool tox_conference_offline_peer_get_public_key( Tox_Conference_Offline_Peer_Number offline_peer_number, uint8_t public_key[TOX_PUBLIC_KEY_SIZE], Tox_Err_Conference_Peer_Query *error); /** - * @brief Return a unix-time timestamp of the last time offline_peer_number was seen to be active. + * @brief Return a unix-time timestamp of the last time offline_peer_number was + * seen to be active. */ uint64_t tox_conference_offline_peer_get_last_active( const Tox *tox, Tox_Conference_Number conference_number, @@ -2832,7 +2844,8 @@ const char *tox_err_conference_invite_to_string(Tox_Err_Conference_Invite value) * @brief Invites a friend to a conference. * * @param friend_number The friend number of the friend we want to invite. - * @param conference_number The conference number of the conference we want to invite the friend to. + * @param conference_number The conference number of the conference we want to + * invite the friend to. * * @return true on success. */ @@ -2853,7 +2866,8 @@ typedef enum Tox_Err_Conference_Join { TOX_ERR_CONFERENCE_JOIN_INVALID_LENGTH, /** - * The conference is not the expected type. This indicates an invalid cookie. + * The conference is not the expected type. This indicates an invalid + * cookie. */ TOX_ERR_CONFERENCE_JOIN_WRONG_TYPE, @@ -2888,7 +2902,7 @@ const char *tox_err_conference_join_to_string(Tox_Err_Conference_Join value); * to it until a handshaking procedure has been completed. A * `conference_connected` event will then occur for the conference. The client * will then remain connected to the conference until the conference is deleted, - * even across core restarts. Many operations on a conference will fail with a + * even across Tox restarts. Many operations on a conference will fail with a * corresponding error if attempted on a conference to which the client is not * yet connected. * @@ -2996,9 +3010,11 @@ size_t tox_conference_get_title_size( const Tox *tox, Tox_Conference_Number conference_number, Tox_Err_Conference_Title *error); /** - * @brief Write the title designated by the given conference number to a byte array. + * @brief Write the title designated by the given conference number to a byte + * array. * - * Call tox_conference_get_title_size to determine the allocation size for the `title` parameter. + * Call tox_conference_get_title_size to determine the allocation size for the + * `title` parameter. * * The data written to `title` is equal to the data received by the last * `conference_title` callback. @@ -3014,7 +3030,8 @@ bool tox_conference_get_title( Tox_Err_Conference_Title *error); /** - * @brief Set the conference title and broadcast it to the rest of the conference. + * @brief Set the conference title and broadcast it to the rest of the + * conference. * * Title length cannot be longer than TOX_MAX_NAME_LENGTH. * @@ -3028,7 +3045,8 @@ bool tox_conference_set_title( /** * @brief Return the number of conferences in the Tox instance. * - * This should be used to determine how much memory to allocate for `tox_conference_get_chatlist`. + * This should be used to determine how much memory to allocate for + * `tox_conference_get_chatlist`. */ size_t tox_conference_get_chatlist_size(const Tox *tox); @@ -3038,8 +3056,8 @@ size_t tox_conference_get_chatlist_size(const Tox *tox); * Determine how much space to allocate for the array with the * `tox_conference_get_chatlist_size` function. * - * Note that `tox_get_savedata` saves all connected conferences; - * when toxcore is created from savedata in which conferences were saved, those + * Note that `tox_get_savedata` saves all connected conferences; when a Tox + * instance is created from savedata in which conferences were saved, those * conferences will be connected at startup, and will be listed by * `tox_conference_get_chatlist`. * @@ -3049,7 +3067,8 @@ size_t tox_conference_get_chatlist_size(const Tox *tox); void tox_conference_get_chatlist(const Tox *tox, Tox_Conference_Number chatlist[]); /** - * @brief Returns the type of conference (Tox_Conference_Type) that conference_number is. + * @brief Returns the type of conference (Tox_Conference_Type) that + * conference_number is. * * Return value is unspecified on failure. */ @@ -3124,10 +3143,12 @@ Tox_Conference_Number tox_conference_by_id( * * If uid is NULL, this function has no effect. * - * @param uid A memory region large enough to store TOX_CONFERENCE_UID_SIZE bytes. + * @param uid A memory region large enough to store TOX_CONFERENCE_UID_SIZE + * bytes. * * @return true on success. - * @deprecated use tox_conference_get_id instead (exactly the same function, just renamed). + * @deprecated use tox_conference_get_id instead (exactly the same function, + * just renamed). */ bool tox_conference_get_uid( const Tox *tox, Tox_Conference_Number conference_number, uint8_t uid[TOX_CONFERENCE_UID_SIZE]); @@ -3156,10 +3177,12 @@ const char *tox_err_conference_by_uid_to_string(Tox_Err_Conference_By_Uid value) /** * @brief Return the conference number associated with the specified uid. * - * @param uid A byte array containing the conference id (TOX_CONFERENCE_UID_SIZE). + * @param uid A byte array containing the conference id + * (TOX_CONFERENCE_UID_SIZE). * * @return the conference number on success, an unspecified value on failure. - * @deprecated use tox_conference_by_id instead (exactly the same function, just renamed). + * @deprecated use tox_conference_by_id instead (exactly the same function, + * just renamed). */ Tox_Conference_Number tox_conference_by_uid( const Tox *tox, const uint8_t uid[TOX_CONFERENCE_UID_SIZE], Tox_Err_Conference_By_Uid *error); @@ -3193,8 +3216,9 @@ typedef enum Tox_Err_Friend_Custom_Packet { TOX_ERR_FRIEND_CUSTOM_PACKET_FRIEND_NOT_CONNECTED, /** - * The first byte of data was not in the specified range for the packet type. - * This range is 192-254 for lossy, and 69, 160-191 for lossless packets. + * The first byte of data was not in the specified range for the packet + * type. This range is 192-254 for lossy, and 69, 160-191 for lossless + * packets. */ TOX_ERR_FRIEND_CUSTOM_PACKET_INVALID, @@ -3323,7 +3347,8 @@ const char *tox_err_get_port_to_string(Tox_Err_Get_Port value); * @brief Writes the temporary DHT public key of this instance to a byte array. * * This can be used in combination with an externally accessible IP address and - * the bound port (from tox_self_get_udp_port) to run a temporary bootstrap node. + * the bound port (from tox_self_get_udp_port) to run a temporary bootstrap + * node. * * Be aware that every time a new instance is created, the DHT public key * changes, meaning this cannot be used to run a permanent bootstrap node. @@ -3436,22 +3461,24 @@ uint32_t tox_group_peer_public_key_size(void); typedef enum Tox_Group_Privacy_State { /** - * The group is considered to be public. Anyone may join the group using the Chat ID. + * The group is considered to be public. Anyone may join the group using + * the Chat ID. * - * If the group is in this state, even if the Chat ID is never explicitly shared - * with someone outside of the group, information including the Chat ID, IP addresses, - * and peer ID's (but not Tox ID's) is visible to anyone with access to a node - * storing a DHT entry for the given group. + * If the group is in this state, even if the Chat ID is never explicitly + * shared with someone outside of the group, information including the Chat + * ID, IP addresses, and peer ID's (but not Tox ID's) is visible to anyone + * with access to a node storing a DHT entry for the given group. */ TOX_GROUP_PRIVACY_STATE_PUBLIC, /** - * The group is considered to be private. The only way to join the group is by having - * someone in your contact list send you an invite. + * The group is considered to be private. The only way to join the group is + * by having someone in your contact list send you an invite. * - * If the group is in this state, no group information (mentioned above) is present in the DHT; - * the DHT is not used for any purpose at all. If a public group is set to private, - * all DHT information related to the group will expire shortly. + * If the group is in this state, no group information (mentioned above) is + * present in the DHT; the DHT is not used for any purpose at all. If a + * public group is set to private, all DHT information related to the group + * will expire shortly. */ TOX_GROUP_PRIVACY_STATE_PRIVATE, @@ -3461,16 +3488,20 @@ const char *tox_group_privacy_state_to_string(Tox_Group_Privacy_State value); /** * Represents the state of the group topic lock. + * + * The default is enabled. */ typedef enum Tox_Group_Topic_Lock { /** - * The topic lock is enabled. Only peers with the founder and moderator roles may set the topic. + * The topic lock is enabled. Only peers with the founder and moderator + * roles may set the topic. */ TOX_GROUP_TOPIC_LOCK_ENABLED, /** - * The topic lock is disabled. All peers except those with the observer role may set the topic. + * The topic lock is disabled. All peers except those with the observer role + * may set the topic. */ TOX_GROUP_TOPIC_LOCK_DISABLED, @@ -3479,8 +3510,9 @@ typedef enum Tox_Group_Topic_Lock { const char *tox_group_topic_lock_to_string(Tox_Group_Topic_Lock value); /** - * Represents the group voice state, which determines which Group Roles have permission to speak - * in the group chat. The voice state does not have any effect private messages or topic setting. + * Represents the group voice state, which determines which Group Roles have + * permission to speak in the group chat. The voice state does not have any + * effect private messages or topic setting. */ typedef enum Tox_Group_Voice_State { /** @@ -3504,14 +3536,15 @@ const char *tox_group_voice_state_to_string(Tox_Group_Voice_State value); /** * Represents group roles. * - * Roles are hierarchical in that each role has a set of privileges plus all the privileges - * of the roles below it. + * Roles are hierarchical in that each role has a set of privileges plus all the + * privileges of the roles below it. */ typedef enum Tox_Group_Role { /** - * May kick all other peers as well as set their role to anything (except founder). - * Founders may also set the group password, toggle the privacy state, and set the peer limit. + * May kick all other peers as well as set their role to anything (except + * founder). Founders may also set the group password, toggle the privacy + * state, and set the peer limit. */ TOX_GROUP_ROLE_FOUNDER, @@ -3527,7 +3560,8 @@ typedef enum Tox_Group_Role { TOX_GROUP_ROLE_USER, /** - * May observe the group and ignore peers; may not communicate with other peers or with the group. + * May observe the group and ignore peers; may not communicate with other + * peers or with the group. */ TOX_GROUP_ROLE_OBSERVER, @@ -3549,7 +3583,8 @@ typedef enum Tox_Err_Group_New { TOX_ERR_GROUP_NEW_OK, /** - * name exceeds TOX_MAX_NAME_LENGTH or group_name exceeded TOX_GROUP_MAX_GROUP_NAME_LENGTH. + * name exceeds TOX_MAX_NAME_LENGTH or group_name exceeded + * TOX_GROUP_MAX_GROUP_NAME_LENGTH. */ TOX_ERR_GROUP_NEW_TOO_LONG, @@ -3564,13 +3599,14 @@ typedef enum Tox_Err_Group_New { TOX_ERR_GROUP_NEW_INIT, /** - * The group state failed to initialize. This usually indicates that something went wrong - * related to cryptographic signing. + * The group state failed to initialize. This usually indicates that + * something went wrong related to cryptographic signing. */ TOX_ERR_GROUP_NEW_STATE, /** - * The group failed to announce to the DHT. This indicates a network related error. + * The group failed to announce to the DHT. This indicates a network related + * error. */ TOX_ERR_GROUP_NEW_ANNOUNCE, @@ -3585,18 +3621,19 @@ const char *tox_err_group_new_to_string(Tox_Err_Group_New value); * * The caller of this function has Founder role privileges. * - * The client should initiate its peer list with self info after calling this function, as - * the peer_join callback will not be triggered. + * The client should initiate its peer list with self info after calling this + * function, as the peer_join callback will not be triggered. * - * @param privacy_state The privacy state of the group. If this is set to TOX_GROUP_PRIVACY_STATE_PUBLIC, - * the group will attempt to announce itself to the DHT and anyone with the Chat ID may join. - * Otherwise a friend invite will be required to join the group. + * @param privacy_state The privacy state of the group. If this is set to + * TOX_GROUP_PRIVACY_STATE_PUBLIC, the group will attempt to announce itself + * to the DHT and anyone with the Chat ID may join. Otherwise a friend invite + * will be required to join the group. * @param group_name The name of the group. The name must be non-NULL. - * @param group_name_length The length of the group name. This must be greater than zero and no larger than - * TOX_GROUP_MAX_GROUP_NAME_LENGTH. + * @param group_name_length The length of the group name. This must be greater + * than zero and no larger than TOX_GROUP_MAX_GROUP_NAME_LENGTH. * @param name The name of the peer creating the group. - * @param name_length The length of the peer's name. This must be greater than zero and no larger - * than TOX_MAX_NAME_LENGTH. + * @param name_length The length of the peer's name. This must be greater than + * zero and no larger than TOX_MAX_NAME_LENGTH. * * @return group_number on success, UINT32_MAX on failure. */ @@ -3618,8 +3655,9 @@ typedef enum Tox_Err_Group_Join { TOX_ERR_GROUP_JOIN_INIT, /** - * The chat_id pointer is set to NULL or a group with chat_id already exists. This usually - * happens if the client attempts to create multiple sessions for the same group. + * The chat_id pointer is set to NULL or a group with chat_id already + * exists. This usually happens if the client attempts to create multiple + * sessions for the same group. */ TOX_ERR_GROUP_JOIN_BAD_CHAT_ID, @@ -3634,7 +3672,8 @@ typedef enum Tox_Err_Group_Join { TOX_ERR_GROUP_JOIN_TOO_LONG, /** - * Failed to set password. This usually occurs if the password exceeds TOX_GROUP_MAX_PASSWORD_SIZE. + * Failed to set password. This usually occurs if the password exceeds + * TOX_GROUP_MAX_PASSWORD_SIZE. */ TOX_ERR_GROUP_JOIN_PASSWORD, @@ -3650,17 +3689,20 @@ const char *tox_err_group_join_to_string(Tox_Err_Group_Join value); /** * Joins a group chat with specified Chat ID. * - * This function creates a new group chat object, adds it to the chats array, and sends - * a DHT announcement to find peers in the group associated with chat_id. Once a peer has been - * found a join attempt will be initiated. + * This function creates a new group chat object, adds it to the chats array, + * and sends a DHT announcement to find peers in the group associated with + * chat_id. Once a peer has been found a join attempt will be initiated. * - * @param chat_id The Chat ID of the group you wish to join. This must be TOX_GROUP_CHAT_ID_SIZE bytes. - * @param password The password required to join the group. Set to NULL if no password is required. - * @param password_length The length of the password. If length is equal to zero, - * the password parameter is ignored. length must be no larger than TOX_GROUP_MAX_PASSWORD_SIZE. + * @param chat_id The Chat ID of the group you wish to join. This must be + * TOX_GROUP_CHAT_ID_SIZE bytes. + * @param password The password required to join the group. Set to NULL if no + * password is required. + * @param password_length The length of the password. If length is equal to + * zero, the password parameter is ignored. length must be no larger than + * TOX_GROUP_MAX_PASSWORD_SIZE. * @param name The name of the peer joining the group. - * @param name_length The length of the peer's name. This must be greater than zero and no larger - * than TOX_MAX_NAME_LENGTH. + * @param name_length The length of the peer's name. This must be greater than + * zero and no larger than TOX_MAX_NAME_LENGTH. * * @return group_number on success, UINT32_MAX on failure. */ @@ -3687,8 +3729,8 @@ typedef enum Tox_Err_Group_Is_Connected { const char *tox_err_group_is_connected_to_string(Tox_Err_Group_Is_Connected value); /** - * Returns true if the group chat is currently connected or attempting to connect to other peers - * in the group. + * Returns true if the group chat is currently connected or attempting to + * connect to other peers in the group. * * @param group_number The group number of the designated group. */ @@ -3715,7 +3757,8 @@ typedef enum Tox_Err_Group_Disconnect { const char *tox_err_group_disconnect_to_string(Tox_Err_Group_Disconnect value); /** - * Disconnects from a group chat while retaining the group state and credentials. + * Disconnects from a group chat while retaining the group state and + * credentials. * * Returns true if we successfully disconnect from the group. * @@ -3747,8 +3790,9 @@ const char *tox_err_group_reconnect_to_string(Tox_Err_Group_Reconnect value); /** * Reconnects to a group. * - * This function disconnects from all peers in the group, then attempts to reconnect with the group. - * The caller's state is not changed (i.e. name, status, role, chat public key etc.). + * This function disconnects from all peers in the group, then attempts to + * reconnect with the group. The caller's state is not changed (i.e. name, + * status, role, chat public key etc.). * * @param group_number The group number of the group we wish to reconnect to. * @@ -3784,14 +3828,16 @@ const char *tox_err_group_leave_to_string(Tox_Err_Group_Leave value); /** * Leaves a group. * - * This function sends a parting packet containing a custom (non-obligatory) message to all - * peers in a group, and deletes the group from the chat array. All group state information is permanently - * lost, including keys and role credentials. + * This function sends a parting packet containing a custom (non-obligatory) + * message to all peers in a group, and deletes the group from the chat array. + * All group state information is permanently lost, including keys and role + * credentials. * * @param group_number The group number of the group we wish to leave. - * @param part_message The parting message to be sent to all the peers. Set to NULL if we do not wish to - * send a parting message. - * @param length The length of the parting message. Set to 0 if we do not wish to send a parting message. + * @param part_message The parting message to be sent to all the peers. Set to + * NULL if we do not wish to send a parting message. + * @param length The length of the parting message. Set to 0 if we do not wish + * to send a parting message. * * @return true if the group chat instance is successfully deleted. */ @@ -3860,10 +3906,11 @@ typedef enum Tox_Err_Group_Self_Name_Set { const char *tox_err_group_self_name_set_to_string(Tox_Err_Group_Self_Name_Set value); /** - * Set the client's nickname for the group instance designated by the given group number. + * Set the client's nickname for the group instance designated by the given + * group number. * - * Nickname length cannot exceed TOX_MAX_NAME_LENGTH. If length is equal to zero or name is a NULL - * pointer, the function call will fail. + * Nickname length cannot exceed TOX_MAX_NAME_LENGTH. If length is equal to + * zero or name is a NULL pointer, the function call will fail. * * @param name A byte array containing the new nickname. * @param length The size of the name byte array. @@ -3876,8 +3923,8 @@ bool tox_group_self_set_name( Tox_Err_Group_Self_Name_Set *error); /** - * Return the length of the client's current nickname for the group instance designated - * by group_number as passed to tox_group_self_set_name. + * Return the length of the client's current nickname for the group instance + * designated by group_number as passed to tox_group_self_set_name. * * If no nickname was set before calling this function, the name is empty, * and this function returns 0. @@ -3892,7 +3939,8 @@ size_t tox_group_self_get_name_size(const Tox *tox, Tox_Group_Number group_numbe * If no nickname was set before calling this function, the name is empty, * and this function has no effect. * - * Call tox_group_self_get_name_size to find out how much memory to allocate for the result. + * Call tox_group_self_get_name_size to find out how much memory to allocate for + * the result. * * @param name A valid memory location large enough to hold the nickname. * If this parameter is NULL, the function has no effect. @@ -3928,7 +3976,8 @@ typedef enum Tox_Err_Group_Self_Status_Set { const char *tox_err_group_self_status_set_to_string(Tox_Err_Group_Self_Status_Set value); /** - * Set the client's status for the group instance. Status must be a Tox_User_Status. + * Set the client's status for the group instance. Status must be a + * Tox_User_Status. * * @return true on success. */ @@ -3954,13 +4003,16 @@ Tox_Group_Role tox_group_self_get_role(const Tox *tox, Tox_Group_Number group_nu Tox_Group_Peer_Number tox_group_self_get_peer_id(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_Self_Query *error); /** - * Write the client's group public key designated by the given group number to a byte array. + * Write the client's group public key designated by the given group number to + * a byte array. * - * This key will be permanently tied to the client's identity for this particular group until - * the client explicitly leaves the group. This key is the only way for other peers to reliably - * identify the client across client restarts. + * This key will be permanently tied to the client's identity for this + * particular group until the client explicitly leaves the group. This key is + * the only way for other peers to reliably identify the client across client + * restarts. * - * `public_key` should have room for at least TOX_GROUP_PEER_PUBLIC_KEY_SIZE bytes. + * `public_key` should have room for at least TOX_GROUP_PEER_PUBLIC_KEY_SIZE + * bytes. * * @param public_key A valid memory region large enough to store the public key. * If this parameter is NULL, this function call has no effect. @@ -4001,8 +4053,8 @@ typedef enum Tox_Err_Group_Peer_Query { const char *tox_err_group_peer_query_to_string(Tox_Err_Group_Peer_Query value); /** - * Return the length of the peer's name. If the group number or ID is invalid, the - * return value is unspecified. + * Return the length of the peer's name. If the group number or ID is invalid, + * the return value is unspecified. * * @param group_number The group number of the group we wish to query. * @param peer_id The ID of the peer whose name length we want to retrieve. @@ -4017,7 +4069,8 @@ size_t tox_group_peer_get_name_size(const Tox *tox, Tox_Group_Number group_numbe * Write the name of the peer designated by the given ID to a byte * array. * - * Call tox_group_peer_get_name_size to determine the allocation size for the `name` parameter. + * Call tox_group_peer_get_name_size to determine the allocation size for the + * `name` parameter. * * The data written to `name` is equal to the data received by the last * `group_peer_name` callback. @@ -4046,8 +4099,8 @@ Tox_User_Status tox_group_peer_get_status(const Tox *tox, Tox_Group_Number group Tox_Err_Group_Peer_Query *error); /** - * Return the peer's role (user/moderator/founder...). If the ID or group number is - * invalid, the return value is unspecified. + * Return the peer's role (user/moderator/founder...). If the ID or group number + * is invalid, the return value is unspecified. * * @param group_number The group number of the group we wish to query. * @param peer_id The ID of the peer whose role we wish to query. @@ -4061,8 +4114,9 @@ Tox_Group_Role tox_group_peer_get_role(const Tox *tox, Tox_Group_Number group_nu /** * Return the type of connection we have established with a peer. * - * If `peer_id` designates ourself, the return value indicates whether we're capable - * of making UDP connections with other peers, or are limited to TCP connections. + * If `peer_id` designates ourself, the return value indicates whether we're + * capable of making UDP connections with other peers, or are limited to TCP + * connections. * * @param group_number The group number of the group we wish to query. * @param peer_id The ID of the peer whose connection status we wish to query. @@ -4071,13 +4125,15 @@ Tox_Connection tox_group_peer_get_connection_status(const Tox *tox, Tox_Group_Nu Tox_Err_Group_Peer_Query *error); /** - * Write the group public key with the designated peer_id for the designated group number to public_key. + * Write the group public key with the designated peer_id for the designated + * group number to public_key. * - * This key will be permanently tied to a particular peer until they explicitly leave the group and is - * the only way to reliably identify the same peer across client restarts. + * This key will be permanently tied to a particular peer until they explicitly + * leave the group and is the only way to reliably identify the same peer across + * client restarts. * - * `public_key` should have room for at least TOX_GROUP_PEER_PUBLIC_KEY_SIZE bytes. If `public_key` is null - * this function has no effect. + * `public_key` should have room for at least TOX_GROUP_PEER_PUBLIC_KEY_SIZE + * bytes. If `public_key` is NULL this function has no effect. * * @param group_number The group number of the group we wish to query. * @param peer_id The ID of the peer whose public key we wish to retrieve. @@ -4091,7 +4147,8 @@ bool tox_group_peer_get_public_key( uint8_t public_key[TOX_PUBLIC_KEY_SIZE], Tox_Err_Group_Peer_Query *error); /** - * @param group_number The group number of the group the name change is intended for. + * @param group_number The group number of the group the name change is intended + * for. * @param peer_id The ID of the peer who has changed their name. * @param name The name data. * @param name_length The length of the name. @@ -4108,7 +4165,8 @@ typedef void tox_group_peer_name_cb( void tox_callback_group_peer_name(Tox *tox, tox_group_peer_name_cb *callback); /** - * @param group_number The group number of the group the status change is intended for. + * @param group_number The group number of the group the status change is + * intended for. * @param peer_id The ID of the peer who has changed their status. * @param status The new status of the peer. */ @@ -4173,7 +4231,8 @@ typedef enum Tox_Err_Group_Topic_Set { TOX_ERR_GROUP_TOPIC_SET_PERMISSIONS, /** - * The packet could not be created. This error is usually related to cryptographic signing. + * The packet could not be created. This error is usually related to + * cryptographic signing. */ TOX_ERR_GROUP_TOPIC_SET_FAIL_CREATE, @@ -4194,8 +4253,8 @@ const char *tox_err_group_topic_set_to_string(Tox_Err_Group_Topic_Set value); /** * Set the group topic and broadcast it to the rest of the group. * - * topic length cannot be longer than TOX_GROUP_MAX_TOPIC_LENGTH. If length is equal to zero or - * topic is set to NULL, the topic will be unset. + * Topic length cannot be longer than TOX_GROUP_MAX_TOPIC_LENGTH. If the length + * is equal to zero or topic is set to NULL, the topic will be unset. * * @return true on success. */ @@ -4216,7 +4275,8 @@ size_t tox_group_get_topic_size(const Tox *tox, Tox_Group_Number group_number, T /** * Write the topic designated by the given group number to a byte array. * - * Call tox_group_get_topic_size to determine the allocation size for the `topic` parameter. + * Call tox_group_get_topic_size to determine the allocation size for the + * `topic` parameter. * * The data written to `topic` is equal to the data received by the last * `group_topic` callback. @@ -4231,9 +4291,10 @@ bool tox_group_get_topic( uint8_t topic[], Tox_Err_Group_State_Query *error); /** - * @param group_number The group number of the group the topic change is intended for. - * @param peer_id The ID of the peer who changed the topic. If the peer who set the topic - * is not present in our peer list this value will be set to 0. + * @param group_number The group number of the group the topic change is + * intended for. + * @param peer_id The ID of the peer who changed the topic. If the peer who set + * the topic is not present in our peer list this value will be set to 0. * @param topic The topic data. * @param topic_length The topic length. */ @@ -4256,9 +4317,11 @@ void tox_callback_group_topic(Tox *tox, tox_group_topic_cb *callback); size_t tox_group_get_name_size(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_State_Query *error); /** - * Write the name of the group designated by the given group number to a byte array. + * Write the name of the group designated by the given group number to a byte + * array. * - * Call tox_group_get_name_size to determine the allocation size for the `name` parameter. + * Call tox_group_get_name_size to determine the allocation size for the `name` + * parameter. * * @param name A valid memory region large enough to store the group name. * If this parameter is NULL, this function call has no effect. @@ -4289,19 +4352,21 @@ bool tox_group_get_chat_id( uint32_t tox_group_get_number_groups(const Tox *tox); /** - * Return the privacy state of the group designated by the given group number. If group number - * is invalid, the return value is unspecified. + * Return the privacy state of the group designated by the given group number. + * If group number is invalid, the return value is unspecified. * * The value returned is equal to the data received by the last * `group_privacy_state` callback. * - * @see the `Group chat founder controls` section for the respective set function. + * @see the `Group chat Founder controls` section for the respective set + * function. */ Tox_Group_Privacy_State tox_group_get_privacy_state(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_State_Query *error); /** - * @param group_number The group number of the group the privacy state is intended for. + * @param group_number The group number of the group the privacy state is + * intended for. * @param privacy_state The new privacy state. */ typedef void tox_group_privacy_state_cb(Tox *tox, Tox_Group_Number group_number, Tox_Group_Privacy_State privacy_state, @@ -4315,18 +4380,21 @@ typedef void tox_group_privacy_state_cb(Tox *tox, Tox_Group_Number group_number, void tox_callback_group_privacy_state(Tox *tox, tox_group_privacy_state_cb *callback); /** - * Return the voice state of the group designated by the given group number. If group number - * is invalid, the return value is unspecified. + * Return the voice state of the group designated by the given group number. If + * group number is invalid, the return value is unspecified. * - * The value returned is equal to the data received by the last `group_voice_state` callback. + * The value returned is equal to the data received by the last + * `group_voice_state` callback. * - * @see the `Group chat founder controls` section for the respective set function. + * @see the `Group chat Founder controls` section for the respective set + * function. */ Tox_Group_Voice_State tox_group_get_voice_state(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_State_Query *error); /** - * @param group_number The group number of the group the voice state change is intended for. + * @param group_number The group number of the group the voice state change is + * intended for. * @param voice_state The new voice state. */ typedef void tox_group_voice_state_cb(Tox *tox, Tox_Group_Number group_number, Tox_Group_Voice_State voice_state, @@ -4340,19 +4408,22 @@ typedef void tox_group_voice_state_cb(Tox *tox, Tox_Group_Number group_number, T void tox_callback_group_voice_state(Tox *tox, tox_group_voice_state_cb *callback); /** - * Return the topic lock status of the group designated by the given group number. If group number + * Return the topic lock status of the group designated by the given group + * number. If group number * is invalid, the return value is unspecified. * * The value returned is equal to the data received by the last * `group_topic_lock` callback. * - * @see the `Group chat founder contols` section for the respective set function. + * @see the `Group chat Founder controls` section for the respective set + * function. */ Tox_Group_Topic_Lock tox_group_get_topic_lock(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_State_Query *error); /** - * @param group_number The group number of the group for which the topic lock has changed. + * @param group_number The group number of the group for which the topic lock + * has changed. * @param topic_lock The new topic lock state. */ typedef void tox_group_topic_lock_cb(Tox *tox, Tox_Group_Number group_number, Tox_Group_Topic_Lock topic_lock, void *user_data); @@ -4365,18 +4436,21 @@ typedef void tox_group_topic_lock_cb(Tox *tox, Tox_Group_Number group_number, To void tox_callback_group_topic_lock(Tox *tox, tox_group_topic_lock_cb *callback); /** - * Return the maximum number of peers allowed for the group designated by the given group number. - * If the group number is invalid, the return value is unspecified. + * Return the maximum number of peers allowed for the group designated by the + * given group number. If the group number is invalid, the return value is + * unspecified. * * The value returned is equal to the data received by the last * `group_peer_limit` callback. * - * @see the `Group chat founder controls` section for the respective set function. + * @see the `Group chat Founder controls` section for the respective set + * function. */ uint16_t tox_group_get_peer_limit(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_State_Query *error); /** - * @param group_number The group number of the group for which the peer limit has changed. + * @param group_number The group number of the group for which the peer limit + * has changed. * @param peer_limit The new peer limit for the group. */ typedef void tox_group_peer_limit_cb(Tox *tox, Tox_Group_Number group_number, uint32_t peer_limit, void *user_data); @@ -4384,7 +4458,8 @@ typedef void tox_group_peer_limit_cb(Tox *tox, Tox_Group_Number group_number, ui /** * Set the callback for the `group_peer_limit` event. Pass NULL to unset. * - * This event is triggered when the group founder changes the maximum peer limit. + * This event is triggered when the group founder changes the maximum peer + * limit. */ void tox_callback_group_peer_limit(Tox *tox, tox_group_peer_limit_cb *callback); @@ -4395,17 +4470,20 @@ void tox_callback_group_peer_limit(Tox *tox, tox_group_peer_limit_cb *callback); size_t tox_group_get_password_size(const Tox *tox, Tox_Group_Number group_number, Tox_Err_Group_State_Query *error); /** - * Write the password for the group designated by the given group number to a byte array. + * Write the password for the group designated by the given group number to a + * byte array. * - * Call tox_group_get_password_size to determine the allocation size for the `password` parameter. + * Call tox_group_get_password_size to determine the allocation size for the + * `password` parameter. * - * The data received is equal to the data received by the last - * `group_password` callback. + * The data received is equal to the data received by the last `group_password` + * callback. * - * @see the `Group chat Founder controls` section for the respective set function. + * @see the `Group chat Founder controls` section for the respective set + * function. * - * @param password A valid memory region large enough to store the group password. - * If this parameter is NULL, this function call has no effect. + * @param password A valid memory region large enough to store the group + * password. If this parameter is NULL, this function call has no effect. * * @return true on success. */ @@ -4414,7 +4492,8 @@ bool tox_group_get_password( Tox_Err_Group_State_Query *error); /** - * @param group_number The group number of the group for which the password has changed. + * @param group_number The group number of the group for which the password has + * changed. * @param password The new group password. * @param password_length The length of the password. */ @@ -4454,7 +4533,7 @@ typedef enum Tox_Err_Group_Send_Message { TOX_ERR_GROUP_SEND_MESSAGE_TOO_LONG, /** - * The message pointer is null or length is zero. + * The message pointer is NULL or length is zero. */ TOX_ERR_GROUP_SEND_MESSAGE_EMPTY, @@ -4488,11 +4567,12 @@ const char *tox_err_group_send_message_to_string(Tox_Err_Group_Send_Message valu * This function creates a group message packet and pushes it into the send * queue. * - * The message length may not exceed TOX_GROUP_MAX_MESSAGE_LENGTH. Larger messages - * must be split by the client and sent as separate messages. Other clients can - * then reassemble the fragments. Messages may not be empty. + * The message length may not exceed TOX_GROUP_MAX_MESSAGE_LENGTH. Larger + * messages must be split by the client and sent as separate messages. Other + * clients can then reassemble the fragments. Messages may not be empty. * - * @param group_number The group number of the group the message is intended for. + * @param group_number The group number of the group the message is intended + * for. * @param message_type Message type (normal, action, ...). * @param message A non-NULL pointer to the first element of a byte array * containing the message text. @@ -4529,7 +4609,7 @@ typedef enum Tox_Err_Group_Send_Private_Message { TOX_ERR_GROUP_SEND_PRIVATE_MESSAGE_TOO_LONG, /** - * The message pointer is null or length is zero. + * The message pointer is NULL or length is zero. */ TOX_ERR_GROUP_SEND_PRIVATE_MESSAGE_EMPTY, @@ -4560,14 +4640,15 @@ const char *tox_err_group_send_private_message_to_string(Tox_Err_Group_Send_Priv /** * Send a text chat message to the specified peer in the specified group. * - * This function creates a group private message packet and pushes it into the send - * queue. + * This function creates a group private message packet and pushes it into the + * send queue. * - * The message length may not exceed TOX_GROUP_MAX_MESSAGE_LENGTH. Larger messages - * must be split by the client and sent as separate messages. Other clients can - * then reassemble the fragments. Messages may not be empty. + * The message length may not exceed TOX_GROUP_MAX_MESSAGE_LENGTH. Larger + * messages must be split by the client and sent as separate messages. Other + * clients can then reassemble the fragments. Messages may not be empty. * - * @param group_number The group number of the group the message is intended for. + * @param group_number The group number of the group the message is intended + * for. * @param peer_id The ID of the peer the message is intended for. * @param message_type The type of message (normal, action, ...). * @param message A non-NULL pointer to the first element of a byte array @@ -4601,7 +4682,7 @@ typedef enum Tox_Err_Group_Send_Custom_Packet { TOX_ERR_GROUP_SEND_CUSTOM_PACKET_TOO_LONG, /** - * The message pointer is null or length is zero. + * The message pointer is NULL or length is zero. */ TOX_ERR_GROUP_SEND_CUSTOM_PACKET_EMPTY, @@ -4623,15 +4704,17 @@ const char *tox_err_group_send_custom_packet_to_string(Tox_Err_Group_Send_Custom /** * Send a custom packet to the group. * - * If lossless is true the packet will be lossless. Lossless packet behaviour is comparable - * to TCP (reliability, arrive in order) but with packets instead of a stream. + * If lossless is true the packet will be lossless. Lossless packet behaviour is + * comparable to TCP (reliability, arrive in order) but with packets instead of + * a stream. * - * If lossless is false, the packet will be lossy. Lossy packets behave like UDP packets, - * meaning they might never reach the other side or might arrive more than once (if someone - * is messing with the connection) or might arrive in the wrong order. + * If lossless is false, the packet will be lossy. Lossy packets behave like UDP + * packets, meaning they might never reach the other side or might arrive more + * than once (if someone is messing with the connection) or might arrive in the + * wrong order. * - * Unless latency is an issue or message reliability is not important, it is recommended that you use - * lossless packets. + * Unless latency is an issue or message reliability is not important, it is + * recommended that you use lossless packets. * * The message length may not exceed TOX_MAX_CUSTOM_PACKET_SIZE. Larger packets * must be split by the client and sent as separate packets. Other clients can @@ -4669,7 +4752,7 @@ typedef enum Tox_Err_Group_Send_Custom_Private_Packet { TOX_ERR_GROUP_SEND_CUSTOM_PRIVATE_PACKET_TOO_LONG, /** - * The message pointer is null or length is zero. + * The message pointer is NULL or length is zero. */ TOX_ERR_GROUP_SEND_CUSTOM_PRIVATE_PACKET_EMPTY, @@ -4695,15 +4778,17 @@ const char *tox_err_group_send_custom_private_packet_to_string(Tox_Err_Group_Sen /** * Send a custom private packet to a designated peer in the group. * - * If lossless is true the packet will be lossless. Lossless packet behaviour is comparable - * to TCP (reliability, arrive in order) but with packets instead of a stream. + * If lossless is true the packet will be lossless. Lossless packet behaviour is + * comparable to TCP (reliability, arrive in order) but with packets instead of + * a stream. * - * If lossless is false, the packet will be lossy. Lossy packets behave like UDP packets, - * meaning they might never reach the other side or might arrive more than once (if someone - * is messing with the connection) or might arrive in the wrong order. + * If lossless is false, the packet will be lossy. Lossy packets behave like UDP + * packets, meaning they might never reach the other side or might arrive more + * than once (if someone is messing with the connection) or might arrive in the + * wrong order. * - * Unless latency is an issue or message reliability is not important, it is recommended that you use - * lossless packets. + * Unless latency is an issue or message reliability is not important, it is + * recommended that you use lossless packets. * * The packet length may not exceed TOX_MAX_CUSTOM_PACKET_SIZE. Larger packets * must be split by the client and sent as separate packets. Other clients can @@ -4728,12 +4813,14 @@ bool tox_group_send_custom_private_packet(const Tox *tox, Tox_Group_Number group ******************************************************************************/ /** - * @param group_number The group number of the group the message is intended for. + * @param group_number The group number of the group the message is intended + * for. * @param peer_id The ID of the peer who sent the message. * @param message_type The type of message (normal, action, ...). * @param message The message data. * @param message_length The length of the message. - * @param message_id A pseudo message id that clients can use to uniquely identify this group message. + * @param message_id A pseudo message id that clients can use to uniquely + * identify this group message. */ typedef void tox_group_message_cb( Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_Message_Type message_type, @@ -4747,12 +4834,14 @@ typedef void tox_group_message_cb( void tox_callback_group_message(Tox *tox, tox_group_message_cb *callback); /** - * @param group_number The group number of the group the private message is intended for. + * @param group_number The group number of the group the private message is + * intended for. * @param peer_id The ID of the peer who sent the private message. * @param message_type The type of message (normal, action, ...). * @param message The message data. * @param message_length The length of the message. - * @param message_id A pseudo message id that clients can use to uniquely identify this group message. + * @param message_id A pseudo message id that clients can use to uniquely + * identify this group message. */ typedef void tox_group_private_message_cb( Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, Tox_Message_Type message_type, @@ -4793,7 +4882,8 @@ typedef void tox_group_custom_private_packet_cb( const uint8_t data[], size_t data_length, void *user_data); /** - * Set the callback for the `group_custom_private_packet` event. Pass NULL to unset. + * Set the callback for the `group_custom_private_packet` event. Pass NULL to + * unset. * * This event is triggered when the client receives a custom private packet. */ @@ -4823,7 +4913,8 @@ typedef enum Tox_Err_Group_Invite_Friend { TOX_ERR_GROUP_INVITE_FRIEND_FRIEND_NOT_FOUND, /** - * Creation of the invite packet failed. This indicates a network related error. + * Creation of the invite packet failed. This indicates a network related + * error. */ TOX_ERR_GROUP_INVITE_FRIEND_INVITE_FAIL, @@ -4844,10 +4935,13 @@ const char *tox_err_group_invite_friend_to_string(Tox_Err_Group_Invite_Friend va /** * Invite a friend to a group. * - * This function creates an invite request packet and pushes it to the send queue. + * This function creates an invite request packet and pushes it to the send + * queue. * - * @param group_number The group number of the group the message is intended for. - * @param friend_number The friend number of the friend the invite is intended for. + * @param group_number The group number of the group the message is intended + * for. + * @param friend_number The friend number of the friend the invite is intended + * for. * * @return true on success. */ @@ -4883,14 +4977,15 @@ typedef enum Tox_Err_Group_Invite_Accept { TOX_ERR_GROUP_INVITE_ACCEPT_EMPTY, /** - * Failed to set password. This usually occurs if the password exceeds TOX_GROUP_MAX_PASSWORD_SIZE. + * Failed to set password. This usually occurs if the password exceeds + * TOX_GROUP_MAX_PASSWORD_SIZE. */ TOX_ERR_GROUP_INVITE_ACCEPT_PASSWORD, /** - * There was a core error when initiating the group. + * The friend number passed did not designate a valid friend. */ - TOX_ERR_GROUP_INVITE_ACCEPT_CORE, + TOX_ERR_GROUP_INVITE_ACCEPT_FRIEND_NOT_FOUND, /** * Packet failed to send. @@ -4902,17 +4997,19 @@ typedef enum Tox_Err_Group_Invite_Accept { const char *tox_err_group_invite_accept_to_string(Tox_Err_Group_Invite_Accept value); /** - * Accept an invite to a group chat that the client previously received from a friend. The invite - * is only valid while the inviter is present in the group. + * Accept an invite to a group chat that the client previously received from a + * friend. The invite is only valid while the inviter is present in the group. * * @param invite_data The invite data received from the `group_invite` event. * @param length The length of the invite data. * @param name The name of the peer joining the group. - * @param name_length The length of the peer's name. This must be greater than zero and no larger - * than TOX_MAX_NAME_LENGTH. - * @param password The password required to join the group. Set to NULL if no password is required. - * @param password_length The length of the password. If password_length is equal to zero, the password - * parameter will be ignored. password_length must be no larger than TOX_GROUP_MAX_PASSWORD_SIZE. + * @param name_length The length of the peer's name. This must be greater than + * zero and no larger than TOX_MAX_NAME_LENGTH. + * @param password The password required to join the group. Set to NULL if no + * password is required. + * @param password_length The length of the password. If password_length is + * equal to zero, the password parameter will be ignored. password_length + * must be no larger than TOX_GROUP_MAX_PASSWORD_SIZE. * * @return the group_number on success, UINT32_MAX on failure. */ @@ -4927,6 +5024,8 @@ Tox_Group_Number tox_group_invite_accept( * @param friend_number The friend number of the contact who sent the invite. * @param invite_data The invite data. * @param invite_data_length The length of invite_data. + * @param group_name The name of the group. In conferences, this is "title". + * @param group_name_length The length of the group name. */ typedef void tox_group_invite_cb( Tox *tox, Tox_Friend_Number friend_number, @@ -4937,15 +5036,17 @@ typedef void tox_group_invite_cb( /** * Set the callback for the `group_invite` event. Pass NULL to unset. * - * This event is triggered when the client receives a group invite from a friend. The client must store - * invite_data which is used to join the group via tox_group_invite_accept. + * This event is triggered when the client receives a group invite from a + * friend. The client must store invite_data which is used to join the group + * via tox_group_invite_accept. */ void tox_callback_group_invite(Tox *tox, tox_group_invite_cb *callback); /** - * @param group_number The group number of the group in which a new peer has joined. - * @param peer_id The permanent ID of the new peer. This id should not be relied on for - * client behaviour and should be treated as a random value. + * @param group_number The group number of the group in which a new peer has + * joined. + * @param peer_id The permanent ID of the new peer. This id should not be relied + * on for client behaviour and should be treated as a random value. */ typedef void tox_group_peer_join_cb(Tox *tox, Tox_Group_Number group_number, Tox_Group_Peer_Number peer_id, void *user_data); @@ -4957,7 +5058,8 @@ typedef void tox_group_peer_join_cb(Tox *tox, Tox_Group_Number group_number, Tox void tox_callback_group_peer_join(Tox *tox, tox_group_peer_join_cb *callback); /** - * Represents peer exit events. These should be used with the `group_peer_exit` event. + * Represents peer exit events. These should be used with the `group_peer_exit` + * event. */ typedef enum Tox_Group_Exit_Type { @@ -4977,8 +5079,9 @@ typedef enum Tox_Group_Exit_Type { TOX_GROUP_EXIT_TYPE_DISCONNECTED, /** - * Your connection with all peers has been severed. This will occur when you are kicked from - * a group, rejoin a group, or manually disconnect from a group. + * Your connection with all peers has been severed. This will occur when you + * are kicked from a group, rejoin a group, or manually disconnect from a + * group. */ TOX_GROUP_EXIT_TYPE_SELF_DISCONNECTED, @@ -4998,8 +5101,8 @@ const char *tox_group_exit_type_to_string(Tox_Group_Exit_Type value); /** * @param group_number The group number of the group in which a peer has left. - * @param peer_id The ID of the peer who left the group. This ID no longer designates a valid peer - * and cannot be used for API calls. + * @param peer_id The ID of the peer who left the group. This ID no longer + * designates a valid peer and cannot be used for API calls. * @param exit_type The type of exit event. One of Tox_Group_Exit_Type. * @param name The nickname of the peer who left the group. * @param name_length The length of the peer name. @@ -5026,14 +5129,14 @@ typedef void tox_group_self_join_cb(Tox *tox, Tox_Group_Number group_number, voi /** * Set the callback for the `group_self_join` event. Pass NULL to unset. * - * This event is triggered when the client has successfully joined a group. Use this to initialize - * any group information the client may need. + * This event is triggered when the client has successfully joined a group. Use + * this to initialize any group information the client may need. */ void tox_callback_group_self_join(Tox *tox, tox_group_self_join_cb *callback); /** - * Represents types of failed group join attempts. These are used in the tox_callback_group_rejected - * callback when a peer fails to join a group. + * Represents types of failed group join attempts. These are used in the + * tox_callback_group_rejected callback when a peer fails to join a group. */ typedef enum Tox_Group_Join_Fail { @@ -5048,8 +5151,8 @@ typedef enum Tox_Group_Join_Fail { TOX_GROUP_JOIN_FAIL_INVALID_PASSWORD, /** - * The join attempt failed due to an unspecified error. This often occurs when the group is - * not found in the DHT. + * The join attempt failed due to an unspecified error. This often occurs + * when the group is not found in the DHT. */ TOX_GROUP_JOIN_FAIL_UNKNOWN, @@ -5058,7 +5161,8 @@ typedef enum Tox_Group_Join_Fail { const char *tox_group_join_fail_to_string(Tox_Group_Join_Fail value); /** - * @param group_number The group number of the group for which the join has failed. + * @param group_number The group number of the group for which the join has + * failed. * @param fail_type The type of group rejection. */ typedef void tox_group_join_fail_cb(Tox *tox, Tox_Group_Number group_number, Tox_Group_Join_Fail fail_type, void *user_data); @@ -5120,12 +5224,16 @@ const char *tox_err_group_set_password_to_string(Tox_Err_Group_Set_Password valu /** * Set or unset the group password. * - * This function allows Founders to set or unset a group password. It will create a new - * group shared state including the change and distribute it to the rest of the group. + * This function allows Founders to set or unset a group password. It will + * create a new group shared state including the change and distribute it to the + * rest of the group. * - * @param group_number The group number of the group for which we wish to set the password. - * @param password The password we want to set. Set password to NULL to unset the password. - * @param length The length of the password. length must be no longer than TOX_GROUP_MAX_PASSWORD_SIZE. + * @param group_number The group number of the group for which we wish to set + * the password. + * @param password The password we want to set. Set password to NULL to unset + * the password. + * @param length The length of the password. length must be no longer than + * TOX_GROUP_MAX_PASSWORD_SIZE. * * @return true on success. */ @@ -5157,8 +5265,8 @@ typedef enum Tox_Err_Group_Set_Topic_Lock { TOX_ERR_GROUP_SET_TOPIC_LOCK_PERMISSIONS, /** - * The topic lock could not be set. This may occur due to an error related to - * cryptographic signing of the new shared state. + * The topic lock could not be set. This may occur due to an error related + * to cryptographic signing of the new shared state. */ TOX_ERR_GROUP_SET_TOPIC_LOCK_FAIL_SET, @@ -5179,13 +5287,16 @@ const char *tox_err_group_set_topic_lock_to_string(Tox_Err_Group_Set_Topic_Lock /** * Set the group topic lock state. * - * This function allows Founders to enable or disable the group's topic lock. It will create a - * new shared state including the change and distribute it to the rest of the group. + * This function allows Founders to enable or disable the group's topic lock. It + * will create a new shared state including the change and distribute it to the + * rest of the group. * - * When the topic lock is enabled, only the group founder and moderators may set the topic. - * When disabled, all peers except those with the observer role may set the topic. + * When the topic lock is enabled, only the group founder and moderators may set + * the topic. When disabled, all peers except those with the observer role may + * set the topic. * - * @param group_number The group number of the group for which we wish to change the topic lock state. + * @param group_number The group number of the group for which we wish to change + * the topic lock state. * @param topic_lock The state we wish to set the topic lock to. * * @return true on success. @@ -5206,13 +5317,14 @@ typedef enum Tox_Err_Group_Set_Voice_State { TOX_ERR_GROUP_SET_VOICE_STATE_GROUP_NOT_FOUND, /** - * The caller does not have the required permissions to set the privacy state. + * The caller does not have the required permissions to set the privacy + * state. */ TOX_ERR_GROUP_SET_VOICE_STATE_PERMISSIONS, /** - * The voice state could not be set. This may occur due to an error related to - * cryptographic signing of the new shared state. + * The voice state could not be set. This may occur due to an error related + * to cryptographic signing of the new shared state. */ TOX_ERR_GROUP_SET_VOICE_STATE_FAIL_SET, @@ -5233,13 +5345,16 @@ const char *tox_err_group_set_voice_state_to_string(Tox_Err_Group_Set_Voice_Stat /** * Set the group voice state. * - * This function allows Founders to set the group's voice state. It will create a new group - * shared state including the change and distribute it to the rest of the group. + * This function allows Founders to set the group's voice state. It will create + * a new group shared state including the change and distribute it to the rest + * of the group. * - * If an attempt is made to set the voice state to the same state that the group is already - * in, the function call will be successful and no action will be taken. + * If an attempt is made to set the voice state to the same state that the group + * is already in, the function call will be successful and no action will be + * taken. * - * @param group_number The group number of the group for which we wish to change the voice state. + * @param group_number The group number of the group for which we wish to change + * the voice state. * @param voice_state The voice state we wish to set the group to. * * @return true on success. @@ -5260,13 +5375,14 @@ typedef enum Tox_Err_Group_Set_Privacy_State { TOX_ERR_GROUP_SET_PRIVACY_STATE_GROUP_NOT_FOUND, /** - * The caller does not have the required permissions to set the privacy state. + * The caller does not have the required permissions to set the privacy + * state. */ TOX_ERR_GROUP_SET_PRIVACY_STATE_PERMISSIONS, /** - * The privacy state could not be set. This may occur due to an error related to - * cryptographic signing of the new shared state. + * The privacy state could not be set. This may occur due to an error + * related to cryptographic signing of the new shared state. */ TOX_ERR_GROUP_SET_PRIVACY_STATE_FAIL_SET, @@ -5287,13 +5403,16 @@ const char *tox_err_group_set_privacy_state_to_string(Tox_Err_Group_Set_Privacy_ /** * Set the group privacy state. * - * This function allows Founders to set the group's privacy state. It will create a new group - * shared state including the change and distribute it to the rest of the group. + * This function allows Founders to set the group's privacy state. It will + * create a new group shared state including the change and distribute it to the + * rest of the group. * - * If an attempt is made to set the privacy state to the same state that the group is already - * in, the function call will be successful and no action will be taken. + * If an attempt is made to set the privacy state to the same state that the + * group is already in, the function call will be successful and no action will + * be taken. * - * @param group_number The group number of the group for which we wish to change the privacy state. + * @param group_number The group number of the group for which we wish to change + * the privacy state. * @param privacy_state The privacy state we wish to set the group to. * * @return true on success. @@ -5319,8 +5438,8 @@ typedef enum Tox_Err_Group_Set_Peer_Limit { TOX_ERR_GROUP_SET_PEER_LIMIT_PERMISSIONS, /** - * The peer limit could not be set. This may occur due to an error related to - * cryptographic signing of the new shared state. + * The peer limit could not be set. This may occur due to an error related + * to cryptographic signing of the new shared state. */ TOX_ERR_GROUP_SET_PEER_LIMIT_FAIL_SET, @@ -5341,11 +5460,12 @@ const char *tox_err_group_set_peer_limit_to_string(Tox_Err_Group_Set_Peer_Limit /** * Set the group peer limit. * - * This function allows Founders to set a limit for the number of peers who may be in the - * group. It will create a new group shared state including the change and distribute it to the - * rest of the group. + * This function allows Founders to set a limit for the number of peers who may + * be in the group. It will create a new group shared state including the change + * and distribute it to the rest of the group. * - * @param group_number The group number of the group for which we wish to set the peer limit. + * @param group_number The group number of the group for which we wish to set + * the peer limit. * @param peer_limit The maximum number of peers to allow in the group. * * @return true on success. @@ -5388,7 +5508,8 @@ const char *tox_err_group_set_ignore_to_string(Tox_Err_Group_Set_Ignore value); /** * Ignore or unignore a peer. * - * @param group_number The group number of the group in which you wish to ignore a peer. + * @param group_number The group number of the group in which you wish to ignore + * a peer. * @param peer_id The ID of the peer who shall be ignored or unignored. * @param ignore True to ignore the peer, false to unignore the peer. * @@ -5410,7 +5531,8 @@ typedef enum Tox_Err_Group_Set_Role { TOX_ERR_GROUP_SET_ROLE_GROUP_NOT_FOUND, /** - * The ID passed did not designate a valid peer. Note: you cannot set your own role. + * The ID passed did not designate a valid peer. Note: you cannot set your + * own role. */ TOX_ERR_GROUP_SET_ROLE_PEER_NOT_FOUND, @@ -5420,14 +5542,14 @@ typedef enum Tox_Err_Group_Set_Role { TOX_ERR_GROUP_SET_ROLE_PERMISSIONS, /** - * The role assignment is invalid. This will occur if you try to set a peer's role to - * the role they already have. + * The role assignment is invalid. This will occur if you try to set a + * peer's role to the role they already have. */ TOX_ERR_GROUP_SET_ROLE_ASSIGNMENT, /** - * The role was not successfully set. This may occur if the packet failed to send, or - * if the role limit has been reached. + * The role was not successfully set. This may occur if the packet failed to + * send, or if the role limit has been reached. */ TOX_ERR_GROUP_SET_ROLE_FAIL_ACTION, @@ -5443,15 +5565,17 @@ const char *tox_err_group_set_role_to_string(Tox_Err_Group_Set_Role value); /** * Set a peer's role. * - * This function will first remove the peer's previous role and then assign them a new role. - * It will also send a packet to the rest of the group, requesting that they perform - * the role reassignment. + * This function will first remove the peer's previous role and then assign them + * a new role. It will also send a packet to the rest of the group, requesting + * that they perform the role reassignment. * - * Only Founders may promote peers to the Moderator role, and only Founders and Moderators may - * set peers to the Observer or User role. Moderators may not set the role of other Moderators - * or the Founder. Peers may not be promoted to the Founder role. + * Only Founders may promote peers to the Moderator role, and only Founders and + * Moderators may set peers to the Observer or User role. Moderators may not set + * the role of other Moderators or the Founder. Peers may not be promoted to the + * Founder role. * - * @param group_number The group number of the group the in which you wish set the peer's role. + * @param group_number The group number of the group the in which you wish set + * the peer's role. * @param peer_id The ID of the peer whose role you wish to set. * @param role The role you wish to set the peer to. * @@ -5504,10 +5628,12 @@ const char *tox_err_group_kick_peer_to_string(Tox_Err_Group_Kick_Peer value); /** * Kick a peer. * - * This function allows peers with the Founder or Moderator role to silently instruct - * all other peers in the group to remove a particular peer from their peer list. + * This function allows peers with the Founder or Moderator role to silently + * instruct all other peers in the group to remove a particular peer from their + * peer list. * - * Note: This function will not trigger the `group_peer_exit` event for the caller. + * Note: This function will not trigger the `group_peer_exit` event for the + * caller. * * @param group_number The group number of the group the action is intended for. * @param peer_id The ID of the peer who will be kicked. @@ -5518,7 +5644,8 @@ bool tox_group_kick_peer(const Tox *tox, Tox_Group_Number group_number, Tox_Grou Tox_Err_Group_Kick_Peer *error); /** - * Represents moderation events. These should be used with the `group_moderation` event. + * Represents moderation events. These should be used with the + * `group_moderation` event. */ typedef enum Tox_Group_Mod_Event { @@ -5559,12 +5686,13 @@ typedef void tox_group_moderation_cb( /** * Set the callback for the `group_moderation` event. Pass NULL to unset. * - * This event is triggered when a moderator or founder executes a moderation event, with - * the exception of the peer who initiates the event. It is also triggered when the - * observer and moderator lists are silently modified (this may occur during group syncing). + * This event is triggered when a moderator or founder executes a moderation + * event, with the exception of the peer who initiates the event. It is also + * triggered when the observer and moderator lists are silently modified (this + * may occur during group syncing). * - * If either peer id does not designate a valid peer in the group chat, the client should - * manually update all peer roles. + * If either peer id does not designate a valid peer in the group chat, the + * client should manually update all peer roles. */ void tox_callback_group_moderation(Tox *tox, tox_group_moderation_cb *callback); diff --git a/toxcore/tox_api.c b/toxcore/tox_api.c index d2ac0f59..6d0d9851 100644 --- a/toxcore/tox_api.c +++ b/toxcore/tox_api.c @@ -265,14 +265,6 @@ void tox_options_set_experimental_thread_safety( { options->experimental_thread_safety = experimental_thread_safety; } -const Tox_System *tox_options_get_operating_system(const Tox_Options *options) -{ - return options->operating_system; -} -void tox_options_set_operating_system(Tox_Options *options, const Tox_System *operating_system) -{ - options->operating_system = operating_system; -} bool tox_options_get_experimental_groups_persistence(const Tox_Options *options) { return options->experimental_groups_persistence; @@ -1451,8 +1443,8 @@ const char *tox_err_group_invite_accept_to_string(Tox_Err_Group_Invite_Accept va case TOX_ERR_GROUP_INVITE_ACCEPT_PASSWORD: return "TOX_ERR_GROUP_INVITE_ACCEPT_PASSWORD"; - case TOX_ERR_GROUP_INVITE_ACCEPT_CORE: - return "TOX_ERR_GROUP_INVITE_ACCEPT_CORE"; + case TOX_ERR_GROUP_INVITE_ACCEPT_FRIEND_NOT_FOUND: + return "TOX_ERR_GROUP_INVITE_ACCEPT_FRIEND_NOT_FOUND"; case TOX_ERR_GROUP_INVITE_ACCEPT_FAIL_SEND: return "TOX_ERR_GROUP_INVITE_ACCEPT_FAIL_SEND"; diff --git a/toxcore/tox_dispatch.h b/toxcore/tox_dispatch.h index 2588065a..29ac66a4 100644 --- a/toxcore/tox_dispatch.h +++ b/toxcore/tox_dispatch.h @@ -2,6 +2,13 @@ * Copyright © 2022 The TokTok team. */ +/** + * WARNING: This is an experimental API and is subject to change. + * + * At this point, it probably won't change very much anymore, but we may have + * small breaking changes before a stable release. + */ + #ifndef C_TOXCORE_TOXCORE_TOX_DISPATCH_H #define C_TOXCORE_TOXCORE_TOX_DISPATCH_H diff --git a/toxcore/tox_events.h b/toxcore/tox_events.h index b69683e9..6bbf13e8 100644 --- a/toxcore/tox_events.h +++ b/toxcore/tox_events.h @@ -2,6 +2,13 @@ * Copyright © 2022-2024 The TokTok team. */ +/** + * WARNING: This is an experimental API and is subject to change. + * + * At this point, it probably won't change very much anymore, but we may have + * small breaking changes before a stable release. + */ + #ifndef C_TOXCORE_TOXCORE_TOX_EVENTS_H #define C_TOXCORE_TOXCORE_TOX_EVENTS_H @@ -570,6 +577,8 @@ void tox_events_free(Tox_Events *events); uint32_t tox_events_bytes_size(const Tox_Events *events); bool tox_events_get_bytes(const Tox_Events *events, uint8_t *bytes); +typedef struct Tox_System Tox_System; + Tox_Events *tox_events_load(const Tox_System *sys, const uint8_t *bytes, uint32_t bytes_size); bool tox_events_equal(const Tox_System *sys, const Tox_Events *a, const Tox_Events *b); diff --git a/toxcore/tox_private.h b/toxcore/tox_private.h index d36ab026..fe86479a 100644 --- a/toxcore/tox_private.h +++ b/toxcore/tox_private.h @@ -1,5 +1,5 @@ /* SPDX-License-Identifier: GPL-3.0-or-later - * Copyright © 2016-2020 The TokTok team. + * Copyright © 2016-2024 The TokTok team. * Copyright © 2013 Tox project. */ @@ -18,38 +18,49 @@ extern "C" { typedef uint64_t tox_mono_time_cb(void *user_data); -struct Tox_System { +typedef struct Tox_System { tox_mono_time_cb *mono_time_callback; void *mono_time_user_data; const struct Random *rng; const struct Network *ns; const struct Memory *mem; -}; +} Tox_System; Tox_System tox_default_system(void); +const Tox_System *tox_get_system(Tox *tox); + +typedef struct Tox_Options_Testing { + const struct Tox_System *operating_system; +} Tox_Options_Testing; + +typedef enum Tox_Err_New_Testing { + TOX_ERR_NEW_TESTING_OK, + TOX_ERR_NEW_TESTING_NULL, +} Tox_Err_New_Testing; + +Tox *tox_new_testing(const Tox_Options *options, Tox_Err_New *error, const Tox_Options_Testing *testing, Tox_Err_New_Testing *testing_error); + void tox_lock(const Tox *tox); void tox_unlock(const Tox *tox); -const Tox_System *tox_get_system(Tox *tox); - /** - * Set the callback for the `friend_lossy_packet` event for a specific packet ID. - * Pass NULL to unset. + * Set the callback for the `friend_lossy_packet` event for a specific packet + * ID. Pass NULL to unset. * * allowed packet ID range: - * from `PACKET_ID_RANGE_LOSSY_START` to `PACKET_ID_RANGE_LOSSY_END` (both inclusive) + * from `PACKET_ID_RANGE_LOSSY_START` to `PACKET_ID_RANGE_LOSSY_END` (both + * inclusive) */ void tox_callback_friend_lossy_packet_per_pktid(Tox *tox, tox_friend_lossy_packet_cb *callback, uint8_t pktid); /** - * Set the callback for the `friend_lossless_packet` event for a specific packet ID. - * Pass NULL to unset. + * Set the callback for the `friend_lossless_packet` event for a specific packet + * ID. Pass NULL to unset. * * allowed packet ID range: - * from `PACKET_ID_RANGE_LOSSLESS_CUSTOM_START` to `PACKET_ID_RANGE_LOSSLESS_CUSTOM_END` (both inclusive) - * and - * `PACKET_ID_MSI` + * from `PACKET_ID_RANGE_LOSSLESS_CUSTOM_START` to + * `PACKET_ID_RANGE_LOSSLESS_CUSTOM_END` (both inclusive) and `PACKET_ID_MSI` */ void tox_callback_friend_lossless_packet_per_pktid(Tox *tox, tox_friend_lossless_packet_cb *callback, uint8_t pktid); @@ -78,7 +89,7 @@ uint32_t tox_dht_node_public_key_size(void); /** * @param public_key The node's public key. - * @param ip The node's IP address, represented as a null terminated string. + * @param ip The node's IP address, represented as a NUL-terminated C string. * @param port The node's port. */ typedef void tox_dht_get_nodes_response_cb(Tox *tox, const uint8_t *public_key, const char *ip, uint16_t port, @@ -98,7 +109,8 @@ typedef enum Tox_Err_Dht_Get_Nodes { TOX_ERR_DHT_GET_NODES_OK, /** - * UDP is disabled in tox options; the DHT can only be queried when UDP is enabled. + * UDP is disabled in Tox options; the DHT can only be queried when UDP is + * enabled. */ TOX_ERR_DHT_GET_NODES_UDP_DISABLED, @@ -118,21 +130,24 @@ typedef enum Tox_Err_Dht_Get_Nodes { TOX_ERR_DHT_GET_NODES_BAD_IP, /** - * The getnodes request failed. This usually means the packet failed to send. + * The getnodes request failed. This usually means the packet failed to + * send. */ TOX_ERR_DHT_GET_NODES_FAIL, } Tox_Err_Dht_Get_Nodes; /** * This function sends a getnodes request to a DHT node for its peers that - * are "close" to the passed target public key according to the distance metric used - * by the DHT implementation. + * are "close" to the passed target public key according to the distance metric + * used by the DHT implementation. * - * @param public_key The public key of the node that we wish to query. This key must be - * at least `TOX_DHT_NODE_PUBLIC_KEY_SIZE` bytes in length. - * @param ip A NULL terminated string representing the IP address of the node we wish to query. + * @param public_key The public key of the node that we wish to query. This key + * must be at least `TOX_DHT_NODE_PUBLIC_KEY_SIZE` bytes in length. + * @param ip A NUL-terminated C string representing the IP address of the node + * we wish to query. * @param port The port of the node we wish to query. - * @param target_public_key The public key for which we want to find close nodes. + * @param target_public_key The public key for which we want to find close + * nodes. * * @return true on success. */ @@ -140,8 +155,9 @@ bool tox_dht_get_nodes(const Tox *tox, const uint8_t *public_key, const char *ip const uint8_t *target_public_key, Tox_Err_Dht_Get_Nodes *error); /** - * This function returns the ratio of close dht nodes that are known to support announce/store. - * This function returns the number of DHT nodes in the closelist. + * This function returns the ratio of close dht nodes that are known to support + * announce/store. This function returns the number of DHT nodes in the + * closelist. * * @return number */ @@ -149,7 +165,7 @@ uint16_t tox_dht_get_num_closelist(const Tox *tox); /** * This function returns the number of DHT nodes in the closelist, - * that are capable to store annouce data (introduced in version 0.2.18). + * that are capable to store announce data (introduced in version 0.2.18). * * @return number */ @@ -169,30 +185,32 @@ uint16_t tox_dht_get_num_closelist_announce_capable(const Tox *tox); uint32_t tox_group_peer_ip_string_max_length(void); /** - * Return the length of the peer's IP address in string form. If the group number or ID - * is invalid, the return value is unspecified. + * Return the length of the peer's IP address in string form. If the group + * number or ID is invalid, the return value is unspecified. * * @param group_number The group number of the group we wish to query. - * @param peer_id The ID of the peer whose IP address length we want to retrieve. + * @param peer_id The ID of the peer whose IP address length we want to + * retrieve. */ size_t tox_group_peer_get_ip_address_size(const Tox *tox, uint32_t group_number, uint32_t peer_id, Tox_Err_Group_Peer_Query *error); /** - * Write the IP address associated with the designated peer_id for the designated group number - * to ip_addr. + * Write the IP address associated with the designated peer_id for the + * designated group number to ip_addr. * - * If the peer is forcing TCP connections a placeholder value will be written instead, - * indicating that their real IP address is unknown to us. + * If the peer is forcing TCP connections a placeholder value will be written + * instead, indicating that their real IP address is unknown to us. * - * If `peer_id` designates ourself, it will write either our own IP address or a placeholder value, - * depending on whether or not we're forcing TCP connections. + * If `peer_id` designates ourself, it will write either our own IP address or a + * placeholder value, depending on whether or not we're forcing TCP connections. * - * Call tox_group_peer_get_ip_address_size to determine the allocation size for the `ip_addr` parameter. + * Call tox_group_peer_get_ip_address_size to determine the allocation size for + * the `ip_addr` parameter. * * @param group_number The group number of the group we wish to query. * @param peer_id The ID of the peer whose public key we wish to retrieve. - * @param ip_addr A valid memory region large enough to store the IP address string. - * If this parameter is NULL, this function call has no effect. + * @param ip_addr A valid memory region large enough to store the IP address + * string. If this parameter is NULL, this function call has no effect. * * @return true on success. */ diff --git a/toxencryptsave/toxencryptsave.c b/toxencryptsave/toxencryptsave.c index c43e3575..f3b88770 100644 --- a/toxencryptsave/toxencryptsave.c +++ b/toxencryptsave/toxencryptsave.c @@ -67,7 +67,8 @@ void tox_pass_key_free(Tox_Pass_Key *key) * produce the same key as was previously used. Any data encrypted with this * module can be used as input. * - * The cipher text must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in length. + * The cipher text must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in + * length. * The salt must be TOX_PASS_SALT_LENGTH bytes in length. * If the passed byte arrays are smaller than required, the behaviour is * undefined. @@ -182,10 +183,11 @@ Tox_Pass_Key *tox_pass_key_derive_with_salt( } /** - * Encrypt a plain text with a key produced by tox_pass_key_derive or tox_pass_key_derive_with_salt. + * Encrypt a plain text with a key produced by tox_pass_key_derive or + * tox_pass_key_derive_with_salt. * - * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` - * bytes long. + * The output array must be at least + * `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. * * @param plaintext A byte array of length `plaintext_len`. * @param plaintext_len The length of the plain text array. Bigger than 0. @@ -242,9 +244,9 @@ bool tox_pass_key_encrypt(const Tox_Pass_Key *key, const uint8_t plaintext[], si /** * Encrypts the given data with the given passphrase. * - * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` - * bytes long. This delegates to tox_pass_key_derive and - * tox_pass_key_encrypt. + * The output array must be at least + * `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. This delegates + * to tox_pass_key_derive and tox_pass_key_encrypt. * * @param plaintext A byte array of length `plaintext_len`. * @param plaintext_len The length of the plain text array. Bigger than 0. @@ -280,7 +282,8 @@ bool tox_pass_encrypt(const uint8_t plaintext[], size_t plaintext_len, const uin * tox_pass_key_derive or tox_pass_key_derive_with_salt. * * @param ciphertext A byte array of length `ciphertext_len`. - * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH. + * @param ciphertext_len The length of the cipher text array. At least + * TOX_PASS_ENCRYPTION_EXTRA_LENGTH. * @param plaintext The plain text array to write the decrypted data to. * * @return true on success. @@ -326,11 +329,13 @@ bool tox_pass_key_decrypt(const Tox_Pass_Key *key, const uint8_t ciphertext[], s /** * Decrypts the given data with the given passphrase. * - * The output array must be at least `ciphertext_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH` - * bytes long. This delegates to tox_pass_key_decrypt. + * The output array must be at least + * `ciphertext_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. This + * delegates to tox_pass_key_decrypt. * * @param ciphertext A byte array of length `ciphertext_len`. - * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH. + * @param ciphertext_len The length of the cipher text array. At least + * TOX_PASS_ENCRYPTION_EXTRA_LENGTH. * @param passphrase The user-provided password. Can be empty. * @param passphrase_len The length of the password. * @param plaintext The plain text array to write the decrypted data to. diff --git a/toxencryptsave/toxencryptsave.h b/toxencryptsave/toxencryptsave.h index b9691551..e4cf116c 100644 --- a/toxencryptsave/toxencryptsave.h +++ b/toxencryptsave/toxencryptsave.h @@ -1,5 +1,5 @@ /* SPDX-License-Identifier: GPL-3.0-or-later - * Copyright © 2016-2018 The TokTok team. + * Copyright © 2016-2024 The TokTok team. * Copyright © 2013-2016 Tox Developers. */ @@ -165,9 +165,9 @@ typedef enum Tox_Err_Decryption { /** * Encrypts the given data with the given passphrase. * - * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` - * bytes long. This delegates to tox_pass_key_derive and - * tox_pass_key_encrypt. + * The output array must be at least + * `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. This delegates + * to tox_pass_key_derive and tox_pass_key_encrypt. * * @param plaintext A byte array of length `plaintext_len`. * @param plaintext_len The length of the plain text array. Bigger than 0. @@ -183,11 +183,13 @@ bool tox_pass_encrypt(const uint8_t plaintext[], size_t plaintext_len, const uin /** * Decrypts the given data with the given passphrase. * - * The output array must be at least `ciphertext_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH` - * bytes long. This delegates to tox_pass_key_decrypt. + * The output array must be at least + * `ciphertext_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. This + * delegates to tox_pass_key_decrypt. * * @param ciphertext A byte array of length `ciphertext_len`. - * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH. + * @param ciphertext_len The length of the cipher text array. At least + * TOX_PASS_ENCRYPTION_EXTRA_LENGTH. * @param passphrase The user-provided password. Can be empty. * @param passphrase_len The length of the password. * @param plaintext The plain text array to write the decrypted data to. @@ -215,7 +217,8 @@ bool tox_pass_decrypt(const uint8_t ciphertext[], size_t ciphertext_len, const u * user-provided password. * * The Tox_Pass_Key structure is hidden in the implementation. It can be created - * using tox_pass_key_derive or tox_pass_key_derive_with_salt and must be deallocated using tox_pass_key_free. + * using tox_pass_key_derive or tox_pass_key_derive_with_salt and must be + * deallocated using tox_pass_key_free. */ #ifndef TOX_PASS_KEY_DEFINED #define TOX_PASS_KEY_DEFINED @@ -261,10 +264,11 @@ Tox_Pass_Key *tox_pass_key_derive_with_salt( const uint8_t salt[TOX_PASS_SALT_LENGTH], Tox_Err_Key_Derivation *error); /** - * Encrypt a plain text with a key produced by tox_pass_key_derive or tox_pass_key_derive_with_salt. + * Encrypt a plain text with a key produced by tox_pass_key_derive or + * tox_pass_key_derive_with_salt. * - * The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` - * bytes long. + * The output array must be at least + * `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH` bytes long. * * @param plaintext A byte array of length `plaintext_len`. * @param plaintext_len The length of the plain text array. Bigger than 0. @@ -280,7 +284,8 @@ bool tox_pass_key_encrypt(const Tox_Pass_Key *key, const uint8_t plaintext[], si * tox_pass_key_derive or tox_pass_key_derive_with_salt. * * @param ciphertext A byte array of length `ciphertext_len`. - * @param ciphertext_len The length of the cipher text array. At least TOX_PASS_ENCRYPTION_EXTRA_LENGTH. + * @param ciphertext_len The length of the cipher text array. At least + * TOX_PASS_ENCRYPTION_EXTRA_LENGTH. * @param plaintext The plain text array to write the decrypted data to. * * @return true on success. @@ -315,7 +320,8 @@ typedef enum Tox_Err_Get_Salt { * produce the same key as was previously used. Any data encrypted with this * module can be used as input. * - * The cipher text must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in length. + * The cipher text must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in + * length. * The salt must be TOX_PASS_SALT_LENGTH bytes in length. * If the passed byte arrays are smaller than required, the behaviour is * undefined.