summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorAlexandre Erwin Ittner <alexandre@ittner.com.br>2014-09-24 22:27:00 -0300
committerAlexandre Erwin Ittner <alexandre@ittner.com.br>2014-09-24 22:27:00 -0300
commitfc28c2402e47427d9e6bab467f86d3f6bc9a7eaa (patch)
tree7f1c35011b5a48295ae757c3477e630ac5789942 /docs
parentba6ae15a739257200b04a10b6ecd22fe210951e1 (diff)
Update documentation after API changes
Commit ba6ae15a739257200b04a10b6ecd22fe210951e1 introduced some API changes, update the documentation to reflect them.
Diffstat (limited to 'docs')
-rw-r--r--docs/Avatars.md44
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 */
135typedef enum { 135typedef enum {
136 TOX_AVATARFORMAT_NONE, 136 TOX_AVATAR_FORMAT_NONE,
137 TOX_AVATARFORMAT_PNG 137 TOX_AVATAR_FORMAT_PNG
138} 138}
139TOX_AVATARFORMAT; 139TOX_AVATAR_FORMAT;
140 140
141 141
142 142
@@ -287,11 +287,11 @@ functions. For a complete, working, example, see `testing/test_avatars.c`.
287In this example `load_data_file` is just an hypothetical function that loads 287In this example `load_data_file` is just an hypothetical function that loads
288data from a file into the buffer and sets the length accordingly. 288data 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
297If the user is connected, this function will also notify all connected 297If 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
309To remove an avatar, an application must set it to `TOX_AVATARFORMAT_NONE`. 309To 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
313If the user is connected, this function will also notify all connected 313If the user is connected, this function will also notify all connected
314friends about the avatar change. 314friends 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
454Where 'format' is the image data format, one of the following: 454Where '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
459and 'hash' is the SHA-256 message digest of the avatar data. 459and '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;