mirror of
https://github.com/irungentoo/toxcore.git
synced 2024-03-22 13:30:51 +08:00
last of the comment refactoring from toxcore
This commit is contained in:
JamoBox
parent
7b944e9c65
commit
61880ab938
|
|
@ -23,7 +23,7 @@
|
|||
|
||||
#include "network.h"
|
||||
|
||||
/* return current UNIX time in microseconds (us). */
|
||||
/* return current UNIX time in microseconds (us). */
|
||||
uint64_t current_time(void)
|
||||
{
|
||||
uint64_t time;
|
||||
|
|
@ -44,7 +44,7 @@ uint64_t current_time(void)
|
|||
#endif
|
||||
}
|
||||
|
||||
/* return a random number.
|
||||
/* return a random number.
|
||||
* NOTE: This function should probably not be used where cryptographic randomness is absolutely necessary.
|
||||
*/
|
||||
uint32_t random_int(void)
|
||||
|
|
@ -145,8 +145,8 @@ static void at_shutdown(void)
|
|||
* ip must be in network order EX: 127.0.0.1 = (7F000001).
|
||||
* port is in host byte order (this means don't worry about it).
|
||||
*
|
||||
* returns Networking_Core object if no problems
|
||||
* returns NULL if there are problems.
|
||||
* return Networking_Core object if no problems
|
||||
* return NULL if there are problems.
|
||||
*/
|
||||
Networking_Core *new_networking(IP ip, uint16_t port)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -123,10 +123,10 @@ typedef struct {
|
|||
int sock;
|
||||
} Networking_Core;
|
||||
|
||||
/* return current time in milleseconds since the epoch. */
|
||||
/* return current time in milleseconds since the epoch. */
|
||||
uint64_t current_time(void);
|
||||
|
||||
/* return a random number.
|
||||
/* return a random number.
|
||||
* NOTE: this function should probably not be used where cryptographic randomness is absolutely necessary.
|
||||
*/
|
||||
uint32_t random_int(void);
|
||||
|
|
@ -143,12 +143,12 @@ void networking_registerhandler(Networking_Core *net, uint8_t byte, packet_handl
|
|||
void networking_poll(Networking_Core *net);
|
||||
|
||||
/* Initialize networking.
|
||||
* bind to ip and port.
|
||||
* ip must be in network order EX: 127.0.0.1 = (7F000001).
|
||||
* port is in host byte order (this means don't worry about it).
|
||||
* bind to ip and port.
|
||||
* ip must be in network order EX: 127.0.0.1 = (7F000001).
|
||||
* port is in host byte order (this means don't worry about it).
|
||||
*
|
||||
* returns 0 if no problems.
|
||||
* returns -1 if there were problems.
|
||||
* return 0 if no problems.
|
||||
* return -1 if there were problems.
|
||||
*/
|
||||
Networking_Core *new_networking(IP ip, uint16_t port);
|
||||
|
||||
|
|
|
|||
|
|
@ -38,16 +38,17 @@ void tox_getaddress(void *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 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_UNKNOWN for unknown error.
|
||||
* 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.
|
||||
* 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_UNKNOWN for unknown error.
|
||||
* 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.
|
||||
*/
|
||||
int tox_addfriend(void *tox, uint8_t *address, uint8_t *data, uint16_t length)
|
||||
{
|
||||
|
|
@ -56,7 +57,8 @@ int tox_addfriend(void *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(void *tox, uint8_t *client_id)
|
||||
|
|
@ -65,8 +67,8 @@ int tox_addfriend_norequest(void *tox, uint8_t *client_id)
|
|||
return m_addfriend_norequest(m, client_id);
|
||||
}
|
||||
|
||||
/* return the friend id associated to that client id.
|
||||
* return -1 if no such friend.
|
||||
/* return the friend id associated to that client id.
|
||||
* return -1 if no such friend.
|
||||
*/
|
||||
int tox_getfriend_id(void *tox, uint8_t *client_id)
|
||||
{
|
||||
|
|
@ -75,7 +77,8 @@ int tox_getfriend_id(void *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.
|
||||
*/
|
||||
|
|
@ -92,11 +95,11 @@ int tox_delfriend(void *tox, int friendnumber)
|
|||
return m_delfriend(m, friendnumber);
|
||||
}
|
||||
|
||||
/* return 4 if friend is online.
|
||||
* return 3 if friend is confirmed.
|
||||
* return 2 if the friend request was sent.
|
||||
* return 1 if the friend was added.
|
||||
* return 0 if there is no friend with that number.
|
||||
/* return 4 if friend is online.
|
||||
* return 3 if friend is confirmed.
|
||||
* return 2 if the friend request was sent.
|
||||
* return 1 if the friend was added.
|
||||
* return 0 if there is no friend with that number.
|
||||
*/
|
||||
int tox_friendstatus(void *tox, int friendnumber)
|
||||
{
|
||||
|
|
@ -105,7 +108,7 @@ int tox_friendstatus(void *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 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
|
||||
|
|
@ -126,7 +129,7 @@ uint32_t tox_sendmessage_withid(void *tox, int friendnumber, uint32_t theid, uin
|
|||
}
|
||||
|
||||
/* 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(void *tox, int friendnumber, uint8_t *action, uint32_t length)
|
||||
|
|
@ -139,8 +142,9 @@ int tox_sendaction(void *tox, int friendnumber, uint8_t *action, uint32_t length
|
|||
* 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.
|
||||
*
|
||||
* return 0 if success.
|
||||
* return -1 if failure.
|
||||
*/
|
||||
int tox_setname(void *tox, uint8_t *name, uint16_t length)
|
||||
{
|
||||
|
|
@ -152,8 +156,9 @@ int tox_setname(void *tox, uint8_t *name, uint16_t length)
|
|||
* m - The messanger context to use.
|
||||
* name - Pointer to a string for the name.
|
||||
* nlen - The length of the string buffer.
|
||||
* return length of the name.
|
||||
* return 0 on error.
|
||||
*
|
||||
* return length of the name.
|
||||
* return 0 on error.
|
||||
*/
|
||||
uint16_t tox_getselfname(void *tox, uint8_t *name, uint16_t nlen)
|
||||
{
|
||||
|
|
@ -162,7 +167,8 @@ uint16_t tox_getselfname(void *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.
|
||||
*/
|
||||
|
|
@ -172,9 +178,11 @@ int tox_getname(void *tox, int friendnumber, uint8_t *name)
|
|||
return getname(m, friendnumber, name);
|
||||
}
|
||||
|
||||
/* set our user status
|
||||
you are responsible for freeing status after
|
||||
returns 0 on success, -1 on failure */
|
||||
/* Set our user status;
|
||||
* you are responsible for freeing status after.
|
||||
*
|
||||
* return 0 on success, -1 on failure.
|
||||
*/
|
||||
int tox_set_statusmessage(void *tox, uint8_t *status, uint16_t length)
|
||||
{
|
||||
Messenger *m = tox;
|
||||
|
|
@ -187,8 +195,8 @@ int tox_set_userstatus(void *tox, USERSTATUS status)
|
|||
return m_set_userstatus(m, 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(void *tox, int friendnumber)
|
||||
{
|
||||
|
|
@ -197,8 +205,8 @@ int tox_get_statusmessage_size(void *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(void *tox, int friendnumber, uint8_t *buf, uint32_t maxlen)
|
||||
{
|
||||
|
|
@ -317,6 +325,7 @@ void tox_callback_read_receipt(void *tox, void (*function)(Messenger *tox, int,
|
|||
|
||||
/* 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
|
||||
|
|
@ -332,7 +341,7 @@ void tox_callback_connectionstatus(void *tox, void (*function)(Messenger *tox, i
|
|||
}
|
||||
|
||||
/* 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(void *tox, IP_Port ip_port, uint8_t *public_key)
|
||||
{
|
||||
|
|
@ -340,8 +349,8 @@ void tox_bootstrap(void *tox, IP_Port ip_port, uint8_t *public_key)
|
|||
DHT_bootstrap(m->dht, ip_port, 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(void *tox)
|
||||
{
|
||||
|
|
@ -350,8 +359,9 @@ int tox_isconnected(void *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.
|
||||
*/
|
||||
void *tox_new(void)
|
||||
{
|
||||
|
|
@ -376,7 +386,7 @@ void tox_do(void *tox)
|
|||
|
||||
/* SAVING AND LOADING FUNCTIONS: */
|
||||
|
||||
/* returns the size of the messenger data (for saving). */
|
||||
/* return size of the messenger data (for saving). */
|
||||
uint32_t tox_size(void *tox)
|
||||
{
|
||||
Messenger *m = tox;
|
||||
|
|
|
|||
|
|
@ -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()). */
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user