libtoxcore-racket🔗 i

2.1Constants🔗 i

value

TOX_PUBLIC_KEY_SIZE :32

value

TOX_SECRET_KEY_SIZE :32

value

TOX_ADDRESS_SIZE

:

(+ TOX_PUBLIC_KEY_SIZE

(ctype-sizeofuint32_t)(ctype-sizeofuint16_t))

value

TOX_MAX_NAME_LENGTH :128

value

TOX_MAX_STATUS_MESSAGE_LENGTH :1007

value

TOX_MAX_FRIEND_REQUEST_LENGTH :1016

value

TOX_MAX_CUSTOM_PACKET_SIZE :1373

value

TOX_HASH_LENGTH :32

value

TOX_FILE_ID_LENGTH :32

value

TOX_MAX_FILENAME_LENGTH :255

value

TOXDNS_MAX_RECOMMENDED_NAME_LENGTH :32

2.2Enums🔗 i

Tox uses various enumerations in many of its functions and they are explained below.

value

_TOX-USER-STATUS :'(availableawaybusy)

value

_TOX-MESSAGE-TYPE :'(normalaction)

value

_TOX-PROXY-TYPE :'(nonehttpsocks5)

value

_TOX-ERR-OPTIONS-NEW :'(okmalloc)

'port-alloc is returned when 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.

'proxy-bad-type is returned when the proxy-type variable was invalid.

'proxy-bad-host is returned when the proxy-type variable was valid, but the proxy-host had an invalid format or was NULL.

'proxy-bad-port is returned when the proxy-type was valid, but the proxy-port was invalid.

'proxy-not-found is returned when the proxy host passed could not be resolved.

'load-encrypted is returned when the bytes loaded into the function contained an encrypted save.

'load-bad-format is returned when 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.

value

_TOX-ERR-BOOTSTRAP :'(oknullbad-hostbad-port)

value

_TOX-CONNECTION :'(nonetcpudp)

value

_TOX-ERR-SET-INFO :'(oknulltoo-long)

'avatar is used when sending avatar 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 TOX_FILE_CONTROL_CANCEL before any other controls), or accept it (by sending TOX_FILE_CONTROL_RESUME). The file_id of length TOX_HASH_LENGTH bytes (same length as TOX_FILE_ID_LENGTH) will contain the hash. A client can compare this hash with a saved hash and send TOX_FILE_CONTROL_CANCEL to terminate the avatar transfer if it matches. When file_size is set to 0 in the transfer request it means that the client has no avatar.

'pause is sent by clients to pause the file transfer. The initial state of a file transfer is always paused on the receiving side and running on the sending side. If both the sending and receiving side pause the transfer, then both need to send TOX_FILE_CONTROL_RESUME for the transfer to resume.

'cancel is sent by the receiving client to reject a file send request before any other commands are sent. Also sent by either side to terminate a file transfer.

'denied is returned when a 'resume control was sent, but the file transfer was paused by the other party. Only the party that paused the transfar can resume it.

'senq is returned when the packet queue is full.

'seek-denied is returned when the file was not in a state where it could be seeked.

'invalid-position is returned when the seek position was invalid.

'senq is returned when the packet queue is full.

value

_TOX-ERR-FILE-GET :'(okfriend-not-foundtransfer-not-found)

value

_TOX-ERR-FILE-SEND :

'(ok

null

friend-not-found

friend-not-connected

name-too-long

too-many)

value

_TOX-ERR-FILE-SEND-CHUNK :

'(ok

null

friend-not-found

friend-not-connected

not-found

not-transferring

invalid-length

senq

wrong-position)

value

_TOX-ERR-FRIEND-CUSTOM-PACKET :

'(ok

null

friend-not-found

friend-not-connected

invalid

empty

too-long

sendq)

value

_TOX-ERR-KEY-DERIVATION :'(oknullfailed)

'key-derivation-failed is returned when 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.

'encryption-failed is returned when the encryption itself failed.

value

_TOX-ERR-DECRYPTION :

'(ok

null

invalid-length

bad-format

key-derivation-failed

decryption-failed)

value

_TOX-GROUPCHAT-TYPE :'(textav)

'del is for when a peer has left the groupchat.

'name is for when a peer has changed her nickname.

'Ringing is when the peer is ready to accept/reject the call.

'Start is when the call (rtp transmission) has started.

'Cancel is when the side that initiated the call has canceled the invite.

'Reject is when the side that was invited rejected the call.

'End is when the call that was active has ended.

'RequestTimeout is when the request didn’t get a response in time.

'PeerTimeout peer timed out; stop the call.

'PeerCSChange is when the peer changed csettings. Prepare for changed AV.

'SelfCSChange is for csettings change confirmation. Once triggered, the peer is ready to receive changed AV.

'CallInviting is for when we’re sending a call invite.

'CallStarting is for when we’re getting a call invite.

'InvalidState means we are trying to perform a call action while in an invalid state.

