diff options
author | JamoBox <petewicken@gmail.com> | 2013-09-02 17:25:28 +0100 |
---|---|---|
committer | JamoBox <petewicken@gmail.com> | 2013-09-02 17:25:28 +0100 |
commit | 61880ab9380f3a71ae1f51df7b6f4836059c041f (patch) | |
tree | e8e1912b43e03282283a8b4ccd420799226a5e88 /toxcore/tox.c | |
parent | 7b944e9c656f5bc9e0165db666db0a89963247c8 (diff) |
last of the comment refactoring from toxcore
Diffstat (limited to 'toxcore/tox.c')
-rw-r--r-- | toxcore/tox.c | 88 |
1 files changed, 49 insertions, 39 deletions
diff --git a/toxcore/tox.c b/toxcore/tox.c index 494de478..23ca6572 100644 --- a/toxcore/tox.c +++ b/toxcore/tox.c | |||
@@ -38,16 +38,17 @@ void tox_getaddress(void *tox, uint8_t *address) | |||
38 | * Set the data that will be sent along with friend request. | 38 | * Set the data that will be sent along with friend request. |
39 | * 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. | 39 | * 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. |
40 | * data is the data and length is the length. | 40 | * data is the data and length is the length. |
41 | * returns the friend number if success. | 41 | * |
42 | * return FA_TOOLONG if message length is too long. | 42 | * return the friend number if success. |
43 | * return FAERR_NOMESSAGE if no message (message length must be >= 1 byte). | 43 | * return FA_TOOLONG if message length is too long. |
44 | * return FAERR_OWNKEY if user's own key. | 44 | * return FAERR_NOMESSAGE if no message (message length must be >= 1 byte). |
45 | * return FAERR_ALREADYSENT if friend request already sent or already a friend. | 45 | * return FAERR_OWNKEY if user's own key. |
46 | * return FAERR_UNKNOWN for unknown error. | 46 | * return FAERR_ALREADYSENT if friend request already sent or already a friend. |
47 | * return FAERR_BADCHECKSUM if bad checksum in address. | 47 | * return FAERR_UNKNOWN for unknown error. |
48 | * return FAERR_SETNEWNOSPAM if the friend was already there but the nospam was different. | 48 | * return FAERR_BADCHECKSUM if bad checksum in address. |
49 | * (the nospam for that friend was set to the new one). | 49 | * return FAERR_SETNEWNOSPAM if the friend was already there but the nospam was different. |
50 | * return FAERR_NOMEM if increasing the friend list size fails. | 50 | * (the nospam for that friend was set to the new one). |
51 | * return FAERR_NOMEM if increasing the friend list size fails. | ||
51 | */ | 52 | */ |
52 | int tox_addfriend(void *tox, uint8_t *address, uint8_t *data, uint16_t length) | 53 | int tox_addfriend(void *tox, uint8_t *address, uint8_t *data, uint16_t length) |
53 | { | 54 | { |
@@ -56,7 +57,8 @@ int tox_addfriend(void *tox, uint8_t *address, uint8_t *data, uint16_t length) | |||
56 | } | 57 | } |
57 | 58 | ||
58 | /* Add a friend without sending a friendrequest. | 59 | /* Add a friend without sending a friendrequest. |
59 | * returns the friend number if success. | 60 | * |
61 | * return the friend number if success. | ||
60 | * return -1 if failure. | 62 | * return -1 if failure. |
61 | */ | 63 | */ |
62 | int tox_addfriend_norequest(void *tox, uint8_t *client_id) | 64 | int tox_addfriend_norequest(void *tox, uint8_t *client_id) |
@@ -65,8 +67,8 @@ int tox_addfriend_norequest(void *tox, uint8_t *client_id) | |||
65 | return m_addfriend_norequest(m, client_id); | 67 | return m_addfriend_norequest(m, client_id); |
66 | } | 68 | } |
67 | 69 | ||
68 | /* return the friend id associated to that client id. | 70 | /* return the friend id associated to that client id. |
69 | * return -1 if no such friend. | 71 | * return -1 if no such friend. |
70 | */ | 72 | */ |
71 | int tox_getfriend_id(void *tox, uint8_t *client_id) | 73 | int tox_getfriend_id(void *tox, uint8_t *client_id) |
72 | { | 74 | { |
@@ -75,7 +77,8 @@ int tox_getfriend_id(void *tox, uint8_t *client_id) | |||
75 | } | 77 | } |
76 | 78 | ||
77 | /* Copies the public key associated to that friend id into client_id buffer. | 79 | /* Copies the public key associated to that friend id into client_id buffer. |
78 | * Make sure that client_id is of size CLIENT_ID_SIZE. | 80 | * Make sure that client_id is of size CLIENT_ID_SIZE. |
81 | * | ||
79 | * return 0 if success. | 82 | * return 0 if success. |
80 | * return -1 if failure. | 83 | * return -1 if failure. |
81 | */ | 84 | */ |
@@ -92,11 +95,11 @@ int tox_delfriend(void *tox, int friendnumber) | |||
92 | return m_delfriend(m, friendnumber); | 95 | return m_delfriend(m, friendnumber); |
93 | } | 96 | } |
94 | 97 | ||
95 | /* return 4 if friend is online. | 98 | /* return 4 if friend is online. |
96 | * return 3 if friend is confirmed. | 99 | * return 3 if friend is confirmed. |
97 | * return 2 if the friend request was sent. | 100 | * return 2 if the friend request was sent. |
98 | * return 1 if the friend was added. | 101 | * return 1 if the friend was added. |
99 | * return 0 if there is no friend with that number. | 102 | * return 0 if there is no friend with that number. |
100 | */ | 103 | */ |
101 | int tox_friendstatus(void *tox, int friendnumber) | 104 | int tox_friendstatus(void *tox, int friendnumber) |
102 | { | 105 | { |
@@ -105,7 +108,7 @@ int tox_friendstatus(void *tox, int friendnumber) | |||
105 | } | 108 | } |
106 | 109 | ||
107 | /* Send a text chat message to an online friend. | 110 | /* Send a text chat message to an online friend. |
108 | * returns the message id if packet was successfully put into the send queue. | 111 | * return the message id if packet was successfully put into the send queue. |
109 | * return 0 if it was not. | 112 | * return 0 if it was not. |
110 | * | 113 | * |
111 | * You will want to retain the return value, it will be passed to your read receipt callback | 114 | * 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 | |||
126 | } | 129 | } |
127 | 130 | ||
128 | /* Send an action to an online friend. | 131 | /* Send an action to an online friend. |
129 | * returns 1 if packet was successfully put into the send queue. | 132 | * return 1 if packet was successfully put into the send queue. |
130 | * return 0 if it was not. | 133 | * return 0 if it was not. |
131 | */ | 134 | */ |
132 | int tox_sendaction(void *tox, int friendnumber, uint8_t *action, uint32_t length) | 135 | 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 | |||
139 | * name must be a string of maximum MAX_NAME_LENGTH length. | 142 | * name must be a string of maximum MAX_NAME_LENGTH length. |
140 | * length must be at least 1 byte. | 143 | * length must be at least 1 byte. |
141 | * length is the length of name with the NULL terminator. | 144 | * length is the length of name with the NULL terminator. |
142 | * return 0 if success. | 145 | * |
143 | * return -1 if failure. | 146 | * return 0 if success. |
147 | * return -1 if failure. | ||
144 | */ | 148 | */ |
145 | int tox_setname(void *tox, uint8_t *name, uint16_t length) | 149 | int tox_setname(void *tox, uint8_t *name, uint16_t length) |
146 | { | 150 | { |
@@ -152,8 +156,9 @@ int tox_setname(void *tox, uint8_t *name, uint16_t length) | |||
152 | * m - The messanger context to use. | 156 | * m - The messanger context to use. |
153 | * name - Pointer to a string for the name. | 157 | * name - Pointer to a string for the name. |
154 | * nlen - The length of the string buffer. | 158 | * nlen - The length of the string buffer. |
155 | * return length of the name. | 159 | * |
156 | * return 0 on error. | 160 | * return length of the name. |
161 | * return 0 on error. | ||
157 | */ | 162 | */ |
158 | uint16_t tox_getselfname(void *tox, uint8_t *name, uint16_t nlen) | 163 | uint16_t tox_getselfname(void *tox, uint8_t *name, uint16_t nlen) |
159 | { | 164 | { |
@@ -162,7 +167,8 @@ uint16_t tox_getselfname(void *tox, uint8_t *name, uint16_t nlen) | |||
162 | } | 167 | } |
163 | 168 | ||
164 | /* Get name of friendnumber and put it in name. | 169 | /* Get name of friendnumber and put it in name. |
165 | * name needs to be a valid memory location with a size of at least MAX_NAME_LENGTH (128) bytes. | 170 | * name needs to be a valid memory location with a size of at least MAX_NAME_LENGTH (128) bytes. |
171 | * | ||
166 | * return 0 if success. | 172 | * return 0 if success. |
167 | * return -1 if failure. | 173 | * return -1 if failure. |
168 | */ | 174 | */ |
@@ -172,9 +178,11 @@ int tox_getname(void *tox, int friendnumber, uint8_t *name) | |||
172 | return getname(m, friendnumber, name); | 178 | return getname(m, friendnumber, name); |
173 | } | 179 | } |
174 | 180 | ||
175 | /* set our user status | 181 | /* Set our user status; |
176 | you are responsible for freeing status after | 182 | * you are responsible for freeing status after. |
177 | returns 0 on success, -1 on failure */ | 183 | * |
184 | * return 0 on success, -1 on failure. | ||
185 | */ | ||
178 | int tox_set_statusmessage(void *tox, uint8_t *status, uint16_t length) | 186 | int tox_set_statusmessage(void *tox, uint8_t *status, uint16_t length) |
179 | { | 187 | { |
180 | Messenger *m = tox; | 188 | Messenger *m = tox; |
@@ -187,8 +195,8 @@ int tox_set_userstatus(void *tox, USERSTATUS status) | |||
187 | return m_set_userstatus(m, status); | 195 | return m_set_userstatus(m, status); |
188 | } | 196 | } |
189 | 197 | ||
190 | /* return the length of friendnumber's status message, including null. | 198 | /* return the length of friendnumber's status message, including null. |
191 | * Pass it into malloc. | 199 | * Pass it into malloc. |
192 | */ | 200 | */ |
193 | int tox_get_statusmessage_size(void *tox, int friendnumber) | 201 | int tox_get_statusmessage_size(void *tox, int friendnumber) |
194 | { | 202 | { |
@@ -197,8 +205,8 @@ int tox_get_statusmessage_size(void *tox, int friendnumber) | |||
197 | } | 205 | } |
198 | 206 | ||
199 | /* Copy friendnumber's status message into buf, truncating if size is over maxlen. | 207 | /* Copy friendnumber's status message into buf, truncating if size is over maxlen. |
200 | * Get the size you need to allocate from m_get_statusmessage_size. | 208 | * Get the size you need to allocate from m_get_statusmessage_size. |
201 | * The self variant will copy our own status message. | 209 | * The self variant will copy our own status message. |
202 | */ | 210 | */ |
203 | int tox_copy_statusmessage(void *tox, int friendnumber, uint8_t *buf, uint32_t maxlen) | 211 | int tox_copy_statusmessage(void *tox, int friendnumber, uint8_t *buf, uint32_t maxlen) |
204 | { | 212 | { |
@@ -317,6 +325,7 @@ void tox_callback_read_receipt(void *tox, void (*function)(Messenger *tox, int, | |||
317 | 325 | ||
318 | /* Set the callback for connection status changes. | 326 | /* Set the callback for connection status changes. |
319 | * function(int friendnumber, uint8_t status) | 327 | * function(int friendnumber, uint8_t status) |
328 | * | ||
320 | * Status: | 329 | * Status: |
321 | * 0 -- friend went offline after being previously online | 330 | * 0 -- friend went offline after being previously online |
322 | * 1 -- friend went online | 331 | * 1 -- friend went online |
@@ -332,7 +341,7 @@ void tox_callback_connectionstatus(void *tox, void (*function)(Messenger *tox, i | |||
332 | } | 341 | } |
333 | 342 | ||
334 | /* Use this function to bootstrap the client. | 343 | /* Use this function to bootstrap the client. |
335 | * Sends a get nodes request to the given node with ip port and public_key. | 344 | * Sends a get nodes request to the given node with ip port and public_key. |
336 | */ | 345 | */ |
337 | void tox_bootstrap(void *tox, IP_Port ip_port, uint8_t *public_key) | 346 | void tox_bootstrap(void *tox, IP_Port ip_port, uint8_t *public_key) |
338 | { | 347 | { |
@@ -340,8 +349,8 @@ void tox_bootstrap(void *tox, IP_Port ip_port, uint8_t *public_key) | |||
340 | DHT_bootstrap(m->dht, ip_port, public_key); | 349 | DHT_bootstrap(m->dht, ip_port, public_key); |
341 | } | 350 | } |
342 | 351 | ||
343 | /* returns 0 if we are not connected to the DHT. | 352 | /* return 0 if we are not connected to the DHT. |
344 | * returns 1 if we are. | 353 | * return 1 if we are. |
345 | */ | 354 | */ |
346 | int tox_isconnected(void *tox) | 355 | int tox_isconnected(void *tox) |
347 | { | 356 | { |
@@ -350,8 +359,9 @@ int tox_isconnected(void *tox) | |||
350 | } | 359 | } |
351 | 360 | ||
352 | /* Run this at startup. | 361 | /* Run this at startup. |
353 | * returns allocated instance of tox on success. | 362 | * |
354 | * returns 0 if there are problems. | 363 | * return allocated instance of tox on success. |
364 | * return 0 if there are problems. | ||
355 | */ | 365 | */ |
356 | void *tox_new(void) | 366 | void *tox_new(void) |
357 | { | 367 | { |
@@ -376,7 +386,7 @@ void tox_do(void *tox) | |||
376 | 386 | ||
377 | /* SAVING AND LOADING FUNCTIONS: */ | 387 | /* SAVING AND LOADING FUNCTIONS: */ |
378 | 388 | ||
379 | /* returns the size of the messenger data (for saving). */ | 389 | /* return size of the messenger data (for saving). */ |
380 | uint32_t tox_size(void *tox) | 390 | uint32_t tox_size(void *tox) |
381 | { | 391 | { |
382 | Messenger *m = tox; | 392 | Messenger *m = tox; |