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 21be438b2b and
d409bad30d
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_HASH_LENGTH 32
#define TOX_HASH_LENGTH 32
/* 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. */
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. */
int tox_avatar_hash(const Tox *tox, uint8_t *hash, const uint8_t *data, const uint32_t datalen);
/* Generates a cryptographic hash of the given data (usually a cached avatar). */
int tox_hash(uint8_t *hash, const uint8_t *data, const uint32_t datalen);
/* Request avatar information from a friend. */
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",
friendnumber, format);
printf("Data hash: ");
hex_printf(hash, TOX_AVATAR_HASH_LENGTH); /* Hypothetical function */
hex_printf(hash, TOX_HASH_LENGTH); /* Hypothetical function */
printf("\n");
}
@ -592,11 +592,10 @@ The present proposal mitigates this situation by:
avatar information when nothing has changed (`PACKET_ID_AVATAR_INFO`);
- Having per-friend data transfer limit. As the current protocol still
allows an user to request an infinite data stream by asking the the
same offset of the avatar again and again, the implementation limits
the amount of data a single user can request for some time. For now,
the library will not allow an user to request more than
`10*TOX_AVATAR_MAX_DATA_LENGTH` in less than 20 minutes;
allows an user to request avatar data again and again, the implementation
limits the amount of data a particular user can request for some time. The
exact values are defined in constants `AVATAR_DATA_TRANSFER_LIMIT` and
`AVATAR_DATA_TRANSFER_TIMEOUT` in file `Messenger.c`.
- Making the requester responsible for storing partial data and state
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)
*
* 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
* image format is NONE, the hash is zeroed.
* the avatar data for caching purposes and it is exactly TOX_HASH_LENGTH long. If the image
* 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 *),
@ -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
* 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.
*
* 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
* data, so this value can be safely used to compare with cached avatars.
* always validated locally with the function tox_hash and ensured to match the image data,
* 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
* 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;
* length - destination pointer to the image data length;
* 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 -1 on failure.