diff options
Diffstat (limited to 'toxcore/tox.h')
-rw-r--r-- | toxcore/tox.h | 144 |
1 files changed, 143 insertions, 1 deletions
diff --git a/toxcore/tox.h b/toxcore/tox.h index 278a19cd..a5efee34 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h | |||
@@ -37,6 +37,8 @@ extern "C" { | |||
37 | #define TOX_MAX_MESSAGE_LENGTH 1368 | 37 | #define TOX_MAX_MESSAGE_LENGTH 1368 |
38 | #define TOX_MAX_STATUSMESSAGE_LENGTH 1007 | 38 | #define TOX_MAX_STATUSMESSAGE_LENGTH 1007 |
39 | #define TOX_CLIENT_ID_SIZE 32 | 39 | #define TOX_CLIENT_ID_SIZE 32 |
40 | #define TOX_MAX_AVATAR_DATA_LENGTH 16384 | ||
41 | #define TOX_AVATAR_HASH_LENGTH 32 | ||
40 | 42 | ||
41 | #define TOX_FRIEND_ADDRESS_SIZE (TOX_CLIENT_ID_SIZE + sizeof(uint32_t) + sizeof(uint16_t)) | 43 | #define TOX_FRIEND_ADDRESS_SIZE (TOX_CLIENT_ID_SIZE + sizeof(uint32_t) + sizeof(uint16_t)) |
42 | 44 | ||
@@ -70,6 +72,16 @@ typedef enum { | |||
70 | } | 72 | } |
71 | TOX_USERSTATUS; | 73 | TOX_USERSTATUS; |
72 | 74 | ||
75 | |||
76 | /* AVATARFORMAT - | ||
77 | * Data formats for user avatar images | ||
78 | */ | ||
79 | typedef enum { | ||
80 | TOX_AVATARFORMAT_NONE, | ||
81 | TOX_AVATARFORMAT_PNG | ||
82 | } | ||
83 | TOX_AVATARFORMAT; | ||
84 | |||
73 | #ifndef __TOX_DEFINED__ | 85 | #ifndef __TOX_DEFINED__ |
74 | #define __TOX_DEFINED__ | 86 | #define __TOX_DEFINED__ |
75 | typedef struct Tox Tox; | 87 | typedef struct Tox Tox; |
@@ -242,7 +254,6 @@ int tox_get_self_status_message(const Tox *tox, uint8_t *buf, uint32_t maxlen); | |||
242 | uint8_t tox_get_user_status(const Tox *tox, int32_t friendnumber); | 254 | uint8_t tox_get_user_status(const Tox *tox, int32_t friendnumber); |
243 | uint8_t tox_get_self_user_status(const Tox *tox); | 255 | uint8_t tox_get_self_user_status(const Tox *tox); |
244 | 256 | ||
245 | |||
246 | /* returns timestamp of last time friendnumber was seen online, or 0 if never seen. | 257 | /* returns timestamp of last time friendnumber was seen online, or 0 if never seen. |
247 | * returns -1 on error. | 258 | * returns -1 on error. |
248 | */ | 259 | */ |
@@ -517,6 +528,137 @@ uint32_t tox_count_chatlist(const Tox *tox); | |||
517 | * of out_list will be truncated to list_size. */ | 528 | * of out_list will be truncated to list_size. */ |
518 | uint32_t tox_get_chatlist(const Tox *tox, int *out_list, uint32_t list_size); | 529 | uint32_t tox_get_chatlist(const Tox *tox, int *out_list, uint32_t list_size); |
519 | 530 | ||
531 | /****************AVATAR FUNCTIONS*****************/ | ||
532 | |||
533 | /* Set the callback function for avatar information. | ||
534 | * This callback will be called when avatar information are received from friends. These events | ||
535 | * can arrive at anytime, but are usually received uppon connection and in reply of avatar | ||
536 | * information requests. | ||
537 | * | ||
538 | * Function format is: | ||
539 | * function(Tox *tox, int32_t friendnumber, uint8_t format, uint8_t *hash, void *userdata) | ||
540 | * | ||
541 | * where 'format' is the avatar image format (see TOX_AVATARFORMAT) and 'hash' is the hash of | ||
542 | * the avatar data for caching purposes and it is exactly TOX_AVATAR_HASH_LENGTH long. If the | ||
543 | * image format is NONE, the hash is zeroed. | ||
544 | * | ||
545 | */ | ||
546 | void tox_callback_avatar_info(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, uint8_t *, void *), | ||
547 | void *userdata); | ||
548 | |||
549 | |||
550 | /* Set the callback function for avatar data. | ||
551 | * This callback will be called when the complete avatar data was correctly received from a | ||
552 | * friend. This only happens in reply of a avatar data request (see tox_request_avatar_data); | ||
553 | * | ||
554 | * Function format is: | ||
555 | * function(Tox *tox, int32_t friendnumber, uint8_t format, uint8_t *hash, uint8_t *data, uint32_t datalen, void *userdata) | ||
556 | * | ||
557 | * where 'format' is the avatar image format (see TOX_AVATARFORMAT); 'hash' is the | ||
558 | * locally-calculated cryptographic hash of the avatar data and it is exactly | ||
559 | * TOX_AVATAR_HASH_LENGTH long; 'data' is the avatar image data and 'datalen' is the length | ||
560 | * of such data. | ||
561 | * | ||
562 | * If format is NONE, 'data' is NULL, 'datalen' is zero, and the hash is zeroed. The hash is | ||
563 | * always validated locally with the function tox_avatar_hash and ensured to match the image | ||
564 | * data, so this value can be safely used to compare with cached avatars. | ||
565 | * | ||
566 | * WARNING: users MUST treat all avatar image data received from another peer as untrusted and | ||
567 | * potentially malicious. The library only ensures that the data which arrived is the same the | ||
568 | * other user sent, and does not interpret or validate any image data. | ||
569 | */ | ||
570 | void tox_callback_avatar_data(Tox *tox, void (*function)(Tox *tox, int32_t, uint8_t, uint8_t *, uint8_t *, uint32_t, | ||
571 | void *), void *userdata); | ||
572 | |||
573 | /* Set the user avatar image data. | ||
574 | * This should be made before connecting, so we will not announce that the user have no avatar | ||
575 | * before setting and announcing a new one, forcing the peers to re-download it. | ||
576 | * | ||
577 | * Notice that the library treats the image as raw data and does not interpret it by any way. | ||
578 | * | ||
579 | * Arguments: | ||
580 | * format - Avatar image format or NONE for user with no avatar (see TOX_AVATARFORMAT); | ||
581 | * data - pointer to the avatar data (may be NULL it the format is NONE); | ||
582 | * length - length of image data. Must be <= TOX_MAX_AVATAR_DATA_LENGTH. | ||
583 | * | ||
584 | * returns 0 on success | ||
585 | * returns -1 on failure. | ||
586 | */ | ||
587 | int tox_set_avatar(Tox *tox, uint8_t format, const uint8_t *data, uint32_t length); | ||
588 | |||
589 | |||
590 | /* Get avatar data from the current user. | ||
591 | * Copies the current user avatar data to the destination buffer and sets the image format | ||
592 | * accordingly. | ||
593 | * | ||
594 | * If the avatar format is NONE, the buffer 'buf' isleft uninitialized, 'hash' is zeroed, and | ||
595 | * 'length' is set to zero. | ||
596 | * | ||
597 | * If any of the pointers format, buf, length, and hash are NULL, that particular field will be ignored. | ||
598 | * | ||
599 | * Arguments: | ||
600 | * format - destination pointer to the avatar image format (see TOX_AVATARFORMAT); | ||
601 | * buf - destination buffer to the image data. Must have at least 'maxlen' bytes; | ||
602 | * length - destination pointer to the image data length; | ||
603 | * maxlen - length of the destination buffer 'buf'; | ||
604 | * hash - destination pointer to the avatar hash (it must be exactly TOX_AVATAR_HASH_LENGTH bytes long). | ||
605 | * | ||
606 | * returns 0 on success; | ||
607 | * returns -1 on failure. | ||
608 | * | ||
609 | */ | ||
610 | int tox_get_self_avatar(const Tox *tox, uint8_t *format, uint8_t *buf, uint32_t *length, uint32_t maxlen, | ||
611 | uint8_t *hash); | ||
612 | |||
613 | |||
614 | /* Generates a cryptographic hash of the given avatar data. | ||
615 | * This function is a wrapper to internal message-digest functions and specifically provided | ||
616 | * to generate hashes from user avatars that may be memcmp()ed with the values returned by the | ||
617 | * other avatar functions. It is specially important to validate cached avatars. | ||
618 | * | ||
619 | * Arguments: | ||
620 | * hash - destination buffer for the hash data, it must be exactly TOX_AVATAR_HASH_LENGTH bytes long. | ||
621 | * data - avatar image data; | ||
622 | * datalen - length of the avatar image data; it must be <= TOX_MAX_AVATAR_DATA_LENGTH. | ||
623 | * | ||
624 | * returns 0 on success | ||
625 | * returns -1 on failure. | ||
626 | */ | ||
627 | int tox_avatar_hash(const Tox *tox, uint8_t *hash, const uint8_t *data, const uint32_t datalen); | ||
628 | |||
629 | |||
630 | /* Request avatar information from a friend. | ||
631 | * Asks a friend to provide their avatar information (image format and hash). The friend may | ||
632 | * or may not answer this request and, if answered, the information will be provided through | ||
633 | * the callback 'avatar_info'. | ||
634 | * | ||
635 | * returns 0 on success | ||
636 | * returns -1 on failure. | ||
637 | */ | ||
638 | int tox_request_avatar_info(const Tox *tox, const int32_t friendnumber); | ||
639 | |||
640 | |||
641 | /* Send an unrequested avatar information to a friend. | ||
642 | * Sends our avatar format and hash to a friend; he/she can use this information to validate | ||
643 | * an avatar from the cache and may (or not) reply with an avatar data request. | ||
644 | * | ||
645 | * Notice: it is NOT necessary to send these notification after changing the avatar or | ||
646 | * connecting. The library already does this. | ||
647 | * | ||
648 | * returns 0 on success | ||
649 | * returns -1 on failure. | ||
650 | */ | ||
651 | int tox_send_avatar_info(Tox *tox, const int32_t friendnumber); | ||
652 | |||
653 | |||
654 | /* Request the avatar data from a friend. | ||
655 | * Ask a friend to send their avatar data. The friend may or may not answer this request and, | ||
656 | * if answered, the information will be provided in callback 'avatar_data'. | ||
657 | * | ||
658 | * returns 0 on sucess | ||
659 | * returns -1 on failure. | ||
660 | */ | ||
661 | int tox_request_avatar_data(const Tox *tox, const int32_t friendnumber); | ||
520 | 662 | ||
521 | /****************FILE SENDING FUNCTIONS*****************/ | 663 | /****************FILE SENDING FUNCTIONS*****************/ |
522 | /* NOTE: This how to will be updated. | 664 | /* NOTE: This how to will be updated. |