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

Merge branch 'dubslow-housekeeping-docs' of https://github.com/ittner/toxcore

Browse Source
This commit is contained in:
dubslow 2014-09-24 20:57:17 -05:00
commit 4ede062e60
1 changed files with 22 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
docs/Avatars.md
View File

@ -127,16 +127,16 @@ complete API documentation is available in `tox.h`.
``` ```
#define TOX_MAX_AVATAR_DATA_LENGTH 16384 #define TOX_AVATAR_MAX_DATA_LENGTH 16384
#define TOX_AVATAR_HASH_LENGTH 32 #define TOX_AVATAR_HASH_LENGTH 32
/* Data formats for user avatar images */ /* Data formats for user avatar images */
typedef enum { typedef enum {
TOX_AVATARFORMAT_NONE, TOX_AVATAR_FORMAT_NONE,
TOX_AVATARFORMAT_PNG TOX_AVATAR_FORMAT_PNG
} }
TOX_AVATARFORMAT; TOX_AVATAR_FORMAT;
@ -287,11 +287,11 @@ functions. For a complete, working, example, see `testing/test_avatars.c`.
In this example `load_data_file` is just an hypothetical function that loads In this example `load_data_file` is just an hypothetical function that loads
data from a file into the buffer and sets the length accordingly. data from a file into the buffer and sets the length accordingly.
uint8_t buf[TOX_MAX_AVATAR_DATA_LENGTH]; uint8_t buf[TOX_AVATAR_MAX_DATA_LENGTH];
uint32_t len; uint32_t len;
if (load_data_file("avatar.png", buf, &len) == 0) if (load_data_file("avatar.png", buf, &len) == 0)
if (tox_set_avatar(tox, TOX_AVATARFORMAT_PNG, buf, len) != 0) if (tox_set_avatar(tox, TOX_AVATAR_FORMAT_PNG, buf, len) != 0)
fprintf(stderr, "Failed to set avatar.\n"); fprintf(stderr, "Failed to set avatar.\n");
If the user is connected, this function will also notify all connected If the user is connected, this function will also notify all connected
@ -306,9 +306,9 @@ notifications and unnecessary data transfers.
#### Removing the avatar from the current user #### Removing the avatar from the current user
To remove an avatar, an application must set it to `TOX_AVATARFORMAT_NONE`. To remove an avatar, an application must set it to `TOX_AVATAR_FORMAT_NONE`.
tox_set_avatar(tox, TOX_AVATARFORMAT_NONE, NULL, 0); tox_set_avatar(tox, TOX_AVATAR_FORMAT_NONE, NULL, 0);
If the user is connected, this function will also notify all connected If the user is connected, this function will also notify all connected
friends about the avatar change. friends about the avatar change.
@ -362,7 +362,7 @@ checks the local avatar cache and emits an avatar data request if necessary:
{ {
printf("Receiving avatar information from friend %d. Format = %d\n", printf("Receiving avatar information from friend %d. Format = %d\n",
friendnumber, format); friendnumber, format);
if (format = TOX_AVATARFORMAT_NONE) { if (format = TOX_AVATAR_FORMAT_NONE) {
/* User have no avatar or removed the avatar */ /* User have no avatar or removed the avatar */
delete_avatar_from_cache(tox, friendnumber); delete_avatar_from_cache(tox, friendnumber);
} else { } else {
@ -382,7 +382,7 @@ cache:
static void avatar_data_cb(Tox *tox, int32_t friendnumber, uint8_t format, static void avatar_data_cb(Tox *tox, int32_t friendnumber, uint8_t format,
uint8_t *hash, uint8_t *data, uint32_t datalen, void *userdata) uint8_t *hash, uint8_t *data, uint32_t datalen, void *userdata)
{ {
if (format = TOX_AVATARFORMAT_NONE) { if (format = TOX_AVATAR_FORMAT_NONE) {
/* User have no avatar or removed the avatar */ /* User have no avatar or removed the avatar */
delete_avatar_from_cache(tox, friendnumber); delete_avatar_from_cache(tox, friendnumber);
} else { } else {
@ -453,8 +453,8 @@ the following structure:
Where 'format' is the image data format, one of the following: Where 'format' is the image data format, one of the following:
0 = AVATARFORMAT_NONE (no avatar set) 0 = AVATAR_FORMAT_NONE (no avatar set)
1 = AVATARFORMAT_PNG 1 = AVATAR_FORMAT_PNG
and 'hash' is the SHA-256 message digest of the avatar data. and 'hash' is the SHA-256 message digest of the avatar data.
@ -481,8 +481,8 @@ types.
return, which semantics are explained bellow. The following values are return, which semantics are explained bellow. The following values are
defined: defined:
0 = AVATARDATACONTROL_REQ 0 = AVATAR_DATACONTROL_REQ
1 = AVATARDATACONTROL_ERROR 1 = AVATAR_DATACONTROL_ERROR
- Packet `PACKET_ID_AVATAR_DATA_START` have the following format: - Packet `PACKET_ID_AVATAR_DATA_START` have the following format:
@ -511,17 +511,17 @@ from a client "B":
- "A" must initialize its control structures and mark its data transfer - "A" must initialize its control structures and mark its data transfer
as not yet started. Then it requests avatar data from "B" by sending a as not yet started. Then it requests avatar data from "B" by sending a
packet `PACKET_ID_AVATAR_DATA_CONTROL` with 'op' set to packet `PACKET_ID_AVATAR_DATA_CONTROL` with 'op' set to
`AVATARDATACONTROL_REQ`. `AVATAR_DATACONTROL_REQ`.
- If "B" accepts this transfer, it answers by sending an - If "B" accepts this transfer, it answers by sending an
`PACKET_ID_AVATAR_DATA_START` with the fields 'format', 'hash' and `PACKET_ID_AVATAR_DATA_START` with the fields 'format', 'hash' and
'data_length' set to the respective values from the current avatar. 'data_length' set to the respective values from the current avatar.
If "B" have no avatar set, 'format' must be `AVATARFORMAT_NONE`, 'hash' If "B" have no avatar set, 'format' must be `AVATAR_FORMAT_NONE`, 'hash'
must be zeroed and 'data_length' must be zero. must be zeroed and 'data_length' must be zero.
If "B" does not accept sending the avatar, it may send a packet If "B" does not accept sending the avatar, it may send a packet
`PACKET_ID_AVATAR_DATA_CONTROL` with the field 'op' set to `PACKET_ID_AVATAR_DATA_CONTROL` with the field 'op' set to
`AVATARDATACONTROL_ERROR` or simply ignore this request. "A" must cope `AVATAR_DATACONTROL_ERROR` or simply ignore this request. "A" must cope
with this. with this.
If "B" have an avatar, it sends a variable number of If "B" have an avatar, it sends a variable number of
@ -531,7 +531,7 @@ from a client "B":
- Upon receiving a `PACKET_ID_AVATAR_DATA_START`, "A" checks if it - Upon receiving a `PACKET_ID_AVATAR_DATA_START`, "A" checks if it
has sent a data request to "B". If not, just ignores the packet. has sent a data request to "B". If not, just ignores the packet.
If "A" really requested avatar data and the format is `AVATARFORMAT_NONE`, If "A" really requested avatar data and the format is `AVATAR_FORMAT_NONE`,
it triggers the avatar data callback, and clears all the temporary data, it triggers the avatar data callback, and clears all the temporary data,
finishing the process. For other formats, "A" just waits for packets finishing the process. For other formats, "A" just waits for packets
of type `PACKET_ID_AVATAR_DATA_PUSH`. of type `PACKET_ID_AVATAR_DATA_PUSH`.
@ -541,9 +541,9 @@ from a client "B":
already received. If this conditions are valid, it checks if the total already received. If this conditions are valid, it checks if the total
length of the data already stored in the receiving buffer plus the data length of the data already stored in the receiving buffer plus the data
present in the push packet is still less or equal than present in the push packet is still less or equal than
`TOX_MAX_AVATAR_DATA_LENGTH`. If invalid, it replies with a `TOX_AVATAR_MAX_DATA_LENGTH`. If invalid, it replies with a
`PACKET_ID_AVATAR_DATA_CONTROL` with the field 'op' set to `PACKET_ID_AVATAR_DATA_CONTROL` with the field 'op' set to
`AVATARDATACONTROL_ERROR`. `AVATAR_DATACONTROL_ERROR`.
If valid, "A" updates the 'bytes_received' counter and concatenates the If valid, "A" updates the 'bytes_received' counter and concatenates the
newly arrived data to the buffer. newly arrived data to the buffer.
@ -566,7 +566,7 @@ from a client "B":
some transfer limit for the data it sends. some transfer limit for the data it sends.
- Any peer receiving a `PACKET_ID_AVATAR_DATA_CONTROL` with the field 'op' - Any peer receiving a `PACKET_ID_AVATAR_DATA_CONTROL` with the field 'op'
set to `AVATARDATACONTROL_ERROR` clears any existing control state and set to `AVATAR_DATACONTROL_ERROR` clears any existing control state and
finishes sending or receiving data. finishes sending or receiving data.
@ -596,7 +596,7 @@ The present proposal mitigates this situation by:
same offset of the avatar again and again, the implementation limits 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 amount of data a single user can request for some time. For now,
the library will not allow an user to request more than the library will not allow an user to request more than
`10*TOX_MAX_AVATAR_DATA_LENGTH` in less than 20 minutes; `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;