summaryrefslogtreecommitdiff
path: root/docs/Avatars.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/Avatars.md')
-rw-r--r--docs/Avatars.md40
1 files changed, 27 insertions, 13 deletions
diff --git a/docs/Avatars.md b/docs/Avatars.md
index 1dcbba96..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.
11This document describes the implementation of avatars in the Tox protocol, 11This document describes the implementation of avatars in the Tox protocol,
12according to the following design considerations: 12according to the following design considerations:
13 13
14 - Avatars are handled as private information, i.e., they are only exchanged over 14 - Avatars are handled as private information, i.e., they are only exchanged
15 Tox encrypted channels among previously authenticated friends; 15 over Tox encrypted channels among previously authenticated friends;
16 16
17 - The library treats all images as blobs and does not interpret or 17 - The library treats all images as blobs and does not interpret or
18 understand image formats. It only ensures that the avatar data sent by 18 understand image formats. It only ensures that the avatar data sent by
@@ -85,14 +85,15 @@ Tox protocol:
85 connects to the network, changes his avatar, or in reply to an **avatar 85 connects to the network, changes his avatar, or in reply to an **avatar
86 information request**. They are delivered by a very lightweight message 86 information request**. They are delivered by a very lightweight message
87 but with information enough to allow a user to validate or discard an 87 but with information enough to allow a user to validate or discard an
88 avatar from the local cache and to decide if it is interesting to request the 88 avatar from the local cache and to decide if it is interesting to request
89 avatar data from the peer. 89 the avatar data from the peer.
90 90
91 This event contains two data fields: (1) the image format, and (2) the 91 This event contains two data fields: (1) the image format, and (2) the
92 cryptographic hash of the actual image data. The image format may be NONE 92 cryptographic hash of the current image data. The image format may be
93 (for users who have no avatar or removed their avatars) or PNG. The 93 NONE (for users who have no avatar or removed their avatars) or PNG. The
94 cryptographic hash is intended to be compared with the hash of the 94 cryptographic hash is intended to be compared with the hash of the
95 currently cached avatar (if any) in order to check if it is still up to date. 95 currently cached avatar (if any) in order to check if it is still up to
96 date.
96 97
97 - **Avatar Information Requests** are very lightweight messages sent by a 98 - **Avatar Information Requests** are very lightweight messages sent by a
98 user asking for an **avatar information notification**. They may be sent 99 user asking for an **avatar information notification**. They may be sent
@@ -145,6 +146,9 @@ TOX_AVATAR_FORMAT;
145/* Set the user avatar image data. */ 146/* Set the user avatar image data. */
146int tox_set_avatar(Tox *tox, uint8_t format, const uint8_t *data, uint32_t length); 147int tox_set_avatar(Tox *tox, uint8_t format, const uint8_t *data, uint32_t length);
147 148
149/* Removes the user avatar image data. */
150int tox_unset_avatar(Tox *tox);
151
148/* Get avatar data from the current user. */ 152/* Get avatar data from the current user. */
149int tox_get_self_avatar(const Tox *tox, uint8_t *format, uint8_t *buf, uint32_t *length, uint32_t maxlen, uint8_t *hash); 153int tox_get_self_avatar(const Tox *tox, uint8_t *format, uint8_t *buf, uint32_t *length, uint32_t maxlen, uint8_t *hash);
150 154
@@ -201,6 +205,11 @@ void tox_callback_avatar_data(Tox *tox, void (*function)(Tox *tox, int32_t, uint
201 * A client may not understand a particular image format and ignore 205 * A client may not understand a particular image format and ignore
202 avatars using it, but request and handle other formats; 206 avatars using it, but request and handle other formats;
203 207
208 * A client on a slow mobile network may ask for avatar information to
209 ensure its cached avatars are still valid, but do not request avatar
210 data. The same client may start asking for avatar data once it
211 connects through a fast network.
212
204 - Clients SHOULD implement a local cache of avatars and do not request 213 - Clients SHOULD implement a local cache of avatars and do not request
205 avatar data from other peers unless necessary; 214 avatar data from other peers unless necessary;
206 215
@@ -244,7 +253,7 @@ already downloaded by other clients can be reused.
244Given the Tox data directory described in STS Draft v0.1.0: 253Given the Tox data directory described in STS Draft v0.1.0:
245 254
246 - Avatars are stored in a directory called "avatars" and named 255 - Avatars are stored in a directory called "avatars" and named
247 as "xxxxx.png", where "xxxxx" is the complete client id (but not friend 256 as "xxxxx.png", where "xxxxx" is the complete public key (but not friend
248 address!) encoded as an uppercase hexadecimal string and "png" is the 257 address!) encoded as an uppercase hexadecimal string and "png" is the
249 extension for the PNG avatar. As new image formats may be used in the 258 extension for the PNG avatar. As new image formats may be used in the
250 future, clients should ensure no other file "xxxxx.*" exists. No file 259 future, clients should ensure no other file "xxxxx.*" exists. No file
@@ -253,7 +262,7 @@ Given the Tox data directory described in STS Draft v0.1.0:
253 - The client's own avatar is not special and is stored like any other. This 262 - The client's own avatar is not special and is stored like any other. This
254 is partially for simplicity, and partially in anticipation of profiles. 263 is partially for simplicity, and partially in anticipation of profiles.
255 264
256 - The avatar should be stored as its recieved, before any modifications by 265 - The avatar should be stored as its received, before any modifications by
257 the client for display purposes. 266 the client for display purposes.
258 267
259 - The hash, as calculated by toxcore and passed in to the data callback, 268 - 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":
269 Tox data directory: /home/gildor/.config/tox/ 278 Tox data directory: /home/gildor/.config/tox/
270 Tox data file: /home/gildor/.config/tox/data 279 Tox data file: /home/gildor/.config/tox/data
271 Avatar data dir: /home/gildor/.config/tox/avatars/ 280 Avatar data dir: /home/gildor/.config/tox/avatars/
272 Gildor's avatar: /home/gildor/.config/tox/avatars/E5809EEF5F11AB29B9BDF543C05B58DDF454AB9CA176C235C7699FDC2757DC33.png 281 Gildor's avatar: /home/gildor/.config/tox/avatars/446F4E6F744D6564646C65496E546865416666616972734F6657697A61726473.png
273 Elrond's avatar: /home/gildor/.config/tox/avatars/43656C65627269616E20646F6E277420546F782E426164206D656D6F72696573.png 282 Elrond's avatar: /home/gildor/.config/tox/avatars/43656C65627269616E20646F6E277420546F782E426164206D656D6F72696573.png
274 Elrond's hash: /home/gildor/.config/tox/avatars/43656C65627269616E20646F6E277420546F782E426164206D656D6F72696573.hash 283 Elrond's hash: /home/gildor/.config/tox/avatars/43656C65627269616E20646F6E277420546F782E426164206D656D6F72696573.hash
275 Elladan's avatar: /home/gildor/.config/tox/avatars/49486174655768656E48756D616E735468696E6B49416D4D7942726F74686572.png 284 Elladan's avatar: /home/gildor/.config/tox/avatars/49486174655768656E48756D616E735468696E6B49416D4D7942726F74686572.png
@@ -313,7 +322,12 @@ notifications and unnecessary data transfers.
313 322
314#### Removing the avatar from the current user 323#### Removing the avatar from the current user
315 324
316To remove an avatar, an application must set it to `TOX_AVATAR_FORMAT_NONE`. 325To remove the current avatar, an application must call
326
327 tox_unset_avatar(tox);
328
329the effect is the same as setting the avatar format to `TOX_AVATAR_FORMAT_NONE`
330and with no data:
317 331
318 tox_set_avatar(tox, TOX_AVATAR_FORMAT_NONE, NULL, 0); 332 tox_set_avatar(tox, TOX_AVATAR_FORMAT_NONE, NULL, 0);
319 333
@@ -408,7 +422,7 @@ calls:
408 422
409In the previous examples, implementation of the functions to check, store 423In the previous examples, implementation of the functions to check, store
410and retrieve data from the cache were omitted for brevity. These functions 424and retrieve data from the cache were omitted for brevity. These functions
411will also need to get the friend client ID (public key) from they friend 425will also need to get the friend public key (client id) from they friend
412number and, usually, convert it from a byte string to a hexadecimal 426number and, usually, convert it from a byte string to a hexadecimal
413string. A complete, yet more complex, example is available in the file 427string. A complete, yet more complex, example is available in the file
414`testing/test_avatars.c`. 428`testing/test_avatars.c`.
@@ -555,7 +569,7 @@ from a client "B":
555 If valid, "A" updates the 'bytes_received' counter and concatenates the 569 If valid, "A" updates the 'bytes_received' counter and concatenates the
556 newly arrived data to the buffer. 570 newly arrived data to the buffer.
557 571
558 The "A" checks if all the data was already received by comparing the 572 Then "A" checks if all the data was already received by comparing the
559 counter 'bytes_received' with the field 'total_length'. If they are 573 counter 'bytes_received' with the field 'total_length'. If they are
560 equal, "A" takes a SHA-256 hash of the data and compares it with the 574 equal, "A" takes a SHA-256 hash of the data and compares it with the
561 hash stored in the field 'hash' received from the first 575 hash stored in the field 'hash' received from the first