diff options
Diffstat (limited to 'protocols/Tox/libtox/src/toxcore/Messenger.h')
| -rw-r--r-- | protocols/Tox/libtox/src/toxcore/Messenger.h | 548 |
1 files changed, 304 insertions, 244 deletions
diff --git a/protocols/Tox/libtox/src/toxcore/Messenger.h b/protocols/Tox/libtox/src/toxcore/Messenger.h index 477b997391..4abd7905d0 100644 --- a/protocols/Tox/libtox/src/toxcore/Messenger.h +++ b/protocols/Tox/libtox/src/toxcore/Messenger.h @@ -11,6 +11,8 @@ #define C_TOXCORE_TOXCORE_MESSENGER_H #include "TCP_server.h" +#include "announce.h" +#include "forwarding.h" #include "friend_connection.h" #include "friend_requests.h" #include "logger.h" @@ -60,6 +62,7 @@ typedef struct Messenger_Options { bool hole_punching_enabled; bool local_discovery_enabled; + bool dht_announcements_enabled; logger_cb *log_callback; void *log_context; @@ -85,7 +88,8 @@ typedef enum Friend_Status { FRIEND_ONLINE, } Friend_Status; -/** Errors for m_addfriend +/** @brief Errors for m_addfriend + * * FAERR - Friend Add Error */ typedef enum Friend_Add_Error { @@ -108,10 +112,9 @@ typedef enum Connection_Status { CONNECTION_UDP, } Connection_Status; -/** USERSTATUS - +/** * Represents userstatuses someone can have. */ - typedef enum Userstatus { USERSTATUS_NONE, USERSTATUS_AWAY, @@ -158,7 +161,7 @@ typedef enum Filekind { } Filekind; -typedef void m_self_connection_status_cb(Messenger *m, unsigned int connection_status, void *user_data); +typedef void m_self_connection_status_cb(Messenger *m, Onion_Connection_Status connection_status, void *user_data); typedef void m_friend_status_cb(Messenger *m, uint32_t friend_number, unsigned int status, void *user_data); typedef void m_friend_connection_status_cb(Messenger *m, uint32_t friend_number, unsigned int connection_status, void *user_data); @@ -207,15 +210,15 @@ typedef struct Friend { uint8_t info[MAX_FRIEND_REQUEST_DATA_SIZE]; // the data that is sent during the friend requests we do. uint8_t name[MAX_NAME_LENGTH]; uint16_t name_length; - uint8_t name_sent; // 0 if we didn't send our name to this friend 1 if we have. + bool name_sent; // false if we didn't send our name to this friend, true if we have. uint8_t statusmessage[MAX_STATUSMESSAGE_LENGTH]; uint16_t statusmessage_length; - uint8_t statusmessage_sent; + bool statusmessage_sent; Userstatus userstatus; - uint8_t userstatus_sent; - uint8_t user_istyping; - uint8_t user_istyping_sent; - uint8_t is_typing; + bool userstatus_sent; + bool user_istyping; + bool user_istyping_sent; + bool is_typing; uint16_t info_size; // Length of the info. uint32_t message_id; // a semi-unique id used in read receipts. uint32_t friendrequest_nospam; // The nospam number used in the friend request. @@ -234,11 +237,16 @@ typedef struct Friend { struct Messenger { Logger *log; Mono_Time *mono_time; + const Random *rng; + const Network *ns; Networking_Core *net; Net_Crypto *net_crypto; DHT *dht; + Forwarding *forwarding; + Announcements *announce; + Onion *onion; Onion_Announce *onion_a; Onion_Client *onion_c; @@ -258,13 +266,15 @@ struct Messenger { Friend *friendlist; uint32_t numfriends; - time_t lastdump; + uint64_t lastdump; + uint8_t is_receiving_file; bool has_added_relays; // If the first connection has occurred in do_messenger uint16_t num_loaded_relays; Node_format loaded_relays[NUM_SAVED_TCP_RELAYS]; // Relays loaded from config + m_friend_request_cb *friend_request; m_friend_message_cb *friend_message; m_friend_name_cb *friend_namechange; m_friend_status_message_cb *friend_statusmessagechange; @@ -290,15 +300,17 @@ struct Messenger { m_friend_lossless_packet_cb *lossless_packethandler; m_self_connection_status_cb *core_connection_change; - unsigned int last_connection_status; + Onion_Connection_Status last_connection_status; Messenger_Options options; }; -/** Format: `[real_pk (32 bytes)][nospam number (4 bytes)][checksum (2 bytes)]` +/** + * Format: `[real_pk (32 bytes)][nospam number (4 bytes)][checksum (2 bytes)]` * - * return FRIEND_ADDRESS_SIZE byte address to give to others. + * @param[out] address FRIEND_ADDRESS_SIZE byte address to give to others. */ +non_null() void getaddress(const Messenger *m, uint8_t *address); /** @@ -312,365 +324,391 @@ void getaddress(const Messenger *m, uint8_t *address); * @param data is the data. * @param length is the length. * - * return the friend number if success. - * return FA_TOOLONG if message length is too long. - * return FAERR_NOMESSAGE if no message (message length must be >= 1 byte). - * return FAERR_OWNKEY if user's own key. - * return FAERR_ALREADYSENT if friend request already sent or already a friend. - * return FAERR_BADCHECKSUM if bad checksum in address. - * return FAERR_SETNEWNOSPAM if the friend was already there but the nospam was different. - * (the nospam for that friend was set to the new one). - * return FAERR_NOMEM if increasing the friend list size fails. - */ + * @return the friend number if success. + * @retval FA_TOOLONG if message length is too long. + * @retval FAERR_NOMESSAGE if no message (message length must be >= 1 byte). + * @retval FAERR_OWNKEY if user's own key. + * @retval FAERR_ALREADYSENT if friend request already sent or already a friend. + * @retval FAERR_BADCHECKSUM if bad checksum in address. + * @retval FAERR_SETNEWNOSPAM if the friend was already there but the nospam was different. + * (the nospam for that friend was set to the new one). + * @retval FAERR_NOMEM if increasing the friend list size fails. + */ +non_null() int32_t m_addfriend(Messenger *m, const uint8_t *address, const uint8_t *data, uint16_t length); -/** Add a friend without sending a friendrequest. - * return the friend number if success. - * return -3 if user's own key. - * return -4 if friend request already sent or already a friend. - * return -6 if bad checksum in address. - * return -8 if increasing the friend list size fails. +/** @brief Add a friend without sending a friendrequest. + * @return the friend number if success. + * @retval -3 if user's own key. + * @retval -4 if friend request already sent or already a friend. + * @retval -6 if bad checksum in address. + * @retval -8 if increasing the friend list size fails. */ +non_null() int32_t m_addfriend_norequest(Messenger *m, const uint8_t *real_pk); -/** return the friend number associated to that public key. - * return -1 if no such friend. +/** @return the friend number associated to that public key. + * @retval -1 if no such friend. */ +non_null() int32_t getfriend_id(const Messenger *m, const uint8_t *real_pk); -/** Copies the public key associated to that friend id into real_pk buffer. +/** @brief Copies the public key associated to that friend id into real_pk buffer. + * * Make sure that real_pk is of size CRYPTO_PUBLIC_KEY_SIZE. * - * return 0 if success. - * return -1 if failure. + * @retval 0 if success. + * @retval -1 if failure. */ +non_null() int get_real_pk(const Messenger *m, int32_t friendnumber, uint8_t *real_pk); -/** return friend connection id on success. - * return -1 if failure. +/** @return friend connection id on success. + * @retval -1 if failure. */ +non_null() int getfriendcon_id(const Messenger *m, int32_t friendnumber); -/** Remove a friend. +/** @brief Remove a friend. * - * return 0 if success. - * return -1 if failure. + * @retval 0 if success. + * @retval -1 if failure. */ +non_null() int m_delfriend(Messenger *m, int32_t friendnumber); -/** Checks friend's connection status. +/** @brief Checks friend's connection status. * - * return CONNECTION_UDP (2) if friend is directly connected to us (Online UDP). - * return CONNECTION_TCP (1) if friend is connected to us (Online TCP). - * return CONNECTION_NONE (0) if friend is not connected to us (Offline). - * return -1 on failure. + * @retval CONNECTION_UDP (2) if friend is directly connected to us (Online UDP). + * @retval CONNECTION_TCP (1) if friend is connected to us (Online TCP). + * @retval CONNECTION_NONE (0) if friend is not connected to us (Offline). + * @retval -1 on failure. */ +non_null() int m_get_friend_connectionstatus(const Messenger *m, int32_t friendnumber); -/** Checks if there exists a friend with given friendnumber. +/** + * Checks if there exists a friend with given friendnumber. + * + * @param friendnumber The index in the friend list. * - * return 1 if friend exists. - * return 0 if friend doesn't exist. + * @retval true if friend exists. + * @retval false if friend doesn't exist. */ -int m_friend_exists(const Messenger *m, int32_t friendnumber); +non_null() +bool m_friend_exists(const Messenger *m, int32_t friendnumber); -/** Send a message of type to an online friend. +/** @brief Send a message of type to an online friend. * - * return -1 if friend not valid. - * return -2 if too large. - * return -3 if friend not online. - * return -4 if send failed (because queue is full). - * return -5 if bad type. - * return 0 if success. + * @retval -1 if friend not valid. + * @retval -2 if too large. + * @retval -3 if friend not online. + * @retval -4 if send failed (because queue is full). + * @retval -5 if bad type. + * @retval 0 if success. * - * the value in message_id will be passed to your read_receipt callback when the other receives the message. + * The value in message_id will be passed to your read_receipt callback when the other receives the message. */ +non_null(1, 4) nullable(6) int m_send_message_generic(Messenger *m, int32_t friendnumber, uint8_t type, const uint8_t *message, uint32_t length, uint32_t *message_id); -/** Set the name and name_length of a friend. +/** @brief Set the name and name_length of a friend. + * * name must be a string of maximum MAX_NAME_LENGTH length. * length must be at least 1 byte. * length is the length of name with the NULL terminator. * - * return 0 if success. - * return -1 if failure. + * @retval 0 if success. + * @retval -1 if failure. */ +non_null() int setfriendname(Messenger *m, int32_t friendnumber, const uint8_t *name, uint16_t length); -/** Set our nickname. +/** @brief Set our nickname. + * * name must be a string of maximum MAX_NAME_LENGTH length. * length must be at least 1 byte. * length is the length of name with the NULL terminator. * - * return 0 if success. - * return -1 if failure. + * @retval 0 if success. + * @retval -1 if failure. */ +non_null() int setname(Messenger *m, const uint8_t *name, uint16_t length); /** - * Get your nickname. + * @brief Get your nickname. + * * m - The messenger context to use. * name needs to be a valid memory location with a size of at least MAX_NAME_LENGTH bytes. * - * return length of the name. - * return 0 on error. + * @return length of the name. + * @retval 0 on error. */ +non_null() uint16_t getself_name(const Messenger *m, uint8_t *name); -/** Get name of friendnumber and put it in name. +/** @brief Get name of friendnumber and put it in name. + * * name needs to be a valid memory location with a size of at least MAX_NAME_LENGTH (128) bytes. * - * return length of name if success. - * return -1 if failure. + * @return length of name if success. + * @retval -1 if failure. */ +non_null() int getname(const Messenger *m, int32_t friendnumber, uint8_t *name); -/** return the length of name, including null on success. - * return -1 on failure. +/** @return the length of name, including null on success. + * @retval -1 on failure. */ -int m_get_name_size(const Messenger *m, int32_t friendnumber); -int m_get_self_name_size(const Messenger *m); +non_null() int m_get_name_size(const Messenger *m, int32_t friendnumber); +non_null() int m_get_self_name_size(const Messenger *m); -/** Set our user status. +/** @brief Set our user status. * You are responsible for freeing status after. * - * returns 0 on success. - * returns -1 on failure. + * @retval 0 on success. + * @retval -1 on failure. */ -int m_set_statusmessage(Messenger *m, const uint8_t *status, uint16_t length); -int m_set_userstatus(Messenger *m, uint8_t status); +non_null() int m_set_statusmessage(Messenger *m, const uint8_t *status, uint16_t length); +non_null() int m_set_userstatus(Messenger *m, uint8_t status); /** * Guaranteed to be at most MAX_STATUSMESSAGE_LENGTH. * - * returns the length of friendnumber's status message, including null on success. - * returns -1 on failure. + * @return the length of friendnumber's status message, including null on success. + * @retval -1 on failure. */ -int m_get_statusmessage_size(const Messenger *m, int32_t friendnumber); -int m_get_self_statusmessage_size(const Messenger *m); +non_null() int m_get_statusmessage_size(const Messenger *m, int32_t friendnumber); +non_null() int m_get_self_statusmessage_size(const Messenger *m); -/** Copy friendnumber's status message into buf, truncating if size is over maxlen. +/** @brief Copy friendnumber's status message into buf, truncating if size is over maxlen. + * * Get the size you need to allocate from m_get_statusmessage_size. * The self variant will copy our own status message. * - * returns the length of the copied data on success - * returns -1 on failure. + * @return the length of the copied data on success + * @retval -1 on failure. */ -int m_copy_statusmessage(const Messenger *m, int32_t friendnumber, uint8_t *buf, uint32_t maxlen); -int m_copy_self_statusmessage(const Messenger *m, uint8_t *buf); +non_null() int m_copy_statusmessage(const Messenger *m, int32_t friendnumber, uint8_t *buf, uint32_t maxlen); +non_null() int m_copy_self_statusmessage(const Messenger *m, uint8_t *buf); -/** return one of Userstatus values. - * Values unknown to your application should be represented as USERSTATUS_NONE. - * As above, the self variant will return our own Userstatus. - * If friendnumber is invalid, this shall return USERSTATUS_INVALID. +/** @brief return one of Userstatus values. + * + * Values unknown to your application should be represented as USERSTATUS_NONE. + * As above, the self variant will return our own Userstatus. + * If friendnumber is invalid, this shall return USERSTATUS_INVALID. */ -uint8_t m_get_userstatus(const Messenger *m, int32_t friendnumber); -uint8_t m_get_self_userstatus(const Messenger *m); +non_null() uint8_t m_get_userstatus(const Messenger *m, int32_t friendnumber); +non_null() uint8_t m_get_self_userstatus(const Messenger *m); -/** returns timestamp of last time friendnumber was seen online or 0 if never seen. +/** @brief returns timestamp of last time friendnumber was seen online or 0 if never seen. * if friendnumber is invalid this function will return UINT64_MAX. */ -uint64_t m_get_last_online(const Messenger *m, int32_t friendnumber); +non_null() uint64_t m_get_last_online(const Messenger *m, int32_t friendnumber); -/** Set our typing status for a friend. +/** @brief Set our typing status for a friend. * You are responsible for turning it on or off. * - * returns 0 on success. - * returns -1 on failure. + * @retval 0 on success. + * @retval -1 on failure. */ -int m_set_usertyping(Messenger *m, int32_t friendnumber, uint8_t is_typing); +non_null() +int m_set_usertyping(Messenger *m, int32_t friendnumber, bool is_typing); -/** Get the typing status of a friend. +/** @brief Get the typing status of a friend. * - * returns 0 if friend is not typing. - * returns 1 if friend is typing. + * @retval -1 if friend number is invalid. + * @retval 0 if friend is not typing. + * @retval 1 if friend is typing. */ +non_null() int m_get_istyping(const Messenger *m, int32_t friendnumber); /** Set the function that will be executed when a friend request is received. */ +non_null(1) nullable(2) void m_callback_friendrequest(Messenger *m, m_friend_request_cb *function); /** Set the function that will be executed when a message from a friend is received. */ -void m_callback_friendmessage(Messenger *m, m_friend_message_cb *function); +non_null() void m_callback_friendmessage(Messenger *m, m_friend_message_cb *function); -/** Set the callback for name changes. - * You are not responsible for freeing newname. +/** @brief Set the callback for name changes. + * You are not responsible for freeing newname. */ -void m_callback_namechange(Messenger *m, m_friend_name_cb *function); +non_null() void m_callback_namechange(Messenger *m, m_friend_name_cb *function); -/** Set the callback for status message changes. +/** @brief Set the callback for status message changes. * - * You are not responsible for freeing newstatus + * You are not responsible for freeing newstatus */ -void m_callback_statusmessage(Messenger *m, m_friend_status_message_cb *function); +non_null() void m_callback_statusmessage(Messenger *m, m_friend_status_message_cb *function); -/** Set the callback for status type changes. - */ -void m_callback_userstatus(Messenger *m, m_friend_status_cb *function); +/** @brief Set the callback for status type changes. */ +non_null() void m_callback_userstatus(Messenger *m, m_friend_status_cb *function); -/** Set the callback for typing changes. - */ -void m_callback_typingchange(Messenger *m, m_friend_typing_cb *function); +/** @brief Set the callback for typing changes. */ +non_null() void m_callback_typingchange(Messenger *m, m_friend_typing_cb *function); -/** Set the callback for read receipts. +/** @brief Set the callback for read receipts. * - * If you are keeping a record of returns from m_sendmessage, - * receipt might be one of those values, meaning the message - * has been received on the other side. - * Since core doesn't track ids for you, receipt may not correspond to any message. - * In that case, you should discard it. + * If you are keeping a record of returns from m_sendmessage, + * receipt might be one of those values, meaning the message + * has been received on the other side. + * Since core doesn't track ids for you, receipt may not correspond to any message. + * In that case, you should discard it. */ -void m_callback_read_receipt(Messenger *m, m_friend_read_receipt_cb *function); +non_null() void m_callback_read_receipt(Messenger *m, m_friend_read_receipt_cb *function); -/** Set the callback for connection status changes. +/** @brief Set the callback for connection status changes. * - * Status: - * 0 -- friend went offline after being previously online. - * 1 -- friend went online. + * Status: + * - 0: friend went offline after being previously online. + * - 1: friend went online. * - * Note that this callback is not called when adding friends, thus the - * "after being previously online" part. - * It's assumed that when adding friends, their connection status is offline. + * Note that this callback is not called when adding friends, thus the + * "after being previously online" part. + * It's assumed that when adding friends, their connection status is offline. */ -void m_callback_connectionstatus(Messenger *m, m_friend_connection_status_cb *function); +non_null() void m_callback_connectionstatus(Messenger *m, m_friend_connection_status_cb *function); /** Same as previous but for internal A/V core usage only */ -void m_callback_connectionstatus_internal_av(Messenger *m, m_friend_connectionstatuschange_internal_cb *function, - void *userdata); +non_null() void m_callback_connectionstatus_internal_av( + Messenger *m, m_friend_connectionstatuschange_internal_cb *function, void *userdata); -/** Set the callback for typing changes. - */ -void m_callback_core_connection(Messenger *m, m_self_connection_status_cb *function); +/** @brief Set the callback for typing changes. */ +non_null() void m_callback_core_connection(Messenger *m, m_self_connection_status_cb *function); /*** CONFERENCES */ -/** Set the callback for conference invites. - */ +/** @brief Set the callback for conference invites. */ +non_null(1) nullable(2) void m_callback_conference_invite(Messenger *m, m_conference_invite_cb *function); -/** Send a conference invite packet. +/** @brief Send a conference invite packet. * - * return 1 on success - * return 0 on failure + * return true on success + * return false on failure */ -int send_conference_invite_packet(const Messenger *m, int32_t friendnumber, const uint8_t *data, uint16_t length); +non_null() +bool send_conference_invite_packet(const Messenger *m, int32_t friendnumber, const uint8_t *data, uint16_t length); /*** FILE SENDING */ -/** Set the callback for file send requests. - */ -void callback_file_sendrequest(Messenger *m, m_file_recv_cb *function); +/** @brief Set the callback for file send requests. */ +non_null() void callback_file_sendrequest(Messenger *m, m_file_recv_cb *function); -/** Set the callback for file control requests. - */ -void callback_file_control(Messenger *m, m_file_recv_control_cb *function); +/** @brief Set the callback for file control requests. */ +non_null() void callback_file_control(Messenger *m, m_file_recv_control_cb *function); -/** Set the callback for file data. - */ -void callback_file_data(Messenger *m, m_file_recv_chunk_cb *function); +/** @brief Set the callback for file data. */ +non_null() void callback_file_data(Messenger *m, m_file_recv_chunk_cb *function); -/** Set the callback for file request chunk. - */ -void callback_file_reqchunk(Messenger *m, m_file_chunk_request_cb *function); +/** @brief Set the callback for file request chunk. */ +non_null() void callback_file_reqchunk(Messenger *m, m_file_chunk_request_cb *function); -/** Copy the file transfer file id to file_id +/** @brief Copy the file transfer file id to file_id * - * return 0 on success. - * return -1 if friend not valid. - * return -2 if filenumber not valid + * @retval 0 on success. + * @retval -1 if friend not valid. + * @retval -2 if filenumber not valid */ +non_null() int file_get_id(const Messenger *m, int32_t friendnumber, uint32_t filenumber, uint8_t *file_id); -/** Send a file send request. +/** @brief Send a file send request. + * * Maximum filename length is 255 bytes. - * return file number on success - * return -1 if friend not found. - * return -2 if filename length invalid. - * return -3 if no more file sending slots left. - * return -4 if could not send packet (friend offline). * + * @return file number on success + * @retval -1 if friend not found. + * @retval -2 if filename length invalid. + * @retval -3 if no more file sending slots left. + * @retval -4 if could not send packet (friend offline). */ +non_null() long int new_filesender(const Messenger *m, int32_t friendnumber, uint32_t file_type, uint64_t filesize, const uint8_t *file_id, const uint8_t *filename, uint16_t filename_length); -/** Send a file control request. +/** @brief Send a file control request. * - * return 0 on success - * return -1 if friend not valid. - * return -2 if friend not online. - * return -3 if file number invalid. - * return -4 if file control is bad. - * return -5 if file already paused. - * return -6 if resume file failed because it was only paused by the other. - * return -7 if resume file failed because it wasn't paused. - * return -8 if packet failed to send. + * @retval 0 on success + * @retval -1 if friend not valid. + * @retval -2 if friend not online. + * @retval -3 if file number invalid. + * @retval -4 if file control is bad. + * @retval -5 if file already paused. + * @retval -6 if resume file failed because it was only paused by the other. + * @retval -7 if resume file failed because it wasn't paused. + * @retval -8 if packet failed to send. */ +non_null() int file_control(const Messenger *m, int32_t friendnumber, uint32_t filenumber, unsigned int control); -/** Send a seek file control request. +/** @brief Send a seek file control request. * - * return 0 on success - * return -1 if friend not valid. - * return -2 if friend not online. - * return -3 if file number invalid. - * return -4 if not receiving file. - * return -5 if file status wrong. - * return -6 if position bad. - * return -8 if packet failed to send. + * @retval 0 on success + * @retval -1 if friend not valid. + * @retval -2 if friend not online. + * @retval -3 if file number invalid. + * @retval -4 if not receiving file. + * @retval -5 if file status wrong. + * @retval -6 if position bad. + * @retval -8 if packet failed to send. */ +non_null() int file_seek(const Messenger *m, int32_t friendnumber, uint32_t filenumber, uint64_t position); -/** Send file data. +/** @brief Send file data. * - * return 0 on success - * return -1 if friend not valid. - * return -2 if friend not online. - * return -3 if filenumber invalid. - * return -4 if file transfer not transferring. - * return -5 if bad data size. - * return -6 if packet queue full. - * return -7 if wrong position. + * @retval 0 on success + * @retval -1 if friend not valid. + * @retval -2 if friend not online. + * @retval -3 if filenumber invalid. + * @retval -4 if file transfer not transferring. + * @retval -5 if bad data size. + * @retval -6 if packet queue full. + * @retval -7 if wrong position. */ -int file_data(const Messenger *m, int32_t friendnumber, uint32_t filenumber, uint64_t position, const uint8_t *data, - uint16_t length); +non_null(1) nullable(5) +int send_file_data(const Messenger *m, int32_t friendnumber, uint32_t filenumber, uint64_t position, const uint8_t *data, uint16_t length); /*** A/V related */ -/** Set the callback for msi packets. - */ +/** @brief Set the callback for msi packets. */ +non_null(1) nullable(2, 3) void m_callback_msi_packet(Messenger *m, m_msi_packet_cb *function, void *userdata); -/** Send an msi packet. +/** @brief Send an msi packet. * - * return 1 on success - * return 0 on failure + * @retval true on success + * @retval false on failure */ -int m_msi_packet(const Messenger *m, int32_t friendnumber, const uint8_t *data, uint16_t length); +non_null() +bool m_msi_packet(const Messenger *m, int32_t friendnumber, const uint8_t *data, uint16_t length); -/** Set handlers for lossy rtp packets. +/** @brief Set handlers for lossy rtp packets. * - * return -1 on failure. - * return 0 on success. + * @retval -1 on failure. + * @retval 0 on success. */ +non_null(1) nullable(4, 5) int m_callback_rtp_packet(Messenger *m, int32_t friendnumber, uint8_t byte, m_lossy_rtp_packet_cb *function, void *object); /*** CUSTOM PACKETS */ -/** Set handlers for custom lossy packets. - * - */ -void custom_lossy_packet_registerhandler(Messenger *m, m_friend_lossy_packet_cb *lossy_packethandler); +/** @brief Set handlers for custom lossy packets. */ +non_null() void custom_lossy_packet_registerhandler(Messenger *m, m_friend_lossy_packet_cb *lossy_packethandler); -/** High level function to send custom lossy packets. +/** @brief High level function to send custom lossy packets. * * TODO(oxij): this name is confusing, because this function sends both av and custom lossy packets. * Meanwhile, m_handle_lossy_packet routes custom packets to custom_lossy_packet_registerhandler @@ -679,30 +717,31 @@ void custom_lossy_packet_registerhandler(Messenger *m, m_friend_lossy_packet_cb * I.e. custom_lossy_packet_registerhandler's "custom lossy packet" and this "custom lossy packet" * are not the same set of packets. * - * return -1 if friend invalid. - * return -2 if length wrong. - * return -3 if first byte invalid. - * return -4 if friend offline. - * return -5 if packet failed to send because of other error. - * return 0 on success. + * @retval -1 if friend invalid. + * @retval -2 if length wrong. + * @retval -3 if first byte invalid. + * @retval -4 if friend offline. + * @retval -5 if packet failed to send because of other error. + * @retval 0 on success. */ +non_null() int m_send_custom_lossy_packet(const Messenger *m, int32_t friendnumber, const uint8_t *data, uint32_t length); -/** Set handlers for custom lossless packets. - * - */ +/** @brief Set handlers for custom lossless packets. */ +non_null() void custom_lossless_packet_registerhandler(Messenger *m, m_friend_lossless_packet_cb *lossless_packethandler); -/** High level function to send custom lossless packets. +/** @brief High level function to send custom lossless packets. * - * return -1 if friend invalid. - * return -2 if length wrong. - * return -3 if first byte invalid. - * return -4 if friend offline. - * return -5 if packet failed to send because of other error. - * return 0 on success. + * @retval -1 if friend invalid. + * @retval -2 if length wrong. + * @retval -3 if first byte invalid. + * @retval -4 if friend offline. + * @retval -5 if packet failed to send because of other error. + * @retval 0 on success. */ +non_null() int send_custom_lossless_packet(const Messenger *m, int32_t friendnumber, const uint8_t *data, uint32_t length); /*** Messenger constructor/destructor/operations. */ @@ -714,46 +753,58 @@ typedef enum Messenger_Error { MESSENGER_ERROR_OTHER, } Messenger_Error; -/** Run this at startup. - * return allocated instance of Messenger on success. - * return 0 if there are problems. +/** @brief Run this at startup. + * + * @return allocated instance of Messenger on success. + * @retval 0 if there are problems. * - * if error is not NULL it will be set to one of the values in the enum above. + * if error is not NULL it will be set to one of the values in the enum above. */ -Messenger *new_messenger(Mono_Time *mono_time, Messenger_Options *options, unsigned int *error); +non_null() +Messenger *new_messenger(Mono_Time *mono_time, const Random *rng, const Network *ns, Messenger_Options *options, Messenger_Error *error); -/** Run this before closing shop +/** @brief Run this before closing shop. + * * Free all datastructures. */ +nullable(1) void kill_messenger(Messenger *m); -/** The main loop that needs to be run at least 20 times per second. */ +/** @brief The main loop that needs to be run at least 20 times per second. */ +non_null(1) nullable(2) void do_messenger(Messenger *m, void *userdata); -/** Return the time in milliseconds before do_messenger() should be called again - * for optimal performance. +/** + * @brief Return the time in milliseconds before `do_messenger()` should be called again + * for optimal performance. * - * returns time (in ms) before the next do_messenger() needs to be run on success. + * @return time (in ms) before the next `do_messenger()` needs to be run on success. */ +non_null() uint32_t messenger_run_interval(const Messenger *m); /* SAVING AND LOADING FUNCTIONS: */ -/** Registers a state plugin for saving, loadding, and getting the size of a section of the save +/** @brief Registers a state plugin for saving, loading, and getting the size of a section of the save. * - * returns true on success - * returns false on error + * @retval true on success + * @retval false on error */ -bool m_register_state_plugin(Messenger *m, State_Type type, m_state_size_cb size_callback, - m_state_load_cb load_callback, m_state_save_cb save_callback); +non_null() +bool m_register_state_plugin(Messenger *m, State_Type type, + m_state_size_cb *size_callback, + m_state_load_cb *load_callback, + m_state_save_cb *save_callback); /** return size of the messenger data (for saving). */ +non_null() uint32_t messenger_size(const Messenger *m); -/** Save the messenger in data (must be allocated memory of size at least Messenger_size()) */ +/** Save the messenger in data (must be allocated memory of size at least `Messenger_size()`) */ +non_null() uint8_t *messenger_save(const Messenger *m, uint8_t *data); -/** Load a state section. +/** @brief Load a state section. * * @param data Data to load. * @param length Length of data. @@ -761,19 +812,28 @@ uint8_t *messenger_save(const Messenger *m, uint8_t *data); * @param status Result of loading section is stored here if the section is handled. * @return true iff section handled. */ +non_null() bool messenger_load_state_section(Messenger *m, const uint8_t *data, uint32_t length, uint16_t type, State_Load_Status *status); -/** Return the number of friends in the instance m. +/** @brief Return the number of friends in the instance m. + * * You should use this to determine how much memory to allocate - * for copy_friendlist. */ + * for copy_friendlist. + */ +non_null() uint32_t count_friendlist(const Messenger *m); -/** Copy a list of valid friend IDs into the array out_list. +/** @brief Copy a list of valid friend IDs into the array out_list. * If out_list is NULL, returns 0. * Otherwise, returns the number of elements copied. * If the array was too small, the contents - * of out_list will be truncated to list_size. */ + * of out_list will be truncated to list_size. + */ +non_null() uint32_t copy_friendlist(const Messenger *m, uint32_t *out_list, uint32_t list_size); +non_null() +bool m_is_receiving_file(Messenger *m); + #endif |