From c2421e6f21482b82257c4926c40dc830397973ea Mon Sep 17 00:00:00 2001 From: Alexandre Erwin Ittner Date: Sat, 31 Jan 2015 20:13:39 -0200 Subject: Update avatar documentation Add missing function and fixes some typos and formatting. --- docs/Avatars.md | 36 +++++++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/Avatars.md b/docs/Avatars.md index a24c1f7c..31138af7 100644 --- a/docs/Avatars.md +++ b/docs/Avatars.md @@ -11,8 +11,8 @@ way for one user to identify another in the friend list. This document describes the implementation of avatars in the Tox protocol, according to the following design considerations: - - Avatars are handled as private information, i.e., they are only exchanged over - Tox encrypted channels among previously authenticated friends; + - Avatars are handled as private information, i.e., they are only exchanged + over Tox encrypted channels among previously authenticated friends; - The library treats all images as blobs and does not interpret or understand image formats. It only ensures that the avatar data sent by @@ -85,14 +85,15 @@ Tox protocol: connects to the network, changes his avatar, or in reply to an **avatar information request**. They are delivered by a very lightweight message but with information enough to allow a user to validate or discard an - avatar from the local cache and to decide if it is interesting to request the - avatar data from the peer. + avatar from the local cache and to decide if it is interesting to request + the avatar data from the peer. This event contains two data fields: (1) the image format, and (2) the - cryptographic hash of the actual image data. The image format may be NONE - (for users who have no avatar or removed their avatars) or PNG. The + cryptographic hash of the current image data. The image format may be + NONE (for users who have no avatar or removed their avatars) or PNG. The cryptographic hash is intended to be compared with the hash of the - currently cached avatar (if any) in order to check if it is still up to date. + currently cached avatar (if any) in order to check if it is still up to + date. - **Avatar Information Requests** are very lightweight messages sent by a user asking for an **avatar information notification**. They may be sent @@ -145,6 +146,9 @@ TOX_AVATAR_FORMAT; /* Set the user avatar image data. */ int tox_set_avatar(Tox *tox, uint8_t format, const uint8_t *data, uint32_t length); +/* Removes the user avatar image data. */ +int tox_unset_avatar(Tox *tox); + /* Get avatar data from the current user. */ int tox_get_self_avatar(const Tox *tox, uint8_t *format, uint8_t *buf, uint32_t *length, uint32_t maxlen, uint8_t *hash); @@ -201,6 +205,11 @@ void tox_callback_avatar_data(Tox *tox, void (*function)(Tox *tox, int32_t, uint * A client may not understand a particular image format and ignore avatars using it, but request and handle other formats; + * A client on a slow mobile network may ask for avatar information to + ensure its cached avatars are still valid, but do not request avatar + data. The same client may start asking for avatar data once it + connects through a fast network. + - Clients SHOULD implement a local cache of avatars and do not request avatar data from other peers unless necessary; @@ -253,7 +262,7 @@ Given the Tox data directory described in STS Draft v0.1.0: - The client's own avatar is not special and is stored like any other. This is partially for simplicity, and partially in anticipation of profiles. - - The avatar should be stored as its recieved, before any modifications by + - The avatar should be stored as its received, before any modifications by the client for display purposes. - The hash, as calculated by toxcore and passed in to the data callback, @@ -269,7 +278,7 @@ Example for Linux and other Unix systems, assuming an user called "gildor": Tox data directory: /home/gildor/.config/tox/ Tox data file: /home/gildor/.config/tox/data Avatar data dir: /home/gildor/.config/tox/avatars/ - Gildor's avatar: /home/gildor/.config/tox/avatars/E5809EEF5F11AB29B9BDF543C05B58DDF454AB9CA176C235C7699FDC2757DC33.png + Gildor's avatar: /home/gildor/.config/tox/avatars/446F4E6F744D6564646C65496E546865416666616972734F6657697A61726473.png Elrond's avatar: /home/gildor/.config/tox/avatars/43656C65627269616E20646F6E277420546F782E426164206D656D6F72696573.png Elrond's hash: /home/gildor/.config/tox/avatars/43656C65627269616E20646F6E277420546F782E426164206D656D6F72696573.hash Elladan's avatar: /home/gildor/.config/tox/avatars/49486174655768656E48756D616E735468696E6B49416D4D7942726F74686572.png @@ -313,7 +322,12 @@ notifications and unnecessary data transfers. #### Removing the avatar from the current user -To remove an avatar, an application must set it to `TOX_AVATAR_FORMAT_NONE`. +To remove the current avatar, an application must call + + tox_unset_avatar(tox); + +the effect is the same as setting the avatar format to `TOX_AVATAR_FORMAT_NONE` +and with no data: tox_set_avatar(tox, TOX_AVATAR_FORMAT_NONE, NULL, 0); @@ -555,7 +569,7 @@ from a client "B": If valid, "A" updates the 'bytes_received' counter and concatenates the newly arrived data to the buffer. - The "A" checks if all the data was already received by comparing the + Then "A" checks if all the data was already received by comparing the counter 'bytes_received' with the field 'total_length'. If they are equal, "A" takes a SHA-256 hash of the data and compares it with the hash stored in the field 'hash' received from the first -- cgit v1.2.3