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.h | |
parent | 7b944e9c656f5bc9e0165db666db0a89963247c8 (diff) |
last of the comment refactoring from toxcore
Diffstat (limited to 'toxcore/tox.h')
-rw-r--r-- | toxcore/tox.h | 79 |
1 files changed, 43 insertions, 36 deletions
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; | |||
86 | 86 | ||
87 | typedef void Tox; | 87 | typedef void Tox; |
88 | 88 | ||
89 | /* returns FRIEND_ADDRESS_SIZE byte address to give to others. | 89 | /* return FRIEND_ADDRESS_SIZE byte address to give to others. |
90 | * format: [client_id (32 bytes)][nospam number (4 bytes)][checksum (2 bytes)] | 90 | * format: [client_id (32 bytes)][nospam number (4 bytes)][checksum (2 bytes)] |
91 | */ | 91 | */ |
92 | void tox_getaddress(Tox *tox, uint8_t *address); | 92 | void tox_getaddress(Tox *tox, uint8_t *address); |
@@ -95,32 +95,33 @@ void tox_getaddress(Tox *tox, uint8_t *address); | |||
95 | * Set the data that will be sent along with friend request. | 95 | * Set the data that will be sent along with friend request. |
96 | * 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. | 96 | * 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. |
97 | * data is the data and length is the length. | 97 | * data is the data and length is the length. |
98 | * returns the friend number if success. | 98 | * |
99 | * return TOX_FA_TOOLONG if message length is too long. | 99 | * return the friend number if success. |
100 | * return TOX_FAERR_NOMESSAGE if no message (message length must be >= 1 byte). | 100 | * return TOX_FA_TOOLONG if message length is too long. |
101 | * return TOX_FAERR_OWNKEY if user's own key. | 101 | * return TOX_FAERR_NOMESSAGE if no message (message length must be >= 1 byte). |
102 | * return TOX_FAERR_ALREADYSENT if friend request already sent or already a friend. | 102 | * return TOX_FAERR_OWNKEY if user's own key. |
103 | * return TOX_FAERR_UNKNOWN for unknown error. | 103 | * return TOX_FAERR_ALREADYSENT if friend request already sent or already a friend. |
104 | * return TOX_FAERR_BADCHECKSUM if bad checksum in address. | 104 | * return TOX_FAERR_UNKNOWN for unknown error. |
105 | * return TOX_FAERR_SETNEWNOSPAM if the friend was already there but the nospam was different. | 105 | * return TOX_FAERR_BADCHECKSUM if bad checksum in address. |
106 | * (the nospam for that friend was set to the new one). | 106 | * return TOX_FAERR_SETNEWNOSPAM if the friend was already there but the nospam was different. |
107 | * return TOX_FAERR_NOMEM if increasing the friend list size fails. | 107 | * (the nospam for that friend was set to the new one). |
108 | * return TOX_FAERR_NOMEM if increasing the friend list size fails. | ||
108 | */ | 109 | */ |
109 | int tox_addfriend(Tox *tox, uint8_t *address, uint8_t *data, uint16_t length); | 110 | int tox_addfriend(Tox *tox, uint8_t *address, uint8_t *data, uint16_t length); |
110 | 111 | ||
111 | 112 | ||
112 | /* Add a friend without sending a friendrequest. | 113 | /* Add a friend without sending a friendrequest. |
113 | * returns the friend number if success. | 114 | * return the friend number if success. |
114 | * return -1 if failure. | 115 | * return -1 if failure. |
115 | */ | 116 | */ |
116 | int tox_addfriend_norequest(Tox *tox, uint8_t *client_id); | 117 | int tox_addfriend_norequest(Tox *tox, uint8_t *client_id); |
117 | 118 | ||
118 | /* return the friend id associated to that client id. | 119 | /* return the friend id associated to that client id. |
119 | return -1 if no such friend */ | 120 | return -1 if no such friend */ |
120 | int tox_getfriend_id(Tox *tox, uint8_t *client_id); | 121 | int tox_getfriend_id(Tox *tox, uint8_t *client_id); |
121 | 122 | ||
122 | /* Copies the public key associated to that friend id into client_id buffer. | 123 | /* Copies the public key associated to that friend id into client_id buffer. |
123 | * Make sure that client_id is of size CLIENT_ID_SIZE. | 124 | * Make sure that client_id is of size CLIENT_ID_SIZE. |
124 | * return 0 if success. | 125 | * return 0 if success. |
125 | * return -1 if failure. | 126 | * return -1 if failure. |
126 | */ | 127 | */ |
@@ -138,8 +139,9 @@ int tox_delfriend(Tox *tox, int friendnumber); | |||
138 | int tox_friendstatus(Tox *tox, int friendnumber); | 139 | int tox_friendstatus(Tox *tox, int friendnumber); |
139 | 140 | ||
140 | /* Send a text chat message to an online friend. | 141 | /* Send a text chat message to an online friend. |
141 | * returns the message id if packet was successfully put into the send queue. | 142 | * |
142 | * return 0 if it was not. | 143 | * return the message id if packet was successfully put into the send queue. |
144 | * return 0 if it was not. | ||
143 | * | 145 | * |
144 | * You will want to retain the return value, it will be passed to your read receipt callback | 146 | * You will want to retain the return value, it will be passed to your read receipt callback |
145 | * if one is received. | 147 | * if one is received. |
@@ -150,7 +152,8 @@ uint32_t tox_sendmessage(Tox *tox, int friendnumber, uint8_t *message, uint32_t | |||
150 | uint32_t tox_sendmessage_withid(Tox *tox, int friendnumber, uint32_t theid, uint8_t *message, uint32_t length); | 152 | uint32_t tox_sendmessage_withid(Tox *tox, int friendnumber, uint32_t theid, uint8_t *message, uint32_t length); |
151 | 153 | ||
152 | /* Send an action to an online friend. | 154 | /* Send an action to an online friend. |
153 | * returns 1 if packet was successfully put into the send queue. | 155 | * |
156 | * return 1 if packet was successfully put into the send queue. | ||
154 | * return 0 if it was not. | 157 | * return 0 if it was not. |
155 | */ | 158 | */ |
156 | int tox_sendaction(Tox *tox, int friendnumber, uint8_t *action, uint32_t length); | 159 | 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) | |||
160 | * length must be at least 1 byte. | 163 | * length must be at least 1 byte. |
161 | * length is the length of name with the NULL terminator. | 164 | * length is the length of name with the NULL terminator. |
162 | * | 165 | * |
163 | * return 0 if success. | 166 | * return 0 if success. |
164 | * return -1 if failure. | 167 | * return -1 if failure. |
165 | */ | 168 | */ |
166 | int tox_setname(Tox *tox, uint8_t *name, uint16_t length); | 169 | int tox_setname(Tox *tox, uint8_t *name, uint16_t length); |
167 | 170 | ||
@@ -171,12 +174,13 @@ int tox_setname(Tox *tox, uint8_t *name, uint16_t length); | |||
171 | * name - Pointer to a string for the name. | 174 | * name - Pointer to a string for the name. |
172 | * nlen - The length of the string buffer. | 175 | * nlen - The length of the string buffer. |
173 | * | 176 | * |
174 | * returns Return the length of the name, 0 on error. | 177 | * return length of name. |
178 | * return 0 on error. | ||
175 | */ | 179 | */ |
176 | uint16_t tox_getselfname(Tox *tox, uint8_t *name, uint16_t nlen); | 180 | uint16_t tox_getselfname(Tox *tox, uint8_t *name, uint16_t nlen); |
177 | 181 | ||
178 | /* Get name of friendnumber and put it in name. | 182 | /* Get name of friendnumber and put it in name. |
179 | * name needs to be a valid memory location with a size of at least MAX_NAME_LENGTH (128) bytes. | 183 | * name needs to be a valid memory location with a size of at least MAX_NAME_LENGTH (128) bytes. |
180 | * | 184 | * |
181 | * return 0 if success. | 185 | * return 0 if success. |
182 | * return -1 if failure. | 186 | * return -1 if failure. |
@@ -184,29 +188,30 @@ uint16_t tox_getselfname(Tox *tox, uint8_t *name, uint16_t nlen); | |||
184 | int tox_getname(Tox *tox, int friendnumber, uint8_t *name); | 188 | int tox_getname(Tox *tox, int friendnumber, uint8_t *name); |
185 | 189 | ||
186 | /* Set our user status. | 190 | /* Set our user status. |
187 | * You are responsible for freeing status after. | 191 | * You are responsible for freeing status after. |
192 | * | ||
188 | * returns 0 on success. | 193 | * returns 0 on success. |
189 | * returns -1 on failure. | 194 | * returns -1 on failure. |
190 | */ | 195 | */ |
191 | int tox_set_statusmessage(Tox *tox, uint8_t *status, uint16_t length); | 196 | int tox_set_statusmessage(Tox *tox, uint8_t *status, uint16_t length); |
192 | int tox_set_userstatus(Tox *tox, TOX_USERSTATUS status); | 197 | int tox_set_userstatus(Tox *tox, TOX_USERSTATUS status); |
193 | 198 | ||
194 | /* return the length of friendnumber's status message, including null. | 199 | /* return the length of friendnumber's status message, including null. |
195 | * Pass it into malloc | 200 | * Pass it into malloc |
196 | */ | 201 | */ |
197 | int tox_get_statusmessage_size(Tox *tox, int friendnumber); | 202 | int tox_get_statusmessage_size(Tox *tox, int friendnumber); |
198 | 203 | ||
199 | /* Copy friendnumber's status message into buf, truncating if size is over maxlen. | 204 | /* 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. | 205 | * Get the size you need to allocate from m_get_statusmessage_size. |
201 | * The self variant will copy our own status message. | 206 | * The self variant will copy our own status message. |
202 | */ | 207 | */ |
203 | int tox_copy_statusmessage(Tox *tox, int friendnumber, uint8_t *buf, uint32_t maxlen); | 208 | int tox_copy_statusmessage(Tox *tox, int friendnumber, uint8_t *buf, uint32_t maxlen); |
204 | int tox_copy_self_statusmessage(Tox *tox, uint8_t *buf, uint32_t maxlen); | 209 | int tox_copy_self_statusmessage(Tox *tox, uint8_t *buf, uint32_t maxlen); |
205 | 210 | ||
206 | /* return one of USERSTATUS values. | 211 | /* return one of USERSTATUS values. |
207 | * Values unknown to your application should be represented as USERSTATUS_NONE. | 212 | * Values unknown to your application should be represented as USERSTATUS_NONE. |
208 | * As above, the self variant will return our own USERSTATUS. | 213 | * As above, the self variant will return our own USERSTATUS. |
209 | * If friendnumber is invalid, this shall return USERSTATUS_INVALID. | 214 | * If friendnumber is invalid, this shall return USERSTATUS_INVALID. |
210 | */ | 215 | */ |
211 | TOX_USERSTATUS tox_get_userstatus(Tox *tox, int friendnumber); | 216 | TOX_USERSTATUS tox_get_userstatus(Tox *tox, int friendnumber); |
212 | TOX_USERSTATUS tox_get_selfuserstatus(Tox *tox); | 217 | TOX_USERSTATUS tox_get_selfuserstatus(Tox *tox); |
@@ -264,6 +269,7 @@ void tox_callback_read_receipt(Tox *tox, void (*function)(Tox *tox, int, uint32_ | |||
264 | 269 | ||
265 | /* Set the callback for connection status changes. | 270 | /* Set the callback for connection status changes. |
266 | * function(int friendnumber, uint8_t status) | 271 | * function(int friendnumber, uint8_t status) |
272 | * | ||
267 | * Status: | 273 | * Status: |
268 | * 0 -- friend went offline after being previously online | 274 | * 0 -- friend went offline after being previously online |
269 | * 1 -- friend went online | 275 | * 1 -- friend went online |
@@ -275,18 +281,19 @@ void tox_callback_read_receipt(Tox *tox, void (*function)(Tox *tox, int, uint32_ | |||
275 | void tox_callback_connectionstatus(Tox *tox, void (*function)(Tox *tox, int, uint8_t, void *), void *userdata); | 281 | void tox_callback_connectionstatus(Tox *tox, void (*function)(Tox *tox, int, uint8_t, void *), void *userdata); |
276 | 282 | ||
277 | /* Use this function to bootstrap the client. | 283 | /* Use this function to bootstrap the client. |
278 | * Sends a get nodes request to the given node with ip port and public_key. | 284 | * Sends a get nodes request to the given node with ip port and public_key. |
279 | */ | 285 | */ |
280 | void tox_bootstrap(Tox *tox, tox_IP_Port ip_port, uint8_t *public_key); | 286 | void tox_bootstrap(Tox *tox, tox_IP_Port ip_port, uint8_t *public_key); |
281 | 287 | ||
282 | /* returns 0 if we are not connected to the DHT. | 288 | /* return 0 if we are not connected to the DHT. |
283 | * returns 1 if we are. | 289 | * return 1 if we are. |
284 | */ | 290 | */ |
285 | int tox_isconnected(Tox *tox); | 291 | int tox_isconnected(Tox *tox); |
286 | 292 | ||
287 | /* Run this at startup. | 293 | /* Run this at startup. |
288 | * returns allocated instance of tox on success. | 294 | * |
289 | * returns 0 if there are problems. | 295 | * return allocated instance of tox on success. |
296 | * return 0 if there are problems. | ||
290 | */ | 297 | */ |
291 | Tox *tox_new(void); | 298 | Tox *tox_new(void); |
292 | 299 | ||
@@ -299,7 +306,7 @@ void tox_do(Tox *tox); | |||
299 | 306 | ||
300 | /* SAVING AND LOADING FUNCTIONS: */ | 307 | /* SAVING AND LOADING FUNCTIONS: */ |
301 | 308 | ||
302 | /* returns the size of the messenger data (for saving). */ | 309 | /* return size of messenger data (for saving). */ |
303 | uint32_t tox_size(Tox *tox); | 310 | uint32_t tox_size(Tox *tox); |
304 | 311 | ||
305 | /* Save the messenger in data (must be allocated memory of size Messenger_size()). */ | 312 | /* Save the messenger in data (must be allocated memory of size Messenger_size()). */ |