diff options
-rw-r--r-- | docs/Avatars.md | 44 |
1 files changed, 22 insertions, 22 deletions
diff --git a/docs/Avatars.md b/docs/Avatars.md index 97b65c10..fee401c0 100644 --- a/docs/Avatars.md +++ b/docs/Avatars.md | |||
@@ -127,16 +127,16 @@ complete API documentation is available in `tox.h`. | |||
127 | 127 | ||
128 | 128 | ||
129 | ``` | 129 | ``` |
130 | #define TOX_MAX_AVATAR_DATA_LENGTH 16384 | 130 | #define TOX_AVATAR_MAX_DATA_LENGTH 16384 |
131 | #define TOX_AVATAR_HASH_LENGTH 32 | 131 | #define TOX_AVATAR_HASH_LENGTH 32 |
132 | 132 | ||
133 | 133 | ||
134 | /* Data formats for user avatar images */ | 134 | /* Data formats for user avatar images */ |
135 | typedef enum { | 135 | typedef enum { |
136 | TOX_AVATARFORMAT_NONE, | 136 | TOX_AVATAR_FORMAT_NONE, |
137 | TOX_AVATARFORMAT_PNG | 137 | TOX_AVATAR_FORMAT_PNG |
138 | } | 138 | } |
139 | TOX_AVATARFORMAT; | 139 | TOX_AVATAR_FORMAT; |
140 | 140 | ||
141 | 141 | ||
142 | 142 | ||
@@ -287,11 +287,11 @@ functions. For a complete, working, example, see `testing/test_avatars.c`. | |||
287 | In this example `load_data_file` is just an hypothetical function that loads | 287 | In this example `load_data_file` is just an hypothetical function that loads |
288 | data from a file into the buffer and sets the length accordingly. | 288 | data from a file into the buffer and sets the length accordingly. |
289 | 289 | ||
290 | uint8_t buf[TOX_MAX_AVATAR_DATA_LENGTH]; | 290 | uint8_t buf[TOX_AVATAR_MAX_DATA_LENGTH]; |
291 | uint32_t len; | 291 | uint32_t len; |
292 | 292 | ||
293 | if (load_data_file("avatar.png", buf, &len) == 0) | 293 | if (load_data_file("avatar.png", buf, &len) == 0) |
294 | if (tox_set_avatar(tox, TOX_AVATARFORMAT_PNG, buf, len) != 0) | 294 | if (tox_set_avatar(tox, TOX_AVATAR_FORMAT_PNG, buf, len) != 0) |
295 | fprintf(stderr, "Failed to set avatar.\n"); | 295 | fprintf(stderr, "Failed to set avatar.\n"); |
296 | 296 | ||
297 | If the user is connected, this function will also notify all connected | 297 | If the user is connected, this function will also notify all connected |
@@ -306,9 +306,9 @@ notifications and unnecessary data transfers. | |||
306 | 306 | ||
307 | #### Removing the avatar from the current user | 307 | #### Removing the avatar from the current user |
308 | 308 | ||
309 | To remove an avatar, an application must set it to `TOX_AVATARFORMAT_NONE`. | 309 | To remove an avatar, an application must set it to `TOX_AVATAR_FORMAT_NONE`. |
310 | 310 | ||
311 | tox_set_avatar(tox, TOX_AVATARFORMAT_NONE, NULL, 0); | 311 | tox_set_avatar(tox, TOX_AVATAR_FORMAT_NONE, NULL, 0); |
312 | 312 | ||
313 | If the user is connected, this function will also notify all connected | 313 | If the user is connected, this function will also notify all connected |
314 | friends about the avatar change. | 314 | friends about the avatar change. |
@@ -362,7 +362,7 @@ checks the local avatar cache and emits an avatar data request if necessary: | |||
362 | { | 362 | { |
363 | printf("Receiving avatar information from friend %d. Format = %d\n", | 363 | printf("Receiving avatar information from friend %d. Format = %d\n", |
364 | friendnumber, format); | 364 | friendnumber, format); |
365 | if (format = TOX_AVATARFORMAT_NONE) { | 365 | if (format = TOX_AVATAR_FORMAT_NONE) { |
366 | /* User have no avatar or removed the avatar */ | 366 | /* User have no avatar or removed the avatar */ |
367 | delete_avatar_from_cache(tox, friendnumber); | 367 | delete_avatar_from_cache(tox, friendnumber); |
368 | } else { | 368 | } else { |
@@ -382,7 +382,7 @@ cache: | |||
382 | static void avatar_data_cb(Tox *tox, int32_t friendnumber, uint8_t format, | 382 | static void avatar_data_cb(Tox *tox, int32_t friendnumber, uint8_t format, |
383 | uint8_t *hash, uint8_t *data, uint32_t datalen, void *userdata) | 383 | uint8_t *hash, uint8_t *data, uint32_t datalen, void *userdata) |
384 | { | 384 | { |
385 | if (format = TOX_AVATARFORMAT_NONE) { | 385 | if (format = TOX_AVATAR_FORMAT_NONE) { |
386 | /* User have no avatar or removed the avatar */ | 386 | /* User have no avatar or removed the avatar */ |
387 | delete_avatar_from_cache(tox, friendnumber); | 387 | delete_avatar_from_cache(tox, friendnumber); |
388 | } else { | 388 | } else { |
@@ -453,8 +453,8 @@ the following structure: | |||
453 | 453 | ||
454 | Where 'format' is the image data format, one of the following: | 454 | Where 'format' is the image data format, one of the following: |
455 | 455 | ||
456 | 0 = AVATARFORMAT_NONE (no avatar set) | 456 | 0 = AVATAR_FORMAT_NONE (no avatar set) |
457 | 1 = AVATARFORMAT_PNG | 457 | 1 = AVATAR_FORMAT_PNG |
458 | 458 | ||
459 | and 'hash' is the SHA-256 message digest of the avatar data. | 459 | and 'hash' is the SHA-256 message digest of the avatar data. |
460 | 460 | ||
@@ -481,8 +481,8 @@ types. | |||
481 | return, which semantics are explained bellow. The following values are | 481 | return, which semantics are explained bellow. The following values are |
482 | defined: | 482 | defined: |
483 | 483 | ||
484 | 0 = AVATARDATACONTROL_REQ | 484 | 0 = AVATAR_DATACONTROL_REQ |
485 | 1 = AVATARDATACONTROL_ERROR | 485 | 1 = AVATAR_DATACONTROL_ERROR |
486 | 486 | ||
487 | 487 | ||
488 | - Packet `PACKET_ID_AVATAR_DATA_START` have the following format: | 488 | - Packet `PACKET_ID_AVATAR_DATA_START` have the following format: |
@@ -511,17 +511,17 @@ from a client "B": | |||
511 | - "A" must initialize its control structures and mark its data transfer | 511 | - "A" must initialize its control structures and mark its data transfer |
512 | as not yet started. Then it requests avatar data from "B" by sending a | 512 | as not yet started. Then it requests avatar data from "B" by sending a |
513 | packet `PACKET_ID_AVATAR_DATA_CONTROL` with 'op' set to | 513 | packet `PACKET_ID_AVATAR_DATA_CONTROL` with 'op' set to |
514 | `AVATARDATACONTROL_REQ`. | 514 | `AVATAR_DATACONTROL_REQ`. |
515 | 515 | ||
516 | - If "B" accepts this transfer, it answers by sending an | 516 | - If "B" accepts this transfer, it answers by sending an |
517 | `PACKET_ID_AVATAR_DATA_START` with the fields 'format', 'hash' and | 517 | `PACKET_ID_AVATAR_DATA_START` with the fields 'format', 'hash' and |
518 | 'data_length' set to the respective values from the current avatar. | 518 | 'data_length' set to the respective values from the current avatar. |
519 | If "B" have no avatar set, 'format' must be `AVATARFORMAT_NONE`, 'hash' | 519 | If "B" have no avatar set, 'format' must be `AVATAR_FORMAT_NONE`, 'hash' |
520 | must be zeroed and 'data_length' must be zero. | 520 | must be zeroed and 'data_length' must be zero. |
521 | 521 | ||
522 | If "B" does not accept sending the avatar, it may send a packet | 522 | If "B" does not accept sending the avatar, it may send a packet |
523 | `PACKET_ID_AVATAR_DATA_CONTROL` with the field 'op' set to | 523 | `PACKET_ID_AVATAR_DATA_CONTROL` with the field 'op' set to |
524 | `AVATARDATACONTROL_ERROR` or simply ignore this request. "A" must cope | 524 | `AVATAR_DATACONTROL_ERROR` or simply ignore this request. "A" must cope |
525 | with this. | 525 | with this. |
526 | 526 | ||
527 | If "B" have an avatar, it sends a variable number of | 527 | If "B" have an avatar, it sends a variable number of |
@@ -531,7 +531,7 @@ from a client "B": | |||
531 | - Upon receiving a `PACKET_ID_AVATAR_DATA_START`, "A" checks if it | 531 | - Upon receiving a `PACKET_ID_AVATAR_DATA_START`, "A" checks if it |
532 | has sent a data request to "B". If not, just ignores the packet. | 532 | has sent a data request to "B". If not, just ignores the packet. |
533 | 533 | ||
534 | If "A" really requested avatar data and the format is `AVATARFORMAT_NONE`, | 534 | If "A" really requested avatar data and the format is `AVATAR_FORMAT_NONE`, |
535 | it triggers the avatar data callback, and clears all the temporary data, | 535 | it triggers the avatar data callback, and clears all the temporary data, |
536 | finishing the process. For other formats, "A" just waits for packets | 536 | finishing the process. For other formats, "A" just waits for packets |
537 | of type `PACKET_ID_AVATAR_DATA_PUSH`. | 537 | of type `PACKET_ID_AVATAR_DATA_PUSH`. |
@@ -541,9 +541,9 @@ from a client "B": | |||
541 | already received. If this conditions are valid, it checks if the total | 541 | already received. If this conditions are valid, it checks if the total |
542 | length of the data already stored in the receiving buffer plus the data | 542 | length of the data already stored in the receiving buffer plus the data |
543 | present in the push packet is still less or equal than | 543 | present in the push packet is still less or equal than |
544 | `TOX_MAX_AVATAR_DATA_LENGTH`. If invalid, it replies with a | 544 | `TOX_AVATAR_MAX_DATA_LENGTH`. If invalid, it replies with a |
545 | `PACKET_ID_AVATAR_DATA_CONTROL` with the field 'op' set to | 545 | `PACKET_ID_AVATAR_DATA_CONTROL` with the field 'op' set to |
546 | `AVATARDATACONTROL_ERROR`. | 546 | `AVATAR_DATACONTROL_ERROR`. |
547 | 547 | ||
548 | If valid, "A" updates the 'bytes_received' counter and concatenates the | 548 | If valid, "A" updates the 'bytes_received' counter and concatenates the |
549 | newly arrived data to the buffer. | 549 | newly arrived data to the buffer. |
@@ -566,7 +566,7 @@ from a client "B": | |||
566 | some transfer limit for the data it sends. | 566 | some transfer limit for the data it sends. |
567 | 567 | ||
568 | - Any peer receiving a `PACKET_ID_AVATAR_DATA_CONTROL` with the field 'op' | 568 | - Any peer receiving a `PACKET_ID_AVATAR_DATA_CONTROL` with the field 'op' |
569 | set to `AVATARDATACONTROL_ERROR` clears any existing control state and | 569 | set to `AVATAR_DATACONTROL_ERROR` clears any existing control state and |
570 | finishes sending or receiving data. | 570 | finishes sending or receiving data. |
571 | 571 | ||
572 | 572 | ||
@@ -596,7 +596,7 @@ The present proposal mitigates this situation by: | |||
596 | same offset of the avatar again and again, the implementation limits | 596 | same offset of the avatar again and again, the implementation limits |
597 | the amount of data a single user can request for some time. For now, | 597 | the amount of data a single user can request for some time. For now, |
598 | the library will not allow an user to request more than | 598 | the library will not allow an user to request more than |
599 | `10*TOX_MAX_AVATAR_DATA_LENGTH` in less than 20 minutes; | 599 | `10*TOX_AVATAR_MAX_DATA_LENGTH` in less than 20 minutes; |
600 | 600 | ||
601 | - Making the requester responsible for storing partial data and state | 601 | - Making the requester responsible for storing partial data and state |
602 | information; | 602 | information; |