From 61880ab9380f3a71ae1f51df7b6f4836059c041f Mon Sep 17 00:00:00 2001 From: JamoBox Date: Mon, 2 Sep 2013 17:25:28 +0100 Subject: last of the comment refactoring from toxcore --- toxcore/tox.h | 79 ++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 43 insertions(+), 36 deletions(-) (limited to 'toxcore/tox.h') diff --git a/toxcore/tox.h b/toxcore/tox.h index eabdf8ff..b17ca36f 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -86,7 +86,7 @@ TOX_USERSTATUS; typedef void Tox; -/* returns FRIEND_ADDRESS_SIZE byte address to give to others. +/* return FRIEND_ADDRESS_SIZE byte address to give to others. * format: [client_id (32 bytes)][nospam number (4 bytes)][checksum (2 bytes)] */ void tox_getaddress(Tox *tox, uint8_t *address); @@ -95,32 +95,33 @@ void tox_getaddress(Tox *tox, uint8_t *address); * Set the data that will be sent along with friend request. * address is the address of the friend (returned by getaddress of the friend you wish to add) it must be FRIEND_ADDRESS_SIZE bytes. TODO: add checksum. * data is the data and length is the length. - * returns the friend number if success. - * return TOX_FA_TOOLONG if message length is too long. - * return TOX_FAERR_NOMESSAGE if no message (message length must be >= 1 byte). - * return TOX_FAERR_OWNKEY if user's own key. - * return TOX_FAERR_ALREADYSENT if friend request already sent or already a friend. - * return TOX_FAERR_UNKNOWN for unknown error. - * return TOX_FAERR_BADCHECKSUM if bad checksum in address. - * return TOX_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 TOX_FAERR_NOMEM if increasing the friend list size fails. + * + * return the friend number if success. + * return TOX_FA_TOOLONG if message length is too long. + * return TOX_FAERR_NOMESSAGE if no message (message length must be >= 1 byte). + * return TOX_FAERR_OWNKEY if user's own key. + * return TOX_FAERR_ALREADYSENT if friend request already sent or already a friend. + * return TOX_FAERR_UNKNOWN for unknown error. + * return TOX_FAERR_BADCHECKSUM if bad checksum in address. + * return TOX_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 TOX_FAERR_NOMEM if increasing the friend list size fails. */ int tox_addfriend(Tox *tox, uint8_t *address, uint8_t *data, uint16_t length); /* Add a friend without sending a friendrequest. - * returns the friend number if success. + * return the friend number if success. * return -1 if failure. */ int tox_addfriend_norequest(Tox *tox, uint8_t *client_id); -/* return the friend id associated to that client id. +/* return the friend id associated to that client id. return -1 if no such friend */ int tox_getfriend_id(Tox *tox, uint8_t *client_id); /* Copies the public key associated to that friend id into client_id buffer. - * Make sure that client_id is of size CLIENT_ID_SIZE. + * Make sure that client_id is of size CLIENT_ID_SIZE. * return 0 if success. * return -1 if failure. */ @@ -138,8 +139,9 @@ int tox_delfriend(Tox *tox, int friendnumber); int tox_friendstatus(Tox *tox, int friendnumber); /* Send a text chat message to an online friend. - * returns the message id if packet was successfully put into the send queue. - * return 0 if it was not. + * + * return the message id if packet was successfully put into the send queue. + * return 0 if it was not. * * You will want to retain the return value, it will be passed to your read receipt callback * if one is received. @@ -150,7 +152,8 @@ uint32_t tox_sendmessage(Tox *tox, int friendnumber, uint8_t *message, uint32_t uint32_t tox_sendmessage_withid(Tox *tox, int friendnumber, uint32_t theid, uint8_t *message, uint32_t length); /* Send an action to an online friend. - * returns 1 if packet was successfully put into the send queue. + * + * return 1 if packet was successfully put into the send queue. * return 0 if it was not. */ int tox_sendaction(Tox *tox, int friendnumber, uint8_t *action, uint32_t length); @@ -160,8 +163,8 @@ int tox_sendaction(Tox *tox, int friendnumber, uint8_t *action, uint32_t 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. + * return 0 if success. + * return -1 if failure. */ int tox_setname(Tox *tox, uint8_t *name, uint16_t length); @@ -171,12 +174,13 @@ int tox_setname(Tox *tox, uint8_t *name, uint16_t length); * name - Pointer to a string for the name. * nlen - The length of the string buffer. * - * returns Return the length of the name, 0 on error. + * return length of name. + * return 0 on error. */ uint16_t tox_getselfname(Tox *tox, uint8_t *name, uint16_t nlen); /* 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. + * name needs to be a valid memory location with a size of at least MAX_NAME_LENGTH (128) bytes. * * return 0 if success. * return -1 if failure. @@ -184,29 +188,30 @@ uint16_t tox_getselfname(Tox *tox, uint8_t *name, uint16_t nlen); int tox_getname(Tox *tox, int friendnumber, uint8_t *name); /* Set our user status. - * You are responsible for freeing status after. + * You are responsible for freeing status after. + * * returns 0 on success. * returns -1 on failure. */ int tox_set_statusmessage(Tox *tox, uint8_t *status, uint16_t length); int tox_set_userstatus(Tox *tox, TOX_USERSTATUS status); -/* return the length of friendnumber's status message, including null. - * Pass it into malloc +/* return the length of friendnumber's status message, including null. + * Pass it into malloc */ int tox_get_statusmessage_size(Tox *tox, int friendnumber); /* 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. + * Get the size you need to allocate from m_get_statusmessage_size. + * The self variant will copy our own status message. */ int tox_copy_statusmessage(Tox *tox, int friendnumber, uint8_t *buf, uint32_t maxlen); int tox_copy_self_statusmessage(Tox *tox, uint8_t *buf, uint32_t maxlen); -/* 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. +/* 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. */ TOX_USERSTATUS tox_get_userstatus(Tox *tox, int friendnumber); TOX_USERSTATUS tox_get_selfuserstatus(Tox *tox); @@ -264,6 +269,7 @@ void tox_callback_read_receipt(Tox *tox, void (*function)(Tox *tox, int, uint32_ /* Set the callback for connection status changes. * function(int friendnumber, uint8_t status) + * * Status: * 0 -- friend went offline after being previously online * 1 -- friend went online @@ -275,18 +281,19 @@ void tox_callback_read_receipt(Tox *tox, void (*function)(Tox *tox, int, uint32_ void tox_callback_connectionstatus(Tox *tox, void (*function)(Tox *tox, int, uint8_t, void *), void *userdata); /* Use this function to bootstrap the client. - * Sends a get nodes request to the given node with ip port and public_key. + * Sends a get nodes request to the given node with ip port and public_key. */ void tox_bootstrap(Tox *tox, tox_IP_Port ip_port, uint8_t *public_key); -/* returns 0 if we are not connected to the DHT. - * returns 1 if we are. +/* return 0 if we are not connected to the DHT. + * return 1 if we are. */ int tox_isconnected(Tox *tox); /* Run this at startup. - * returns allocated instance of tox on success. - * returns 0 if there are problems. + * + * return allocated instance of tox on success. + * return 0 if there are problems. */ Tox *tox_new(void); @@ -299,7 +306,7 @@ void tox_do(Tox *tox); /* SAVING AND LOADING FUNCTIONS: */ -/* returns the size of the messenger data (for saving). */ +/* return size of messenger data (for saving). */ uint32_t tox_size(Tox *tox); /* Save the messenger in data (must be allocated memory of size Messenger_size()). */ -- cgit v1.2.3