diff --git a/.cirrus.yml b/.cirrus.yml index e0143e4b..b97a8594 100644 --- a/.cirrus.yml +++ b/.cirrus.yml @@ -1,7 +1,7 @@ --- cirrus-ci_task: container: - image: toxchat/toktok-stack:0.0.27-third_party + image: toxchat/toktok-stack:0.0.28-third_party cpu: 2 memory: 2G configure_script: @@ -19,7 +19,7 @@ cirrus-ci_task: cimple_task: container: - image: toxchat/toktok-stack:0.0.27-third_party + image: toxchat/toktok-stack:0.0.28-third_party cpu: 2 memory: 4G configure_script: diff --git a/CMakeLists.txt b/CMakeLists.txt index 91ba63aa..59ed2ffb 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -52,7 +52,6 @@ message("SOVERSION: ${SOVERSION}") # ################################################################################ -include(ApiDsl) include(CTest) include(ModulePackage) include(StrictAbi) @@ -240,7 +239,6 @@ set(toxcore_SOURCES ${toxcore_SOURCES} # LAYER 8: Public API # ------------------- -apidsl(toxcore/tox.api.h) set(toxcore_SOURCES ${toxcore_SOURCES} toxcore/tox_api.c toxcore/tox.c @@ -255,7 +253,6 @@ set(toxcore_API_HEADERS ${toxcore_API_HEADERS} ${toxcore_SOURCE_DIR}/toxcore/tox ################################################################################ if(BUILD_TOXAV) - apidsl(toxav/toxav.api.h) set(toxcore_SOURCES ${toxcore_SOURCES} toxav/audio.c toxav/audio.h @@ -286,7 +283,6 @@ endif() # ################################################################################ -apidsl(toxencryptsave/toxencryptsave.api.h) set(toxcore_SOURCES ${toxcore_SOURCES} toxencryptsave/toxencryptsave.c toxencryptsave/toxencryptsave.h) diff --git a/cmake/ApiDsl.cmake b/cmake/ApiDsl.cmake deleted file mode 100644 index 759f7f05..00000000 --- a/cmake/ApiDsl.cmake +++ /dev/null @@ -1,44 +0,0 @@ -################################################################################ -# -# :: APIDSL regeneration -# -################################################################################ - -find_program(APIDSL NAMES - apidsl - apidsl.native - apidsl.byte - ${CMAKE_SOURCE_DIR}/../apidsl/apigen.native) -find_program(ASTYLE NAMES - astyle - $ENV{ASTYLE}) - -function(apidsl) - if(APIDSL AND ASTYLE) - foreach(in_file ${ARGN}) - # Get the directory component of the input file name. - if(CMAKE_VERSION VERSION_LESS 3.0) - execute_process( - COMMAND dirname ${in_file} - OUTPUT_VARIABLE dirname - OUTPUT_STRIP_TRAILING_WHITESPACE) - else() - get_filename_component(dirname ${in_file} DIRECTORY) - endif() - - # Get the name without extension (i.e. without ".api.h"). - get_filename_component(filename ${in_file} NAME_WE) - - # Put them together, with the new extension that is ".h". - set(out_file ${CMAKE_SOURCE_DIR}/${dirname}/${filename}.h) - - # Run apidsl. - add_custom_command( - OUTPUT ${out_file} - COMMAND "${APIDSL}" "${CMAKE_SOURCE_DIR}/${in_file}" - | "${ASTYLE}" --options="${CMAKE_SOURCE_DIR}/other/astyle/astylerc" - > "${out_file}" - DEPENDS ${in_file}) - endforeach() - endif() -endfunction() diff --git a/other/astyle/format-source b/other/astyle/format-source index effc9cd6..0fd5668a 100755 --- a/other/astyle/format-source +++ b/other/astyle/format-source @@ -4,7 +4,6 @@ set -ex SOURCE_DIR="$1" ASTYLE="$2" -APIDSL="$3" # Go to the source root. if [ -z "$SOURCE_DIR" ]; then @@ -22,62 +21,6 @@ if ! which "$ASTYLE"; then exit 1 fi -if ! which "$APIDSL"; then - if [ -f ../apidsl/apigen.native ]; then - APIDSL=../apidsl/apigen.native - else - APIDSL=apidsl_curl - fi -fi - -TO_JSON='s/\\/\\\\/g;s/\n/\\n/g;s/"/\\"/g;s/^(.*)$/"$1"/' -FROM_JSON='s/\\"/"/g;s/^"(.*)"$/$1/;s/\\\\/\\/g;s/\\n/\n/g' - -apidsl_request() { - TMPFILE=$(mktemp /tmp/apidsl.XXXXXX) - curl -s -o "$TMPFILE" -X POST --data @<( - echo '["Request",' - cat "$2" - echo ']' - ) "https://apidsl.herokuapp.com/$1" - if grep '\[1,"' "$TMPFILE" >/dev/null; then - echo "Error: $(grep -o '".*"' /tmp/apidsl-$$ | perl -0777 -pe "$FROM_JSON")" >&2 - rm "$TMPFILE" - exit 1 - fi - perl -0777 -pe 's/^\[0,(.*)\]$/$1/' "$TMPFILE" - rm "$TMPFILE" -} - -apidsl_curl() { - echo "apidsl_curl $*" >&2 - apidsl_request "c" <( - apidsl_request "parse" <( - perl -0777 -pe "$TO_JSON" "$1" - ) - ) | perl -0777 -pe "$FROM_JSON" -} - -# Check if apidsl generated sources are up to date. -set +x -"$APIDSL" toxcore/tox.api.h >toxcore/tox.h & -"$APIDSL" toxav/toxav.api.h >toxav/toxav.h & -"$APIDSL" toxencryptsave/toxencryptsave.api.h >toxencryptsave/toxencryptsave.h & -set -x - -wait -wait -wait -wait -wait -wait -wait - -if grep '' ./*/*.h; then - echo "error: some apidsl references were unresolved" - exit 1 -fi - readarray -t CC_SOURCES <<<"$(find . '(' -name '*.cc' ')')" CC_SOURCES+=(toxcore/crypto_core.c) CC_SOURCES+=(toxcore/ping_array.c) diff --git a/toxav/BUILD.bazel b/toxav/BUILD.bazel index ef3f5a96..7935b886 100644 --- a/toxav/BUILD.bazel +++ b/toxav/BUILD.bazel @@ -115,7 +115,6 @@ cc_library( "toxav_old.c", ], hdrs = [ - "toxav.api.h", "toxav.h", ], visibility = ["//c-toxcore:__subpackages__"], @@ -125,16 +124,11 @@ cc_library( ], ) -CIMPLE_SRCS = glob( - [ - "*.c", - "*.h", - ], - exclude = ["*.api.h"], -) - sh_library( name = "cimple_files", - srcs = CIMPLE_SRCS, + srcs = glob([ + "*.c", + "*.h", + ]), visibility = ["//c-toxcore/testing:__pkg__"], ) diff --git a/toxav/toxav.api.h b/toxav/toxav.api.h deleted file mode 100644 index aca7e411..00000000 --- a/toxav/toxav.api.h +++ /dev/null @@ -1,746 +0,0 @@ -%{ -/* SPDX-License-Identifier: GPL-3.0-or-later - * Copyright © 2016-2018 The TokTok team. - * Copyright © 2013-2015 Tox project. - */ -#ifndef C_TOXCORE_TOXAV_TOXAV_H -#define C_TOXCORE_TOXAV_TOXAV_H - -#include -#include -#include - -//!TOKSTYLE- - -#ifdef __cplusplus -extern "C" { -#endif -%} - -/** \page av 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. - * - */ - -/** \subsection events Events and callbacks - * - * As in Core 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. - * - */ - -/** \subsection threading Threading implications - * - * Only ${toxAV.iterate} is thread-safe, all other functions must run from the - * 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, - * 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. - * - * 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 multi-threading Separate audio and video threads - * - * ToxAV supports either a single thread for audio and video or decoding and - * encoding them in separate threads. You have to choose one mode and can not - * mix function calls to those different modes. - * - * For best results use the multi-threaded mode and run the audio thread with - * higher priority than the video thread. This prioritizes audio over video. - */ - -/** - * External Tox type. - */ -class tox { - struct this; -} - -/** - * ToxAV. - */ -class toxAV { - -/** - * The ToxAV instance type. 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. - * - */ -struct this; - -/******************************************************************************* - * - * :: Creation and destruction - * - ******************************************************************************/ - - -/** - * Start new A/V session. There can only be only one session per Tox instance. - */ -static this new(tox::this *tox) { - NULL, - /** - * Memory allocation failure while trying to allocate structures required for - * the A/V session. - */ - MALLOC, - /** - * Attempted to create a second session for the same Tox instance. - */ - MULTIPLE, -} - -/** - * Releases all resources associated with the A/V session. - * - * If any calls were ongoing, these will be forcibly terminated without - * notifying peers. After calling this function, no other functions may be - * called and the av pointer becomes invalid. - */ -void kill(); - -/** - * Returns the Tox instance the A/V object was created for. - */ -tox::this *tox { get(); } - - -/******************************************************************************* - * - * :: A/V event loop, single thread - * - ******************************************************************************/ - - -/** - * Returns the interval in milliseconds when the next toxav_iterate call should - * be. If no call is active at the moment, this function returns 200. - * This function MUST be called from the same thread as toxav_iterate. - */ -const uint32_t iteration_interval(); - -/** - * Main loop for the session. This function needs to be called in intervals of - * toxav_iteration_interval() milliseconds. It is best called in the separate - * thread from tox_iterate. - */ -void iterate(); - -/******************************************************************************* - * - * :: A/V event loop, multiple threads - * - ******************************************************************************/ - -/** - * Returns the interval in milliseconds when the next toxav_audio_iterate call - * should be. If no call is active at the moment, this function returns 200. - * This function MUST be called from the same thread as toxav_audio_iterate. - */ -const uint32_t audio_iteration_interval(); - -/** - * Main loop for the session. This function needs to be called in intervals of - * toxav_audio_iteration_interval() milliseconds. It is best called in a - * separate thread from tox_iterate and toxav_video_iterate. The thread calling - * this function should have higher priority than the one calling - * toxav_video_iterate to prioritize audio over video. - */ -void audio_iterate(); - -/** - * Returns the interval in milliseconds when the next toxav_video_iterate call - * should be. If no call is active at the moment, this function returns 200. - * This function MUST be called from the same thread as toxav_video_iterate. - */ -const uint32_t video_iteration_interval(); - -/** - * Main loop for the session. This function needs to be called in intervals of - * toxav_video_iteration_interval() milliseconds. It is best called in a - * separate thread from tox_iterate and toxav_audio_iterate. The thread calling - * this function should have lower priority than the one calling - * toxav_audio_iterate to prioritize audio over video. - */ -void video_iterate(); - -/******************************************************************************* - * - * :: Call setup - * - ******************************************************************************/ - - -/** - * Call a friend. This will start ringing the friend. - * - * It is the client's responsibility to stop ringing after a certain timeout, - * if such behaviour is desired. If the client does not stop ringing, the - * library will not stop until the friend is disconnected. Audio and video - * receiving are both enabled by default. - * - * @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. - * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable - * video sending. - */ -bool call(uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate) { - /** - * A resource allocation error occurred while trying to create the structures - * required for the call. - */ - MALLOC, - /** - * Synchronization error occurred. - */ - SYNC, - /** - * The friend number did not designate a valid friend. - */ - FRIEND_NOT_FOUND, - /** - * The friend was valid, but not currently connected. - */ - FRIEND_NOT_CONNECTED, - /** - * Attempted to call a friend while already in an audio or video call with - * them. - */ - FRIEND_ALREADY_IN_CALL, - /** - * Audio or video bit rate is invalid. - */ - INVALID_BIT_RATE, -} - -event call { - /** - * The function type for the ${event call} callback. - * - * @param friend_number The friend number from which the call is incoming. - * @param audio_enabled True if friend is sending audio. - * @param video_enabled True if friend is sending video. - */ - typedef void(uint32_t friend_number, bool audio_enabled, bool video_enabled); -} - -/** - * Accept an incoming call. - * - * If answering fails for any reason, the call will still be pending and it is - * possible to try and answer it later. Audio and video receiving are both - * enabled by default. - * - * @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. - * @param video_bit_rate Video bit rate in Kb/sec. Set this to 0 to disable - * video sending. - */ -bool answer(uint32_t friend_number, uint32_t audio_bit_rate, uint32_t video_bit_rate) { - /** - * Synchronization error occurred. - */ - SYNC, - /** - * Failed to initialize codecs for call session. Note that codec initiation - * will fail if there is no receive callback registered for either audio or - * video. - */ - CODEC_INITIALIZATION, - /** - * The friend number did not designate a valid friend. - */ - 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. - */ - FRIEND_NOT_CALLING, - /** - * Audio or video bit rate is invalid. - */ - INVALID_BIT_RATE, -} - - -/******************************************************************************* - * - * :: Call state graph - * - ******************************************************************************/ - - -bitmask 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. - */ - ERROR, - /** - * The call has finished. 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. - */ - FINISHED, - /** - * The flag that marks that friend is sending audio. - */ - SENDING_A, - /** - * The flag that marks that friend is sending video. - */ - SENDING_V, - /** - * The flag that marks that friend is receiving audio. - */ - ACCEPTING_A, - /** - * The flag that marks that friend is receiving video. - */ - ACCEPTING_V, -} - -event call_state { - /** - * The function type for the ${event call_state} callback. - * - * @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. - */ - typedef void(uint32_t friend_number, uint32_t state); -} - - -/******************************************************************************* - * - * :: Call control - * - ******************************************************************************/ - - -enum class 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, - /** - * Put a call on hold. Not valid before the call is accepted. - */ - PAUSE, - /** - * Reject a call if it was not answered, yet. Cancel a call after it was - * answered. - */ - CANCEL, - /** - * Request that the friend stops sending audio. Regardless of the friend's - * compliance, this will cause the ${event audio.receive_frame} event to stop being - * triggered on receiving an audio frame from the friend. - */ - MUTE_AUDIO, - /** - * Calling this control will notify client to start sending audio again. - */ - UNMUTE_AUDIO, - /** - * Request that the friend stops sending video. Regardless of the friend's - * compliance, this will cause the ${event video.receive_frame} event to stop being - * triggered on receiving a video frame from the friend. - */ - HIDE_VIDEO, - /** - * Calling this control will notify client to start sending video again. - */ - SHOW_VIDEO, -} - -/** - * Sends a call control command to a friend. - * - * @param friend_number The friend number of the friend this client is in a call - * with. - * @param control The control command to send. - * - * @return true on success. - */ -bool call_control(uint32_t friend_number, CALL_CONTROL control) { - /** - * Synchronization error occurred. - */ - SYNC, - /** - * The friend_number passed did not designate a valid friend. - */ - 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. - */ - FRIEND_NOT_IN_CALL, - /** - * Happens if user tried to pause an already paused call or if trying to - * resume a call that is not paused. - */ - INVALID_TRANSITION, -} - - -/******************************************************************************* - * - * :: Controlling bit rates - * - ******************************************************************************/ - - -error for bit_rate_set { - /** - * Synchronization error occurred. - */ - SYNC, - /** - * The bit rate passed was not one of the supported values. - */ - INVALID_BIT_RATE, - /** - * The friend_number passed did not designate a valid friend. - */ - FRIEND_NOT_FOUND, - /** - * This client is currently not in a call with the friend. - */ - FRIEND_NOT_IN_CALL, -} - -/******************************************************************************* - * - * :: A/V sending - * - ******************************************************************************/ - - -error for send_frame { - /** - * In case of video, one of Y, U, or V was NULL. In case of audio, the samples - * data pointer was NULL. - */ - NULL, - /** - * The friend_number passed did not designate a valid friend. - */ - FRIEND_NOT_FOUND, - /** - * This client is currently not in a call with the friend. - */ - FRIEND_NOT_IN_CALL, - /** - * Synchronization error occurred. - */ - SYNC, - /** - * One of the frame parameters was invalid. E.g. the resolution may be too - * small or too large, or the audio sampling rate may be unsupported. - */ - INVALID, - /** - * Either friend turned off audio or video receiving or we turned off sending - * for the said payload. - */ - PAYLOAD_TYPE_DISABLED, - /** - * Failed to push frame through rtp interface. - */ - RTP_FAILED, -} - -namespace audio { - /** - * Send an audio frame to a friend. - * - * 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 - * alternating. - * - * @param friend_number The friend number of the friend to which to send an - * audio frame. - * @param pcm An array of audio samples. The size of this array must be - * 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. - * @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. - */ - bool send_frame(uint32_t friend_number, const int16_t *pcm, size_t sample_count, - uint8_t channels, uint32_t sampling_rate) with error for send_frame; - - uint32_t bit_rate { - /** - * 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. - * @param bit_rate The new audio bit rate in Kb/sec. Set to 0 to disable. - * - * @return true on success. - */ - set(uint32_t friend_number) with error for bit_rate_set; - } - - event bit_rate { - /** - * The function type for the ${event 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. - * - * @param friend_number The friend number of the friend for which to set the - * bit rate. - * @param audio_bit_rate Suggested maximum audio bit rate in Kb/sec. - */ - typedef void(uint32_t friend_number, uint32_t audio_bit_rate); - } -} - -namespace video { - /** - * Send a video frame to a friend. - * - * Y - plane should be of size: height * width - * U - plane should be of size: (height/2) * (width/2) - * 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. - * @param width Width of the frame in pixels. - * @param height Height of the frame in pixels. - * @param y Y (Luminance) plane data. - * @param u U (Chroma) plane data. - * @param v V (Chroma) plane data. - */ - bool send_frame(uint32_t friend_number, uint16_t width, uint16_t height, - const uint8_t *y, const uint8_t *u, const uint8_t *v) with error for send_frame; - - uint32_t bit_rate { - /** - * 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. - * @param bit_rate The new video bit rate in Kb/sec. Set to 0 to disable. - * - * @return true on success. - */ - set(uint32_t friend_number) with error for bit_rate_set; - } - - event bit_rate { - /** - * The function type for the ${event 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. - * - * @param friend_number The friend number of the friend for which to set the - * bit rate. - * @param video_bit_rate Suggested maximum video bit rate in Kb/sec. - */ - typedef void(uint32_t friend_number, uint32_t video_bit_rate); - } -} - - -/******************************************************************************* - * - * :: A/V receiving - * - ******************************************************************************/ - - -namespace audio { - event receive_frame { - /** - * The function type for the ${event receive_frame} callback. The callback can be - * called multiple times per single iteration depending on the amount of queued - * frames in the buffer. The received format is the same as in send function. - * - * @param friend_number The friend number of the friend who sent an audio frame. - * @param pcm An array of audio samples (sample_count * channels elements). - * @param sample_count The number of audio samples per channel in the PCM array. - * @param channels Number of audio channels. - * @param sampling_rate Sampling rate used in this frame. - * - */ - typedef void(uint32_t friend_number, const int16_t *pcm, size_t sample_count, - uint8_t channels, uint32_t sampling_rate); - } -} - -namespace video { - event receive_frame { - /** - * The function type for the ${event receive_frame} callback. - * - * The size of plane data is derived from width and height as documented - * below. - * - * Strides represent padding for each plane that may or may not be present. - * You must handle strides in your image processing code. Strides are - * negative if the image is bottom-up hence why you MUST abs() it when - * calculating plane buffer size. - * - * @param friend_number The friend number of the friend who sent a video frame. - * @param width Width of the frame in pixels. - * @param height Height of the frame in pixels. - * @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. - */ - typedef void(uint32_t friend_number, uint16_t width, uint16_t height, - const uint8_t *y, const uint8_t *u, const uint8_t *v, - int32_t ystride, int32_t ustride, int32_t vstride); - } -} - -} - -%{ -/** - * 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. - */ -/* Create a new toxav group. - * - * return group number on success. - * return -1 on failure. - * - * Audio data callback format: - * audio_callback(Tox *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, uint32_t sample_rate, void *userdata) - * - * Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)). - */ -int toxav_add_av_groupchat(Tox *tox, - void (*audio_callback)(void *, uint32_t, uint32_t, const int16_t *, unsigned int, uint8_t, uint32_t, void *), - void *userdata); - -/* Join a AV group (you need to have been invited first.) - * - * returns group number on success - * returns -1 on failure. - * - * Audio data callback format (same as the one for toxav_add_av_groupchat()): - * audio_callback(Tox *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, uint32_t sample_rate, void *userdata) - * - * Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)). - */ -int toxav_join_av_groupchat(Tox *tox, uint32_t friendnumber, const uint8_t *data, uint16_t length, - void (*audio_callback)(void *, uint32_t, uint32_t, const int16_t *, unsigned int, uint8_t, uint32_t, void *), - void *userdata); - -/* Send audio to the group chat. - * - * return 0 on success. - * return -1 on failure. - * - * 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 (Valid ones are: 2.5, 5, 10, 20, 40 or 60 ms)) / 1000) - * Valid number of channels are 1 or 2. - * Valid sample rates are 8000, 12000, 16000, 24000, or 48000. - * - * Recommended values are: samples = 960, channels = 1, sample_rate = 48000 - */ -int toxav_group_send_audio(Tox *tox, uint32_t groupnumber, const int16_t *pcm, unsigned int samples, uint8_t channels, - uint32_t sample_rate); - -/* Enable A/V in a groupchat. - * - * 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 loaded from a savefile will start with A/V disabled. - * - * return 0 on success. - * return -1 on failure. - * - * Audio data callback format (same as the one for toxav_add_av_groupchat()): - * audio_callback(Tox *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, uint32_t sample_rate, void *userdata) - * - * Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)). - */ -int toxav_groupchat_enable_av(Tox *tox, uint32_t groupnumber, - void (*audio_callback)(void *, uint32_t, uint32_t, const int16_t *, unsigned int, uint8_t, uint32_t, void *), - void *userdata); - -/* Disable A/V in a groupchat. - * - * return 0 on success. - * return -1 on failure. - */ -int toxav_groupchat_disable_av(Tox *tox, uint32_t groupnumber); - -/* Return whether A/V is enabled in the groupchat. - */ -bool toxav_groupchat_av_enabled(Tox *tox, uint32_t groupnumber); - -#ifdef __cplusplus -} -#endif - -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 TOXAV_ERR_CALL Toxav_Err_Call; -typedef TOXAV_ERR_NEW Toxav_Err_New; -typedef TOXAV_ERR_ANSWER Toxav_Err_Answer; -typedef TOXAV_ERR_CALL_CONTROL Toxav_Err_Call_Control; -typedef TOXAV_ERR_BIT_RATE_SET Toxav_Err_Bit_Rate_Set; -typedef TOXAV_ERR_SEND_FRAME Toxav_Err_Send_Frame; -typedef TOXAV_CALL_CONTROL Toxav_Call_Control; - -//!TOKSTYLE+ - -#endif // C_TOXCORE_TOXAV_TOXAV_H -%} diff --git a/toxav/toxav.h b/toxav/toxav.h index 974dc85f..6d345529 100644 --- a/toxav/toxav.h +++ b/toxav/toxav.h @@ -2,26 +2,14 @@ * Copyright © 2016-2018 The TokTok team. * Copyright © 2013-2015 Tox project. */ -#ifndef C_TOXCORE_TOXAV_TOXAV_H -#define C_TOXCORE_TOXAV_TOXAV_H - -#include -#include -#include - -//!TOKSTYLE- - -#ifdef __cplusplus -extern "C" { -#endif /** \page av 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. * - */ -/** \subsection events Events and callbacks + * + * \subsection events Events and callbacks * * As in Core API, events are handled by callbacks. One callback can be * registered per event. All events have a callback function type named @@ -33,8 +21,8 @@ extern "C" { * library to drop calls before they are started. Hanging up call from a * callback causes undefined behaviour. * - */ -/** \subsection threading Threading implications + * + * \subsection threading Threading implications * * Only toxav_iterate is thread-safe, all other functions must run from the * tox thread. @@ -45,7 +33,7 @@ extern "C" { * * 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, - * sleeping for toxav_iteration_interval * milliseconds on each iteration. + * 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 @@ -54,8 +42,8 @@ extern "C" { * 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 multi-threading Separate audio and video threads + * + * \subsection multi-threading Separate audio and video threads * * ToxAV supports either a single thread for audio and video or decoding and * encoding them in separate threads. You have to choose one mode and can not @@ -64,6 +52,17 @@ extern "C" { * For best results use the multi-threaded mode and run the audio thread with * higher priority than the video thread. This prioritizes audio over video. */ +#ifndef C_TOXCORE_TOXAV_TOXAV_H +#define C_TOXCORE_TOXAV_TOXAV_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + /** * External Tox type. */ @@ -72,16 +71,12 @@ extern "C" { typedef struct Tox Tox; #endif /* TOX_DEFINED */ -/** - * ToxAV. - */ /** * The ToxAV instance type. 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. - * */ #ifndef TOXAV_DEFINED #define TOXAV_DEFINED @@ -97,7 +92,7 @@ typedef struct ToxAV ToxAV; -typedef enum TOXAV_ERR_NEW { +typedef enum Toxav_Err_New { /** * The function returned successfully. @@ -120,13 +115,13 @@ typedef enum TOXAV_ERR_NEW { */ TOXAV_ERR_NEW_MULTIPLE, -} TOXAV_ERR_NEW; +} Toxav_Err_New; /** * Start new A/V session. There can only be only one session per Tox instance. */ -ToxAV *toxav_new(Tox *tox, TOXAV_ERR_NEW *error); +ToxAV *toxav_new(Tox *tox, Toxav_Err_New *error); /** * Releases all resources associated with the A/V session. @@ -215,7 +210,7 @@ void toxav_video_iterate(ToxAV *av); -typedef enum TOXAV_ERR_CALL { +typedef enum Toxav_Err_Call { /** * The function returned successfully. @@ -254,7 +249,7 @@ typedef enum TOXAV_ERR_CALL { */ TOXAV_ERR_CALL_INVALID_BIT_RATE, -} TOXAV_ERR_CALL; +} Toxav_Err_Call; /** @@ -272,7 +267,7 @@ typedef enum TOXAV_ERR_CALL { * 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); + Toxav_Err_Call *error); /** * The function type for the call callback. @@ -290,7 +285,7 @@ typedef void toxav_call_cb(ToxAV *av, uint32_t friend_number, bool audio_enabled */ void toxav_callback_call(ToxAV *av, toxav_call_cb *callback, void *user_data); -typedef enum TOXAV_ERR_ANSWER { +typedef enum Toxav_Err_Answer { /** * The function returned successfully. @@ -325,7 +320,7 @@ typedef enum TOXAV_ERR_ANSWER { */ TOXAV_ERR_ANSWER_INVALID_BIT_RATE, -} TOXAV_ERR_ANSWER; +} Toxav_Err_Answer; /** @@ -342,7 +337,7 @@ typedef enum TOXAV_ERR_ANSWER { * 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); + Toxav_Err_Answer *error); /******************************************************************************* @@ -353,7 +348,7 @@ bool toxav_answer(ToxAV *av, uint32_t friend_number, uint32_t audio_bit_rate, ui -enum TOXAV_FRIEND_CALL_STATE { +enum Toxav_Friend_Call_State { /** * The empty bit mask. None of the bits specified below are set. @@ -425,7 +420,7 @@ void toxav_callback_call_state(ToxAV *av, toxav_call_state_cb *callback, void *u -typedef enum TOXAV_CALL_CONTROL { +typedef enum Toxav_Call_Control { /** * Resume a previously paused call. Only valid if the pause was caused by this @@ -468,10 +463,10 @@ typedef enum TOXAV_CALL_CONTROL { */ TOXAV_CALL_CONTROL_SHOW_VIDEO, -} TOXAV_CALL_CONTROL; +} Toxav_Call_Control; -typedef enum TOXAV_ERR_CALL_CONTROL { +typedef enum Toxav_Err_Call_Control { /** * The function returned successfully. @@ -500,7 +495,7 @@ typedef enum TOXAV_ERR_CALL_CONTROL { */ TOXAV_ERR_CALL_CONTROL_INVALID_TRANSITION, -} TOXAV_ERR_CALL_CONTROL; +} Toxav_Err_Call_Control; /** @@ -512,7 +507,7 @@ typedef enum TOXAV_ERR_CALL_CONTROL { * * @return true on success. */ -bool toxav_call_control(ToxAV *av, uint32_t friend_number, TOXAV_CALL_CONTROL control, TOXAV_ERR_CALL_CONTROL *error); +bool toxav_call_control(ToxAV *av, uint32_t friend_number, Toxav_Call_Control control, Toxav_Err_Call_Control *error); /******************************************************************************* @@ -523,7 +518,7 @@ bool toxav_call_control(ToxAV *av, uint32_t friend_number, TOXAV_CALL_CONTROL co -typedef enum TOXAV_ERR_BIT_RATE_SET { +typedef enum Toxav_Err_Bit_Rate_Set { /** * The function returned successfully. @@ -550,7 +545,7 @@ typedef enum TOXAV_ERR_BIT_RATE_SET { */ TOXAV_ERR_BIT_RATE_SET_FRIEND_NOT_IN_CALL, -} TOXAV_ERR_BIT_RATE_SET; +} Toxav_Err_Bit_Rate_Set; @@ -562,7 +557,7 @@ typedef enum TOXAV_ERR_BIT_RATE_SET { -typedef enum TOXAV_ERR_SEND_FRAME { +typedef enum Toxav_Err_Send_Frame { /** * The function returned successfully. @@ -607,13 +602,13 @@ typedef enum TOXAV_ERR_SEND_FRAME { */ TOXAV_ERR_SEND_FRAME_RTP_FAILED, -} TOXAV_ERR_SEND_FRAME; +} 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 @@ -622,16 +617,16 @@ typedef enum TOXAV_ERR_SEND_FRAME { * @param friend_number The friend number of the friend to which to send an * audio frame. * @param pcm An array of audio samples. The size of this array must be - * sample_count * channels. + * `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 + * `((sample rate) * (audio length) / 1000)`, where audio length can be * 2.5, 5, 10, 20, 40 or 60 millseconds. * @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. */ 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); + uint8_t channels, uint32_t sampling_rate, Toxav_Err_Send_Frame *error); /** * Set the bit rate to be used in subsequent video frames. @@ -642,7 +637,7 @@ bool toxav_audio_send_frame(ToxAV *av, uint32_t friend_number, const int16_t *pc * * @return true on success. */ -bool toxav_audio_set_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t bit_rate, TOXAV_ERR_BIT_RATE_SET *error); +bool toxav_audio_set_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t bit_rate, Toxav_Err_Bit_Rate_Set *error); /** * The function type for the audio_bit_rate callback. The event is triggered @@ -665,9 +660,9 @@ void toxav_callback_audio_bit_rate(ToxAV *av, toxav_audio_bit_rate_cb *callback, /** * Send a video frame to a friend. * - * Y - plane should be of size: height * width - * U - plane should be of size: (height/2) * (width/2) - * V - plane should be of size: (height/2) * (width/2) + * Y - plane should be of size: `height * width` + * U - plane should be of size: `(height/2) * (width/2)` + * 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. @@ -678,7 +673,7 @@ void toxav_callback_audio_bit_rate(ToxAV *av, toxav_audio_bit_rate_cb *callback, * @param v V (Chroma) plane data. */ bool toxav_video_send_frame(ToxAV *av, uint32_t friend_number, uint16_t width, uint16_t height, const uint8_t *y, - const uint8_t *u, const uint8_t *v, TOXAV_ERR_SEND_FRAME *error); + const uint8_t *u, const uint8_t *v, Toxav_Err_Send_Frame *error); /** * Set the bit rate to be used in subsequent video frames. @@ -689,7 +684,7 @@ bool toxav_video_send_frame(ToxAV *av, uint32_t friend_number, uint16_t width, u * * @return true on success. */ -bool toxav_video_set_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t bit_rate, TOXAV_ERR_BIT_RATE_SET *error); +bool toxav_video_set_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t bit_rate, Toxav_Err_Bit_Rate_Set *error); /** * The function type for the video_bit_rate callback. The event is triggered @@ -724,7 +719,7 @@ void toxav_callback_video_bit_rate(ToxAV *av, toxav_video_bit_rate_cb *callback, * frames in the buffer. The received format is the same as in send function. * * @param friend_number The friend number of the friend who sent an audio frame. - * @param pcm An array of audio samples (sample_count * channels elements). + * @param pcm An array of audio samples (`sample_count * channels` elements). * @param sample_count The number of audio samples per channel in the PCM array. * @param channels Number of audio channels. * @param sampling_rate Sampling rate used in this frame. @@ -754,9 +749,9 @@ void toxav_callback_audio_receive_frame(ToxAV *av, toxav_audio_receive_frame_cb * @param friend_number The friend number of the friend who sent a video frame. * @param width Width of the frame in pixels. * @param height Height of the frame in pixels. - * @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 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. @@ -773,49 +768,48 @@ typedef void toxav_video_receive_frame_cb(ToxAV *av, uint32_t friend_number, uin */ void toxav_callback_video_receive_frame(ToxAV *av, toxav_video_receive_frame_cb *callback, void *user_data); -/** +/*** * 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. +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); + /* Create a new toxav group. * * return group number on success. * return -1 on failure. * - * Audio data callback format: - * audio_callback(Tox *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, uint32_t sample_rate, void *userdata) - * - * 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)`. */ -int toxav_add_av_groupchat(Tox *tox, - void (*audio_callback)(void *, uint32_t, uint32_t, const int16_t *, unsigned int, uint8_t, uint32_t, void *), - void *userdata); +int toxav_add_av_groupchat(Tox *tox, toxav_audio_data_cb *audio_callback, void *userdata); /* Join a AV group (you need to have been invited first.) * * returns group number on success * returns -1 on failure. * - * Audio data callback format (same as the one for toxav_add_av_groupchat()): - * audio_callback(Tox *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, uint32_t sample_rate, void *userdata) - * - * 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)`. */ int toxav_join_av_groupchat(Tox *tox, uint32_t friendnumber, const uint8_t *data, uint16_t length, - void (*audio_callback)(void *, uint32_t, uint32_t, const int16_t *, unsigned int, uint8_t, uint32_t, void *), - void *userdata); + toxav_audio_data_cb *audio_callback, void *userdata); /* Send audio to the group chat. * * return 0 on success. * return -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 (Valid ones are: 2.5, 5, 10, 20, 40 or 60 ms)) / 1000) + * Valid number of samples are `(sample rate) * (audio length) / 1000` (Valid audio lengths are: 2.5, 5, 10, 20, 40 or 60 ms) * Valid number of channels are 1 or 2. * Valid sample rates are 8000, 12000, 16000, 24000, or 48000. * @@ -829,7 +823,7 @@ int toxav_group_send_audio(Tox *tox, uint32_t groupnumber, const int16_t *pcm, u * 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 + * 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. @@ -837,14 +831,10 @@ int toxav_group_send_audio(Tox *tox, uint32_t groupnumber, const int16_t *pcm, u * return 0 on success. * return -1 on failure. * - * Audio data callback format (same as the one for toxav_add_av_groupchat()): - * audio_callback(Tox *tox, uint32_t groupnumber, uint32_t peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, uint32_t sample_rate, void *userdata) - * - * 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)`. */ int toxav_groupchat_enable_av(Tox *tox, uint32_t groupnumber, - void (*audio_callback)(void *, uint32_t, uint32_t, const int16_t *, unsigned int, uint8_t, uint32_t, void *), - void *userdata); + toxav_audio_data_cb *audio_callback, void *userdata); /* Disable A/V in a groupchat. * @@ -861,16 +851,16 @@ bool toxav_groupchat_av_enabled(Tox *tox, uint32_t groupnumber); } #endif -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); +//!TOKSTYLE- -typedef TOXAV_ERR_CALL Toxav_Err_Call; -typedef TOXAV_ERR_NEW Toxav_Err_New; -typedef TOXAV_ERR_ANSWER Toxav_Err_Answer; -typedef TOXAV_ERR_CALL_CONTROL Toxav_Err_Call_Control; -typedef TOXAV_ERR_BIT_RATE_SET Toxav_Err_Bit_Rate_Set; -typedef TOXAV_ERR_SEND_FRAME Toxav_Err_Send_Frame; -typedef TOXAV_CALL_CONTROL Toxav_Call_Control; +typedef Toxav_Err_Call TOXAV_ERR_CALL; +typedef Toxav_Err_New TOXAV_ERR_NEW; +typedef Toxav_Err_Answer TOXAV_ERR_ANSWER; +typedef Toxav_Err_Call_Control TOXAV_ERR_CALL_CONTROL; +typedef Toxav_Err_Bit_Rate_Set TOXAV_ERR_BIT_RATE_SET; +typedef Toxav_Err_Send_Frame TOXAV_ERR_SEND_FRAME; +typedef Toxav_Call_Control TOXAV_CALL_CONTROL; +typedef enum Toxav_Friend_Call_State TOXAV_FRIEND_CALL_STATE; //!TOKSTYLE+ diff --git a/toxcore/BUILD.bazel b/toxcore/BUILD.bazel index abf84ca1..1073dece 100644 --- a/toxcore/BUILD.bazel +++ b/toxcore/BUILD.bazel @@ -323,16 +323,11 @@ cc_library( ], ) -CIMPLE_SRCS = glob( - [ - "*.c", - "*.h", - ], - exclude = ["*.api.h"], -) - sh_library( name = "cimple_files", - srcs = CIMPLE_SRCS, + srcs = glob([ + "*.c", + "*.h", + ]), visibility = ["//c-toxcore/testing:__pkg__"], ) diff --git a/toxcore/ccompat.h b/toxcore/ccompat.h index 7b38880b..051b2789 100644 --- a/toxcore/ccompat.h +++ b/toxcore/ccompat.h @@ -9,6 +9,9 @@ #define C_TOXCORE_TOXCORE_CCOMPAT_H #include +#include + +bool unused_for_tokstyle(void); //!TOKSTYLE- diff --git a/toxcore/crypto_core.c b/toxcore/crypto_core.c index 1f221338..c05ec60a 100644 --- a/toxcore/crypto_core.c +++ b/toxcore/crypto_core.c @@ -16,7 +16,7 @@ #include "ccompat.h" #ifndef VANILLA_NACL -/* We use libsodium by default. */ +// We use libsodium by default. #include #else #include @@ -29,7 +29,6 @@ #define crypto_box_MACBYTES (crypto_box_ZEROBYTES - crypto_box_BOXZEROBYTES) #endif -//!TOKSTYLE- static_assert(CRYPTO_PUBLIC_KEY_SIZE == crypto_box_PUBLICKEYBYTES, "CRYPTO_PUBLIC_KEY_SIZE should be equal to crypto_box_PUBLICKEYBYTES"); static_assert(CRYPTO_SECRET_KEY_SIZE == crypto_box_SECRETKEYBYTES, @@ -48,7 +47,6 @@ static_assert(CRYPTO_SHA512_SIZE == crypto_hash_sha512_BYTES, "CRYPTO_SHA512_SIZE should be equal to crypto_hash_sha512_BYTES"); static_assert(CRYPTO_PUBLIC_KEY_SIZE == 32, "CRYPTO_PUBLIC_KEY_SIZE is required to be 32 bytes for public_key_cmp to work"); -//!TOKSTYLE+ static uint8_t *crypto_malloc(size_t bytes) { @@ -69,6 +67,15 @@ int32_t public_key_cmp(const uint8_t *pk1, const uint8_t *pk2) return crypto_verify_32(pk1, pk2); } +int32_t crypto_sha512_cmp(const uint8_t *cksum1, const uint8_t *cksum2) +{ +#ifndef VANILLA_NACL + return crypto_verify_64(cksum1, cksum2); +#else + return crypto_verify_32(cksum1, cksum2) && crypto_verify_32(cksum1 + 8, cksum2 + 8); +#endif +} + uint8_t random_u08(void) { uint8_t randnum; diff --git a/toxcore/crypto_core.h b/toxcore/crypto_core.h index 8160fefa..1b5464b1 100644 --- a/toxcore/crypto_core.h +++ b/toxcore/crypto_core.h @@ -18,12 +18,12 @@ extern "C" { #endif /** - * The number of bytes in a Tox public key. + * The number of bytes in a Tox public key used for encryption. */ #define CRYPTO_PUBLIC_KEY_SIZE 32 /** - * The number of bytes in a Tox secret key. + * The number of bytes in a Tox secret key used for encryption. */ #define CRYPTO_SECRET_KEY_SIZE 32 @@ -58,17 +58,6 @@ extern "C" { */ #define CRYPTO_SHA512_SIZE 64 -/** - * A `memcmp`-like function whose running time does not depend on the input - * bytes, only on the input length. Useful to compare sensitive data where - * timing attacks could reveal that data. - * - * This means for instance that comparing "aaaa" and "aaaa" takes 4 time, and - * "aaaa" and "baaa" also takes 4 time. With a regular `memcmp`, the latter may - * take 1 time, because it immediately knows that the two strings are not equal. - */ -int32_t crypto_memcmp(const uint8_t *p1, const uint8_t *p2, size_t length); - /** * A `bzero`-like function which won't be optimised away by the compiler. Some * compilers will inline `bzero` or `memset` if they can prove that there will @@ -95,6 +84,14 @@ void crypto_sha512(uint8_t *hash, const uint8_t *data, size_t length); */ int32_t public_key_cmp(const uint8_t *pk1, const uint8_t *pk2); +/** + * Compare 2 SHA512 checksums of length CRYPTO_SHA512_SIZE, not vulnerable to + * timing attacks. + * + * @return 0 if both mem locations of length are equal, -1 if they are not. + */ +int32_t crypto_sha512_cmp(const uint8_t *cksum1, const uint8_t *cksum2); + /** * Return a random 8 bit integer. */ @@ -214,6 +211,26 @@ void increment_nonce_number(uint8_t *nonce, uint32_t increment); */ void new_symmetric_key(uint8_t *key); +/** + * Locks `length` bytes of memory pointed to by `data`. This will attempt to prevent + * the specified memory region from being swapped to disk. + * + * Returns true on success. + */ +bool crypto_memlock(void *data, size_t length); + +/** + * Unlocks `length` bytes of memory pointed to by `data`. This allows the specified + * memory region to be swapped to disk. + * + * This function call has the side effect of zeroing the specified memory region + * whether or not it succeeds. Therefore it should only be used once the memory + * is no longer in use. + * + * Returns true on success. + */ +bool crypto_memunlock(void *data, size_t length); + #ifdef __cplusplus } // extern "C" #endif diff --git a/toxcore/crypto_core_mem.c b/toxcore/crypto_core_mem.c index 4bd5ca88..2ff25d55 100644 --- a/toxcore/crypto_core_mem.c +++ b/toxcore/crypto_core_mem.c @@ -1,42 +1,13 @@ /* SPDX-License-Identifier: ISC * Copyright © 2016-2021 The TokTok team. - * Copyright © 2013-2016 Frank Denis */ -/* - * ISC License - * - * Copyright (c) 2013-2016 - * Frank Denis - * - * Permission to use, copy, modify, and/or distribute this software for any - * purpose with or without fee is hereby granted, provided that the above - * copyright notice and this permission notice appear in all copies. - * - * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES - * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR - * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF - * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - */ - -// For explicit_bzero. -#ifndef _DEFAULT_SOURCE -#define _DEFAULT_SOURCE -#endif - #include "crypto_core.h" #ifndef VANILLA_NACL -/* We use libsodium by default. */ +// We use libsodium by default. #include #else -#if defined(_WIN32) || defined(__WIN32__) || defined(WIN32) -#include -#include -#endif #include #endif @@ -45,51 +16,52 @@ void crypto_memzero(void *data, size_t length) { #ifndef VANILLA_NACL sodium_memzero(data, length); -#elif defined(_WIN32) - SecureZeroMemory(data, length); -#elif defined(HAVE_MEMSET_S) - - if (length > 0U) { - errno_t code = memset_s(data, (rsize_t) length, 0, (rsize_t) length); - - if (code != 0) { - abort(); /* LCOV_EXCL_LINE */ - } - } - -#elif defined(HAVE_EXPLICIT_BZERO) - explicit_bzero(data, length); #else - //!TOKSTYLE- - volatile uint8_t *volatile pnt = data; - //!TOKSTYLE+ - size_t i = (size_t) 0U; - - while (i < length) { - pnt[i] = 0U; - ++i; - } - + memset(data, 0, length); #endif } -int32_t crypto_memcmp(const uint8_t *p1, const uint8_t *p2, size_t length) +/** + * Locks `length` bytes of memory pointed to by `data`. This will attempt to prevent + * the specified memory region from being swapped to disk. + * + * Returns true on success. + */ +bool crypto_memlock(void *data, size_t length) { #ifndef VANILLA_NACL - return sodium_memcmp(p1, p2, length); -#else - //!TOKSTYLE- - const volatile uint8_t *volatile b1 = p1; - const volatile uint8_t *volatile b2 = p2; - //!TOKSTYLE+ - size_t i; - uint8_t d = (uint8_t) 0U; - - for (i = 0U; i < length; ++i) { - d |= b1[i] ^ b2[i]; + if (sodium_mlock(data, length) != 0) { + return false; } - return (1 & ((d - 1) >> 8)) - 1; + return true; +#else + return false; +#endif +} + +/** + * Unlocks `length` bytes of memory pointed to by `data`. This allows the specified + * memory region to be swapped to disk. + * + * This function call has the side effect of zeroing the specified memory region + * whether or not it succeeds. Therefore it should only be used once the memory + * is no longer in use. + * + * Return 0 on success. + * Return -1 on failure. + */ +bool crypto_memunlock(void *data, size_t length) +{ +#ifndef VANILLA_NACL + + if (sodium_munlock(data, length) != 0) { + return false; + } + + return true; +#else + return false; #endif } diff --git a/toxcore/crypto_core_test.cc b/toxcore/crypto_core_test.cc index cf2012ac..708bbe7a 100644 --- a/toxcore/crypto_core_test.cc +++ b/toxcore/crypto_core_test.cc @@ -7,88 +7,6 @@ namespace { -enum { - /** - * The size of the arrays to compare. This was chosen to take around 2000 - * CPU clocks on x86_64. - * - * This is 1MiB. - */ - CRYPTO_TEST_MEMCMP_SIZE = 1024 * 1024, - /** - * The number of times we run memcmp in the test. - * - * We compute the median time taken to reduce error margins. - */ - CRYPTO_TEST_MEMCMP_ITERATIONS = 500, - /** - * The margin of error (in clocks) we allow for this test. - * - * Should be within 0.5% of ~2000 CPU clocks. In reality, the code is much - * more precise and is usually within 1 CPU clock. - */ - CRYPTO_TEST_MEMCMP_EPS = 10, -}; - -clock_t memcmp_time(uint8_t const *a, uint8_t const *b, size_t len) { - clock_t start = clock(); - volatile int result = crypto_memcmp(a, b, len); - (void)result; - return clock() - start; -} - -/** - * This function performs the actual timing. It interleaves comparison of - * equal and non-equal arrays to reduce the influence of external effects - * such as the machine being a little more busy 1 second later. - */ -std::pair memcmp_median(uint8_t const *src, uint8_t const *same, - uint8_t const *not_same, size_t len) { - clock_t same_results[CRYPTO_TEST_MEMCMP_ITERATIONS]; - clock_t not_same_results[CRYPTO_TEST_MEMCMP_ITERATIONS]; - - for (size_t i = 0; i < CRYPTO_TEST_MEMCMP_ITERATIONS; i++) { - same_results[i] = memcmp_time(src, same, len); - not_same_results[i] = memcmp_time(src, not_same, len); - } - - std::sort(same_results, same_results + CRYPTO_TEST_MEMCMP_ITERATIONS); - clock_t const same_median = same_results[CRYPTO_TEST_MEMCMP_ITERATIONS / 2]; - std::sort(not_same_results, not_same_results + CRYPTO_TEST_MEMCMP_ITERATIONS); - clock_t const not_same_median = not_same_results[CRYPTO_TEST_MEMCMP_ITERATIONS / 2]; - return {same_median, not_same_median}; -} - -/** - * This test checks whether crypto_memcmp takes the same time for equal and - * non-equal chunks of memory. - */ -TEST(CryptoCore, MemcmpTimingIsDataIndependent) { - // A random piece of memory. - std::vector src(CRYPTO_TEST_MEMCMP_SIZE); - random_bytes(src.data(), CRYPTO_TEST_MEMCMP_SIZE); - - // A separate piece of memory containing the same data. - std::vector same = src; - - // Another piece of memory containing different data. - std::vector not_same(CRYPTO_TEST_MEMCMP_SIZE); - random_bytes(not_same.data(), CRYPTO_TEST_MEMCMP_SIZE); - - // Once we have C++17: - // auto const [same_median, not_same_median] = - auto const result = - memcmp_median(src.data(), same.data(), not_same.data(), CRYPTO_TEST_MEMCMP_SIZE); - - clock_t const delta = - std::max(result.first, result.second) - std::min(result.first, result.second); - - EXPECT_LT(delta, CRYPTO_TEST_MEMCMP_EPS) - << "Delta time is too long (" << delta << " >= " << CRYPTO_TEST_MEMCMP_EPS << ")\n" - << "Time of the same data comparison: " << result.first << " clocks\n" - << "Time of the different data comparison: " << result.second << " clocks"; -} - TEST(CryptoCore, IncrementNonce) { using Nonce = std::array; Nonce nonce{}; diff --git a/toxcore/group.c b/toxcore/group.c index 6cad97f0..3235febf 100644 --- a/toxcore/group.c +++ b/toxcore/group.c @@ -54,6 +54,14 @@ typedef enum Peer_Id { #define MIN_MESSAGE_PACKET_LEN (sizeof(uint16_t) * 2 + sizeof(uint32_t) + 1) +static_assert(GROUP_ID_LENGTH == CRYPTO_PUBLIC_KEY_SIZE, + "GROUP_ID_LENGTH should be equal to CRYPTO_PUBLIC_KEY_SIZE"); + +static bool group_id_eq(const uint8_t *a, const uint8_t *b) +{ + return public_key_cmp(a, b) == 0; +} + /* return false if the groupnumber is not valid. * return true if the groupnumber is valid. */ @@ -197,7 +205,7 @@ static int frozen_in_group(const Group_c *g, const uint8_t *real_pk) static int32_t get_group_num(const Group_Chats *g_c, const uint8_t type, const uint8_t *id) { for (uint16_t i = 0; i < g_c->num_chats; ++i) { - if (g_c->chats[i].type == type && crypto_memcmp(g_c->chats[i].id, id, GROUP_ID_LENGTH) == 0) { + if (g_c->chats[i].type == type && group_id_eq(g_c->chats[i].id, id)) { return i; } } @@ -208,7 +216,7 @@ static int32_t get_group_num(const Group_Chats *g_c, const uint8_t type, const u int32_t conference_by_id(const Group_Chats *g_c, const uint8_t *id) { for (uint16_t i = 0; i < g_c->num_chats; ++i) { - if (crypto_memcmp(g_c->chats[i].id, id, GROUP_ID_LENGTH) == 0) { + if (group_id_eq(g_c->chats[i].id, id)) { return i; } } @@ -1948,7 +1956,7 @@ static void handle_friend_invite_packet(Messenger *m, uint32_t friendnumber, con return; } - if (crypto_memcmp(data + 1 + sizeof(uint16_t) * 2 + 1, g->id, GROUP_ID_LENGTH) != 0) { + if (!group_id_eq(data + 1 + sizeof(uint16_t) * 2 + 1, g->id)) { return; } diff --git a/toxcore/mono_time.c b/toxcore/mono_time.c index 876902f5..3db7badd 100644 --- a/toxcore/mono_time.c +++ b/toxcore/mono_time.c @@ -8,6 +8,11 @@ #if !defined(OS_WIN32) && (defined(_WIN32) || defined(__WIN32__) || defined(WIN32)) #define OS_WIN32 +#endif + +#include "mono_time.h" + +#ifdef OS_WIN32 #define WIN32_LEAN_AND_MEAN #include #endif @@ -21,8 +26,6 @@ #include #endif -#include "mono_time.h" - #include #include #include diff --git a/toxcore/net_crypto.c b/toxcore/net_crypto.c index 1efb19f9..2dfc6639 100644 --- a/toxcore/net_crypto.c +++ b/toxcore/net_crypto.c @@ -535,8 +535,7 @@ static int handle_crypto_handshake(const Net_Crypto *c, uint8_t *nonce, uint8_t return -1; } - if (crypto_memcmp(cookie_hash, plain + CRYPTO_NONCE_SIZE + CRYPTO_PUBLIC_KEY_SIZE, - CRYPTO_SHA512_SIZE) != 0) { + if (crypto_sha512_cmp(cookie_hash, plain + CRYPTO_NONCE_SIZE + CRYPTO_PUBLIC_KEY_SIZE) != 0) { return -1; } diff --git a/toxcore/network.c b/toxcore/network.c index 6d7209b2..f09410bf 100644 --- a/toxcore/network.c +++ b/toxcore/network.c @@ -6,6 +6,7 @@ /* * Functions for the core networking. */ + #ifdef __APPLE__ #define _DARWIN_C_SOURCE #endif @@ -29,12 +30,12 @@ #define OS_WIN32 #endif -#ifdef OS_WIN32 -#ifndef WINVER +#if defined(OS_WIN32) && !defined(WINVER) // Windows XP #define WINVER 0x0501 #endif -#endif + +#include "network.h" #ifdef PLAN9 #include // Plan 9 requires this is imported first @@ -42,7 +43,7 @@ #include #endif -#ifdef OS_WIN32 /* Put win32 includes here */ +#ifdef OS_WIN32 // Put win32 includes here // The mingw32/64 Windows library warns about including winsock2.h after // windows.h even though with the above it's a valid thing to do. So, to make // mingw32 headers happy, we include winsock2.h first. @@ -52,15 +53,12 @@ #include #endif -#include "network.h" - #ifdef __APPLE__ #include #include #endif #if !defined(OS_WIN32) - #include #include #include @@ -77,6 +75,33 @@ #include #endif +#else +#ifndef IPV6_V6ONLY +#define IPV6_V6ONLY 27 +#endif +#endif + +#include +#include +#include +#include + +#include "logger.h" +#include "mono_time.h" +#include "util.h" + +// Disable MSG_NOSIGNAL on systems not supporting it, e.g. Windows, FreeBSD +#if !defined(MSG_NOSIGNAL) +#define MSG_NOSIGNAL 0 +#endif + +#ifndef IPV6_ADD_MEMBERSHIP +#ifdef IPV6_JOIN_GROUP +#define IPV6_ADD_MEMBERSHIP IPV6_JOIN_GROUP +#endif +#endif + +#if !defined(OS_WIN32) #define TOX_EWOULDBLOCK EWOULDBLOCK static const char *inet_ntop4(const struct in_addr *addr, char *buf, size_t bufsize) @@ -170,32 +195,10 @@ static int inet_pton6(const char *addrString, struct in6_addr *addrbuf) #endif -#include -#include -#include -#include - -#include "logger.h" -#include "mono_time.h" -#include "util.h" - -// Disable MSG_NOSIGNAL on systems not supporting it, e.g. Windows, FreeBSD -#if !defined(MSG_NOSIGNAL) -#define MSG_NOSIGNAL 0 -#endif - -#ifndef IPV6_ADD_MEMBERSHIP -#ifdef IPV6_JOIN_GROUP -#define IPV6_ADD_MEMBERSHIP IPV6_JOIN_GROUP -#endif -#endif - -//!TOKSTYLE- static_assert(TOX_INET6_ADDRSTRLEN >= INET6_ADDRSTRLEN, "TOX_INET6_ADDRSTRLEN should be greater or equal to INET6_ADDRSTRLEN (#INET6_ADDRSTRLEN)"); static_assert(TOX_INET_ADDRSTRLEN >= INET_ADDRSTRLEN, "TOX_INET_ADDRSTRLEN should be greater or equal to INET_ADDRSTRLEN (#INET_ADDRSTRLEN)"); -//!TOKSTYLE+ static int make_proto(int proto) { diff --git a/toxcore/onion_announce.c b/toxcore/onion_announce.c index 56b6080e..8e168152 100644 --- a/toxcore/onion_announce.c +++ b/toxcore/onion_announce.c @@ -22,10 +22,8 @@ #define DATA_REQUEST_MIN_SIZE ONION_DATA_REQUEST_MIN_SIZE #define DATA_REQUEST_MIN_SIZE_RECV (DATA_REQUEST_MIN_SIZE + ONION_RETURN_3) -//!TOKSTYLE- static_assert(ONION_PING_ID_SIZE == CRYPTO_PUBLIC_KEY_SIZE, "announce response packets assume that ONION_PING_ID_SIZE is equal to CRYPTO_PUBLIC_KEY_SIZE"); -//!TOKSTYLE+ typedef struct Onion_Announce_Entry { uint8_t public_key[CRYPTO_PUBLIC_KEY_SIZE]; @@ -47,6 +45,11 @@ struct Onion_Announce { Shared_Keys shared_keys_recv; }; +static bool onion_ping_id_eq(const uint8_t *a, const uint8_t *b) +{ + return public_key_cmp(a, b) == 0; +} + uint8_t *onion_announce_entry_public_key(Onion_Announce *onion_a, uint32_t entry) { return onion_a->entries[entry].public_key; @@ -390,8 +393,8 @@ static int handle_announce_request(void *object, IP_Port source, const uint8_t * uint8_t *data_public_key = plain + ONION_PING_ID_SIZE + CRYPTO_PUBLIC_KEY_SIZE; - if (crypto_memcmp(ping_id1, plain, ONION_PING_ID_SIZE) == 0 - || crypto_memcmp(ping_id2, plain, ONION_PING_ID_SIZE) == 0) { + if (onion_ping_id_eq(ping_id1, plain) + || onion_ping_id_eq(ping_id2, plain)) { index = add_to_entries(onion_a, source, packet_public_key, data_public_key, packet + (ANNOUNCE_REQUEST_SIZE_RECV - ONION_RETURN_3)); } else { diff --git a/toxcore/tox.api.h b/toxcore/tox.api.h deleted file mode 100644 index 90a6ffc8..00000000 --- a/toxcore/tox.api.h +++ /dev/null @@ -1,2862 +0,0 @@ -%{ -/* SPDX-License-Identifier: GPL-3.0-or-later - * Copyright © 2016-2018 The TokTok team. - * Copyright © 2013 Tox project. - */ - -/* - * The Tox public API. - */ -#ifndef C_TOXCORE_TOXCORE_TOX_H -#define C_TOXCORE_TOXCORE_TOX_H - -#include -#include -#include - -//!TOKSTYLE- - -#ifdef __cplusplus -extern "C" { -#endif -%} - - -/***************************************************************************** - * `tox.h` SHOULD *NOT* BE EDITED MANUALLY – any changes should be made to * - * `tox.api.h`, located in `toxcore/`. For instructions on how to * - * generate `tox.h` from `tox.api.h` please refer to `docs/apidsl.md` * - *****************************************************************************/ - - -/** - * @page core Public core API for Tox clients. - * - * Every function that can fail takes a function-specific error code pointer - * that can be used to diagnose problems with the Tox state or the function - * arguments. The error code pointer can be NULL, which does not influence the - * function's behaviour, but can be done if the reason for failure is irrelevant - * to the client. - * - * The exception to this rule are simple allocation functions whose only failure - * mode is allocation failure. They return NULL in that case, and do not set an - * error code. - * - * Every error code type has an OK value to which functions will set their error - * code value on success. Clients can keep their error code uninitialised before - * passing it to a function. The library guarantees that after returning, the - * value pointed to by the error code pointer has been initialised. - * - * Functions with pointer parameters often have a NULL error code, meaning they - * could not perform any operation, because one of the required parameters was - * NULL. Some functions operate correctly or are defined as effectless on NULL. - * - * Some functions additionally return a value outside their - * return type domain, or a bool containing true on success and false on - * failure. - * - * All functions that take a Tox instance pointer will cause undefined behaviour - * when passed a NULL Tox pointer. - * - * All integer values are expected in host byte order. - * - * Functions with parameters with enum types cause unspecified behaviour if the - * enumeration value is outside the valid range of the type. If possible, the - * function will try to use a sane default, but there will be no error code, - * and one possible action for the function to take is to have no effect. - * - * Integer constants and the memory layout of publicly exposed structs are not - * part of the ABI. - */ - -/** - * @subsection events Events and callbacks - * - * Events are handled by callbacks. One callback can be registered per event. - * All events have a callback function type named `tox_{event}_cb` and a - * function to register it named `tox_callback_{event}`. Passing a NULL - * callback will result in no callback being registered for that event. Only - * one callback per event can be registered, so if a client needs multiple - * event listeners, it needs to implement the dispatch functionality itself. - * - * The last argument to a callback is the user data pointer. It is passed from - * ${tox.iterate} to each callback in sequence. - * - * The user data pointer is never stored or dereferenced by any library code, so - * can be any pointer, including NULL. Callbacks must all operate on the same - * object type. In the apidsl code (tox.in.h), this is denoted with `any`. The - * `any` in ${tox.iterate} must be the same `any` as in all callbacks. In C, - * lacking parametric polymorphism, this is a pointer to void. - * - * Old style callbacks that are registered together with a user data pointer - * receive that pointer as argument when they are called. They can each have - * their own user data pointer of their own type. - */ - -/** - * @subsection threading Threading implications - * - * It is possible to run multiple concurrent threads with a Tox instance for - * each thread. It is also possible to run all Tox instances in the same thread. - * A common way to run Tox (multiple or single instance) is to have one thread - * running a simple ${tox.iterate} loop, sleeping for ${tox.iteration_interval} - * milliseconds on each iteration. - * - * If you want to access a single Tox instance from multiple threads, access - * to the instance must be synchronised. While multiple threads can concurrently - * access multiple different Tox instances, no more than one API function can - * operate on a single instance at any given time. - * - * Functions that write to variable length byte arrays will always have a size - * function associated with them. The result of this size function is only valid - * until another mutating function (one that takes a pointer to non-const Tox) - * is called. Thus, clients must ensure that no other thread calls a mutating - * function between the call to the size function and the call to the retrieval - * function. - * - * E.g. to get the current nickname, one would write - * - * @code - * size_t length = ${tox.self.name.size}(tox); - * uint8_t *name = malloc(length); - * if (!name) abort(); - * ${tox.self.name.get}(tox, name); - * @endcode - * - * If any other thread calls ${tox.self.name.set} while this thread is allocating - * memory, the length may have become invalid, and the call to - * ${tox.self.name.get} may cause undefined behaviour. - */ - -// The rest of this file is in class tox. -class tox { - -/** - * The Tox instance type. All the state associated with a connection is held - * within the instance. Multiple instances can exist and operate concurrently. - * The maximum number of Tox instances that can exist on a single network - * device is limited. Note that this is not just a per-process limit, since the - * limiting factor is the number of usable ports on a device. - */ -struct this; - - -/******************************************************************************* - * - * :: API version - * - ******************************************************************************/ - - -/** - * The major version number. Incremented when the API or ABI changes in an - * incompatible way. - * - * The function variants of these constants return the version number of the - * library. They can be used to display the Tox library version or to check - * whether the client is compatible with the dynamically linked version of Tox. - */ -const VERSION_MAJOR = 0; - -/** - * The minor version number. Incremented when functionality is added without - * breaking the API or ABI. Set to 0 when the major version number is - * incremented. - */ -const VERSION_MINOR = 2; - -/** - * The patch or revision number. Incremented when bugfixes are applied without - * changing any functionality or API or ABI. - */ -const VERSION_PATCH = 13; - -/** - * A macro to check at preprocessing time whether the client code is compatible - * with the installed version of Tox. Leading zeros in the version number are - * ignored. E.g. 0.1.5 is to 0.1.4 what 1.5 is to 1.4, that is: it can add new - * features, but can't break the API. - */ -#define TOX_VERSION_IS_API_COMPATIBLE(MAJOR, MINOR, PATCH) \ - ((TOX_VERSION_MAJOR > 0 && TOX_VERSION_MAJOR == MAJOR) && ( \ - /* 1.x.x, 2.x.x, etc. with matching major version. */ \ - TOX_VERSION_MINOR > MINOR || \ - (TOX_VERSION_MINOR == MINOR && TOX_VERSION_PATCH >= PATCH) \ - )) || ((TOX_VERSION_MAJOR == 0 && MAJOR == 0) && ( \ - /* 0.x.x makes minor behave like major above. */ \ - ((TOX_VERSION_MINOR > 0 && TOX_VERSION_MINOR == MINOR) && ( \ - TOX_VERSION_PATCH >= PATCH \ - )) || ((TOX_VERSION_MINOR == 0 && MINOR == 0) && ( \ - /* 0.0.x and 0.0.y are only compatible if x == y. */ \ - TOX_VERSION_PATCH == PATCH \ - )) \ - )) - -static namespace version { - - /** - * Return whether the compiled library version is compatible with the passed - * version numbers. - */ - bool is_compatible(uint32_t major, uint32_t minor, uint32_t patch); - -} - -/** - * A convenience macro to call tox_version_is_compatible with the currently - * compiling API version. - */ -#define TOX_VERSION_IS_ABI_COMPATIBLE() \ - tox_version_is_compatible(TOX_VERSION_MAJOR, TOX_VERSION_MINOR, TOX_VERSION_PATCH) - -/******************************************************************************* - * - * :: Numeric constants - * - * 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. - * - ******************************************************************************/ - - -/** - * The size of a Tox Public Key in bytes. - */ -const PUBLIC_KEY_SIZE = 32; - -/** - * The size of a Tox Secret Key in bytes. - */ -const SECRET_KEY_SIZE = 32; - -/** - * The size of a Tox Conference unique id in bytes. - * - * @deprecated Use $CONFERENCE_ID_SIZE instead. - */ -const CONFERENCE_UID_SIZE = 32; - -/** - * The size of a Tox Conference unique id in bytes. - */ -const CONFERENCE_ID_SIZE = 32; - -/** - * The size of the nospam in bytes when written in a Tox address. - */ -const NOSPAM_SIZE = sizeof(uint32_t); - -/** - * The size of a Tox address in bytes. Tox addresses are in the format - * [Public Key ($PUBLIC_KEY_SIZE bytes)][nospam (4 bytes)][checksum (2 bytes)]. - * - * The checksum is computed over the Public Key and the nospam value. The first - * byte is an XOR of all the even bytes (0, 2, 4, ...), the second byte is an - * XOR of all the odd bytes (1, 3, 5, ...) of the Public Key and nospam. - */ -const ADDRESS_SIZE = PUBLIC_KEY_SIZE + NOSPAM_SIZE + sizeof(uint16_t); - -/** - * Maximum length of a nickname in bytes. - * - * @deprecated The macro will be removed in 0.3.0. Use the function instead. - */ -const MAX_NAME_LENGTH = 128; - -/** - * Maximum length of a status message in bytes. - * - * @deprecated The macro will be removed in 0.3.0. Use the function instead. - */ -const MAX_STATUS_MESSAGE_LENGTH = 1007; - -/** - * Maximum length of a friend request message in bytes. - * - * @deprecated The macro will be removed in 0.3.0. Use the function instead. - */ -const MAX_FRIEND_REQUEST_LENGTH = 1016; - -/** - * Maximum length of a single message after which it should be split. - * - * @deprecated The macro will be removed in 0.3.0. Use the function instead. - */ -const MAX_MESSAGE_LENGTH = 1372; - -/** - * Maximum size of custom packets. TODO(iphydf): should be LENGTH? - * - * @deprecated The macro will be removed in 0.3.0. Use the function instead. - */ -const MAX_CUSTOM_PACKET_SIZE = 1373; - -/** - * The number of bytes in a hash generated by $hash. - */ -const HASH_LENGTH = 32; - -/** - * The number of bytes in a file id. - */ -const FILE_ID_LENGTH = 32; - -/** - * Maximum file name length for file transfers. - * - * @deprecated The macro will be removed in 0.3.0. Use the function instead. - */ -const MAX_FILENAME_LENGTH = 255; - -/** - * Maximum length of a hostname, e.g. proxy or bootstrap node names. - * - * This length does not include the NUL byte. Hostnames are NUL-terminated C - * strings, so they are 255 characters plus one NUL byte. - * - * @deprecated The macro will be removed in 0.3.0. Use the function instead. - */ -const MAX_HOSTNAME_LENGTH = 255; - - -/******************************************************************************* - * - * :: Global enumerations - * - ******************************************************************************/ - - -/** - * Represents the possible statuses a client can have. - * - * @deprecated All UPPER_CASE enum type names are deprecated. Use the - * Camel_Snake_Case versions, instead. - */ -enum class USER_STATUS { - /** - * User is online and available. - */ - NONE, - /** - * User is away. Clients can set this e.g. after a user defined - * inactivity time. - */ - AWAY, - /** - * User is busy. Signals to other clients that this client does not - * currently wish to communicate. - */ - BUSY, -} - - -/** - * Represents message types for ${tox.friend.send.message} and conference - * messages. - * - * @deprecated All UPPER_CASE enum type names are deprecated. Use the - * Camel_Snake_Case versions, instead. - */ -enum class MESSAGE_TYPE { - /** - * Normal text message. Similar to PRIVMSG on IRC. - */ - NORMAL, - /** - * A message describing an user action. This is similar to /me (CTCP ACTION) - * on IRC. - */ - ACTION, -} - - -/******************************************************************************* - * - * :: Startup options - * - ******************************************************************************/ - - -/** - * Type of proxy used to connect to TCP relays. - * - * @deprecated All UPPER_CASE enum type names are deprecated. Use the - * Camel_Snake_Case versions, instead. - */ -enum class PROXY_TYPE { - /** - * Don't use a proxy. - */ - NONE, - /** - * HTTP proxy using CONNECT. - */ - HTTP, - /** - * SOCKS proxy for simple socket pipes. - */ - SOCKS5, -} - -/** - * Type of savedata to create the Tox instance from. - * - * @deprecated All UPPER_CASE enum type names are deprecated. Use the - * Camel_Snake_Case versions, instead. - */ -enum class SAVEDATA_TYPE { - /** - * No savedata. - */ - NONE, - /** - * Savedata is one that was obtained from ${savedata.get}. - */ - TOX_SAVE, - /** - * Savedata is a secret key of length $SECRET_KEY_SIZE. - */ - SECRET_KEY, -} - - -/** - * Severity level of log messages. - * - * @deprecated All UPPER_CASE enum type names are deprecated. Use the - * Camel_Snake_Case versions, instead. - */ -enum class LOG_LEVEL { - /** - * Very detailed traces including all network activity. - */ - TRACE, - /** - * Debug messages such as which port we bind to. - */ - DEBUG, - /** - * Informational log messages such as video call status changes. - */ - INFO, - /** - * Warnings about internal inconsistency or logic errors. - */ - WARNING, - /** - * Severe unexpected errors caused by external or internal inconsistency. - */ - ERROR, -} - -/** - * This event is triggered when the toxcore library logs an internal message. - * This is mostly useful for debugging. This callback can be called from any - * function, not just $iterate. This means the user data lifetime must at - * least extend between registering and unregistering it or $kill. - * - * Other toxcore modules such as toxav may concurrently call this callback at - * any time. Thus, user code must make sure it is equipped to handle concurrent - * execution, e.g. by employing appropriate mutex locking. - * - * @param level The severity of the log message. - * @param file The source file from which the message originated. - * @param line The source line from which the message originated. - * @param func The function from which the message originated. - * @param message The log message. - * @param user_data The user data pointer passed to $new in options. - */ -typedef void log_cb(LOG_LEVEL level, string file, uint32_t line, string func, string message, any user_data); - - -static class options { - /** - * This struct contains all the startup options for Tox. You must $new to - * allocate an object of this type. - * - * WARNING: Although this struct happens to be visible in the API, it is - * effectively private. Do not allocate this yourself or access members - * directly, as it *will* break binary compatibility frequently. - * - * @deprecated The memory layout of this struct (size, alignment, and field - * order) is not part of the ABI. To remain compatible, prefer to use $new to - * allocate the object and accessor functions to set the members. The struct - * will become opaque (i.e. the definition will become private) in v0.3.0. - */ - struct this [get, set] { - /** - * The type of socket to create. - * - * If this is set to false, an IPv4 socket is created, which subsequently - * only allows IPv4 communication. - * If it is set to true, an IPv6 socket is created, allowing both IPv4 and - * IPv6 communication. - */ - bool ipv6_enabled; - - /** - * 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. - * - * If a proxy is enabled, UDP will be disabled if either toxcore or the - * proxy don't support proxying UDP messages. - */ - bool udp_enabled; - - /** - * Enable local network peer discovery. - * - * Disabling this will cause Tox to not look for peers on the local network. - */ - bool local_discovery_enabled; - - namespace proxy { - /** - * Pass communications through a proxy. - */ - PROXY_TYPE type; - - /** - * 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 $MAX_HOSTNAME_LENGTH characters, and be in a NUL-terminated C string - * format ($MAX_HOSTNAME_LENGTH includes the NUL byte). - * - * This member is ignored (it can be NULL) if proxy_type is ${PROXY_TYPE.NONE}. - * - * The data pointed at by this member is owned by the user, so must - * outlive the options object. - */ - string host; - - /** - * The port to use to connect to the proxy server. - * - * Ports must be in the range (1, 65535). The value is ignored if - * proxy_type is ${PROXY_TYPE.NONE}. - */ - uint16_t port; - } - - /** - * The start port of the inclusive port range to attempt to use. - * - * If both start_port and end_port are 0, the default port range will be - * used: [33445, 33545]. - * - * 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. - */ - uint16_t start_port; - - /** - * The end port of the inclusive port range to attempt to use. - */ - uint16_t end_port; - - /** - * The port to use for the TCP server (relay). If 0, the TCP server is - * disabled. - * - * Enabling it is not required for Tox to function properly. - * - * When enabled, your Tox instance can act as a TCP relay for other Tox - * instance. This leads to increased traffic, thus when writing a client - * it is recommended to enable TCP server only if the user has an option - * to disable it. - */ - uint16_t tcp_port; - - /** - * Enables or disables UDP hole-punching in toxcore. (Default: enabled). - */ - bool hole_punching_enabled; - - namespace savedata { - /** - * The type of savedata to load from. - */ - SAVEDATA_TYPE type; - - /** - * The savedata. - * - * The data pointed at by this member is owned by the user, so must - * outlive the options object. - */ - const uint8_t[length] data; - - /** - * The length of the savedata. - */ - size_t length; - } - - namespace log { - /** - * Logging callback for the new tox instance. - */ - log_cb *callback; - - /** - * User data pointer passed to the logging callback. - */ - any user_data; - } - - /** - * These options are experimental, so avoid writing code that depends on - * them. Options marked "experimental" may change their behaviour or go away - * entirely in the future, or may be renamed to something non-experimental - * if they become part of the supported API. - */ - namespace experimental { - /** - * Make public API functions thread-safe using a per-instance lock. - * - * Default: false. - */ - bool thread_safety; - } - } - - - /** - * Initialises a $this object with the default options. - * - * The result of this function is independent of the original options. All - * values will be overwritten, no values will be read (so it is permissible - * to pass an uninitialised object). - * - * If options is NULL, this function has no effect. - * - * @param options An options object to be filled with default options. - */ - void default(); - - - /** - * Allocates a new $this object and initialises it with the default - * options. This function can be used to preserve long term ABI compatibility by - * giving the responsibility of allocation and deallocation to the Tox library. - * - * Objects returned from this function must be freed using the $free - * function. - * - * @return A new $this object with default options or NULL on failure. - */ - static this new() { - /** - * The function failed to allocate enough memory for the options struct. - */ - MALLOC, - } - - - /** - * Releases all resources associated with an options objects. - * - * Passing a pointer that was not returned by $new results in - * undefined behaviour. - */ - void free(); -} - - -/******************************************************************************* - * - * :: Creation and destruction - * - ******************************************************************************/ - - -/** - * @brief Creates and initialises a new Tox instance with the options passed. - * - * This function will bring the instance into a valid state. Running the event - * loop with a new instance will operate correctly. - * - * If loading failed or succeeded only partially, the new or partially loaded - * instance is returned and an error code is set. - * - * @param options An options object as described above. If this parameter is - * NULL, the default options are used. - * - * @see $iterate for the event loop. - * - * @return A new Tox instance pointer on success or NULL on failure. - */ -static this new(const options_t *options) { - NULL, - /** - * The function was unable to allocate enough memory to store the internal - * structures for the Tox object. - */ - 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. - */ - PORT_ALLOC, - - namespace PROXY { - /** - * proxy_type was invalid. - */ - BAD_TYPE, - /** - * proxy_type was valid but the proxy_host passed had an invalid format - * or was NULL. - */ - BAD_HOST, - /** - * proxy_type was valid, but the proxy_port was invalid. - */ - BAD_PORT, - /** - * The proxy address passed could not be resolved. - */ - NOT_FOUND, - } - - namespace LOAD { - /** - * The byte array to be loaded contained an encrypted save. - */ - ENCRYPTED, - /** - * The data format was invalid. This can happen when loading data that was - * saved by an older version of Tox, or when the data has been corrupted. - * When loading from badly formatted data, some data may have been loaded, - * and the rest is discarded. Passing an invalid length parameter also - * causes this error. - */ - BAD_FORMAT, - } -} - - -/** - * Releases all resources associated with the Tox instance and disconnects from - * the network. - * - * After calling this function, the Tox pointer becomes invalid. No other - * functions can be called, and the pointer value can no longer be read. - */ -void kill(); - - -uint8_t[size] savedata { - /** - * Calculates the number of bytes required to store the tox instance with - * $get. This function cannot fail. The result is always greater than 0. - * - * @see threading for concurrency implications. - */ - size(); - - /** - * 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 $size to find the number of bytes required. If this parameter - * is NULL, this function has no effect. - */ - get(); -} - - -/******************************************************************************* - * - * :: Connection lifecycle and event loop - * - ******************************************************************************/ - - -/** - * Sends a "get nodes" request to the given bootstrap node with IP, port, and - * public key to setup connections. - * - * This function will attempt to connect to the node using UDP. You must use - * this function even if ${options.this.udp_enabled} was set to false. - * - * @param host The hostname or IP address (IPv4 or IPv6) of the node. Must be - * at most $MAX_HOSTNAME_LENGTH chars, including the NUL byte. - * @param port The port on the host on which the bootstrap Tox instance is - * listening. - * @param public_key The long term public key of the bootstrap node - * ($PUBLIC_KEY_SIZE bytes). - * @return true on success. - */ -bool bootstrap(string host, uint16_t port, const uint8_t[PUBLIC_KEY_SIZE] public_key) { - NULL, - /** - * The hostname could not be resolved to an IP address, or the IP address - * passed was invalid. - */ - BAD_HOST, - /** - * The port passed was invalid. The valid port range is (1, 65535). - */ - BAD_PORT, -} - - -/** - * Adds additional host:port pair as TCP relay. - * - * This function can be used to initiate TCP connections to different ports on - * the same bootstrap node, or to add TCP relays without using them as - * bootstrap nodes. - * - * @param host The hostname or IP address (IPv4 or IPv6) of the TCP relay. - * Must be at most $MAX_HOSTNAME_LENGTH chars, including the NUL byte. - * @param port The port on the host on which the TCP relay is listening. - * @param public_key The long term public key of the TCP relay - * ($PUBLIC_KEY_SIZE bytes). - * @return true on success. - */ -bool add_tcp_relay(string host, uint16_t port, const uint8_t[PUBLIC_KEY_SIZE] public_key) - with error for bootstrap; - - -/** - * Protocols that can be used to connect to the network or friends. - * - * @deprecated All UPPER_CASE enum type names are deprecated. Use the - * Camel_Snake_Case versions, instead. - */ -enum class CONNECTION { - /** - * There is no connection. This instance, or the friend the state change is - * about, is now offline. - */ - NONE, - /** - * A TCP connection has been established. For the own instance, this means it - * is connected through a TCP relay, only. For a friend, this means that the - * connection to that particular friend goes through a TCP relay. - */ - TCP, - /** - * A UDP connection has been established. For the own instance, this means it - * is able to send UDP packets to DHT nodes, but may still be connected to - * a TCP relay. For a friend, this means that the connection to that - * particular friend was built using direct UDP packets. - */ - UDP, -} - - -namespace self { - - CONNECTION connection_status { - /** - * Return whether we are connected to the DHT. The return value is equal to the - * last value received through the `${event connection_status}` callback. - * - * @deprecated This getter is deprecated. Use the event and store the status - * in the client state. - */ - get(); - } - - - /** - * This event is triggered whenever there is a change in the DHT connection - * state. When disconnected, a client may choose to call $bootstrap again, to - * reconnect to the DHT. Note that this state may frequently change for short - * amounts of time. Clients should therefore not immediately bootstrap on - * receiving a disconnect. - * - * TODO(iphydf): how long should a client wait before bootstrapping again? - */ - event connection_status const { - /** - * @param connection_status Whether we are connected to the DHT. - */ - typedef void(CONNECTION connection_status); - } - -} - - -/** - * Return the time in milliseconds before $iterate() should be called again - * for optimal performance. - */ -const uint32_t iteration_interval(); - - -/** - * The main loop that needs to be run in intervals of $iteration_interval() - * milliseconds. - */ -void iterate(any user_data); - - -/******************************************************************************* - * - * :: Internal client information (Tox address/id) - * - ******************************************************************************/ - - -namespace self { - - uint8_t[ADDRESS_SIZE] address { - /** - * Writes the Tox friend address of the client to a byte array. The address is - * not in human-readable format. If a client wants to display the address, - * formatting is required. - * - * @param address A memory region of at least $ADDRESS_SIZE bytes. If this - * parameter is NULL, this function has no effect. - * @see $ADDRESS_SIZE for the address format. - */ - get(); - } - - - uint32_t nospam { - /** - * Set the 4-byte nospam part of the address. This value is expected in host - * byte order. I.e. 0x12345678 will form the bytes [12, 34, 56, 78] in the - * nospam part of the Tox friend address. - * - * @param nospam Any 32 bit unsigned integer. - */ - set(); - - /** - * Get the 4-byte nospam part of the address. This value is returned in host - * byte order. - */ - get(); - } - - - uint8_t[PUBLIC_KEY_SIZE] public_key { - /** - * Copy the Tox Public Key (long term) from the Tox object. - * - * @param public_key A memory region of at least $PUBLIC_KEY_SIZE bytes. If - * this parameter is NULL, this function has no effect. - */ - get(); - } - - - uint8_t[SECRET_KEY_SIZE] secret_key { - /** - * Copy the Tox Secret Key from the Tox object. - * - * @param secret_key A memory region of at least $SECRET_KEY_SIZE bytes. If - * this parameter is NULL, this function has no effect. - */ - get(); - } - -} - - -/******************************************************************************* - * - * :: User-visible client information (nickname/status) - * - ******************************************************************************/ - - -/** - * Common error codes for all functions that set a piece of user-visible - * client information. - */ -error for set_info { - NULL, - /** - * Information length exceeded maximum permissible size. - */ - TOO_LONG, -} - - -namespace self { - - uint8_t[length <= MAX_NAME_LENGTH] name { - /** - * Set the nickname for the Tox client. - * - * Nickname length cannot exceed $MAX_NAME_LENGTH. If length is 0, the name - * parameter is ignored (it can be NULL), and the nickname is set back to empty. - * - * @param name A byte array containing the new nickname. - * @param length The size of the name byte array. - * - * @return true on success. - */ - set() with error for set_info; - - /** - * Return the length of the current nickname as passed to $set. - * - * If no nickname was set before calling this function, the name is empty, - * and this function returns 0. - * - * @see threading for concurrency implications. - */ - size(); - - /** - * Write the nickname set by $set to a byte array. - * - * If no nickname was set before calling this function, the name is empty, - * and this function has no effect. - * - * Call $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. - */ - get(); - } - - - uint8_t[length <= MAX_STATUS_MESSAGE_LENGTH] status_message { - /** - * Set the client's status message. - * - * Status message length cannot exceed $MAX_STATUS_MESSAGE_LENGTH. If - * length is 0, the status parameter is ignored (it can be NULL), and the - * user status is set back to empty. - */ - set() with error for set_info; - - /** - * Return the length of the current status message as passed to $set. - * - * If no status message was set before calling this function, the status - * is empty, and this function returns 0. - * - * @see threading for concurrency implications. - */ - size(); - - /** - * Write the status message set by $set 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 $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. - */ - get(); - } - - - USER_STATUS status { - /** - * Set the client's user status. - * - * @param status One of the user statuses listed in the enumeration above. - */ - set(); - - /** - * Returns the client's user status. - */ - get(); - } - -} - - -/******************************************************************************* - * - * :: Friend list management - * - ******************************************************************************/ - - -namespace friend { - - /** - * Add a friend to the friend list and send a friend request. - * - * A friend request message must be at least 1 byte long and at most - * $MAX_FRIEND_REQUEST_LENGTH. - * - * Friend numbers are unique identifiers used in all functions that operate on - * friends. Once added, a friend number is stable for the lifetime of the Tox - * object. After saving the state and reloading it, the friend numbers may not - * be the same as before. Deleting a friend creates a gap in the friend number - * set, which is filled by the next adding of a friend. Any pattern in friend - * numbers should not be relied on. - * - * If more than INT32_MAX friends are added, this function causes undefined - * behaviour. - * - * @param address The address of the friend (returned by ${self.address.get} of - * the friend you wish to add) it must be $ADDRESS_SIZE bytes. - * @param message The message that will be sent along with the friend request. - * @param length The length of the data byte array. - * - * @return the friend number on success, an unspecified value on failure. - */ - uint32_t add( - const uint8_t[ADDRESS_SIZE] address, - const uint8_t[length <= MAX_FRIEND_REQUEST_LENGTH] message - ) { - NULL, - /** - * The length of the friend request message exceeded - * $MAX_FRIEND_REQUEST_LENGTH. - */ - TOO_LONG, - /** - * The friend request message was empty. This, and the TOO_LONG code will - * never be returned from $add_norequest. - */ - NO_MESSAGE, - /** - * The friend address belongs to the sending client. - */ - OWN_KEY, - /** - * A friend request has already been sent, or the address belongs to a friend - * that is already on the friend list. - */ - ALREADY_SENT, - /** - * The friend address checksum failed. - */ - BAD_CHECKSUM, - /** - * The friend was already there, but the nospam value was different. - */ - SET_NEW_NOSPAM, - /** - * A memory allocation failed when trying to increase the friend list size. - */ - MALLOC, - } - - - /** - * Add a friend without sending a friend request. - * - * This function is used to add a friend in response to a friend request. If the - * client receives a friend request, it can be reasonably sure that the other - * client added this client as a friend, eliminating the need for a friend - * request. - * - * This function is also useful in a situation where both instances are - * controlled by the same entity, so that this entity can perform the mutual - * friend adding. In this case, there is no need for a friend request, either. - * - * @param public_key A byte array of length $PUBLIC_KEY_SIZE containing the - * Public Key (not the Address) of the friend to add. - * - * @return the friend number on success, an unspecified value on failure. - * @see $add for a more detailed description of friend numbers. - */ - uint32_t add_norequest(const uint8_t[PUBLIC_KEY_SIZE] public_key) - with error for add; - - - /** - * Remove a friend from the friend list. - * - * This does not notify the friend of their deletion. After calling this - * function, this client will appear offline to the friend and no communication - * can occur between the two. - * - * @param friend_number Friend number for the friend to be deleted. - * - * @return true on success. - */ - bool delete(uint32_t friend_number) { - /** - * There was no friend with the given friend number. No friends were deleted. - */ - FRIEND_NOT_FOUND, - } - -} - - -/******************************************************************************* - * - * :: Friend list queries - * - ******************************************************************************/ - -namespace friend { - - /** - * 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. - */ - const uint32_t by_public_key(const uint8_t[PUBLIC_KEY_SIZE] public_key) { - NULL, - /** - * No friend with the given Public Key exists on the friend list. - */ - NOT_FOUND, - } - - - /** - * Checks if a friend with the given friend number exists and returns true if - * it does. - */ - const bool exists(uint32_t friend_number); - -} - -namespace self { - - uint32_t[size] friend_list { - /** - * Return the number of friends on the friend list. - * - * This function can be used to determine how much memory to allocate for - * $get. - */ - size(); - - - /** - * Copy a list of valid friend numbers into an array. - * - * Call $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. - */ - get(); - } - -} - - - -namespace friend { - - uint8_t[PUBLIC_KEY_SIZE] public_key { - /** - * 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 $PUBLIC_KEY_SIZE bytes. If - * this parameter is NULL, this function has no effect. - * - * @return true on success. - */ - get(uint32_t friend_number) { - /** - * No friend with the given number exists on the friend list. - */ - FRIEND_NOT_FOUND, - } - } - -} - -namespace friend { - - uint64_t last_online { - /** - * 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. - * - * @param friend_number The friend number you want to query. - */ - get(uint32_t friend_number) { - /** - * No friend with the given number exists on the friend list. - */ - FRIEND_NOT_FOUND, - } - } - -} - -/******************************************************************************* - * - * :: Friend-specific state queries (can also be received through callbacks) - * - ******************************************************************************/ - - -namespace friend { - - /** - * Common error codes for friend state query functions. - */ - error for 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, - /** - * The friend_number did not designate a valid friend. - */ - FRIEND_NOT_FOUND, - } - - - uint8_t[length <= MAX_NAME_LENGTH] name { - /** - * Return the length of the friend's name. If the friend number is invalid, the - * return value is unspecified. - * - * The return value is equal to the `length` argument received by the last - * `${event name}` callback. - */ - size(uint32_t friend_number) - with error for query; - - /** - * Write the name of the friend designated by the given friend number to a byte - * array. - * - * Call $size to determine the allocation size for the `name` - * parameter. - * - * The data written to `name` is equal to the data received by the last - * `${event name}` callback. - * - * @param name A valid memory region large enough to store the friend's name. - * - * @return true on success. - */ - get(uint32_t friend_number) - with error for query; - } - - - /** - * This event is triggered when a friend changes their name. - */ - event name const { - /** - * @param friend_number The friend number of the friend whose name changed. - * @param name A byte array containing the same data as - * ${name.get} would write to its `name` parameter. - * @param length A value equal to the return value of - * ${name.size}. - */ - typedef void(uint32_t friend_number, const uint8_t[length <= MAX_NAME_LENGTH] name); - } - - - uint8_t[length <= MAX_STATUS_MESSAGE_LENGTH] status_message { - /** - * Return the length of the friend's status message. If the friend number is - * invalid, the return value is SIZE_MAX. - */ - size(uint32_t friend_number) - with error for query; - - /** - * Write the status message of the friend designated by the given friend number to a byte - * array. - * - * Call $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 - * `${event status_message}` callback. - * - * @param status_message A valid memory region large enough to store the friend's status message. - */ - get(uint32_t friend_number) - with error for query; - } - - - /** - * This event is triggered when a friend changes their status message. - */ - event status_message const { - /** - * @param friend_number The friend number of the friend whose status message - * changed. - * @param message A byte array containing the same data as - * ${status_message.get} would write to its `status_message` parameter. - * @param length A value equal to the return value of - * ${status_message.size}. - */ - typedef void(uint32_t friend_number, const uint8_t[length <= MAX_STATUS_MESSAGE_LENGTH] message); - } - - - USER_STATUS status { - /** - * Return the friend's user status (away/busy/...). If the friend number is - * invalid, the return value is unspecified. - * - * The status returned is equal to the last status received through the - * `${event status}` callback. - * - * @deprecated This getter is deprecated. Use the event and store the status - * in the client state. - */ - get(uint32_t friend_number) - with error for query; - } - - - /** - * This event is triggered when a friend changes their user status. - */ - event status const { - /** - * @param friend_number The friend number of the friend whose user status - * changed. - * @param status The new user status. - */ - typedef void(uint32_t friend_number, USER_STATUS status); - } - - - CONNECTION connection_status { - /** - * Check whether a friend is currently connected to this client. - * - * The result of this function is equal to the last value received by the - * `${event connection_status}` callback. - * - * @param friend_number The friend number for which to query the connection - * status. - * - * @return the friend's connection status as it was received through the - * `${event connection_status}` event. - * - * @deprecated This getter is deprecated. Use the event and store the status - * in the client state. - */ - get(uint32_t friend_number) - with error for query; - } - - - /** - * This event is triggered when a friend goes offline after having been online, - * or when a friend goes online. - * - * This callback is not called when adding friends. It is assumed that when - * adding friends, their connection status is initially offline. - */ - event connection_status const { - /** - * @param friend_number The friend number of the friend whose connection status - * changed. - * @param connection_status The result of calling - * ${connection_status.get} on the passed friend_number. - */ - typedef void(uint32_t friend_number, CONNECTION connection_status); - } - - - bool typing { - /** - * Check whether a friend is currently typing a message. - * - * @param friend_number The friend number for which to query the typing status. - * - * @return true if the friend is typing. - * @return false if the friend is not typing, or the friend number was - * invalid. Inspect the error code to determine which case it is. - * - * @deprecated This getter is deprecated. Use the event and store the status - * in the client state. - */ - get(uint32_t friend_number) - with error for query; - } - - - /** - * This event is triggered when a friend starts or stops typing. - */ - event typing const { - /** - * @param friend_number The friend number of the friend who started or stopped - * typing. - * @param is_typing The result of calling ${typing.get} on the passed - * friend_number. - */ - typedef void(uint32_t friend_number, bool is_typing); - } - -} - - -/******************************************************************************* - * - * :: Sending private messages - * - ******************************************************************************/ - -error for set_typing { - /** - * The friend number did not designate a valid friend. - */ - FRIEND_NOT_FOUND, -} - -namespace self { - - bool typing { - /** - * Set the client's typing status for a friend. - * - * The client is responsible for turning it on or off. - * - * @param friend_number The friend to which the client is typing a message. - * @param typing The typing status. True means the client is typing. - * - * @return true on success. - */ - set(uint32_t friend_number) with error for set_typing; - } - -} - - -namespace friend { - - namespace send { - - /** - * Send a text chat message to an online friend. - * - * This function creates a chat message packet and pushes it into the send - * queue. - * - * The message length may not exceed $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 return value of this function is the message ID. If a read receipt is - * received, the triggered `${event 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 - * sent, the next message ID is 0. - * - * @param type Message type (normal, action, ...). - * @param friend_number The friend number of the friend to send the message to. - * @param message A non-NULL pointer to the first element of a byte array - * containing the message text. - * @param length Length of the message to be sent. - */ - uint32_t message(uint32_t friend_number, MESSAGE_TYPE type, - const uint8_t[length <= MAX_MESSAGE_LENGTH] message) { - NULL, - /** - * The friend number did not designate a valid friend. - */ - FRIEND_NOT_FOUND, - /** - * This client is currently not connected to the friend. - */ - FRIEND_NOT_CONNECTED, - /** - * An allocation error occurred while increasing the send queue size. - */ - SENDQ, - /** - * Message length exceeded $MAX_MESSAGE_LENGTH. - */ - TOO_LONG, - /** - * Attempted to send a zero-length message. - */ - EMPTY, - } - - } - - - /** - * This event is triggered when the friend receives the message sent with - * ${send.message} with the corresponding message ID. - */ - event read_receipt const { - /** - * @param friend_number The friend number of the friend who received the message. - * @param message_id The message ID as returned from ${send.message} - * corresponding to the message sent. - */ - typedef void(uint32_t friend_number, uint32_t message_id); - } - -} - - -/******************************************************************************* - * - * :: Receiving private messages and friend requests - * - ******************************************************************************/ - - -namespace friend { - - /** - * This event is triggered when a friend request is received. - */ - event request const { - /** - * @param public_key The Public Key of the user who sent the friend request. - * @param message The message they sent along with the request. - * @param length The size of the message byte array. - */ - typedef void(const uint8_t[PUBLIC_KEY_SIZE] public_key, - const uint8_t[length <= MAX_MESSAGE_LENGTH] message); - } - - - /** - * This event is triggered when a message from a friend is received. - */ - event message const { - /** - * @param friend_number The friend number of the friend who sent the message. - * @param message The message data they sent. - * @param length The size of the message byte array. - */ - typedef void(uint32_t friend_number, MESSAGE_TYPE type, - const uint8_t[length <= MAX_MESSAGE_LENGTH] message); - } - -} - - -/******************************************************************************* - * - * :: File transmission: common between sending and receiving - * - ******************************************************************************/ - - -/** - * Generates a cryptographic hash of the given data. - * - * This function may be used by clients for any purpose, but is provided - * 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. - * - * This function is a wrapper to internal message-digest functions. - * - * @param hash A valid memory location the hash data. It must be at least - * $HASH_LENGTH bytes in size. - * @param data Data to be hashed or NULL. - * @param length Size of the data array or 0. - * - * @return true if hash was not NULL. - */ -static bool hash(uint8_t[HASH_LENGTH] hash, const uint8_t[length] data); - - -namespace file { - - /** - * 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 `uint32_t`, not $KIND, because - * clients can invent their own file kind. Unknown file kinds should be - * treated as ${KIND.DATA}. - */ - enum KIND { - /** - * Arbitrary file data. Clients can choose to handle it based on the file name - * or magic or any other way they choose. - */ - DATA, - /** - * Avatar file_id. This consists of $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. - * - * Clients who receive avatar send requests can reject it (by sending - * ${CONTROL.CANCEL} before any other controls), or accept it (by - * sending ${CONTROL.RESUME}). The file_id of length $HASH_LENGTH bytes - * (same length as $FILE_ID_LENGTH) will contain the hash. A client can compare - * this hash with a saved hash and send ${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. - */ - AVATAR, - } - - - enum class CONTROL { - /** - * Sent by the receiving side to accept a file send request. Also sent after a - * $PAUSE command to continue sending or receiving. - */ - 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 $RESUME for the transfer to resume. - */ - PAUSE, - /** - * Sent by the receiving side to reject a file send request before any other - * commands are sent. Also sent by either side to terminate a file transfer. - */ - CANCEL, - } - - - /** - * Sends a file control command to a friend for a given file transfer. - * - * @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 control The control command to send. - * - * @return true on success. - */ - bool control(uint32_t friend_number, uint32_t file_number, CONTROL control) { - /** - * The friend_number passed did not designate a valid friend. - */ - FRIEND_NOT_FOUND, - /** - * This client is currently not connected to the friend. - */ - FRIEND_NOT_CONNECTED, - /** - * No file transfer with the given file number was found for the given friend. - */ - NOT_FOUND, - /** - * A RESUME control was sent, but the file transfer is running normally. - */ - NOT_PAUSED, - /** - * A RESUME control was sent, but the file transfer was paused by the other - * party. Only the party that paused the transfer can resume it. - */ - DENIED, - /** - * A PAUSE control was sent, but the file transfer was already paused. - */ - ALREADY_PAUSED, - /** - * Packet queue is full. - */ - SENDQ, - } - - - /** - * This event is triggered when a file control command is received from a - * friend. - */ - event recv_control const { - /** - * When receiving ${CONTROL.CANCEL}, the client should release the - * resources associated with the file number and consider the transfer failed. - * - * @param friend_number The friend number of the friend who is sending the file. - * @param file_number The friend-specific file number the data received is - * associated with. - * @param control The file control command received. - */ - typedef void(uint32_t friend_number, uint32_t file_number, CONTROL control); - } - - /** - * 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 - * ${CONTROL.RESUME} is sent. - * - * @param friend_number The friend number of the friend the file is being - * received from. - * @param file_number The friend-specific identifier for the file transfer. - * @param position The position that the file should be seeked to. - */ - bool seek(uint32_t friend_number, uint32_t file_number, uint64_t position) { - /** - * The friend_number passed did not designate a valid friend. - */ - FRIEND_NOT_FOUND, - /** - * This client is currently not connected to the friend. - */ - FRIEND_NOT_CONNECTED, - /** - * No file transfer with the given file number was found for the given friend. - */ - NOT_FOUND, - /** - * File was not in a state where it could be seeked. - */ - DENIED, - /** - * Seek position was invalid - */ - INVALID_POSITION, - /** - * Packet queue is full. - */ - SENDQ, - } - - - error for get { - NULL, - /** - * The friend_number passed did not designate a valid friend. - */ - FRIEND_NOT_FOUND, - /** - * No file transfer with the given file number was found for the given friend. - */ - NOT_FOUND, - } - - uint8_t[FILE_ID_LENGTH] file_id { - /** - * Copy the file id associated to the file transfer to a byte array. - * - * @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 $FILE_ID_LENGTH bytes. If - * this parameter is NULL, this function has no effect. - * - * @return true on success. - */ - get(uint32_t friend_number, uint32_t file_number) - with error for get; - } - -} - - -/******************************************************************************* - * - * :: File transmission: sending - * - ******************************************************************************/ - - -namespace file { - - /** - * Send a file transmission request. - * - * Maximum filename length is $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 streaming - * data of unknown size. - * - * File transmission occurs in chunks, which are requested through the - * `${event chunk_request}` event. - * - * When a friend goes offline, all file transfers associated with the friend are - * purged from core. - * - * 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 - * was modified and how the client determines the file size. - * - * - 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 - * ${event 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. - * - 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 - * cancelled. - * - If the file contents were modified - * - at a position before the current read, the two files (local and remote) - * will differ after the transfer terminates. - * - at a position after the current read, the file transfer will succeed as - * expected. - * - In either case, both sides will regard the transfer as complete and - * successful. - * - * @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 $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 ${file_id.get}(). - * @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. - */ - uint32_t send(uint32_t friend_number, uint32_t kind, uint64_t file_size, - const uint8_t[FILE_ID_LENGTH] file_id, - const uint8_t[filename_length <= MAX_FILENAME_LENGTH] filename) { - NULL, - /** - * The friend_number passed did not designate a valid friend. - */ - FRIEND_NOT_FOUND, - /** - * This client is currently not connected to the friend. - */ - FRIEND_NOT_CONNECTED, - /** - * Filename length exceeded $MAX_FILENAME_LENGTH bytes. - */ - 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, - } - - - /** - * Send a chunk of file data to a friend. - * - * This function is called in response to the `${event 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 - * 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. - * - * @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. - * @param position The file or stream position from which to continue reading. - * @return true on success. - */ - bool send_chunk(uint32_t friend_number, uint32_t file_number, uint64_t position, const uint8_t[length] data) { - /** - * The length parameter was non-zero, but data was NULL. - */ - NULL, - /** - * The friend_number passed did not designate a valid friend. - */ - FRIEND_NOT_FOUND, - /** - * This client is currently not connected to the friend. - */ - FRIEND_NOT_CONNECTED, - /** - * No file transfer with the given file number was found for the given friend. - */ - 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). - */ - 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. - */ - INVALID_LENGTH, - /** - * Packet queue is full. - */ - SENDQ, - /** - * Position parameter was wrong. - */ - WRONG_POSITION, - } - - - /** - * This event is triggered when Core is ready to send more file data. - */ - event chunk_request const { - /** - * If the length parameter is 0, the file transfer is finished, and the client's - * resources associated with the file number should be released. After a call - * with zero length, the file number can be reused for future file transfers. - * - * If the requested position is not equal to the client's idea of the current - * file or stream position, it will need to seek. In case of read-once streams, - * the client should keep the last read chunk so that a seek back can be - * supported. A seek-back only ever needs to read from the last requested chunk. - * This happens when a chunk was requested, but the send failed. A seek-back - * request can occur an arbitrary number of times for any given chunk. - * - * In response to receiving this callback, the client should call the function - * `$send_chunk` with the requested chunk. If the number of bytes sent - * through that function is zero, the file transfer is assumed complete. A - * client must send the full length of data requested with this callback. - * - * @param friend_number The friend number of the receiving friend for this file. - * @param file_number The file transfer identifier returned by $send. - * @param position The file or stream position from which to continue reading. - * @param length The number of bytes requested for the current chunk. - */ - typedef void(uint32_t friend_number, uint32_t file_number, uint64_t position, size_t length); - } - -} - - -/******************************************************************************* - * - * :: File transmission: receiving - * - ******************************************************************************/ - - -namespace file { - - /** - * This event is triggered when a file transfer request is received. - */ - event recv const { - /** - * The client should acquire resources to be associated with the file transfer. - * Incoming file transfers start in the PAUSED state. After this callback - * returns, a transfer can be rejected by sending a ${CONTROL.CANCEL} - * control command before any other control commands. It can be accepted by - * sending ${CONTROL.RESUME}. - * - * @param friend_number The friend number of the friend who is sending the file - * transfer request. - * @param file_number The friend-specific file number the data received is - * associated with. - * @param kind The meaning of the file that was sent. - * @param file_size Size in bytes of the file the client wants to send, - * UINT64_MAX if unknown or streaming. - * @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. - */ - typedef void(uint32_t friend_number, uint32_t file_number, uint32_t kind, - uint64_t file_size, const uint8_t[filename_length <= MAX_FILENAME_LENGTH] filename); - } - - - /** - * This event is first triggered when a file transfer request is received, and - * subsequently when a chunk of file data for an accepted request was received. - */ - event recv_chunk const { - /** - * When length is 0, the transfer is finished and the client should release the - * resources it acquired for the transfer. After a call with length = 0, the - * file number can be reused for new file transfers. - * - * If position is equal to file_size (received in the file_receive callback) - * when the transfer finishes, the file was received completely. Otherwise, if - * file_size was UINT64_MAX, streaming ended successfully when length is 0. - * - * @param friend_number The friend number of the friend who is sending the file. - * @param file_number The friend-specific file number the data received is - * associated with. - * @param position The file position of the first byte in data. - * @param data A byte array containing the received chunk. - * @param length The length of the received chunk. - */ - typedef void(uint32_t friend_number, uint32_t file_number, uint64_t position, - const uint8_t[length] data); - } - -} - - -/******************************************************************************* - * - * :: Conference management - * - ******************************************************************************/ - -namespace conference { - - /** - * Conference types for the ${event invite} event. - * - * @deprecated All UPPER_CASE enum type names are deprecated. Use the - * Camel_Snake_Case versions, instead. - */ - enum class TYPE { - /** - * Text-only conferences that must be accepted with the $join function. - */ - TEXT, - /** - * Video conference. The function to accept these is in toxav. - */ - AV, - } - - - /** - * This event is triggered when the client is invited to join a conference. - */ - event invite const { - /** - * The invitation will remain valid until the inviting friend goes offline - * or exits the conference. - * - * @param friend_number The friend who invited us. - * @param type The conference type (text only or audio/video). - * @param cookie A piece of data of variable length required to join the - * conference. - * @param length The length of the cookie. - */ - typedef void(uint32_t friend_number, TYPE type, const uint8_t[length] cookie); - } - - - /** - * This event is triggered when the client successfully connects to a - * conference after joining it with the $join function. - */ - event connected const { - /** - * @param conference_number The conference number of the conference to which we have connected. - */ - typedef void(uint32_t conference_number); - } - - - /** - * This event is triggered when the client receives a conference message. - */ - event message const { - /** - * @param conference_number The conference number of the conference the message is intended for. - * @param peer_number The ID of the peer who sent the message. - * @param type The type of message (normal, action, ...). - * @param message The message data. - * @param length The length of the message. - */ - typedef void(uint32_t conference_number, uint32_t peer_number, MESSAGE_TYPE type, - const uint8_t[length] message); - } - - - /** - * 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). - */ - event title const { - /** - * @param conference_number The conference number of the conference the title change is intended for. - * @param peer_number The ID of the peer who changed the title. - * @param title The title data. - * @param length The title length. - */ - typedef void(uint32_t conference_number, uint32_t peer_number, const uint8_t[length] title); - } - - namespace peer { - - /** - * This event is triggered when a peer changes their name. - */ - event name const { - /** - * @param conference_number The conference number of the conference the - * peer is in. - * @param peer_number The ID of the peer who changed their nickname. - * @param name A byte array containing the new nickname. - * @param length The size of the name byte array. - */ - typedef void(uint32_t conference_number, uint32_t peer_number, const uint8_t[length] name); - } - - /** - * This event is triggered when a peer joins or leaves the conference. - */ - event list_changed const { - /** - * @param conference_number The conference number of the conference the - * peer is in. - */ - typedef void(uint32_t conference_number); - } - - } - - - /** - * Creates a new conference. - * - * This function creates and connects to a new text conference. - * - * @return conference number on success, or an unspecified value on failure. - */ - uint32_t new() { - /** - * The conference instance failed to initialize. - */ - INIT, - } - - /** - * This function deletes a conference. - * - * @param conference_number The conference number of the conference to be deleted. - * - * @return true on success. - */ - bool delete(uint32_t conference_number) { - /** - * The conference number passed did not designate a valid conference. - */ - CONFERENCE_NOT_FOUND, - } - - /** - * Error codes for peer info queries. - */ - error for peer_query { - /** - * The conference number passed did not designate a valid conference. - */ - CONFERENCE_NOT_FOUND, - /** - * The peer number passed did not designate a valid peer. - */ - PEER_NOT_FOUND, - /** - * The client is not connected to the conference. - */ - NO_CONNECTION, - } - - - namespace peer { - - /** - * Return the number of online peers in the conference. The unsigned - * integers less than this number are the valid values of peer_number for - * the functions querying these peers. Return value is unspecified on - * failure. - */ - const uint32_t count(uint32_t conference_number) - with error for peer_query; - - uint8_t[size] name { - - /** - * Return the length of the peer's name. Return value is unspecified on failure. - */ - size(uint32_t conference_number, uint32_t peer_number) - with error for peer_query; - - /** - * Copy the name of peer_number who is in conference_number to name. - * - * Call $size to determine the allocation size for the `name` parameter. - * - * @param name A valid memory region large enough to store the peer's name. - * - * @return true on success. - */ - get(uint32_t conference_number, uint32_t peer_number) - with error for peer_query; - } - - /** - * Copy the public key of peer_number who is in conference_number to public_key. - * public_key must be $PUBLIC_KEY_SIZE long. - * - * @return true on success. - */ - uint8_t[PUBLIC_KEY_SIZE] public_key { - get(uint32_t conference_number, uint32_t peer_number) - with error for peer_query; - } - - /** - * Return true if passed peer_number corresponds to our own. - */ - const bool number_is_ours(uint32_t conference_number, uint32_t peer_number) - with error for peer_query; - - } - - namespace offline_peer { - - /** - * Return the number of offline peers in the conference. The unsigned - * integers less than this number are the valid values of offline_peer_number for - * the functions querying these peers. Return value is unspecified on failure. - */ - const uint32_t count(uint32_t conference_number) - with error for peer_query; - - uint8_t[size] name { - - /** - * Return the length of the offline peer's name. Return value is unspecified on failure. - */ - size(uint32_t conference_number, uint32_t offline_peer_number) - with error for peer_query; - - /** - * Copy the name of offline_peer_number who is in conference_number to name. - * - * Call $size to determine the allocation size for the `name` parameter. - * - * @param name A valid memory region large enough to store the peer's name. - * - * @return true on success. - */ - get(uint32_t conference_number, uint32_t offline_peer_number) - with error for peer_query; - } - - /** - * Copy the public key of offline_peer_number who is in conference_number to public_key. - * public_key must be $PUBLIC_KEY_SIZE long. - * - * @return true on success. - */ - uint8_t[PUBLIC_KEY_SIZE] public_key { - get(uint32_t conference_number, uint32_t offline_peer_number) - with error for peer_query; - } - - /** - * Return a unix-time timestamp of the last time offline_peer_number was seen to be active. - */ - uint64_t last_active { - get(uint32_t conference_number, uint32_t offline_peer_number) - with error for peer_query; - } - - } - - /** - * Set maximum number of offline peers to store, overriding the default. - */ - bool set_max_offline(uint32_t conference_number, uint32_t max_offline_peers) { - /** - * The conference number passed did not designate a valid conference. - */ - CONFERENCE_NOT_FOUND, - } - - - /** - * 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. - * - * @return true on success. - */ - bool invite(uint32_t friend_number, uint32_t conference_number) { - /** - * The conference number passed did not designate a valid conference. - */ - CONFERENCE_NOT_FOUND, - /** - * The invite packet failed to send. - */ - FAIL_SEND, - /** - * The client is not connected to the conference. - */ - NO_CONNECTION, - } - - - /** - * Joins a conference that the client has been invited to. - * - * After successfully joining the conference, the client will not be "connected" - * to it until a handshaking procedure has been completed. A - * `${event 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 - * corresponding error if attempted on a conference to which the client is not - * yet connected. - * - * @param friend_number The friend number of the friend who sent the invite. - * @param cookie Received via the `${event invite}` event. - * @param length The size of cookie. - * - * @return conference number on success, an unspecified value on failure. - */ - uint32_t join(uint32_t friend_number, const uint8_t[length] cookie) { - /** - * The cookie passed has an invalid length. - */ - INVALID_LENGTH, - /** - * The conference is not the expected type. This indicates an invalid cookie. - */ - WRONG_TYPE, - /** - * The friend number passed does not designate a valid friend. - */ - FRIEND_NOT_FOUND, - /** - * Client is already in this conference. - */ - DUPLICATE, - /** - * Conference instance failed to initialize. - */ - INIT_FAIL, - /** - * The join packet failed to send. - */ - FAIL_SEND, - } - - - namespace send { - - /** - * Send a text chat message to the conference. - * - * This function creates a conference message packet and pushes it into the send - * queue. - * - * The message length may not exceed $MAX_MESSAGE_LENGTH. Larger messages - * must be split by the client and sent as separate messages. Other clients can - * then reassemble the fragments. - * - * @param conference_number The conference number of the conference the message is intended for. - * @param type Message type (normal, action, ...). - * @param message A non-NULL pointer to the first element of a byte array - * containing the message text. - * @param length Length of the message to be sent. - * - * @return true on success. - */ - bool message(uint32_t conference_number, MESSAGE_TYPE type, const uint8_t[length] message) { - /** - * The conference number passed did not designate a valid conference. - */ - CONFERENCE_NOT_FOUND, - /** - * The message is too long. - */ - TOO_LONG, - /** - * The client is not connected to the conference. - */ - NO_CONNECTION, - /** - * The message packet failed to send. - */ - FAIL_SEND, - } - } - - error for title { - /** - * The conference number passed did not designate a valid conference. - */ - CONFERENCE_NOT_FOUND, - /** - * The title is too long or empty. - */ - INVALID_LENGTH, - /** - * The title packet failed to send. - */ - FAIL_SEND, - } - - uint8_t[length <= MAX_NAME_LENGTH] title { - - /** - * Return the length of the conference title. Return value is unspecified on failure. - * - * The return value is equal to the `length` argument received by the last - * `${event title}` callback. - */ - size(uint32_t conference_number) - with error for title; - - /** - * Write the title designated by the given conference number to a byte array. - * - * Call $size to determine the allocation size for the `title` parameter. - * - * The data written to `title` is equal to the data received by the last - * `${event title}` callback. - * - * @param title A valid memory region large enough to store the title. - * If this parameter is NULL, this function has no effect. - * - * @return true on success. - */ - get(uint32_t conference_number) - with error for title; - - /** - * Set the conference title and broadcast it to the rest of the conference. - * - * Title length cannot be longer than $MAX_NAME_LENGTH. - * - * @return true on success. - */ - set(uint32_t conference_number) - with error for title; - } - - - uint32_t[size] chatlist { - /** - * Return the number of conferences in the Tox instance. - * This should be used to determine how much memory to allocate for `$get`. - */ - size(); - - /** - * Copy a list of valid conference numbers into the array chatlist. Determine - * how much space to allocate for the array with the `$size` function. - * - * Note that `${savedata.get}` saves all connected conferences; - * when toxcore is created from savedata in which conferences were saved, those - * conferences will be connected at startup, and will be listed by - * `$get`. - * - * The conference number of a loaded conference may differ from the conference - * number it had when it was saved. - */ - get(); - } - - - /** - * Returns the type of conference ($TYPE) that conference_number is. Return value is - * unspecified on failure. - */ - TYPE type { - get(uint32_t conference_number) { - /** - * The conference number passed did not designate a valid conference. - */ - CONFERENCE_NOT_FOUND, - } - } - - /** - * Get the conference unique ID. - * - * If id is NULL, this function has no effect. - * - * @param id A memory region large enough to store $CONFERENCE_ID_SIZE bytes. - * - * @return true on success. - */ - const bool get_id(uint32_t conference_number, uint8_t[CONFERENCE_ID_SIZE] id); - - /** - * Return the conference number associated with the specified id. - * - * @param id A byte array containing the conference id ($CONFERENCE_ID_SIZE). - * - * @return the conference number on success, an unspecified value on failure. - */ - const uint32_t by_id(const uint8_t[CONFERENCE_ID_SIZE] id) { - NULL, - /** - * No conference with the given id exists on the conference list. - */ - NOT_FOUND, - } - - /** - * Get the conference unique ID. - * - * If uid is NULL, this function has no effect. - * - * @param uid A memory region large enough to store $CONFERENCE_UID_SIZE bytes. - * - * @return true on success. - * @deprecated use $get_id instead (exactly the same function, just renamed). - */ - const bool get_uid(uint32_t conference_number, uint8_t[CONFERENCE_UID_SIZE] uid); - - /** - * Return the conference number associated with the specified uid. - * - * @param uid A byte array containing the conference id ($CONFERENCE_UID_SIZE). - * - * @return the conference number on success, an unspecified value on failure. - * @deprecated use $by_id instead (exactly the same function, just renamed). - */ - const uint32_t by_uid(const uint8_t[CONFERENCE_UID_SIZE] uid) { - NULL, - /** - * No conference with the given uid exists on the conference list. - */ - NOT_FOUND, - } - -} - - -/******************************************************************************* - * - * :: Low-level custom packet sending and receiving - * - ******************************************************************************/ - - -namespace friend { - - error for custom_packet { - NULL, - /** - * The friend number did not designate a valid friend. - */ - FRIEND_NOT_FOUND, - /** - * This client is currently not connected to the friend. - */ - 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. - */ - INVALID, - /** - * Attempted to send an empty packet. - */ - EMPTY, - /** - * Packet data length exceeded $MAX_CUSTOM_PACKET_SIZE. - */ - TOO_LONG, - /** - * Packet queue is full. - */ - SENDQ, - } - - namespace send { - - /** - * Send a custom lossy packet to a friend. - * - * The first byte of data must be in the range 192-254. Maximum length of a - * custom packet is $MAX_CUSTOM_PACKET_SIZE. - * - * 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, it is recommended that you use lossless custom - * packets instead. - * - * @param friend_number The friend number of the friend this lossy packet - * should be sent to. - * @param data A byte array containing the packet data. - * @param length The length of the packet data byte array. - * - * @return true on success. - */ - bool lossy_packet(uint32_t friend_number, const uint8_t[length <= MAX_CUSTOM_PACKET_SIZE] data) - with error for custom_packet; - - - /** - * Send a custom lossless packet to a friend. - * - * The first byte of data must be in the range 69, 160-191. Maximum length of a - * custom packet is $MAX_CUSTOM_PACKET_SIZE. - * - * Lossless packet behaviour is comparable to TCP (reliability, arrive in order) - * but with packets instead of a stream. - * - * @param friend_number The friend number of the friend this lossless packet - * should be sent to. - * @param data A byte array containing the packet data. - * @param length The length of the packet data byte array. - * - * @return true on success. - */ - bool lossless_packet(uint32_t friend_number, const uint8_t[length <= MAX_CUSTOM_PACKET_SIZE] data) - with error for custom_packet; - - } - - - event lossy_packet const { - /** - * @param friend_number The friend number of the friend who sent a lossy packet. - * @param data A byte array containing the received packet data. - * @param length The length of the packet data byte array. - */ - typedef void(uint32_t friend_number, const uint8_t[length <= MAX_CUSTOM_PACKET_SIZE] data); - } - - - event lossless_packet const { - /** - * @param friend_number The friend number of the friend who sent the packet. - * @param data A byte array containing the received packet data. - * @param length The length of the packet data byte array. - */ - typedef void(uint32_t friend_number, const uint8_t[length <= MAX_CUSTOM_PACKET_SIZE] data); - } - -} - - - -/******************************************************************************* - * - * :: Low-level network information - * - ******************************************************************************/ - - -error for get_port { - /** - * The instance was not bound to any port. - */ - NOT_BOUND, -} - -namespace self { - - uint8_t[PUBLIC_KEY_SIZE] dht_id { - /** - * 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 ${udp_port.get}) 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. - * - * @param dht_id A memory region of at least $PUBLIC_KEY_SIZE bytes. If this - * parameter is NULL, this function has no effect. - */ - get(); - } - - - - uint16_t udp_port { - /** - * Return the UDP port this Tox instance is bound to. - */ - get() with error for get_port; - } - - - uint16_t tcp_port { - /** - * Return the TCP port this Tox instance is bound to. This is only relevant if - * the instance is acting as a TCP relay. - */ - get() with error for get_port; - } - -} - -} // class tox - -%{ -#ifdef __cplusplus -} -#endif - -typedef TOX_ERR_OPTIONS_NEW Tox_Err_Options_New; -typedef TOX_ERR_NEW Tox_Err_New; -typedef TOX_ERR_BOOTSTRAP Tox_Err_Bootstrap; -typedef TOX_ERR_SET_INFO Tox_Err_Set_Info; -typedef TOX_ERR_FRIEND_ADD Tox_Err_Friend_Add; -typedef TOX_ERR_FRIEND_DELETE Tox_Err_Friend_Delete; -typedef TOX_ERR_FRIEND_BY_PUBLIC_KEY Tox_Err_Friend_By_Public_Key; -typedef TOX_ERR_FRIEND_GET_PUBLIC_KEY Tox_Err_Friend_Get_Public_Key; -typedef TOX_ERR_FRIEND_GET_LAST_ONLINE Tox_Err_Friend_Get_Last_Online; -typedef TOX_ERR_FRIEND_QUERY Tox_Err_Friend_Query; -typedef TOX_ERR_SET_TYPING Tox_Err_Set_Typing; -typedef TOX_ERR_FRIEND_SEND_MESSAGE Tox_Err_Friend_Send_Message; -typedef TOX_ERR_FILE_CONTROL Tox_Err_File_Control; -typedef TOX_ERR_FILE_SEEK Tox_Err_File_Seek; -typedef TOX_ERR_FILE_GET Tox_Err_File_Get; -typedef TOX_ERR_FILE_SEND Tox_Err_File_Send; -typedef TOX_ERR_FILE_SEND_CHUNK Tox_Err_File_Send_Chunk; -typedef TOX_ERR_CONFERENCE_NEW Tox_Err_Conference_New; -typedef TOX_ERR_CONFERENCE_DELETE Tox_Err_Conference_Delete; -typedef TOX_ERR_CONFERENCE_PEER_QUERY Tox_Err_Conference_Peer_Query; -typedef TOX_ERR_CONFERENCE_SET_MAX_OFFLINE Tox_Err_Conference_Set_Max_Offline; -typedef TOX_ERR_CONFERENCE_BY_ID Tox_Err_Conference_By_Id; -typedef TOX_ERR_CONFERENCE_BY_UID Tox_Err_Conference_By_Uid; -typedef TOX_ERR_CONFERENCE_INVITE Tox_Err_Conference_Invite; -typedef TOX_ERR_CONFERENCE_JOIN Tox_Err_Conference_Join; -typedef TOX_ERR_CONFERENCE_SEND_MESSAGE Tox_Err_Conference_Send_Message; -typedef TOX_ERR_CONFERENCE_TITLE Tox_Err_Conference_Title; -typedef TOX_ERR_CONFERENCE_GET_TYPE Tox_Err_Conference_Get_Type; -typedef TOX_ERR_FRIEND_CUSTOM_PACKET Tox_Err_Friend_Custom_Packet; -typedef TOX_ERR_GET_PORT Tox_Err_Get_Port; -typedef TOX_USER_STATUS Tox_User_Status; -typedef TOX_MESSAGE_TYPE Tox_Message_Type; -typedef TOX_PROXY_TYPE Tox_Proxy_Type; -typedef TOX_SAVEDATA_TYPE Tox_Savedata_Type; -typedef TOX_LOG_LEVEL Tox_Log_Level; -typedef TOX_CONNECTION Tox_Connection; -typedef TOX_FILE_CONTROL Tox_File_Control; -typedef TOX_CONFERENCE_TYPE Tox_Conference_Type; - -//!TOKSTYLE+ - -#endif // C_TOXCORE_TOXCORE_TOX_H -%} diff --git a/toxcore/tox.c b/toxcore/tox.c index 459e8272..eaf5516c 100644 --- a/toxcore/tox.c +++ b/toxcore/tox.c @@ -6,11 +6,9 @@ /* * The Tox public API. */ -#ifndef __cplusplus #ifndef _XOPEN_SOURCE #define _XOPEN_SOURCE 600 #endif -#endif #include "tox.h" #include "tox_private.h" @@ -33,7 +31,6 @@ } \ } while (0) -//!TOKSTYLE- static_assert(TOX_HASH_LENGTH == CRYPTO_SHA256_SIZE, "TOX_HASH_LENGTH is assumed to be equal to CRYPTO_SHA256_SIZE"); static_assert(FILE_ID_LENGTH == CRYPTO_SYMMETRIC_KEY_SIZE, @@ -50,7 +47,6 @@ static_assert(TOX_MAX_NAME_LENGTH == MAX_NAME_LENGTH, "TOX_MAX_NAME_LENGTH is assumed to be equal to MAX_NAME_LENGTH"); static_assert(TOX_MAX_STATUS_MESSAGE_LENGTH == MAX_STATUSMESSAGE_LENGTH, "TOX_MAX_STATUS_MESSAGE_LENGTH is assumed to be equal to MAX_STATUSMESSAGE_LENGTH"); -//!TOKSTYLE+ struct Tox { // XXX: Messenger *must* be the first member, because toxav casts its @@ -439,7 +435,7 @@ Tox *tox_new(const struct Tox_Options *options, Tox_Err_New *error) return nullptr; } - if (crypto_memcmp(tox_options_get_savedata_data(opts), TOX_ENC_SAVE_MAGIC_NUMBER, TOX_ENC_SAVE_MAGIC_LENGTH) == 0) { + if (memcmp(tox_options_get_savedata_data(opts), TOX_ENC_SAVE_MAGIC_NUMBER, TOX_ENC_SAVE_MAGIC_LENGTH) == 0) { SET_ERROR_PARAMETER(error, TOX_ERR_NEW_LOAD_ENCRYPTED); tox_options_free(default_options); free(tox); diff --git a/toxcore/tox.h b/toxcore/tox.h index ab71986e..236714fd 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -13,17 +13,15 @@ #include #include -//!TOKSTYLE- - #ifdef __cplusplus extern "C" { #endif /******************************************************************************* - * `tox.h` SHOULD *NOT* BE EDITED MANUALLY – any changes should be made to * - * `tox.api.h`, located in `toxcore/`. For instructions on how to * - * generate `tox.h` from `tox.api.h` please refer to `docs/apidsl.md` * + * `tox.h` SHOULD NOT BE EDITED MANUALLY – any changes should be made to + * `tox.api.h`, located in `toxcore/`. For instructions on how to + * generate `tox.h` from `tox.api.h` please refer to `docs/apidsl.md` ******************************************************************************/ @@ -174,6 +172,7 @@ uint32_t tox_version_minor(void); uint32_t tox_version_patch(void); +//!TOKSTYLE- /** * A macro to check at preprocessing time whether the client code is compatible * with the installed version of Tox. Leading zeros in the version number are @@ -194,6 +193,7 @@ uint32_t tox_version_patch(void); TOX_VERSION_PATCH == PATCH \ )) \ )) +//!TOKSTYLE+ /** * Return whether the compiled library version is compatible with the passed @@ -260,7 +260,7 @@ uint32_t tox_nospam_size(void); /** * The size of a Tox address in bytes. Tox addresses are in the format - * [Public Key (TOX_PUBLIC_KEY_SIZE bytes)][nospam (4 bytes)][checksum (2 bytes)]. + * `[Public Key (TOX_PUBLIC_KEY_SIZE bytes)][nospam (4 bytes)][checksum (2 bytes)]`. * * The checksum is computed over the Public Key and the nospam value. The first * byte is an XOR of all the even bytes (0, 2, 4, ...), the second byte is an @@ -365,7 +365,7 @@ uint32_t tox_max_hostname_length(void); * @deprecated All UPPER_CASE enum type names are deprecated. Use the * Camel_Snake_Case versions, instead. */ -typedef enum TOX_USER_STATUS { +typedef enum Tox_User_Status { /** * User is online and available. @@ -384,7 +384,7 @@ typedef enum TOX_USER_STATUS { */ TOX_USER_STATUS_BUSY, -} TOX_USER_STATUS; +} Tox_User_Status; /** @@ -394,7 +394,7 @@ typedef enum TOX_USER_STATUS { * @deprecated All UPPER_CASE enum type names are deprecated. Use the * Camel_Snake_Case versions, instead. */ -typedef enum TOX_MESSAGE_TYPE { +typedef enum Tox_Message_Type { /** * Normal text message. Similar to PRIVMSG on IRC. @@ -407,7 +407,7 @@ typedef enum TOX_MESSAGE_TYPE { */ TOX_MESSAGE_TYPE_ACTION, -} TOX_MESSAGE_TYPE; +} Tox_Message_Type; @@ -425,7 +425,7 @@ typedef enum TOX_MESSAGE_TYPE { * @deprecated All UPPER_CASE enum type names are deprecated. Use the * Camel_Snake_Case versions, instead. */ -typedef enum TOX_PROXY_TYPE { +typedef enum Tox_Proxy_Type { /** * Don't use a proxy. @@ -442,7 +442,7 @@ typedef enum TOX_PROXY_TYPE { */ TOX_PROXY_TYPE_SOCKS5, -} TOX_PROXY_TYPE; +} Tox_Proxy_Type; /** @@ -451,7 +451,7 @@ typedef enum TOX_PROXY_TYPE { * @deprecated All UPPER_CASE enum type names are deprecated. Use the * Camel_Snake_Case versions, instead. */ -typedef enum TOX_SAVEDATA_TYPE { +typedef enum Tox_Savedata_Type { /** * No savedata. @@ -468,7 +468,7 @@ typedef enum TOX_SAVEDATA_TYPE { */ TOX_SAVEDATA_TYPE_SECRET_KEY, -} TOX_SAVEDATA_TYPE; +} Tox_Savedata_Type; /** @@ -477,7 +477,7 @@ typedef enum TOX_SAVEDATA_TYPE { * @deprecated All UPPER_CASE enum type names are deprecated. Use the * Camel_Snake_Case versions, instead. */ -typedef enum TOX_LOG_LEVEL { +typedef enum Tox_Log_Level { /** * Very detailed traces including all network activity. @@ -504,7 +504,7 @@ typedef enum TOX_LOG_LEVEL { */ TOX_LOG_LEVEL_ERROR, -} TOX_LOG_LEVEL; +} Tox_Log_Level; /** @@ -524,7 +524,7 @@ typedef enum TOX_LOG_LEVEL { * @param message The log message. * @param user_data The user data pointer passed to tox_new in options. */ -typedef void tox_log_cb(Tox *tox, TOX_LOG_LEVEL level, const char *file, uint32_t line, const char *func, +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); @@ -577,7 +577,7 @@ struct Tox_Options { /** * Pass communications through a proxy. */ - TOX_PROXY_TYPE proxy_type; + Tox_Proxy_Type proxy_type; /** @@ -608,7 +608,7 @@ struct Tox_Options { * The start port of the inclusive port range to attempt to use. * * If both start_port and end_port are 0, the default port range will be - * used: [33445, 33545]. + * used: `[33445, 33545]`. * * 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. @@ -648,7 +648,7 @@ struct Tox_Options { /** * The type of savedata to load from. */ - TOX_SAVEDATA_TYPE savedata_type; + Tox_Savedata_Type savedata_type; /** @@ -706,9 +706,9 @@ bool tox_options_get_local_discovery_enabled(const struct Tox_Options *options); void tox_options_set_local_discovery_enabled(struct Tox_Options *options, bool local_discovery_enabled); -TOX_PROXY_TYPE tox_options_get_proxy_type(const struct Tox_Options *options); +Tox_Proxy_Type tox_options_get_proxy_type(const struct Tox_Options *options); -void tox_options_set_proxy_type(struct Tox_Options *options, TOX_PROXY_TYPE type); +void tox_options_set_proxy_type(struct Tox_Options *options, Tox_Proxy_Type type); const char *tox_options_get_proxy_host(const struct Tox_Options *options); @@ -734,9 +734,9 @@ bool tox_options_get_hole_punching_enabled(const struct Tox_Options *options); void tox_options_set_hole_punching_enabled(struct Tox_Options *options, bool hole_punching_enabled); -TOX_SAVEDATA_TYPE tox_options_get_savedata_type(const struct Tox_Options *options); +Tox_Savedata_Type tox_options_get_savedata_type(const struct Tox_Options *options); -void tox_options_set_savedata_type(struct Tox_Options *options, TOX_SAVEDATA_TYPE type); +void tox_options_set_savedata_type(struct Tox_Options *options, Tox_Savedata_Type type); const uint8_t *tox_options_get_savedata_data(const struct Tox_Options *options); @@ -771,7 +771,7 @@ void tox_options_set_experimental_thread_safety(struct Tox_Options *options, boo */ void tox_options_default(struct Tox_Options *options); -typedef enum TOX_ERR_OPTIONS_NEW { +typedef enum Tox_Err_Options_New { /** * The function returned successfully. @@ -783,7 +783,7 @@ typedef enum TOX_ERR_OPTIONS_NEW { */ TOX_ERR_OPTIONS_NEW_MALLOC, -} TOX_ERR_OPTIONS_NEW; +} Tox_Err_Options_New; /** @@ -796,7 +796,7 @@ typedef enum TOX_ERR_OPTIONS_NEW { * * @return A new Tox_Options object with default options or NULL on failure. */ -struct Tox_Options *tox_options_new(TOX_ERR_OPTIONS_NEW *error); +struct Tox_Options *tox_options_new(Tox_Err_Options_New *error); /** * Releases all resources associated with an options objects. @@ -815,7 +815,7 @@ void tox_options_free(struct Tox_Options *options); -typedef enum TOX_ERR_NEW { +typedef enum Tox_Err_New { /** * The function returned successfully. @@ -875,7 +875,7 @@ typedef enum TOX_ERR_NEW { */ TOX_ERR_NEW_LOAD_BAD_FORMAT, -} TOX_ERR_NEW; +} Tox_Err_New; /** @@ -894,7 +894,7 @@ typedef enum TOX_ERR_NEW { * * @return A new Tox instance pointer on success or NULL on failure. */ -Tox *tox_new(const struct Tox_Options *options, TOX_ERR_NEW *error); +Tox *tox_new(const struct Tox_Options *options, Tox_Err_New *error); /** * Releases all resources associated with the Tox instance and disconnects from @@ -931,7 +931,7 @@ void tox_get_savedata(const Tox *tox, uint8_t *savedata); -typedef enum TOX_ERR_BOOTSTRAP { +typedef enum Tox_Err_Bootstrap { /** * The function returned successfully. @@ -954,7 +954,7 @@ typedef enum TOX_ERR_BOOTSTRAP { */ TOX_ERR_BOOTSTRAP_BAD_PORT, -} TOX_ERR_BOOTSTRAP; +} Tox_Err_Bootstrap; /** @@ -972,7 +972,7 @@ typedef enum TOX_ERR_BOOTSTRAP { * (TOX_PUBLIC_KEY_SIZE bytes). * @return true on success. */ -bool tox_bootstrap(Tox *tox, const char *host, uint16_t port, const uint8_t *public_key, TOX_ERR_BOOTSTRAP *error); +bool tox_bootstrap(Tox *tox, const char *host, uint16_t port, const uint8_t *public_key, Tox_Err_Bootstrap *error); /** * Adds additional host:port pair as TCP relay. @@ -988,7 +988,7 @@ bool tox_bootstrap(Tox *tox, const char *host, uint16_t port, const uint8_t *pub * (TOX_PUBLIC_KEY_SIZE bytes). * @return true on success. */ -bool tox_add_tcp_relay(Tox *tox, const char *host, uint16_t port, const uint8_t *public_key, TOX_ERR_BOOTSTRAP *error); +bool tox_add_tcp_relay(Tox *tox, const char *host, uint16_t port, const uint8_t *public_key, Tox_Err_Bootstrap *error); /** * Protocols that can be used to connect to the network or friends. @@ -996,7 +996,7 @@ bool tox_add_tcp_relay(Tox *tox, const char *host, uint16_t port, const uint8_t * @deprecated All UPPER_CASE enum type names are deprecated. Use the * Camel_Snake_Case versions, instead. */ -typedef enum TOX_CONNECTION { +typedef enum Tox_Connection { /** * There is no connection. This instance, or the friend the state change is @@ -1019,7 +1019,7 @@ typedef enum TOX_CONNECTION { */ TOX_CONNECTION_UDP, -} TOX_CONNECTION; +} Tox_Connection; /** @@ -1029,12 +1029,12 @@ typedef enum TOX_CONNECTION { * @deprecated This getter is deprecated. Use the event and store the status * in the client state. */ -TOX_CONNECTION tox_self_get_connection_status(const Tox *tox); +Tox_Connection tox_self_get_connection_status(const Tox *tox); /** * @param connection_status Whether we are connected to the DHT. */ -typedef void tox_self_connection_status_cb(Tox *tox, TOX_CONNECTION connection_status, void *user_data); +typedef void tox_self_connection_status_cb(Tox *tox, Tox_Connection connection_status, void *user_data); /** @@ -1084,7 +1084,7 @@ void tox_self_get_address(const Tox *tox, uint8_t *address); /** * Set the 4-byte nospam part of the address. This value is expected in host - * byte order. I.e. 0x12345678 will form the bytes [12, 34, 56, 78] in the + * byte order. I.e. 0x12345678 will form the bytes `[12, 34, 56, 78]` in the * nospam part of the Tox friend address. * * @param nospam Any 32 bit unsigned integer. @@ -1126,7 +1126,7 @@ void tox_self_get_secret_key(const Tox *tox, uint8_t *secret_key); * Common error codes for all functions that set a piece of user-visible * client information. */ -typedef enum TOX_ERR_SET_INFO { +typedef enum Tox_Err_Set_Info { /** * The function returned successfully. @@ -1143,7 +1143,7 @@ typedef enum TOX_ERR_SET_INFO { */ TOX_ERR_SET_INFO_TOO_LONG, -} TOX_ERR_SET_INFO; +} Tox_Err_Set_Info; /** @@ -1157,7 +1157,7 @@ typedef enum TOX_ERR_SET_INFO { * * @return true on success. */ -bool tox_self_set_name(Tox *tox, const uint8_t *name, size_t length, TOX_ERR_SET_INFO *error); +bool tox_self_set_name(Tox *tox, const uint8_t *name, size_t length, Tox_Err_Set_Info *error); /** * Return the length of the current nickname as passed to tox_self_set_name. @@ -1190,7 +1190,7 @@ void tox_self_get_name(const Tox *tox, uint8_t *name); * length is 0, the status parameter is ignored (it can be NULL), and the * user status is set back to empty. */ -bool tox_self_set_status_message(Tox *tox, const uint8_t *status_message, size_t length, TOX_ERR_SET_INFO *error); +bool tox_self_set_status_message(Tox *tox, const uint8_t *status_message, size_t length, Tox_Err_Set_Info *error); /** * Return the length of the current status message as passed to tox_self_set_status_message. @@ -1221,12 +1221,12 @@ void tox_self_get_status_message(const Tox *tox, uint8_t *status_message); * * @param status One of the user statuses listed in the enumeration above. */ -void tox_self_set_status(Tox *tox, TOX_USER_STATUS status); +void tox_self_set_status(Tox *tox, Tox_User_Status status); /** * Returns the client's user status. */ -TOX_USER_STATUS tox_self_get_status(const Tox *tox); +Tox_User_Status tox_self_get_status(const Tox *tox); /******************************************************************************* @@ -1237,7 +1237,7 @@ TOX_USER_STATUS tox_self_get_status(const Tox *tox); -typedef enum TOX_ERR_FRIEND_ADD { +typedef enum Tox_Err_Friend_Add { /** * The function returned successfully. @@ -1287,7 +1287,7 @@ typedef enum TOX_ERR_FRIEND_ADD { */ TOX_ERR_FRIEND_ADD_MALLOC, -} TOX_ERR_FRIEND_ADD; +} Tox_Err_Friend_Add; /** @@ -1314,7 +1314,7 @@ typedef enum TOX_ERR_FRIEND_ADD { * @return the friend number on success, an unspecified value on failure. */ uint32_t tox_friend_add(Tox *tox, const uint8_t *address, const uint8_t *message, size_t length, - TOX_ERR_FRIEND_ADD *error); + Tox_Err_Friend_Add *error); /** * Add a friend without sending a friend request. @@ -1334,9 +1334,9 @@ uint32_t tox_friend_add(Tox *tox, const uint8_t *address, const uint8_t *message * @return the friend number on success, an unspecified value on failure. * @see tox_friend_add for a more detailed description of friend numbers. */ -uint32_t tox_friend_add_norequest(Tox *tox, const uint8_t *public_key, TOX_ERR_FRIEND_ADD *error); +uint32_t tox_friend_add_norequest(Tox *tox, const uint8_t *public_key, Tox_Err_Friend_Add *error); -typedef enum TOX_ERR_FRIEND_DELETE { +typedef enum Tox_Err_Friend_Delete { /** * The function returned successfully. @@ -1348,7 +1348,7 @@ typedef enum TOX_ERR_FRIEND_DELETE { */ TOX_ERR_FRIEND_DELETE_FRIEND_NOT_FOUND, -} TOX_ERR_FRIEND_DELETE; +} Tox_Err_Friend_Delete; /** @@ -1362,7 +1362,7 @@ typedef enum TOX_ERR_FRIEND_DELETE { * * @return true on success. */ -bool tox_friend_delete(Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_DELETE *error); +bool tox_friend_delete(Tox *tox, uint32_t friend_number, Tox_Err_Friend_Delete *error); /******************************************************************************* @@ -1373,7 +1373,7 @@ bool tox_friend_delete(Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_DELETE * -typedef enum TOX_ERR_FRIEND_BY_PUBLIC_KEY { +typedef enum Tox_Err_Friend_By_Public_Key { /** * The function returned successfully. @@ -1390,7 +1390,7 @@ typedef enum TOX_ERR_FRIEND_BY_PUBLIC_KEY { */ TOX_ERR_FRIEND_BY_PUBLIC_KEY_NOT_FOUND, -} TOX_ERR_FRIEND_BY_PUBLIC_KEY; +} Tox_Err_Friend_By_Public_Key; /** @@ -1399,7 +1399,7 @@ typedef enum TOX_ERR_FRIEND_BY_PUBLIC_KEY { * @return the friend number on success, an unspecified value on failure. * @param public_key A byte array containing the Public Key. */ -uint32_t tox_friend_by_public_key(const Tox *tox, const uint8_t *public_key, TOX_ERR_FRIEND_BY_PUBLIC_KEY *error); +uint32_t tox_friend_by_public_key(const Tox *tox, const uint8_t *public_key, Tox_Err_Friend_By_Public_Key *error); /** * Checks if a friend with the given friend number exists and returns true if @@ -1425,7 +1425,7 @@ size_t tox_self_get_friend_list_size(const Tox *tox); */ void tox_self_get_friend_list(const Tox *tox, uint32_t *friend_list); -typedef enum TOX_ERR_FRIEND_GET_PUBLIC_KEY { +typedef enum Tox_Err_Friend_Get_Public_Key { /** * The function returned successfully. @@ -1437,7 +1437,7 @@ typedef enum TOX_ERR_FRIEND_GET_PUBLIC_KEY { */ TOX_ERR_FRIEND_GET_PUBLIC_KEY_FRIEND_NOT_FOUND, -} TOX_ERR_FRIEND_GET_PUBLIC_KEY; +} Tox_Err_Friend_Get_Public_Key; /** @@ -1450,9 +1450,9 @@ typedef enum TOX_ERR_FRIEND_GET_PUBLIC_KEY { * @return true on success. */ bool tox_friend_get_public_key(const Tox *tox, uint32_t friend_number, uint8_t *public_key, - TOX_ERR_FRIEND_GET_PUBLIC_KEY *error); + Tox_Err_Friend_Get_Public_Key *error); -typedef enum TOX_ERR_FRIEND_GET_LAST_ONLINE { +typedef enum Tox_Err_Friend_Get_Last_Online { /** * The function returned successfully. @@ -1464,7 +1464,7 @@ typedef enum TOX_ERR_FRIEND_GET_LAST_ONLINE { */ TOX_ERR_FRIEND_GET_LAST_ONLINE_FRIEND_NOT_FOUND, -} TOX_ERR_FRIEND_GET_LAST_ONLINE; +} Tox_Err_Friend_Get_Last_Online; /** @@ -1473,7 +1473,7 @@ typedef enum TOX_ERR_FRIEND_GET_LAST_ONLINE { * * @param friend_number The friend number you want to query. */ -uint64_t tox_friend_get_last_online(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_GET_LAST_ONLINE *error); +uint64_t tox_friend_get_last_online(const Tox *tox, uint32_t friend_number, Tox_Err_Friend_Get_Last_Online *error); /******************************************************************************* @@ -1487,7 +1487,7 @@ uint64_t tox_friend_get_last_online(const Tox *tox, uint32_t friend_number, TOX_ /** * Common error codes for friend state query functions. */ -typedef enum TOX_ERR_FRIEND_QUERY { +typedef enum Tox_Err_Friend_Query { /** * The function returned successfully. @@ -1506,7 +1506,7 @@ typedef enum TOX_ERR_FRIEND_QUERY { */ TOX_ERR_FRIEND_QUERY_FRIEND_NOT_FOUND, -} TOX_ERR_FRIEND_QUERY; +} Tox_Err_Friend_Query; /** @@ -1516,7 +1516,7 @@ typedef enum TOX_ERR_FRIEND_QUERY { * The return value is equal to the `length` argument received by the last * `friend_name` callback. */ -size_t tox_friend_get_name_size(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); +size_t tox_friend_get_name_size(const Tox *tox, uint32_t friend_number, Tox_Err_Friend_Query *error); /** * Write the name of the friend designated by the given friend number to a byte @@ -1532,7 +1532,7 @@ size_t tox_friend_get_name_size(const Tox *tox, uint32_t friend_number, TOX_ERR_ * * @return true on success. */ -bool tox_friend_get_name(const Tox *tox, uint32_t friend_number, uint8_t *name, TOX_ERR_FRIEND_QUERY *error); +bool tox_friend_get_name(const Tox *tox, uint32_t friend_number, uint8_t *name, Tox_Err_Friend_Query *error); /** * @param friend_number The friend number of the friend whose name changed. @@ -1555,7 +1555,7 @@ void tox_callback_friend_name(Tox *tox, tox_friend_name_cb *callback); * Return the length of the friend's status message. If the friend number is * invalid, the return value is SIZE_MAX. */ -size_t tox_friend_get_status_message_size(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); +size_t tox_friend_get_status_message_size(const Tox *tox, uint32_t friend_number, Tox_Err_Friend_Query *error); /** * Write the status message of the friend designated by the given friend number to a byte @@ -1570,7 +1570,7 @@ size_t tox_friend_get_status_message_size(const Tox *tox, uint32_t friend_number * @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, uint32_t friend_number, uint8_t *status_message, - TOX_ERR_FRIEND_QUERY *error); + Tox_Err_Friend_Query *error); /** * @param friend_number The friend number of the friend whose status message @@ -1601,14 +1601,14 @@ void tox_callback_friend_status_message(Tox *tox, tox_friend_status_message_cb * * @deprecated This getter is deprecated. Use the event and store the status * in the client state. */ -TOX_USER_STATUS tox_friend_get_status(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); +Tox_User_Status tox_friend_get_status(const Tox *tox, uint32_t friend_number, Tox_Err_Friend_Query *error); /** * @param friend_number The friend number of the friend whose user status * changed. * @param status The new user status. */ -typedef void tox_friend_status_cb(Tox *tox, uint32_t friend_number, TOX_USER_STATUS status, void *user_data); +typedef void tox_friend_status_cb(Tox *tox, uint32_t friend_number, Tox_User_Status status, void *user_data); /** @@ -1633,7 +1633,7 @@ void tox_callback_friend_status(Tox *tox, tox_friend_status_cb *callback); * @deprecated This getter is deprecated. Use the event and store the status * in the client state. */ -TOX_CONNECTION tox_friend_get_connection_status(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); +Tox_Connection tox_friend_get_connection_status(const Tox *tox, uint32_t friend_number, Tox_Err_Friend_Query *error); /** * @param friend_number The friend number of the friend whose connection status @@ -1641,7 +1641,7 @@ TOX_CONNECTION tox_friend_get_connection_status(const Tox *tox, uint32_t friend_ * @param connection_status The result of calling * tox_friend_get_connection_status on the passed friend_number. */ -typedef void tox_friend_connection_status_cb(Tox *tox, uint32_t friend_number, TOX_CONNECTION connection_status, +typedef void tox_friend_connection_status_cb(Tox *tox, uint32_t friend_number, Tox_Connection connection_status, void *user_data); @@ -1668,7 +1668,7 @@ void tox_callback_friend_connection_status(Tox *tox, tox_friend_connection_statu * @deprecated This getter is deprecated. Use the event and store the status * in the client state. */ -bool tox_friend_get_typing(const Tox *tox, uint32_t friend_number, TOX_ERR_FRIEND_QUERY *error); +bool tox_friend_get_typing(const Tox *tox, uint32_t friend_number, Tox_Err_Friend_Query *error); /** * @param friend_number The friend number of the friend who started or stopped @@ -1695,7 +1695,7 @@ void tox_callback_friend_typing(Tox *tox, tox_friend_typing_cb *callback); -typedef enum TOX_ERR_SET_TYPING { +typedef enum Tox_Err_Set_Typing { /** * The function returned successfully. @@ -1707,7 +1707,7 @@ typedef enum TOX_ERR_SET_TYPING { */ TOX_ERR_SET_TYPING_FRIEND_NOT_FOUND, -} TOX_ERR_SET_TYPING; +} Tox_Err_Set_Typing; /** @@ -1720,9 +1720,9 @@ typedef enum TOX_ERR_SET_TYPING { * * @return true on success. */ -bool tox_self_set_typing(Tox *tox, uint32_t friend_number, bool typing, TOX_ERR_SET_TYPING *error); +bool tox_self_set_typing(Tox *tox, uint32_t friend_number, bool typing, Tox_Err_Set_Typing *error); -typedef enum TOX_ERR_FRIEND_SEND_MESSAGE { +typedef enum Tox_Err_Friend_Send_Message { /** * The function returned successfully. @@ -1759,7 +1759,7 @@ typedef enum TOX_ERR_FRIEND_SEND_MESSAGE { */ TOX_ERR_FRIEND_SEND_MESSAGE_EMPTY, -} TOX_ERR_FRIEND_SEND_MESSAGE; +} Tox_Err_Friend_Send_Message; /** @@ -1785,8 +1785,8 @@ typedef enum TOX_ERR_FRIEND_SEND_MESSAGE { * containing the message text. * @param length Length of the message to be sent. */ -uint32_t tox_friend_send_message(Tox *tox, uint32_t friend_number, TOX_MESSAGE_TYPE type, const uint8_t *message, - size_t length, TOX_ERR_FRIEND_SEND_MESSAGE *error); +uint32_t tox_friend_send_message(Tox *tox, uint32_t friend_number, Tox_Message_Type type, 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. @@ -1834,7 +1834,7 @@ void tox_callback_friend_request(Tox *tox, tox_friend_request_cb *callback); * @param message The message data they sent. * @param length The size of the message byte array. */ -typedef void tox_friend_message_cb(Tox *tox, uint32_t friend_number, TOX_MESSAGE_TYPE type, const uint8_t *message, +typedef void tox_friend_message_cb(Tox *tox, uint32_t friend_number, Tox_Message_Type type, const uint8_t *message, size_t length, void *user_data); @@ -1879,11 +1879,11 @@ bool tox_hash(uint8_t *hash, const uint8_t *data, size_t length); * 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 `uint32_t`, not TOX_FILE_KIND, because + * 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 { +enum Tox_File_Kind { /** * Arbitrary file data. Clients can choose to handle it based on the file name @@ -1916,7 +1916,7 @@ enum TOX_FILE_KIND { }; -typedef enum TOX_FILE_CONTROL { +typedef enum Tox_File_Control { /** * Sent by the receiving side to accept a file send request. Also sent after a @@ -1938,10 +1938,10 @@ typedef enum TOX_FILE_CONTROL { */ TOX_FILE_CONTROL_CANCEL, -} TOX_FILE_CONTROL; +} Tox_File_Control; -typedef enum TOX_ERR_FILE_CONTROL { +typedef enum Tox_Err_File_Control { /** * The function returned successfully. @@ -1984,7 +1984,7 @@ typedef enum TOX_ERR_FILE_CONTROL { */ TOX_ERR_FILE_CONTROL_SENDQ, -} TOX_ERR_FILE_CONTROL; +} Tox_Err_File_Control; /** @@ -1997,8 +1997,8 @@ typedef enum TOX_ERR_FILE_CONTROL { * * @return true on success. */ -bool tox_file_control(Tox *tox, uint32_t friend_number, uint32_t file_number, TOX_FILE_CONTROL control, - TOX_ERR_FILE_CONTROL *error); +bool tox_file_control(Tox *tox, uint32_t friend_number, uint32_t file_number, Tox_File_Control control, + Tox_Err_File_Control *error); /** * When receiving TOX_FILE_CONTROL_CANCEL, the client should release the @@ -2009,7 +2009,7 @@ bool tox_file_control(Tox *tox, uint32_t friend_number, uint32_t file_number, TO * associated with. * @param control The file control command received. */ -typedef void tox_file_recv_control_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, TOX_FILE_CONTROL control, +typedef void tox_file_recv_control_cb(Tox *tox, uint32_t friend_number, uint32_t file_number, Tox_File_Control control, void *user_data); @@ -2021,7 +2021,7 @@ typedef void tox_file_recv_control_cb(Tox *tox, uint32_t friend_number, uint32_t */ void tox_callback_file_recv_control(Tox *tox, tox_file_recv_control_cb *callback); -typedef enum TOX_ERR_FILE_SEEK { +typedef enum Tox_Err_File_Seek { /** * The function returned successfully. @@ -2058,7 +2058,7 @@ typedef enum TOX_ERR_FILE_SEEK { */ TOX_ERR_FILE_SEEK_SENDQ, -} TOX_ERR_FILE_SEEK; +} Tox_Err_File_Seek; /** @@ -2072,9 +2072,9 @@ typedef enum TOX_ERR_FILE_SEEK { * @param file_number The friend-specific identifier for the file transfer. * @param position The position that the file should be seeked to. */ -bool tox_file_seek(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, TOX_ERR_FILE_SEEK *error); +bool tox_file_seek(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, Tox_Err_File_Seek *error); -typedef enum TOX_ERR_FILE_GET { +typedef enum Tox_Err_File_Get { /** * The function returned successfully. @@ -2096,7 +2096,7 @@ typedef enum TOX_ERR_FILE_GET { */ TOX_ERR_FILE_GET_NOT_FOUND, -} TOX_ERR_FILE_GET; +} Tox_Err_File_Get; /** @@ -2111,7 +2111,7 @@ typedef enum TOX_ERR_FILE_GET { * @return true on success. */ bool tox_file_get_file_id(const Tox *tox, uint32_t friend_number, uint32_t file_number, uint8_t *file_id, - TOX_ERR_FILE_GET *error); + Tox_Err_File_Get *error); /******************************************************************************* @@ -2122,7 +2122,7 @@ bool tox_file_get_file_id(const Tox *tox, uint32_t friend_number, uint32_t file_ -typedef enum TOX_ERR_FILE_SEND { +typedef enum Tox_Err_File_Send { /** * The function returned successfully. @@ -2155,7 +2155,7 @@ typedef enum TOX_ERR_FILE_SEND { */ TOX_ERR_FILE_SEND_TOO_MANY, -} TOX_ERR_FILE_SEND; +} Tox_Err_File_Send; /** @@ -2218,9 +2218,9 @@ typedef enum TOX_ERR_FILE_SEND { * should not be relied on. */ uint32_t tox_file_send(Tox *tox, uint32_t friend_number, uint32_t kind, uint64_t file_size, const uint8_t *file_id, - const uint8_t *filename, size_t filename_length, TOX_ERR_FILE_SEND *error); + const uint8_t *filename, size_t filename_length, Tox_Err_File_Send *error); -typedef enum TOX_ERR_FILE_SEND_CHUNK { +typedef enum Tox_Err_File_Send_Chunk { /** * The function returned successfully. @@ -2270,7 +2270,7 @@ typedef enum TOX_ERR_FILE_SEND_CHUNK { */ TOX_ERR_FILE_SEND_CHUNK_WRONG_POSITION, -} TOX_ERR_FILE_SEND_CHUNK; +} Tox_Err_File_Send_Chunk; /** @@ -2290,7 +2290,7 @@ typedef enum TOX_ERR_FILE_SEND_CHUNK { * @return true on success. */ bool tox_file_send_chunk(Tox *tox, uint32_t friend_number, uint32_t file_number, uint64_t position, const uint8_t *data, - size_t length, TOX_ERR_FILE_SEND_CHUNK *error); + size_t length, Tox_Err_File_Send_Chunk *error); /** * If the length parameter is 0, the file transfer is finished, and the client's @@ -2406,7 +2406,7 @@ void tox_callback_file_recv_chunk(Tox *tox, tox_file_recv_chunk_cb *callback); * @deprecated All UPPER_CASE enum type names are deprecated. Use the * Camel_Snake_Case versions, instead. */ -typedef enum TOX_CONFERENCE_TYPE { +typedef enum Tox_Conference_Type { /** * Text-only conferences that must be accepted with the tox_conference_join function. @@ -2418,7 +2418,7 @@ typedef enum TOX_CONFERENCE_TYPE { */ TOX_CONFERENCE_TYPE_AV, -} TOX_CONFERENCE_TYPE; +} Tox_Conference_Type; /** @@ -2431,7 +2431,7 @@ typedef enum TOX_CONFERENCE_TYPE { * conference. * @param length The length of the cookie. */ -typedef void tox_conference_invite_cb(Tox *tox, uint32_t friend_number, TOX_CONFERENCE_TYPE type, const uint8_t *cookie, +typedef void tox_conference_invite_cb(Tox *tox, uint32_t friend_number, Tox_Conference_Type type, const uint8_t *cookie, size_t length, void *user_data); @@ -2464,7 +2464,7 @@ void tox_callback_conference_connected(Tox *tox, tox_conference_connected_cb *ca * @param length The length of the message. */ typedef void tox_conference_message_cb(Tox *tox, uint32_t conference_number, uint32_t peer_number, - TOX_MESSAGE_TYPE type, const uint8_t *message, size_t length, void *user_data); + Tox_Message_Type type, const uint8_t *message, size_t length, void *user_data); /** @@ -2525,7 +2525,7 @@ typedef void tox_conference_peer_list_changed_cb(Tox *tox, uint32_t conference_n */ void tox_callback_conference_peer_list_changed(Tox *tox, tox_conference_peer_list_changed_cb *callback); -typedef enum TOX_ERR_CONFERENCE_NEW { +typedef enum Tox_Err_Conference_New { /** * The function returned successfully. @@ -2537,7 +2537,7 @@ typedef enum TOX_ERR_CONFERENCE_NEW { */ TOX_ERR_CONFERENCE_NEW_INIT, -} TOX_ERR_CONFERENCE_NEW; +} Tox_Err_Conference_New; /** @@ -2547,9 +2547,9 @@ typedef enum TOX_ERR_CONFERENCE_NEW { * * @return conference number on success, or an unspecified value on failure. */ -uint32_t tox_conference_new(Tox *tox, TOX_ERR_CONFERENCE_NEW *error); +uint32_t tox_conference_new(Tox *tox, Tox_Err_Conference_New *error); -typedef enum TOX_ERR_CONFERENCE_DELETE { +typedef enum Tox_Err_Conference_Delete { /** * The function returned successfully. @@ -2561,7 +2561,7 @@ typedef enum TOX_ERR_CONFERENCE_DELETE { */ TOX_ERR_CONFERENCE_DELETE_CONFERENCE_NOT_FOUND, -} TOX_ERR_CONFERENCE_DELETE; +} Tox_Err_Conference_Delete; /** @@ -2571,12 +2571,12 @@ typedef enum TOX_ERR_CONFERENCE_DELETE { * * @return true on success. */ -bool tox_conference_delete(Tox *tox, uint32_t conference_number, TOX_ERR_CONFERENCE_DELETE *error); +bool tox_conference_delete(Tox *tox, uint32_t conference_number, Tox_Err_Conference_Delete *error); /** * Error codes for peer info queries. */ -typedef enum TOX_ERR_CONFERENCE_PEER_QUERY { +typedef enum Tox_Err_Conference_Peer_Query { /** * The function returned successfully. @@ -2598,7 +2598,7 @@ typedef enum TOX_ERR_CONFERENCE_PEER_QUERY { */ TOX_ERR_CONFERENCE_PEER_QUERY_NO_CONNECTION, -} TOX_ERR_CONFERENCE_PEER_QUERY; +} Tox_Err_Conference_Peer_Query; /** @@ -2607,13 +2607,13 @@ typedef enum TOX_ERR_CONFERENCE_PEER_QUERY { * the functions querying these peers. Return value is unspecified on * failure. */ -uint32_t tox_conference_peer_count(const Tox *tox, uint32_t conference_number, TOX_ERR_CONFERENCE_PEER_QUERY *error); +uint32_t tox_conference_peer_count(const Tox *tox, uint32_t conference_number, Tox_Err_Conference_Peer_Query *error); /** * Return the length of the peer's name. Return value is unspecified on failure. */ size_t tox_conference_peer_get_name_size(const Tox *tox, uint32_t conference_number, uint32_t peer_number, - TOX_ERR_CONFERENCE_PEER_QUERY *error); + Tox_Err_Conference_Peer_Query *error); /** * Copy the name of peer_number who is in conference_number to name. @@ -2625,7 +2625,7 @@ size_t tox_conference_peer_get_name_size(const Tox *tox, uint32_t conference_num * @return true on success. */ bool tox_conference_peer_get_name(const Tox *tox, uint32_t conference_number, uint32_t peer_number, uint8_t *name, - TOX_ERR_CONFERENCE_PEER_QUERY *error); + Tox_Err_Conference_Peer_Query *error); /** * Copy the public key of peer_number who is in conference_number to public_key. @@ -2634,13 +2634,13 @@ bool tox_conference_peer_get_name(const Tox *tox, uint32_t conference_number, ui * @return true on success. */ bool tox_conference_peer_get_public_key(const Tox *tox, uint32_t conference_number, uint32_t peer_number, - uint8_t *public_key, TOX_ERR_CONFERENCE_PEER_QUERY *error); + uint8_t *public_key, Tox_Err_Conference_Peer_Query *error); /** * Return true if passed peer_number corresponds to our own. */ bool tox_conference_peer_number_is_ours(const Tox *tox, uint32_t conference_number, uint32_t peer_number, - TOX_ERR_CONFERENCE_PEER_QUERY *error); + Tox_Err_Conference_Peer_Query *error); /** * Return the number of offline peers in the conference. The unsigned @@ -2648,13 +2648,13 @@ bool tox_conference_peer_number_is_ours(const Tox *tox, uint32_t conference_numb * the functions querying these peers. Return value is unspecified on failure. */ uint32_t tox_conference_offline_peer_count(const Tox *tox, uint32_t conference_number, - TOX_ERR_CONFERENCE_PEER_QUERY *error); + Tox_Err_Conference_Peer_Query *error); /** * Return the length of the offline peer's name. Return value is unspecified on failure. */ size_t tox_conference_offline_peer_get_name_size(const Tox *tox, uint32_t conference_number, - uint32_t offline_peer_number, TOX_ERR_CONFERENCE_PEER_QUERY *error); + uint32_t offline_peer_number, Tox_Err_Conference_Peer_Query *error); /** * Copy the name of offline_peer_number who is in conference_number to name. @@ -2666,7 +2666,7 @@ size_t tox_conference_offline_peer_get_name_size(const Tox *tox, uint32_t confer * @return true on success. */ bool tox_conference_offline_peer_get_name(const Tox *tox, uint32_t conference_number, uint32_t offline_peer_number, - uint8_t *name, TOX_ERR_CONFERENCE_PEER_QUERY *error); + uint8_t *name, Tox_Err_Conference_Peer_Query *error); /** * Copy the public key of offline_peer_number who is in conference_number to public_key. @@ -2675,15 +2675,15 @@ bool tox_conference_offline_peer_get_name(const Tox *tox, uint32_t conference_nu * @return true on success. */ bool tox_conference_offline_peer_get_public_key(const Tox *tox, uint32_t conference_number, - uint32_t offline_peer_number, uint8_t *public_key, TOX_ERR_CONFERENCE_PEER_QUERY *error); + uint32_t offline_peer_number, uint8_t *public_key, Tox_Err_Conference_Peer_Query *error); /** * 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, uint32_t conference_number, - uint32_t offline_peer_number, TOX_ERR_CONFERENCE_PEER_QUERY *error); + uint32_t offline_peer_number, Tox_Err_Conference_Peer_Query *error); -typedef enum TOX_ERR_CONFERENCE_SET_MAX_OFFLINE { +typedef enum Tox_Err_Conference_Set_Max_Offline { /** * The function returned successfully. @@ -2695,16 +2695,16 @@ typedef enum TOX_ERR_CONFERENCE_SET_MAX_OFFLINE { */ TOX_ERR_CONFERENCE_SET_MAX_OFFLINE_CONFERENCE_NOT_FOUND, -} TOX_ERR_CONFERENCE_SET_MAX_OFFLINE; +} Tox_Err_Conference_Set_Max_Offline; /** * Set maximum number of offline peers to store, overriding the default. */ bool tox_conference_set_max_offline(Tox *tox, uint32_t conference_number, uint32_t max_offline_peers, - TOX_ERR_CONFERENCE_SET_MAX_OFFLINE *error); + Tox_Err_Conference_Set_Max_Offline *error); -typedef enum TOX_ERR_CONFERENCE_INVITE { +typedef enum Tox_Err_Conference_Invite { /** * The function returned successfully. @@ -2726,7 +2726,7 @@ typedef enum TOX_ERR_CONFERENCE_INVITE { */ TOX_ERR_CONFERENCE_INVITE_NO_CONNECTION, -} TOX_ERR_CONFERENCE_INVITE; +} Tox_Err_Conference_Invite; /** @@ -2738,9 +2738,9 @@ typedef enum TOX_ERR_CONFERENCE_INVITE { * @return true on success. */ bool tox_conference_invite(Tox *tox, uint32_t friend_number, uint32_t conference_number, - TOX_ERR_CONFERENCE_INVITE *error); + Tox_Err_Conference_Invite *error); -typedef enum TOX_ERR_CONFERENCE_JOIN { +typedef enum Tox_Err_Conference_Join { /** * The function returned successfully. @@ -2777,7 +2777,7 @@ typedef enum TOX_ERR_CONFERENCE_JOIN { */ TOX_ERR_CONFERENCE_JOIN_FAIL_SEND, -} TOX_ERR_CONFERENCE_JOIN; +} Tox_Err_Conference_Join; /** @@ -2798,9 +2798,9 @@ typedef enum TOX_ERR_CONFERENCE_JOIN { * @return conference number on success, an unspecified value on failure. */ uint32_t tox_conference_join(Tox *tox, uint32_t friend_number, const uint8_t *cookie, size_t length, - TOX_ERR_CONFERENCE_JOIN *error); + Tox_Err_Conference_Join *error); -typedef enum TOX_ERR_CONFERENCE_SEND_MESSAGE { +typedef enum Tox_Err_Conference_Send_Message { /** * The function returned successfully. @@ -2827,7 +2827,7 @@ typedef enum TOX_ERR_CONFERENCE_SEND_MESSAGE { */ TOX_ERR_CONFERENCE_SEND_MESSAGE_FAIL_SEND, -} TOX_ERR_CONFERENCE_SEND_MESSAGE; +} Tox_Err_Conference_Send_Message; /** @@ -2848,10 +2848,10 @@ typedef enum TOX_ERR_CONFERENCE_SEND_MESSAGE { * * @return true on success. */ -bool tox_conference_send_message(Tox *tox, uint32_t conference_number, TOX_MESSAGE_TYPE type, const uint8_t *message, - size_t length, TOX_ERR_CONFERENCE_SEND_MESSAGE *error); +bool tox_conference_send_message(Tox *tox, uint32_t conference_number, Tox_Message_Type type, const uint8_t *message, + size_t length, Tox_Err_Conference_Send_Message *error); -typedef enum TOX_ERR_CONFERENCE_TITLE { +typedef enum Tox_Err_Conference_Title { /** * The function returned successfully. @@ -2873,7 +2873,7 @@ typedef enum TOX_ERR_CONFERENCE_TITLE { */ TOX_ERR_CONFERENCE_TITLE_FAIL_SEND, -} TOX_ERR_CONFERENCE_TITLE; +} Tox_Err_Conference_Title; /** @@ -2882,7 +2882,7 @@ typedef enum TOX_ERR_CONFERENCE_TITLE { * The return value is equal to the `length` argument received by the last * `conference_title` callback. */ -size_t tox_conference_get_title_size(const Tox *tox, uint32_t conference_number, TOX_ERR_CONFERENCE_TITLE *error); +size_t tox_conference_get_title_size(const Tox *tox, uint32_t conference_number, Tox_Err_Conference_Title *error); /** * Write the title designated by the given conference number to a byte array. @@ -2898,7 +2898,7 @@ size_t tox_conference_get_title_size(const Tox *tox, uint32_t conference_number, * @return true on success. */ bool tox_conference_get_title(const Tox *tox, uint32_t conference_number, uint8_t *title, - TOX_ERR_CONFERENCE_TITLE *error); + Tox_Err_Conference_Title *error); /** * Set the conference title and broadcast it to the rest of the conference. @@ -2908,7 +2908,7 @@ bool tox_conference_get_title(const Tox *tox, uint32_t conference_number, uint8_ * @return true on success. */ bool tox_conference_set_title(Tox *tox, uint32_t conference_number, const uint8_t *title, size_t length, - TOX_ERR_CONFERENCE_TITLE *error); + Tox_Err_Conference_Title *error); /** * Return the number of conferences in the Tox instance. @@ -2931,10 +2931,10 @@ size_t tox_conference_get_chatlist_size(const Tox *tox); void tox_conference_get_chatlist(const Tox *tox, uint32_t *chatlist); /** - * Returns the type of conference (TOX_CONFERENCE_TYPE) that conference_number is. Return value is + * Returns the type of conference (Tox_Conference_Type) that conference_number is. Return value is * unspecified on failure. */ -typedef enum TOX_ERR_CONFERENCE_GET_TYPE { +typedef enum Tox_Err_Conference_Get_Type { /** * The function returned successfully. @@ -2946,11 +2946,11 @@ typedef enum TOX_ERR_CONFERENCE_GET_TYPE { */ TOX_ERR_CONFERENCE_GET_TYPE_CONFERENCE_NOT_FOUND, -} TOX_ERR_CONFERENCE_GET_TYPE; +} Tox_Err_Conference_Get_Type; -TOX_CONFERENCE_TYPE tox_conference_get_type(const Tox *tox, uint32_t conference_number, - TOX_ERR_CONFERENCE_GET_TYPE *error); +Tox_Conference_Type tox_conference_get_type(const Tox *tox, uint32_t conference_number, + Tox_Err_Conference_Get_Type *error); /** * Get the conference unique ID. @@ -2963,7 +2963,7 @@ TOX_CONFERENCE_TYPE tox_conference_get_type(const Tox *tox, uint32_t conference_ */ bool tox_conference_get_id(const Tox *tox, uint32_t conference_number, uint8_t *id); -typedef enum TOX_ERR_CONFERENCE_BY_ID { +typedef enum Tox_Err_Conference_By_Id { /** * The function returned successfully. @@ -2980,7 +2980,7 @@ typedef enum TOX_ERR_CONFERENCE_BY_ID { */ TOX_ERR_CONFERENCE_BY_ID_NOT_FOUND, -} TOX_ERR_CONFERENCE_BY_ID; +} Tox_Err_Conference_By_Id; /** @@ -2990,7 +2990,7 @@ typedef enum TOX_ERR_CONFERENCE_BY_ID { * * @return the conference number on success, an unspecified value on failure. */ -uint32_t tox_conference_by_id(const Tox *tox, const uint8_t *id, TOX_ERR_CONFERENCE_BY_ID *error); +uint32_t tox_conference_by_id(const Tox *tox, const uint8_t *id, Tox_Err_Conference_By_Id *error); /** * Get the conference unique ID. @@ -3004,7 +3004,7 @@ uint32_t tox_conference_by_id(const Tox *tox, const uint8_t *id, TOX_ERR_CONFERE */ bool tox_conference_get_uid(const Tox *tox, uint32_t conference_number, uint8_t *uid); -typedef enum TOX_ERR_CONFERENCE_BY_UID { +typedef enum Tox_Err_Conference_By_Uid { /** * The function returned successfully. @@ -3021,7 +3021,7 @@ typedef enum TOX_ERR_CONFERENCE_BY_UID { */ TOX_ERR_CONFERENCE_BY_UID_NOT_FOUND, -} TOX_ERR_CONFERENCE_BY_UID; +} Tox_Err_Conference_By_Uid; /** @@ -3032,7 +3032,7 @@ typedef enum TOX_ERR_CONFERENCE_BY_UID { * @return the conference number on success, an unspecified value on failure. * @deprecated use tox_conference_by_id instead (exactly the same function, just renamed). */ -uint32_t tox_conference_by_uid(const Tox *tox, const uint8_t *uid, TOX_ERR_CONFERENCE_BY_UID *error); +uint32_t tox_conference_by_uid(const Tox *tox, const uint8_t *uid, Tox_Err_Conference_By_Uid *error); /******************************************************************************* @@ -3043,7 +3043,7 @@ uint32_t tox_conference_by_uid(const Tox *tox, const uint8_t *uid, TOX_ERR_CONFE -typedef enum TOX_ERR_FRIEND_CUSTOM_PACKET { +typedef enum Tox_Err_Friend_Custom_Packet { /** * The function returned successfully. @@ -3086,7 +3086,7 @@ typedef enum TOX_ERR_FRIEND_CUSTOM_PACKET { */ TOX_ERR_FRIEND_CUSTOM_PACKET_SENDQ, -} TOX_ERR_FRIEND_CUSTOM_PACKET; +} Tox_Err_Friend_Custom_Packet; /** @@ -3110,7 +3110,7 @@ typedef enum TOX_ERR_FRIEND_CUSTOM_PACKET { * @return true on success. */ bool tox_friend_send_lossy_packet(Tox *tox, uint32_t friend_number, const uint8_t *data, size_t length, - TOX_ERR_FRIEND_CUSTOM_PACKET *error); + Tox_Err_Friend_Custom_Packet *error); /** * Send a custom lossless packet to a friend. @@ -3129,7 +3129,7 @@ bool tox_friend_send_lossy_packet(Tox *tox, uint32_t friend_number, const uint8_ * @return true on success. */ bool tox_friend_send_lossless_packet(Tox *tox, uint32_t friend_number, const uint8_t *data, size_t length, - TOX_ERR_FRIEND_CUSTOM_PACKET *error); + Tox_Err_Friend_Custom_Packet *error); /** * @param friend_number The friend number of the friend who sent a lossy packet. @@ -3170,7 +3170,7 @@ void tox_callback_friend_lossless_packet(Tox *tox, tox_friend_lossless_packet_cb -typedef enum TOX_ERR_GET_PORT { +typedef enum Tox_Err_Get_Port { /** * The function returned successfully. @@ -3182,7 +3182,7 @@ typedef enum TOX_ERR_GET_PORT { */ TOX_ERR_GET_PORT_NOT_BOUND, -} TOX_ERR_GET_PORT; +} Tox_Err_Get_Port; /** @@ -3202,56 +3202,60 @@ void tox_self_get_dht_id(const Tox *tox, uint8_t *dht_id); /** * Return the UDP port this Tox instance is bound to. */ -uint16_t tox_self_get_udp_port(const Tox *tox, TOX_ERR_GET_PORT *error); +uint16_t tox_self_get_udp_port(const Tox *tox, Tox_Err_Get_Port *error); /** * Return the TCP port this Tox instance is bound to. This is only relevant if * the instance is acting as a TCP relay. */ -uint16_t tox_self_get_tcp_port(const Tox *tox, TOX_ERR_GET_PORT *error); +uint16_t tox_self_get_tcp_port(const Tox *tox, Tox_Err_Get_Port *error); + #ifdef __cplusplus } #endif -typedef TOX_ERR_OPTIONS_NEW Tox_Err_Options_New; -typedef TOX_ERR_NEW Tox_Err_New; -typedef TOX_ERR_BOOTSTRAP Tox_Err_Bootstrap; -typedef TOX_ERR_SET_INFO Tox_Err_Set_Info; -typedef TOX_ERR_FRIEND_ADD Tox_Err_Friend_Add; -typedef TOX_ERR_FRIEND_DELETE Tox_Err_Friend_Delete; -typedef TOX_ERR_FRIEND_BY_PUBLIC_KEY Tox_Err_Friend_By_Public_Key; -typedef TOX_ERR_FRIEND_GET_PUBLIC_KEY Tox_Err_Friend_Get_Public_Key; -typedef TOX_ERR_FRIEND_GET_LAST_ONLINE Tox_Err_Friend_Get_Last_Online; -typedef TOX_ERR_FRIEND_QUERY Tox_Err_Friend_Query; -typedef TOX_ERR_SET_TYPING Tox_Err_Set_Typing; -typedef TOX_ERR_FRIEND_SEND_MESSAGE Tox_Err_Friend_Send_Message; -typedef TOX_ERR_FILE_CONTROL Tox_Err_File_Control; -typedef TOX_ERR_FILE_SEEK Tox_Err_File_Seek; -typedef TOX_ERR_FILE_GET Tox_Err_File_Get; -typedef TOX_ERR_FILE_SEND Tox_Err_File_Send; -typedef TOX_ERR_FILE_SEND_CHUNK Tox_Err_File_Send_Chunk; -typedef TOX_ERR_CONFERENCE_NEW Tox_Err_Conference_New; -typedef TOX_ERR_CONFERENCE_DELETE Tox_Err_Conference_Delete; -typedef TOX_ERR_CONFERENCE_PEER_QUERY Tox_Err_Conference_Peer_Query; -typedef TOX_ERR_CONFERENCE_SET_MAX_OFFLINE Tox_Err_Conference_Set_Max_Offline; -typedef TOX_ERR_CONFERENCE_BY_ID Tox_Err_Conference_By_Id; -typedef TOX_ERR_CONFERENCE_BY_UID Tox_Err_Conference_By_Uid; -typedef TOX_ERR_CONFERENCE_INVITE Tox_Err_Conference_Invite; -typedef TOX_ERR_CONFERENCE_JOIN Tox_Err_Conference_Join; -typedef TOX_ERR_CONFERENCE_SEND_MESSAGE Tox_Err_Conference_Send_Message; -typedef TOX_ERR_CONFERENCE_TITLE Tox_Err_Conference_Title; -typedef TOX_ERR_CONFERENCE_GET_TYPE Tox_Err_Conference_Get_Type; -typedef TOX_ERR_FRIEND_CUSTOM_PACKET Tox_Err_Friend_Custom_Packet; -typedef TOX_ERR_GET_PORT Tox_Err_Get_Port; -typedef TOX_USER_STATUS Tox_User_Status; -typedef TOX_MESSAGE_TYPE Tox_Message_Type; -typedef TOX_PROXY_TYPE Tox_Proxy_Type; -typedef TOX_SAVEDATA_TYPE Tox_Savedata_Type; -typedef TOX_LOG_LEVEL Tox_Log_Level; -typedef TOX_CONNECTION Tox_Connection; -typedef TOX_FILE_CONTROL Tox_File_Control; -typedef TOX_CONFERENCE_TYPE Tox_Conference_Type; +//!TOKSTYLE- + +typedef Tox_Err_Options_New TOX_ERR_OPTIONS_NEW; +typedef Tox_Err_New TOX_ERR_NEW; +typedef Tox_Err_Bootstrap TOX_ERR_BOOTSTRAP; +typedef Tox_Err_Set_Info TOX_ERR_SET_INFO; +typedef Tox_Err_Friend_Add TOX_ERR_FRIEND_ADD; +typedef Tox_Err_Friend_Delete TOX_ERR_FRIEND_DELETE; +typedef Tox_Err_Friend_By_Public_Key TOX_ERR_FRIEND_BY_PUBLIC_KEY; +typedef Tox_Err_Friend_Get_Public_Key TOX_ERR_FRIEND_GET_PUBLIC_KEY; +typedef Tox_Err_Friend_Get_Last_Online TOX_ERR_FRIEND_GET_LAST_ONLINE; +typedef Tox_Err_Friend_Query TOX_ERR_FRIEND_QUERY; +typedef Tox_Err_Set_Typing TOX_ERR_SET_TYPING; +typedef Tox_Err_Friend_Send_Message TOX_ERR_FRIEND_SEND_MESSAGE; +typedef Tox_Err_File_Control TOX_ERR_FILE_CONTROL; +typedef Tox_Err_File_Seek TOX_ERR_FILE_SEEK; +typedef Tox_Err_File_Get TOX_ERR_FILE_GET; +typedef Tox_Err_File_Send TOX_ERR_FILE_SEND; +typedef Tox_Err_File_Send_Chunk TOX_ERR_FILE_SEND_CHUNK; +typedef Tox_Err_Conference_New TOX_ERR_CONFERENCE_NEW; +typedef Tox_Err_Conference_Delete TOX_ERR_CONFERENCE_DELETE; +typedef Tox_Err_Conference_Peer_Query TOX_ERR_CONFERENCE_PEER_QUERY; +typedef Tox_Err_Conference_Set_Max_Offline TOX_ERR_CONFERENCE_SET_MAX_OFFLINE; +typedef Tox_Err_Conference_By_Id TOX_ERR_CONFERENCE_BY_ID; +typedef Tox_Err_Conference_By_Uid TOX_ERR_CONFERENCE_BY_UID; +typedef Tox_Err_Conference_Invite TOX_ERR_CONFERENCE_INVITE; +typedef Tox_Err_Conference_Join TOX_ERR_CONFERENCE_JOIN; +typedef Tox_Err_Conference_Send_Message TOX_ERR_CONFERENCE_SEND_MESSAGE; +typedef Tox_Err_Conference_Title TOX_ERR_CONFERENCE_TITLE; +typedef Tox_Err_Conference_Get_Type TOX_ERR_CONFERENCE_GET_TYPE; +typedef Tox_Err_Friend_Custom_Packet TOX_ERR_FRIEND_CUSTOM_PACKET; +typedef Tox_Err_Get_Port TOX_ERR_GET_PORT; +typedef Tox_User_Status TOX_USER_STATUS; +typedef Tox_Message_Type TOX_MESSAGE_TYPE; +typedef Tox_Proxy_Type TOX_PROXY_TYPE; +typedef Tox_Savedata_Type TOX_SAVEDATA_TYPE; +typedef Tox_Log_Level TOX_LOG_LEVEL; +typedef Tox_Connection TOX_CONNECTION; +typedef Tox_File_Control TOX_FILE_CONTROL; +typedef Tox_Conference_Type TOX_CONFERENCE_TYPE; +typedef enum Tox_File_Kind TOX_FILE_KIND; //!TOKSTYLE+ diff --git a/toxencryptsave/toxencryptsave.api.h b/toxencryptsave/toxencryptsave.api.h deleted file mode 100644 index df5d1136..00000000 --- a/toxencryptsave/toxencryptsave.api.h +++ /dev/null @@ -1,311 +0,0 @@ -%{ -/* SPDX-License-Identifier: GPL-3.0-or-later - * Copyright © 2016-2018 The TokTok team. - * Copyright © 2013-2016 Tox Developers. - */ - -/* - * Batch encryption functions. - */ -#ifndef C_TOXCORE_TOXENCRYPTSAVE_TOXENCRYPTSAVE_H -#define C_TOXCORE_TOXENCRYPTSAVE_TOXENCRYPTSAVE_H - -//!TOKSTYLE- - -#ifdef __cplusplus -extern "C" { -#endif - -#include -#include -#include -%} - -/******************************************************************************* - * - * This module is organized into two parts. - * - * 1. A simple API operating on plain text/cipher text data and a password to - * encrypt or decrypt it. - * 2. A more advanced API that splits key derivation and encryption into two - * separate function calls. - * - * The first part is implemented in terms of the second part and simply calls - * the separate functions in sequence. Since key derivation is very expensive - * compared to the actual encryption, clients that do a lot of crypto should - * prefer the advanced API and reuse pass-key objects. - * - * To use the second part, first derive an encryption key from a password with - * ${tox.pass_Key.derive}, then use the derived key to encrypt the data. - * - * The encrypted data is prepended with a magic number, to aid validity - * checking (no guarantees are made of course). Any data to be decrypted must - * start with the magic number. - * - * Clients should consider alerting their users that, unlike plain data, if - * even one bit becomes corrupted, the data will be entirely unrecoverable. - * Ditto if they forget their password, there is no way to recover the data. - * - *******************************************************************************/ - -class tox { - -/** - * The size of the salt part of a pass-key. - */ -const PASS_SALT_LENGTH = 32; -/** - * The size of the key part of a pass-key. - */ -const PASS_KEY_LENGTH = 32; -/** - * The amount of additional data required to store any encrypted byte array. - * Encrypting an array of N bytes requires N + $PASS_ENCRYPTION_EXTRA_LENGTH - * bytes in the encrypted byte array. - */ -const PASS_ENCRYPTION_EXTRA_LENGTH = 80; - -error for key_derivation { - NULL, - /** - * The crypto lib was unable to derive a key from the given passphrase, - * which is usually a lack of memory issue. - */ - FAILED, -} - -error for encryption { - NULL, - /** - * The crypto lib was unable to derive a key from the given passphrase, - * which is usually a lack of memory issue. The functions accepting keys - * do not produce this error. - */ - KEY_DERIVATION_FAILED, - /** - * The encryption itself failed. - */ - FAILED, -} - -error for decryption { - NULL, - /** - * The input data was shorter than $PASS_ENCRYPTION_EXTRA_LENGTH bytes - */ - INVALID_LENGTH, - /** - * The input data is missing the magic number (i.e. wasn't created by this - * module, or is corrupted). - */ - BAD_FORMAT, - /** - * The crypto lib was unable to derive a key from the given passphrase, - * which is usually a lack of memory issue. The functions accepting keys - * do not produce this error. - */ - KEY_DERIVATION_FAILED, - /** - * The encrypted byte array could not be decrypted. Either the data was - * corrupted or the password/key was incorrect. - */ - FAILED, -} - - -/******************************************************************************* - * - * BEGIN PART 1 - * - * The simple API is presented first. If your code spends too much time using - * these functions, consider using the advanced functions instead and caching - * the generated pass-key. - * - *******************************************************************************/ - -/** - * Encrypts the given data with the given passphrase. - * - * The output array must be at least `plaintext_len + $PASS_ENCRYPTION_EXTRA_LENGTH` - * bytes long. This delegates to ${pass_Key.derive} and - * ${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. - * @param passphrase The user-provided password. Can be empty. - * @param passphrase_len The length of the password. - * @param ciphertext The cipher text array to write the encrypted data to. - * - * @return true on success. - */ -static bool pass_encrypt(const uint8_t[plaintext_len] plaintext, const uint8_t[passphrase_len] passphrase, uint8_t *ciphertext) - with error for encryption; - - -/** - * Decrypts the given data with the given passphrase. - * - * The output array must be at least `ciphertext_len - $PASS_ENCRYPTION_EXTRA_LENGTH` - * bytes long. This delegates to ${pass_Key.decrypt}. - * - * @param ciphertext A byte array of length `ciphertext_len`. - * @param ciphertext_len The length of the cipher text array. At least $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. - * - * @return true on success. - */ -static bool pass_decrypt(const uint8_t[ciphertext_len] ciphertext, const uint8_t[passphrase_len] passphrase, uint8_t *plaintext) - with error for decryption; - - -/******************************************************************************* - * - * BEGIN PART 2 - * - * And now part 2, which does the actual encryption, and can be used to write - * less CPU intensive client code than part one. - * - *******************************************************************************/ - -class pass_Key { - /** - * This type represents a pass-key. - * - * A pass-key and a password are two different concepts: a password is given - * by the user in plain text. A pass-key is the generated symmetric key used - * for encryption and decryption. It is derived from a salt and the user- - * provided password. - * - * The $this structure is hidden in the implementation. It can be created - * using $derive or $derive_with_salt and must be deallocated using $free. - */ - struct this; - - /** - * Deallocate a $this. This function behaves like free(), so NULL is an - * acceptable argument value. - */ - void free(); - - /** - * Generates a secret symmetric key from the given passphrase. - * - * Be sure to not compromise the key! Only keep it in memory, do not write - * it to disk. - * - * Note that this function is not deterministic; to derive the same key from - * a password, you also must know the random salt that was used. A - * deterministic version of this function is $derive_with_salt. - * - * @param passphrase The user-provided password. Can be empty. - * @param passphrase_len The length of the password. - * - * @return true on success. - */ - static this derive(const uint8_t[passphrase_len] passphrase) - with error for key_derivation; - - /** - * Same as above, except use the given salt for deterministic key derivation. - * - * @param passphrase The user-provided password. Can be empty. - * @param passphrase_len The length of the password. - * @param salt An array of at least $PASS_SALT_LENGTH bytes. - * - * @return true on success. - */ - static this derive_with_salt(const uint8_t[passphrase_len] passphrase, const uint8_t[PASS_SALT_LENGTH] salt) - with error for key_derivation; - - /** - * Encrypt a plain text with a key produced by $derive or $derive_with_salt. - * - * The output array must be at least `plaintext_len + $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. - * @param ciphertext The cipher text array to write the encrypted data to. - * - * @return true on success. - */ - const bool encrypt(const uint8_t[plaintext_len] plaintext, uint8_t *ciphertext) - with error for encryption; - - /** - * This is the inverse of $encrypt, also using only keys produced by - * $derive or $derive_with_salt. - * - * @param ciphertext A byte array of length `ciphertext_len`. - * @param ciphertext_len The length of the cipher text array. At least $PASS_ENCRYPTION_EXTRA_LENGTH. - * @param plaintext The plain text array to write the decrypted data to. - * - * @return true on success. - */ - const bool decrypt(const uint8_t[ciphertext_len] ciphertext, uint8_t *plaintext) - with error for decryption; -} - -/** - * Retrieves the salt used to encrypt the given data. - * - * The retrieved salt can then be passed to ${pass_Key.derive_with_salt} to - * 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 $PASS_ENCRYPTION_EXTRA_LENGTH bytes in length. - * The salt must be $PASS_SALT_LENGTH bytes in length. - * If the passed byte arrays are smaller than required, the behaviour is - * undefined. - * - * If the cipher text pointer or the salt is NULL, this function returns false. - * - * Success does not say anything about the validity of the data, only that - * data of the appropriate size was copied. - * - * @return true on success. - */ -static bool get_salt(const uint8_t *ciphertext, uint8_t[PASS_SALT_LENGTH] salt) { - NULL, - /** - * The input data is missing the magic number (i.e. wasn't created by this - * module, or is corrupted). - */ - BAD_FORMAT, -} - -/** - * Determines whether or not the given data is encrypted by this module. - * - * It does this check by verifying that the magic number is the one put in - * place by the encryption functions. - * - * The data must be at least $PASS_ENCRYPTION_EXTRA_LENGTH bytes in length. - * If the passed byte array is smaller than required, the behaviour is - * undefined. - * - * If the data pointer is NULL, the behaviour is undefined - * - * @return true if the data is encrypted by this module. - */ -static bool is_data_encrypted(const uint8_t *data); - -} - -%{ - -#ifdef __cplusplus -} -#endif - -typedef TOX_ERR_KEY_DERIVATION Tox_Err_Key_Derivation; -typedef TOX_ERR_ENCRYPTION Tox_Err_Encryption; -typedef TOX_ERR_DECRYPTION Tox_Err_Decryption; -typedef TOX_ERR_GET_SALT Tox_Err_Get_Salt; - -//!TOKSTYLE+ - -#endif // C_TOXCORE_TOXENCRYPTSAVE_TOXENCRYPTSAVE_H -%} diff --git a/toxencryptsave/toxencryptsave.h b/toxencryptsave/toxencryptsave.h index 4b58165e..cca8878a 100644 --- a/toxencryptsave/toxencryptsave.h +++ b/toxencryptsave/toxencryptsave.h @@ -6,11 +6,10 @@ /* * Batch encryption functions. */ + #ifndef C_TOXCORE_TOXENCRYPTSAVE_TOXENCRYPTSAVE_H #define C_TOXCORE_TOXENCRYPTSAVE_TOXENCRYPTSAVE_H -//!TOKSTYLE- - #ifdef __cplusplus extern "C" { #endif @@ -72,7 +71,7 @@ uint32_t tox_pass_key_length(void); uint32_t tox_pass_encryption_extra_length(void); -typedef enum TOX_ERR_KEY_DERIVATION { +typedef enum Tox_Err_Key_Derivation { /** * The function returned successfully. @@ -90,10 +89,10 @@ typedef enum TOX_ERR_KEY_DERIVATION { */ TOX_ERR_KEY_DERIVATION_FAILED, -} TOX_ERR_KEY_DERIVATION; +} Tox_Err_Key_Derivation; -typedef enum TOX_ERR_ENCRYPTION { +typedef enum Tox_Err_Encryption { /** * The function returned successfully. @@ -117,10 +116,10 @@ typedef enum TOX_ERR_ENCRYPTION { */ TOX_ERR_ENCRYPTION_FAILED, -} TOX_ERR_ENCRYPTION; +} Tox_Err_Encryption; -typedef enum TOX_ERR_DECRYPTION { +typedef enum Tox_Err_Decryption { /** * The function returned successfully. @@ -156,7 +155,7 @@ typedef enum TOX_ERR_DECRYPTION { */ TOX_ERR_DECRYPTION_FAILED, -} TOX_ERR_DECRYPTION; +} Tox_Err_Decryption; @@ -188,7 +187,7 @@ typedef enum TOX_ERR_DECRYPTION { * @return true on success. */ bool tox_pass_encrypt(const uint8_t *plaintext, size_t plaintext_len, const uint8_t *passphrase, size_t passphrase_len, - uint8_t *ciphertext, TOX_ERR_ENCRYPTION *error); + uint8_t *ciphertext, Tox_Err_Encryption *error); /** * Decrypts the given data with the given passphrase. @@ -205,7 +204,7 @@ bool tox_pass_encrypt(const uint8_t *plaintext, size_t plaintext_len, const uint * @return true on success. */ bool tox_pass_decrypt(const uint8_t *ciphertext, size_t ciphertext_len, const uint8_t *passphrase, - size_t passphrase_len, uint8_t *plaintext, TOX_ERR_DECRYPTION *error); + size_t passphrase_len, uint8_t *plaintext, Tox_Err_Decryption *error); /******************************************************************************* @@ -239,7 +238,7 @@ typedef struct Tox_Pass_Key Tox_Pass_Key; * Deallocate a Tox_Pass_Key. This function behaves like free(), so NULL is an * acceptable argument value. */ -void tox_pass_key_free(struct Tox_Pass_Key *_key); +void tox_pass_key_free(struct Tox_Pass_Key *key); /** * Generates a secret symmetric key from the given passphrase. @@ -249,7 +248,7 @@ void tox_pass_key_free(struct Tox_Pass_Key *_key); * * Note that this function is not deterministic; to derive the same key from * a password, you also must know the random salt that was used. A - * deterministic version of this function is tox_pass_key_derive_with_salt. + * deterministic version of this function is `tox_pass_key_derive_with_salt`. * * @param passphrase The user-provided password. Can be empty. * @param passphrase_len The length of the password. @@ -257,7 +256,7 @@ void tox_pass_key_free(struct Tox_Pass_Key *_key); * @return true on success. */ struct Tox_Pass_Key *tox_pass_key_derive(const uint8_t *passphrase, size_t passphrase_len, - TOX_ERR_KEY_DERIVATION *error); + Tox_Err_Key_Derivation *error); /** * Same as above, except use the given salt for deterministic key derivation. @@ -269,7 +268,7 @@ struct Tox_Pass_Key *tox_pass_key_derive(const uint8_t *passphrase, size_t passp * @return true on success. */ struct Tox_Pass_Key *tox_pass_key_derive_with_salt(const uint8_t *passphrase, size_t passphrase_len, - const uint8_t *salt, TOX_ERR_KEY_DERIVATION *error); + const uint8_t *salt, 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. @@ -283,8 +282,8 @@ struct Tox_Pass_Key *tox_pass_key_derive_with_salt(const uint8_t *passphrase, si * * @return true on success. */ -bool tox_pass_key_encrypt(const struct Tox_Pass_Key *_key, const uint8_t *plaintext, size_t plaintext_len, - uint8_t *ciphertext, TOX_ERR_ENCRYPTION *error); +bool tox_pass_key_encrypt(const struct Tox_Pass_Key *key, const uint8_t *plaintext, size_t plaintext_len, + uint8_t *ciphertext, Tox_Err_Encryption *error); /** * This is the inverse of tox_pass_key_encrypt, also using only keys produced by @@ -296,10 +295,10 @@ bool tox_pass_key_encrypt(const struct Tox_Pass_Key *_key, const uint8_t *plaint * * @return true on success. */ -bool tox_pass_key_decrypt(const struct Tox_Pass_Key *_key, const uint8_t *ciphertext, size_t ciphertext_len, - uint8_t *plaintext, TOX_ERR_DECRYPTION *error); +bool tox_pass_key_decrypt(const struct Tox_Pass_Key *key, const uint8_t *ciphertext, size_t ciphertext_len, + uint8_t *plaintext, Tox_Err_Decryption *error); -typedef enum TOX_ERR_GET_SALT { +typedef enum Tox_Err_Get_Salt { /** * The function returned successfully. @@ -317,7 +316,7 @@ typedef enum TOX_ERR_GET_SALT { */ TOX_ERR_GET_SALT_BAD_FORMAT, -} TOX_ERR_GET_SALT; +} Tox_Err_Get_Salt; /** @@ -339,7 +338,7 @@ typedef enum TOX_ERR_GET_SALT { * * @return true on success. */ -bool tox_get_salt(const uint8_t *ciphertext, uint8_t *salt, TOX_ERR_GET_SALT *error); +bool tox_get_salt(const uint8_t *ciphertext, uint8_t *salt, Tox_Err_Get_Salt *error); /** * Determines whether or not the given data is encrypted by this module. @@ -362,10 +361,12 @@ bool tox_is_data_encrypted(const uint8_t *data); } #endif -typedef TOX_ERR_KEY_DERIVATION Tox_Err_Key_Derivation; -typedef TOX_ERR_ENCRYPTION Tox_Err_Encryption; -typedef TOX_ERR_DECRYPTION Tox_Err_Decryption; -typedef TOX_ERR_GET_SALT Tox_Err_Get_Salt; +//!TOKSTYLE- + +typedef Tox_Err_Key_Derivation TOX_ERR_KEY_DERIVATION; +typedef Tox_Err_Encryption TOX_ERR_ENCRYPTION; +typedef Tox_Err_Decryption TOX_ERR_DECRYPTION; +typedef Tox_Err_Get_Salt TOX_ERR_GET_SALT; //!TOKSTYLE+