'AlreadyInCallWithPeer means we are trying to call peer when already in a call with peer.

'ReachedCallLimit means we cannot handle more calls.

'InitializingCodecs means we failed to create a CSSession.

'SplittingVideoPayload means there was an error splitting the video payload

'EncodingVideo means vpx_codec_encode failed.

'EncodingAudio means opus_encode failed.

'SendingPayload means sending lossy packet failed.

'CreatingRtpSessions means one of the rtp sessions failed to initialize.

'NoRtpSession means we tried to perform an rtp action on an invalid session.

'InvalidCodecState means the codec state was not initialized.

'PacketTooLarge means the buffer exceeds size while encoding.

Those not listed above are self-explanatory.

'AudioDecoding is equivalent to 1 << 1 or (expt 21)

'VideoEncoding is equivalent to 1 << 2 or (expt 22)

'VideoDecoding is equivalent to 1 << 3 or (expt 23)

3.1Getters and Setters🔗 i

You should use this to determine how much memory to allocate for copy_friendlist.

return #t if friend exists.

return #f if friend doesn’t exist.

Return an address to give to others. (Must be transformed into hex format for ordinary usage).

return public key if success.

return #f if failure.

return 1 if friend is connected to us (Online).

return 0 if friend is not connected to us (Offline).

return -1 on failure.

Returns the friend list (in bytes).

If the list-size was too small, the contents of the return value will be truncated to list-size.

return #f if no such friend

returns #t if friend is typing.

returns #f if friend is not typing.

returns #f on error.

return #f if failure.

returns #f on failure.

return 0 on error.

return #f on failure.

return #f on failure.

Values unknown to your application should be represented as TOX_USERSTATUS_NONE.

If friendnumber is invalid, this shall return TOX_USERSTATUS_INVALID.

The self variant will return our own status message.

returns the status message (in bytes) of the friend on success.

return #f on failure.

returns #f on failure.

name must be a string of maximum TOX_MAX_NAME_LENGTH length.

length must be at least 1 byte.

length is the length of name with the NULL terminator.

return #t if success.

return #f if failure.

max length of the status is TOX_MAX_STATUSMESSAGE_LENGTH.

returns #t on success.

returns #f on failure.

userstatus must be one of TOX_USERSTATUS values.

returns #t on success.

returns #f on failure.

You are responsible for turning it on or off.

returns #t on success.

returns #f on failure.

return #f on failure

Returns a list whose car is the lengths if the names in its cdr on success.

return #f on failure.

return #f on failure

You should use this to determine how much memory to allocate for copy_chatlist.

If list-size was too small, the contents of the return value will be truncated to list-size.

return 0 on failure.

public-key and secret-key must be 32 bytes long.

if the pointer is NULL, no data will be copied to it.

return #t on success

return #f on failure.

Return title (in bytes) on success.

return #f on failure.

3.2Interact with Tox🔗 i

address can be a hostname or an IP address (IPv4 or IPv6)

returns #t if the address was converted into an IP address

returns #f otherwise

return #t if we are.

return the message id if packet was successfully put into the send queue.

return 0 if it was not.

maximum length of messages is TOX_MAX_MESSAGE_LENGTH , your client must split larger messages or else sending them will not work.

You will want to retain the return value, it will be passed to your read_receipt callback if one is received.

return the message id if packet was successfully put into the send queue.

return 0 if it was not.

You will want to retain the return value, it will be passed to your read_receipt callback if one is received.

return #t on success.

return #f on failure.

return #t on success.

return #f on failure.

returns #t if it does

returns #f if it does not.

Set udp-disabled? to #t to disable udp support. (default: #f) This will force Tox to use TCP only which may slow things down. Disabling udp support is necessary when using anonymous proxies or Tor.

proxy-type is a value from TOX_PROXY_TYPE enumerator.

proxy-address is the IP or domain of the proxy.

proxy-port is the port of the proxy in host byte order.

Options are some options that can be passed to the Tox instance (see above struct).

If options is null , tox-new will use default settings.

Initializes a tox structure

return allocated instance of tox on success.

return 0 if there are problems.

Free all datastructures.

3.3Saving and Loading Functions🔗 i

returns #t on success

returns #f on failure

3.4Friend and Group Manipulation🔗 i

Set the message that will be sent along with friend request. Must not be longer than TOX_MAX_FRIENDREQUEST_LENGTH length in bytes.

address is the address of the friend (returned by getaddress of the friend you wish to add) it must be TOX_ADDRESS_SIZE bytes.

message is the friend request message and message-length is the length of the message being sent.

return the friend number if success.

return TOX_FA_TOOLONG if message length is too long.

return TOX_FAERR_NOMESSAGE if no message (message length must be >= 1 byte).

return TOX_FAERR_OWNKEY if our own key.

return TOX_FAERR_ALREADYSENT if friend request already sent or already a friend.

