StarMirror/toxcore
1
0
Fork 0
mirror of https://github.com/irungentoo/toxcore.git synced 2024-03-22 13:30:51 +08:00
Code Issues Projects Releases Wiki Activity

Update avatar documentation

Browse Source 
Update the documentation to reflect the API changes introduced by
commits 21be438b2b3f7aa1b65b76a7f528eacfe5b634db and
d409bad30dd1657f6b54ea5e38a4d9155f718ae1
This commit is contained in:
Alexandre Erwin Ittner 2014-09-25 22:03:36 -03:00
parent d264010364
commit c17fc040a4
2 changed files with 14 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
docs/Avatars.md
View File

@ -128,7 +128,7 @@ complete API documentation is available in `tox.h`.
``` ```
#define TOX_AVATAR_MAX_DATA_LENGTH 16384 #define TOX_AVATAR_MAX_DATA_LENGTH 16384
#define TOX_AVATAR_HASH_LENGTH 32 #define TOX_HASH_LENGTH 32
/* Data formats for user avatar images */ /* Data formats for user avatar images */
@ -146,8 +146,8 @@ int tox_set_avatar(Tox *tox, uint8_t format, const uint8_t *data, uint32_t lengt
/* Get avatar data from the current user. */ /* 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); int tox_get_self_avatar(const Tox *tox, uint8_t *format, uint8_t *buf, uint32_t *length, uint32_t maxlen, uint8_t *hash);
/* Generates a cryptographic hash of the given avatar data. */ /* Generates a cryptographic hash of the given data (usually a cached avatar). */
int tox_avatar_hash(const Tox *tox, uint8_t *hash, const uint8_t *data, const uint32_t datalen); int tox_hash(uint8_t *hash, const uint8_t *data, const uint32_t datalen);
/* Request avatar information from a friend. */ /* Request avatar information from a friend. */
int tox_request_avatar_info(const Tox *tox, const int32_t friendnumber); int tox_request_avatar_info(const Tox *tox, const int32_t friendnumber);
@ -332,7 +332,7 @@ As in this example:
printf("Receiving avatar information from friend %d. Format = %d\n", printf("Receiving avatar information from friend %d. Format = %d\n",
friendnumber, format); friendnumber, format);
printf("Data hash: "); printf("Data hash: ");
hex_printf(hash, TOX_AVATAR_HASH_LENGTH); /* Hypothetical function */ hex_printf(hash, TOX_HASH_LENGTH); /* Hypothetical function */
printf("\n"); printf("\n");
} }
@ -592,11 +592,10 @@ The present proposal mitigates this situation by:
avatar information when nothing has changed (`PACKET_ID_AVATAR_INFO`); avatar information when nothing has changed (`PACKET_ID_AVATAR_INFO`);
- Having per-friend data transfer limit. As the current protocol still - Having per-friend data transfer limit. As the current protocol still
allows an user to request an infinite data stream by asking the the allows an user to request avatar data again and again, the implementation
same offset of the avatar again and again, the implementation limits limits the amount of data a particular user can request for some time. The
the amount of data a single user can request for some time. For now, exact values are defined in constants `AVATAR_DATA_TRANSFER_LIMIT` and
the library will not allow an user to request more than `AVATAR_DATA_TRANSFER_TIMEOUT` in file `Messenger.c`.
`10*TOX_AVATAR_MAX_DATA_LENGTH` in less than 20 minutes;
- Making the requester responsible for storing partial data and state - Making the requester responsible for storing partial data and state
information; information;

12
toxcore/tox.h
View File

@ -539,8 +539,8 @@ uint32_t tox_get_chatlist(const Tox *tox, int *out_list, uint32_t list_size);
* function(Tox *tox, int32_t friendnumber, uint8_t format, uint8_t *hash, void *userdata) * function(Tox *tox, int32_t friendnumber, uint8_t format, uint8_t *hash, void *userdata)
* *
* where 'format' is the avatar image format (see TOX_AVATAR_FORMAT) and 'hash' is the hash of * where 'format' is the avatar image format (see TOX_AVATAR_FORMAT) and 'hash' is the hash of
* the avatar data for caching purposes and it is exactly TOX_AVATAR_HASH_LENGTH long. If the * the avatar data for caching purposes and it is exactly TOX_HASH_LENGTH long. If the image
* image format is NONE, the hash is zeroed. * format is NONE, the hash is zeroed.
* *
*/ */
void tox_callback_avatar_info(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, uint8_t *, void *), void tox_callback_avatar_info(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, uint8_t *, void *),
@ -556,12 +556,12 @@ void tox_callback_avatar_info(Tox *tox, void (*function)(Tox *tox, int32_t, uint
* *
* where 'format' is the avatar image format (see TOX_AVATAR_FORMAT); 'hash' is the * where 'format' is the avatar image format (see TOX_AVATAR_FORMAT); 'hash' is the
* locally-calculated cryptographic hash of the avatar data and it is exactly * locally-calculated cryptographic hash of the avatar data and it is exactly
* TOX_AVATAR_HASH_LENGTH long; 'data' is the avatar image data and 'datalen' is the length * TOX_HASH_LENGTH long; 'data' is the avatar image data and 'datalen' is the length
* of such data. * of such data.
* *
* If format is NONE, 'data' is NULL, 'datalen' is zero, and the hash is zeroed. The hash is * If format is NONE, 'data' is NULL, 'datalen' is zero, and the hash is zeroed. The hash is
* always validated locally with the function tox_avatar_hash and ensured to match the image * always validated locally with the function tox_hash and ensured to match the image data,
* data, so this value can be safely used to compare with cached avatars. * so this value can be safely used to compare with cached avatars.
* *
* WARNING: users MUST treat all avatar image data received from another peer as untrusted and * WARNING: users MUST treat all avatar image data received from another peer as untrusted and
* potentially malicious. The library only ensures that the data which arrived is the same the * potentially malicious. The library only ensures that the data which arrived is the same the
@ -601,7 +601,7 @@ int tox_set_avatar(Tox *tox, uint8_t format, const uint8_t *data, uint32_t lengt
* buf - destination buffer to the image data. Must have at least 'maxlen' bytes; * buf - destination buffer to the image data. Must have at least 'maxlen' bytes;
* length - destination pointer to the image data length; * length - destination pointer to the image data length;
* maxlen - length of the destination buffer 'buf'; * maxlen - length of the destination buffer 'buf';
* hash - destination pointer to the avatar hash (it must be exactly TOX_AVATAR_HASH_LENGTH bytes long). * hash - destination pointer to the avatar hash (it must be exactly TOX_HASH_LENGTH bytes long).
* *
* returns 0 on success; * returns 0 on success;
* returns -1 on failure. * returns -1 on failure.