├── Important ├── Avatars.md ├── File_Transfers.md ├── Toxcore_Save_Data_Directory.md ├── Toxcore_Save_Export_Import.md └── User_Profile_Encryption.md ├── README.md ├── Recommendations └── Tox_ID_DNS_resolution.md ├── Required ├── Bootstrapping.md ├── Tox_ID.md └── Toxcore_features.md └── Suggestions ├── Resuming.md └── Theme_support.md /Important/Avatars.md: -------------------------------------------------------------------------------- 1 | Avatars are PNG images with a maximum size of (2^16) bytes (client enforced). 2 | 3 | Currently avatars are sent as a normal file transfer with kind avatar. Every 4 | time a friend goes online you must send them a new avatar transfer. The file_id 5 | will be set to the hash of the avatar (If no avatar is set, the size of the 6 | avatar will be set to zero and the file_id will be set to NULL). If the avatar 7 | transfer is canceled by the friend, the client will assume the friend already 8 | has the avatar and will not try to send it again (unless the friend goes 9 | offline and back online). 10 | 11 | If the avatar is changed a new avatar transfer will be started to all online 12 | friends. 13 | 14 | If the client receives a new file transfer with type avatar, he will first 15 | check if the size is 0. If the size is 0 he will cancel the file transfer and 16 | remove the avatar of the friend if it was set. If the size is non zero, the 17 | client will check if the hash of the current avatar he has for the friend 18 | matches the file_id for the incoming avatar transfer. If it matches, the 19 | client will cancel the transfer. If it doesn't, the client will accept the 20 | transfer. 21 | 22 | 23 | It is desirable that the user avatar and the cached friends avatars could be 24 | shared among different Tox clients in the same system. This not only makes 25 | switching from one client to another easier, but also minimizes the need of 26 | data transfers, as avatars already downloaded by other clients can be reused. 27 | 28 | - Avatars are stored in a directory called "avatars" and named 29 | as "xxxxx.png", where "xxxxx" is the complete public key (but not friend 30 | address!) encoded as an uppercase hexadecimal string and "png" is the 31 | extension for the PNG avatar. As new image formats may be used in the 32 | future, clients should ensure no other file "xxxxx.*" exists. No file 33 | should be kept for a user who has no avatar. 34 | 35 | - The client's own avatar is not special and is stored like any other. This 36 | is partially for simplicity, and partially in anticipation of profiles. 37 | 38 | - The avatar should be stored as its received, before any modifications by 39 | the client for display purposes. 40 | 41 | 42 | Example for Linux and other Unix systems, assuming an user called "gildor": 43 | 44 | Tox data directory: /home/gildor/.config/tox/ 45 | Tox data file: /home/gildor/.config/tox/tox_save 46 | Avatar data dir: /home/gildor/.config/tox/avatars/ 47 | Gildor's avatar: /home/gildor/.config/tox/avatars/446F4E6F744D6564646C65496E546865416666616972734F6657697A61726473.png 48 | Elrond's avatar: /home/gildor/.config/tox/avatars/43656C65627269616E20646F6E277420546F782E426164206D656D6F72696573.png 49 | Elladan's avatar: /home/gildor/.config/tox/avatars/49486174655768656E48756D616E735468696E6B49416D4D7942726F74686572.png 50 | Elrohir's avatar /home/gildor/.config/tox/avatars/726568746F7242794D6D41496B6E696854736E616D75486E6568576574614849.png 51 | -------------------------------------------------------------------------------- /Important/File_Transfers.md: -------------------------------------------------------------------------------- 1 | # File Transfers 2 | The ability to send and receive files is a required feature for any useful instant messaging client. Toxcore will handle 3 | all of your data transfer needs. All you have to do is provide the data, and any helpful information to pass along to 4 | your friend. 5 | 6 | At the very least, you'll need to give Toxcore 7 | * The friend you want to send to 8 | * The kind of data you want to send. 9 | * The size of data you plan to send. 10 | * A name for the file you're sending, along with the length of the name string (don't include the NULL term in the 11 | length, but do include one!) 12 | Optionally, you can also provide a file_id, and an int pointer if you'd like an error code if something goes wrong. The 13 | API function looks like this `tox_file_send(tox, friend_number, TOX_FILE_KIND_DATA, file_size, file_id, filename, 14 | filename_length, error);` 15 | 16 | If the file transfer completes, the client may delete all stored info about the file. A file completes when the receiver 17 | has received it completely as such there is no need to try resuming completed files so any other info can be deleted, at 18 | the clients discretion. Toxcore will make one final callback to the chuck request function with a length of 0. At that 19 | point Toxcore considers the file completed, and purges any information about the file transfer and will reuse the file 20 | transfer number. 21 | 22 | ## File Resuming 23 | Good clients support file resuming. Great clients do so even across client/core restarts! 24 | 25 | Toxcore doesn't keep data that might have expired. So File transfers for a specific friend are purged from core whenever 26 | that friend goes offline/disconnects. Toxcore also makes no attempt to save file transfer info in the core data file. 27 | This means that it's the sole responsibility of the client to index, save, and restore file transfer information. 28 | Clients must take care of resuming file transfers using the same `file_id` parameter and make use of the `seek api` to 29 | avoid duplicating transfered data. If you don't want to create your own file_id, Toxcore will generate one for you that you can 30 | retrieve with `tox_file_get_file_id(tox, friend_number, file_number, new_id, error);`. You're always welcome to supply a 31 | file_id yourself, but the general recommendation is to let Toxcore generate one for you. (You can do this by setting 32 | file_id to NULL). 33 | 34 | When you're ready to resume a broken/interrupted transfer, you'll need to start the transfer from the original sending 35 | client. The sending client will save the file_id (tox_file_get_file_id()) along with file data/location, and any other 36 | useful information that your client may need to restart the file. Again, this information must be saved in long term by 37 | the client, because Toxcore won't save anything for you. 38 | 39 | If the client is closed and reopened it will reload all the saved file info from disk. 40 | 41 | The expectation of clients is that every time a friend comes online, the client will restart any pending transfers. 42 | Restarting a transfer is the same as starting a new transfer with the exception of the `file_id` parameter. For resumed 43 | transfers it **MUST NOT BE NULL**! Again Toxcore has no information about this file and will generate a NEW and UNIQUE 44 | `file_id` one that will not match the original. If the `file_id` changes the receiving client will have no means of 45 | differentiating it from a new transfer. 46 | 47 | Complient clients will first check if it has any incomplete files with the same `file_id`. If it does, it will open the 48 | incomplete file and look at how much data was received already, and use 49 | `tox_file_seek(tox, friend_number, file_number, size_transferred, error)` with the 4th parameter equal to the number of 50 | bytes already received. It will then call 51 | `tox_file_control(tox, friend_number, file_number, TOX_FILE_CONTROL_RESUME, error)` to accept the transfer. It's up to 52 | your client if you want to prompt the user to RE-accept the transfer, or just resume the transfer automatically for the 53 | user. See also [Resuming Suggestions](Suggestions/Resuming.md). 54 | 55 | When a receiving file completes, all stored info related to the file transfer can, and should be deleted, (not the file 56 | transfer data it self, only the data associated with transferring that data). Doing so will prevent future conflicts 57 | new/different transfers. 58 | -------------------------------------------------------------------------------- /Important/Toxcore_Save_Data_Directory.md: -------------------------------------------------------------------------------- 1 | Your client should load/save to this directory or a subfolder of it. 2 | 3 | On windows: ``%APPDATA%/tox/`` 4 | 5 | On Linux: ``~/.config/tox/`` 6 | 7 | Your client must be careful not to delete any files that are not compatible with it. 8 | -------------------------------------------------------------------------------- /Important/Toxcore_Save_Export_Import.md: -------------------------------------------------------------------------------- 1 | Clients must have the ability to export the toxcore save to or import it from any file/directory designated by the user. 2 | -------------------------------------------------------------------------------- /Important/User_Profile_Encryption.md: -------------------------------------------------------------------------------- 1 | toxencryptsave in the toxcore directory can be used to load and save encrypted versions of the tox save. Clients should support loading and saving encrypted tox saves. 2 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Tox Client Guidelines. 2 | This git repo contains the documentation for the suggestions and recommendations a model Tox client would follow. As 3 | with any client, you don't have to follow them as most are merely recommendation however if you do not only will your 4 | users will thank you, but other clients won't hate you either! 5 | 6 | Additionally, some client quirks are also detailed to make interaction a little enigmatic. 7 | 8 | All suggestions and contributions from other clients (or any community member) are always welcome! To suggest a change 9 | to this or any of the other docs available make a pull request at 10 | [GitHub](https://github.com/irungentoo/Tox_Client_Guidelines) 11 | 12 | If you're a developer for in the tox community, and would like to contribute regularly, send me a message. You should 13 | already know where to find me. 14 | 15 | ## Hierarchy of recommendations. 16 | The docs in this repo are sorted into different folders by how important it is that clients to follow them: 17 | 18 | ### [Required](Required/): 19 | Your client must follow these or else using it with other clients in Tox will be very difficult or impossible. Ignoring 20 | these WILL make other dev's curse your very existence, and your users abandon you! 21 | 22 | ### [Important](Important/): 23 | Your client must follow these but not following them won't make it impossible to use with other clients. It might cause 24 | some headaches for your users, and you'll likely be shunned by other dev's, or at the very least... mocked relentlessly. 25 | 26 | ### [Recommendations](Recommendations/): 27 | These are general recommendations, strictly speaking these aren't yet standard, but it's what everyone else does... Your 28 | client should follow these for optimal compatibility with the other *cool* clients. And don't you want to be cool too?! 29 | 30 | ### [Suggestions](Suggestions/): 31 | These are some quirks or procedures that other clients tend to use. The docs here will never break compatibility, and 32 | it's likely that any client that does use these will likely change for something better. But it can't hurt to follow 33 | them so you should at least check them out. 34 | 35 | Also included are some general ideas that will endear you to you users! 36 | -------------------------------------------------------------------------------- /Recommendations/Tox_ID_DNS_resolution.md: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /Required/Bootstrapping.md: -------------------------------------------------------------------------------- 1 | Clients should bootstrap agressively to at least 4 random nodes from a list every ~5 seconds until toxcore reports that it is connected. 2 | 3 | When loading from a save, you do not need to bootstrap unless ~10 seconds after running the first tox_iterate() toxcore still doesn't report that it is connected. If that happens refer to the above strategy. 4 | 5 | A list of nodes can be found: https://wiki.tox.im/Nodes 6 | -------------------------------------------------------------------------------- /Required/Tox_ID.md: -------------------------------------------------------------------------------- 1 | A client must have the ability to add and display Tox IDs in hexadecimal format. 2 | -------------------------------------------------------------------------------- /Required/Toxcore_features.md: -------------------------------------------------------------------------------- 1 | Clients should implement all toxcore and toxav features. 2 | 3 | These include simple messaging, audio and video messaging, groups and file transfers. 4 | -------------------------------------------------------------------------------- /Suggestions/Resuming.md: -------------------------------------------------------------------------------- 1 | # File Resuming 2 | 3 | When deciding if you should automagicly resume a incoming existing file transfer, It's probably best to resume the 4 | transfer without user interaction if the data related to the transfer is still in memory. In this case it was likely a 5 | short network stall causing a disconnect, and it's likely to be the least interrupting this way. If you have information 6 | about the incoming file, but you got that information from long term storage, (e.g. from the hard disk) you may want to 7 | prompt the user before resuming. Tox file transfers use all of the available bandwidth and may cause bottlenecks that 8 | would inconvenience users, if they're friend comes online at an inopportune time. But as always, it's up to however you 9 | wish to handle file transfers. 10 | -------------------------------------------------------------------------------- /Suggestions/Theme_support.md: -------------------------------------------------------------------------------- 1 | Clients should have a way to change their appearance, some suggested themes are a light theme, a dark theme and a high contrast theme. Of course the more there are, the better. 2 | --------------------------------------------------------------------------------