return TOX_FAERR_UNKNOWN for unknown error.

return TOX_FAERR_BADCHECKSUM if bad checksum in address.

return TOX_FAERR_SETNEWNOSPAM if the friend was already there but the nospam was different. (the nospam for that friend was set to a different one).

return TOX_FAERR_NOMEM if increasing the friend list size fails.

return the friend number on success.

return #f on failure.

public-key is the bytes form of the Tox ID; e.g. (hex-string->bytesstr).

return #t if success.

return #f if failure.

return group number on success.

return #f on failure.

return #t on success.

return #f on failure.

return #t on success.

return #f on failure.

return groupnumber on success.

return #f on failure.

3.5Filesending Functions🔗 i

Maximum filename length is 255 bytes.

return file number on success

return #f on failure

return #t on success

return #f on failure

return #t on success

return #f on failure

If this function returns #f, you must tox-do, sleep tox-do-interval miliseconds, then attempt to send the data again.

return size on success

return #f on failure (currently will never return #f)

return number of bytes remaining to be sent/received on success

return #f on failure

3.6Avatar Handling and Manipulation🔗 i

This should be made before connecting, so we will not announce that the user have no avatar before setting and announcing a new one, forcing the peers to re-download it.

Notice that the library treats the image as raw data and does not interpret it by any way.

Arguments:

format - Avatar image format or NONE for user with no avatar (see TOX_AVATAR_FORMAT);

data - bytes containing the avatar data (may be NULL it the format is NONE);

len - length of image data. Must be <= TOX_AVATAR_MAX_DATA_LENGTH.

returns #t on success

returns #f on failure.

returns 0 on success (currently always returns 0).

returns a list containing the image hash and the image data.

returns #f on failure.

This function may be used by clients for any purpose, but is provided primarily for validating cached avatars.

This function is a wrapper to internal message-digest functions.

returns hash (in bytes) on success

returns #f on failure.

Asks a friend to provide their avatar information (image format and hash). The friend may or may not answer this request and, if answered, the information will be provided through the callback ’avatar_info’.

returns #t on success

returns #f on failure.

Sends our avatar format and hash to a friend; he/she can use this information to validate an avatar from the cache and may (or not) reply with an avatar data request.

Notice: it is NOT necessary to send this notification after changing the avatar or connecting. The library already does this.

returns #t on success

returns #f on failure.

Ask a friend to send their avatar data. The friend may or may not answer this request and, if answered, the information will be provided in callback ’avatar_data’.

returns #t on sucess

returns #f on failure.

3.7Callbacks🔗 i

4.1Structs🔗 i

video_bitrate is in kbit/s

video_width is in px

video_height is in px

audio_bitrate is in bits/s

audio_frame_duration is in ms

audio_sample_rate is in Hz

4.2Procedures🔗 i

return _ToxAv-pointer

return NULL On error.

return void

callback is the ToxAvCallback procedure.

id is one of the ToxAvCallbackID values

return void

callback is in the ToxAvAudioCallback procedure.

return void

callback is in the ToxAvAudioCallback procedure.

return void

return #t on success.

return _ToxAvError on error.

return #t on success.

return _ToxAvError On error.

Optional reason. Set NULL if none.

return #t on success.

return _ToxAvError on error.

return 0 on success

return _ToxAvError

Optional reason.

return 0 on success.

return _ToxAvError on error.

return 0 on success.

return _ToxAvError on error.

Also, it must be called when call is started

return 0 on success.

return _ToxAvError on error.

return 0 on success.

return _ToxAvError on error.

return >0 on success.

return _ToxAvError on error.

frame is the frame (raw 16 bit signed pcm with AUDIO_CHANNELS channels audio.)

frame-size is its size in number of frames/samples (one frame/sample is 16 bits or 2 bytes). frame-size should be AUDIO_FRAME_SIZE.

return 0 on success.

return _ToxAvError on error.

return a list containing _ToxAvCallType and a csettings cpointer on success.

return a list containing _ToxAvError on error.

return _ToxAvError when there is no peer id

returns integer from _ToxAvCallState .

capability is on of ToxAvCapabilities.

audio-callback is in the form (audio-callbacktoxgroupnumberpeernumberpcmsampleschannelssample-rateuserdata) where pcm is a byte string of the size (* sampleschannels(ctype-sizeofint16_t)).

return groupnumber on success.

return -1 on failure.

audio-callback is in the form (audio-callbacktoxgroupnumberpeernumberpcmsampleschannelssample-rateuserdata) where pcm is of size (* sampleschannels).

return groupnumber on success.

return -1 on failure.

Note that pcm is a byte string of the size (* sampleschannels(ctype-sizeofint16_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

return 0 on success

return -1 on failure.

5.1Library License🔗 i

Copyright (C) 2014 Lehi Toskin.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License and GNU Lesser General Public License for more details.

5.2Documentation License🔗 i

Copyright (C) 2014 Lehi Toskin.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".