diff options
Diffstat (limited to 'toxcore/tox.h')
-rw-r--r-- | toxcore/tox.h | 261 |
1 files changed, 144 insertions, 117 deletions
diff --git a/toxcore/tox.h b/toxcore/tox.h index bdfac1d6..5a4dcf49 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h | |||
@@ -46,11 +46,11 @@ typedef union { | |||
46 | typedef struct { | 46 | typedef struct { |
47 | tox_IP ip; | 47 | tox_IP ip; |
48 | uint16_t port; | 48 | uint16_t port; |
49 | /* not used for anything right now */ | 49 | /* Not used for anything right now. */ |
50 | uint16_t padding; | 50 | uint16_t padding; |
51 | } tox_IP_Port; | 51 | } tox_IP_Port; |
52 | 52 | ||
53 | /* status definitions */ | 53 | /* Status definitions. */ |
54 | enum { | 54 | enum { |
55 | TOX_NOFRIEND, | 55 | TOX_NOFRIEND, |
56 | TOX_FRIEND_ADDED, | 56 | TOX_FRIEND_ADDED, |
@@ -59,8 +59,9 @@ enum { | |||
59 | TOX_FRIEND_ONLINE, | 59 | TOX_FRIEND_ONLINE, |
60 | }; | 60 | }; |
61 | 61 | ||
62 | /* errors for m_addfriend | 62 | /* Errors for m_addfriend |
63 | * FAERR - Friend Add Error */ | 63 | * FAERR - Friend Add Error |
64 | */ | ||
64 | enum { | 65 | enum { |
65 | TOX_FAERR_TOOLONG = -1, | 66 | TOX_FAERR_TOOLONG = -1, |
66 | TOX_FAERR_NOMESSAGE = -2, | 67 | TOX_FAERR_NOMESSAGE = -2, |
@@ -71,9 +72,10 @@ enum { | |||
71 | TOX_FAERR_SETNEWNOSPAM = -7, | 72 | TOX_FAERR_SETNEWNOSPAM = -7, |
72 | TOX_FAERR_NOMEM = -8 | 73 | TOX_FAERR_NOMEM = -8 |
73 | }; | 74 | }; |
74 | /* USERSTATUS | ||
75 | * Represents userstatuses someone can have. */ | ||
76 | 75 | ||
76 | /* USERSTATUS - | ||
77 | * Represents userstatuses someone can have. | ||
78 | */ | ||
77 | typedef enum { | 79 | typedef enum { |
78 | TOX_USERSTATUS_NONE, | 80 | TOX_USERSTATUS_NONE, |
79 | TOX_USERSTATUS_AWAY, | 81 | TOX_USERSTATUS_AWAY, |
@@ -84,201 +86,226 @@ TOX_USERSTATUS; | |||
84 | 86 | ||
85 | typedef void Tox; | 87 | typedef void Tox; |
86 | 88 | ||
87 | /* | 89 | /* returns FRIEND_ADDRESS_SIZE byte address to give to others. |
88 | * returns a FRIEND_ADDRESS_SIZE byte address to give to others. | ||
89 | * 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)] |
90 | * | ||
91 | */ | 91 | */ |
92 | void tox_getaddress(Tox *tox, uint8_t *address); | 92 | void tox_getaddress(Tox *tox, uint8_t *address); |
93 | 93 | ||
94 | /* | 94 | /* Add a friend. |
95 | * add a friend | 95 | * Set the data that will be sent along with friend request. |
96 | * set the data that will be sent along with friend request | ||
97 | * 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. |
98 | * data is the data and length is the length | 97 | * data is the data and length is the length. |
99 | * returns the friend number if success | 98 | * returns the friend number if success. |
100 | * return TOX_FA_TOOLONG if message length is too long | 99 | * return TOX_FA_TOOLONG if message length is too long. |
101 | * return TOX_FAERR_NOMESSAGE if no message (message length must be >= 1 byte) | 100 | * return TOX_FAERR_NOMESSAGE if no message (message length must be >= 1 byte). |
102 | * return TOX_FAERR_OWNKEY if user's own key | 101 | * return TOX_FAERR_OWNKEY if user's own key. |
103 | * return TOX_FAERR_ALREADYSENT if friend request already sent or already a friend | 102 | * return TOX_FAERR_ALREADYSENT if friend request already sent or already a friend. |
104 | * return TOX_FAERR_UNKNOWN for unknown error | 103 | * return TOX_FAERR_UNKNOWN for unknown error. |
105 | * return TOX_FAERR_BADCHECKSUM if bad checksum in address | 104 | * return TOX_FAERR_BADCHECKSUM if bad checksum in address. |
106 | * return TOX_FAERR_SETNEWNOSPAM if the friend was already there but the nospam was different | 105 | * return TOX_FAERR_SETNEWNOSPAM if the friend was already there but the nospam was different. |
107 | * (the nospam for that friend was set to the new one) | 106 | * (the nospam for that friend was set to the new one). |
108 | * return TOX_FAERR_NOMEM if increasing the friend list size fails | 107 | * return TOX_FAERR_NOMEM if increasing the friend list size fails. |
109 | */ | 108 | */ |
110 | int tox_addfriend(Tox *tox, uint8_t *address, uint8_t *data, uint16_t length); | 109 | int tox_addfriend(Tox *tox, uint8_t *address, uint8_t *data, uint16_t length); |
111 | 110 | ||
112 | 111 | ||
113 | /* add a friend without sending a friendrequest. | 112 | /* Add a friend without sending a friendrequest. |
114 | returns the friend number if success | 113 | * returns the friend number if success. |
115 | return -1 if failure. */ | 114 | * return -1 if failure. |
115 | */ | ||
116 | int tox_addfriend_norequest(Tox *tox, uint8_t *client_id); | 116 | int tox_addfriend_norequest(Tox *tox, uint8_t *client_id); |
117 | 117 | ||
118 | /* return the friend id associated to that client id. | 118 | /* return the friend id associated to that client id. |
119 | return -1 if no such friend */ | 119 | return -1 if no such friend */ |
120 | int tox_getfriend_id(Tox *tox, uint8_t *client_id); | 120 | int tox_getfriend_id(Tox *tox, uint8_t *client_id); |
121 | 121 | ||
122 | /* copies the public key associated to that friend id into client_id buffer. | 122 | /* 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. | 123 | * Make sure that client_id is of size CLIENT_ID_SIZE. |
124 | return 0 if success | 124 | * return 0 if success. |
125 | return -1 if failure */ | 125 | * return -1 if failure. |
126 | */ | ||
126 | int tox_getclient_id(Tox *tox, int friend_id, uint8_t *client_id); | 127 | int tox_getclient_id(Tox *tox, int friend_id, uint8_t *client_id); |
127 | 128 | ||
128 | /* remove a friend */ | 129 | /* Remove a friend. */ |
129 | int tox_delfriend(Tox *tox, int friendnumber); | 130 | int tox_delfriend(Tox *tox, int friendnumber); |
130 | 131 | ||
131 | /* return TOX_FRIEND_ONLINE if friend is online | 132 | /* return TOX_FRIEND_ONLINE if friend is online. |
132 | return TOX_FRIEND_CONFIRMED if friend is confirmed | 133 | * return TOX_FRIEND_CONFIRMED if friend is confirmed. |
133 | return TOX_FRIEND_REQUESTED if the friend request was sent | 134 | * return TOX_FRIEND_REQUESTED if the friend request was sent. |
134 | return TOX_FRIEND_ADDED if the friend was added | 135 | * return TOX_FRIEND_ADDED if the friend was added. |
135 | return TOX_NOFRIEND if there is no friend with that number */ | 136 | * return TOX_NOFRIEND if there is no friend with that number. |
137 | */ | ||
136 | int tox_friendstatus(Tox *tox, int friendnumber); | 138 | int tox_friendstatus(Tox *tox, int friendnumber); |
137 | 139 | ||
138 | /* send a text chat message to an online friend | 140 | /* Send a text chat message to an online friend. |
139 | returns the message id if packet was successfully put into the send queue | 141 | * returns the message id if packet was successfully put into the send queue. |
140 | return 0 if it was not | 142 | * return 0 if it was not. |
141 | you will want to retain the return value, it will be passed to your read receipt callback | 143 | * |
142 | if one is received. | 144 | * You will want to retain the return value, it will be passed to your read receipt callback |
143 | m_sendmessage_withid will send a message with the id of your choosing, | 145 | * if one is received. |
144 | however we can generate an id for you by calling plain m_sendmessage. */ | 146 | * m_sendmessage_withid will send a message with the id of your choosing, |
147 | * however we can generate an id for you by calling plain m_sendmessage. | ||
148 | */ | ||
145 | uint32_t tox_sendmessage(Tox *tox, int friendnumber, uint8_t *message, uint32_t length); | 149 | uint32_t tox_sendmessage(Tox *tox, int friendnumber, uint8_t *message, uint32_t length); |
146 | uint32_t tox_sendmessage_withid(Tox *tox, int friendnumber, uint32_t theid, uint8_t *message, uint32_t length); | 150 | uint32_t tox_sendmessage_withid(Tox *tox, int friendnumber, uint32_t theid, uint8_t *message, uint32_t length); |
147 | 151 | ||
148 | /* send an action to an online friend | 152 | /* Send an action to an online friend. |
149 | returns 1 if packet was successfully put into the send queue | 153 | * returns 1 if packet was successfully put into the send queue. |
150 | return 0 if it was not */ | 154 | * return 0 if it was not. |
155 | */ | ||
151 | int tox_sendaction(Tox *tox, int friendnumber, uint8_t *action, uint32_t length); | 156 | int tox_sendaction(Tox *tox, int friendnumber, uint8_t *action, uint32_t length); |
152 | 157 | ||
153 | /* Set our nickname | 158 | /* Set our nickname. |
154 | name must be a string of maximum MAX_NAME_LENGTH length. | 159 | * name must be a string of maximum MAX_NAME_LENGTH length. |
155 | length must be at least 1 byte | 160 | * length must be at least 1 byte. |
156 | length is the length of name with the NULL terminator | 161 | * length is the length of name with the NULL terminator. |
157 | return 0 if success | 162 | * |
158 | return -1 if failure */ | 163 | * return 0 if success. |
164 | * return -1 if failure. | ||
165 | */ | ||
159 | int tox_setname(Tox *tox, uint8_t *name, uint16_t length); | 166 | int tox_setname(Tox *tox, uint8_t *name, uint16_t length); |
160 | 167 | ||
161 | /* | 168 | /* |
162 | Get your nickname. | 169 | * Get your nickname. |
163 | m The messanger context to use. | 170 | * m - The messanger context to use. |
164 | name Pointer to a string for the name. | 171 | * name - Pointer to a string for the name. |
165 | nlen The length of the string buffer. | 172 | * nlen - The length of the string buffer. |
166 | returns Return the length of the name, 0 on error. | 173 | * |
167 | */ | 174 | * returns Return the length of the name, 0 on error. |
175 | */ | ||
168 | uint16_t tox_getselfname(Tox *tox, uint8_t *name, uint16_t nlen); | 176 | uint16_t tox_getselfname(Tox *tox, uint8_t *name, uint16_t nlen); |
169 | 177 | ||
170 | /* get name of friendnumber | 178 | /* Get name of friendnumber and put it in name. |
171 | put it in name | 179 | * name needs to be a valid memory location with a size of at least MAX_NAME_LENGTH (128) bytes. |
172 | name needs to be a valid memory location with a size of at least MAX_NAME_LENGTH (128) bytes. | 180 | * |
173 | return 0 if success | 181 | * return 0 if success. |
174 | return -1 if failure */ | 182 | * return -1 if failure. |
183 | */ | ||
175 | int tox_getname(Tox *tox, int friendnumber, uint8_t *name); | 184 | int tox_getname(Tox *tox, int friendnumber, uint8_t *name); |
176 | 185 | ||
177 | /* set our user status | 186 | /* Set our user status. |
178 | you are responsible for freeing status after | 187 | * You are responsible for freeing status after. |
179 | returns 0 on success, -1 on failure */ | 188 | * returns 0 on success. |
189 | * returns -1 on failure. | ||
190 | */ | ||
180 | int tox_set_statusmessage(Tox *tox, uint8_t *status, uint16_t length); | 191 | int tox_set_statusmessage(Tox *tox, uint8_t *status, uint16_t length); |
181 | int tox_set_userstatus(Tox *tox, TOX_USERSTATUS status); | 192 | int tox_set_userstatus(Tox *tox, TOX_USERSTATUS status); |
182 | 193 | ||
183 | /* return the length of friendnumber's status message, | 194 | /* return the length of friendnumber's status message, including null. |
184 | including null | 195 | * Pass it into malloc |
185 | pass it into malloc */ | 196 | */ |
186 | int tox_get_statusmessage_size(Tox *tox, int friendnumber); | 197 | int tox_get_statusmessage_size(Tox *tox, int friendnumber); |
187 | 198 | ||
188 | /* copy friendnumber's status message into buf, truncating if size is over maxlen | 199 | /* Copy friendnumber's status message into buf, truncating if size is over maxlen. |
189 | get the size you need to allocate from m_get_statusmessage_size | 200 | * Get the size you need to allocate from m_get_statusmessage_size. |
190 | The self variant will copy our own status message. */ | 201 | * The self variant will copy our own status message. |
202 | */ | ||
191 | int tox_copy_statusmessage(Tox *tox, int friendnumber, uint8_t *buf, uint32_t maxlen); | 203 | int tox_copy_statusmessage(Tox *tox, int friendnumber, uint8_t *buf, uint32_t maxlen); |
192 | int tox_copy_self_statusmessage(Tox *tox, uint8_t *buf, uint32_t maxlen); | 204 | int tox_copy_self_statusmessage(Tox *tox, uint8_t *buf, uint32_t maxlen); |
193 | 205 | ||
194 | /* Return one of USERSTATUS values. | 206 | /* return one of USERSTATUS values. |
195 | * Values unknown to your application should be represented as USERSTATUS_NONE. | 207 | * Values unknown to your application should be represented as USERSTATUS_NONE. |
196 | * As above, the self variant will return our own USERSTATUS. | 208 | * As above, the self variant will return our own USERSTATUS. |
197 | * If friendnumber is invalid, this shall return USERSTATUS_INVALID. */ | 209 | * If friendnumber is invalid, this shall return USERSTATUS_INVALID. |
210 | */ | ||
198 | TOX_USERSTATUS tox_get_userstatus(Tox *tox, int friendnumber); | 211 | TOX_USERSTATUS tox_get_userstatus(Tox *tox, int friendnumber); |
199 | TOX_USERSTATUS tox_get_selfuserstatus(Tox *tox); | 212 | TOX_USERSTATUS tox_get_selfuserstatus(Tox *tox); |
200 | 213 | ||
201 | /* Sets whether we send read receipts for friendnumber. | 214 | /* Sets whether we send read receipts for friendnumber. |
202 | * This function is not lazy, and it will fail if yesno is not (0 or 1).*/ | 215 | * This function is not lazy, and it will fail if yesno is not (0 or 1). |
216 | */ | ||
203 | void tox_set_sends_receipts(Tox *tox, int friendnumber, int yesno); | 217 | void tox_set_sends_receipts(Tox *tox, int friendnumber, int yesno); |
204 | 218 | ||
205 | /* set the function that will be executed when a friend request is received. | 219 | /* Set the function that will be executed when a friend request is received. |
206 | function format is function(uint8_t * public_key, uint8_t * data, uint16_t length) */ | 220 | * Function format is function(uint8_t * public_key, uint8_t * data, uint16_t length) |
221 | */ | ||
207 | void tox_callback_friendrequest(Tox *tox, void (*function)(uint8_t *, uint8_t *, uint16_t, void *), void *userdata); | 222 | void tox_callback_friendrequest(Tox *tox, void (*function)(uint8_t *, uint8_t *, uint16_t, void *), void *userdata); |
208 | 223 | ||
209 | /* set the function that will be executed when a message from a friend is received. | 224 | /* Set the function that will be executed when a message from a friend is received. |
210 | function format is: function(int friendnumber, uint8_t * message, uint32_t length) */ | 225 | * Function format is: function(int friendnumber, uint8_t * message, uint32_t length) |
226 | */ | ||
211 | void tox_callback_friendmessage(Tox *tox, void (*function)(Tox *tox, int, uint8_t *, uint16_t, void *), | 227 | void tox_callback_friendmessage(Tox *tox, void (*function)(Tox *tox, int, uint8_t *, uint16_t, void *), |
212 | void *userdata); | 228 | void *userdata); |
213 | 229 | ||
214 | /* set the function that will be executed when an action from a friend is received. | 230 | /* Set the function that will be executed when an action from a friend is received. |
215 | function format is: function(int friendnumber, uint8_t * action, uint32_t length) */ | 231 | * Function format is: function(int friendnumber, uint8_t * action, uint32_t length) |
232 | */ | ||
216 | void tox_callback_action(Tox *tox, void (*function)(Tox *tox, int, uint8_t *, uint16_t, void *), void *userdata); | 233 | void tox_callback_action(Tox *tox, void (*function)(Tox *tox, int, uint8_t *, uint16_t, void *), void *userdata); |
217 | 234 | ||
218 | /* set the callback for name changes | 235 | /* Set the callback for name changes. |
219 | function(int friendnumber, uint8_t *newname, uint16_t length) | 236 | * function(int friendnumber, uint8_t *newname, uint16_t length) |
220 | you are not responsible for freeing newname */ | 237 | * You are not responsible for freeing newname |
238 | */ | ||
221 | void tox_callback_namechange(Tox *tox, void (*function)(Tox *tox, int, uint8_t *, uint16_t, void *), | 239 | void tox_callback_namechange(Tox *tox, void (*function)(Tox *tox, int, uint8_t *, uint16_t, void *), |
222 | void *userdata); | 240 | void *userdata); |
223 | 241 | ||
224 | /* set the callback for status message changes | 242 | /* Set the callback for status message changes. |
225 | function(int friendnumber, uint8_t *newstatus, uint16_t length) | 243 | * function(int friendnumber, uint8_t *newstatus, uint16_t length) |
226 | you are not responsible for freeing newstatus */ | 244 | * You are not responsible for freeing newstatus. |
245 | */ | ||
227 | void tox_callback_statusmessage(Tox *tox, void (*function)(Tox *tox, int, uint8_t *, uint16_t, void *), | 246 | void tox_callback_statusmessage(Tox *tox, void (*function)(Tox *tox, int, uint8_t *, uint16_t, void *), |
228 | void *userdata); | 247 | void *userdata); |
229 | 248 | ||
230 | /* set the callback for status type changes | 249 | /* Set the callback for status type changes. |
231 | function(int friendnumber, USERSTATUS kind) */ | 250 | * function(int friendnumber, USERSTATUS kind) |
251 | */ | ||
232 | void tox_callback_userstatus(Tox *tox, void (*function)(Tox *tox, int, TOX_USERSTATUS, void *), void *userdata); | 252 | void tox_callback_userstatus(Tox *tox, void (*function)(Tox *tox, int, TOX_USERSTATUS, void *), void *userdata); |
233 | 253 | ||
234 | /* set the callback for read receipts | 254 | /* Set the callback for read receipts. |
235 | function(int friendnumber, uint32_t receipt) | 255 | * function(int friendnumber, uint32_t receipt) |
236 | if you are keeping a record of returns from m_sendmessage, | 256 | * |
237 | receipt might be one of those values, and that means the message | 257 | * If you are keeping a record of returns from m_sendmessage; |
238 | has been received on the other side. since core doesn't | 258 | * receipt might be one of those values, meaning the message |
239 | track ids for you, receipt may not correspond to any message | 259 | * has been received on the other side. |
240 | in that case, you should discard it. */ | 260 | * Since core doesn't track ids for you, receipt may not correspond to any message. |
261 | * In that case, you should discard it. | ||
262 | */ | ||
241 | void tox_callback_read_receipt(Tox *tox, void (*function)(Tox *tox, int, uint32_t, void *), void *userdata); | 263 | void tox_callback_read_receipt(Tox *tox, void (*function)(Tox *tox, int, uint32_t, void *), void *userdata); |
242 | 264 | ||
243 | /* set the callback for connection status changes | 265 | /* Set the callback for connection status changes. |
244 | function(int friendnumber, uint8_t status) | 266 | * function(int friendnumber, uint8_t status) |
245 | status: | 267 | * Status: |
246 | 0 -- friend went offline after being previously online | 268 | * 0 -- friend went offline after being previously online |
247 | 1 -- friend went online | 269 | * 1 -- friend went online |
248 | note that this callback is not called when adding friends, thus the "after | 270 | * |
249 | being previously online" part. it's assumed that when adding friends, | 271 | * NOTE: This callback is not called when adding friends, thus the "after |
250 | their connection status is offline. */ | 272 | * being previously online" part. it's assumed that when adding friends, |
273 | * their connection status is offline. | ||
274 | */ | ||
251 | void tox_callback_connectionstatus(Tox *tox, void (*function)(Tox *tox, int, uint8_t, void *), void *userdata); | 275 | void tox_callback_connectionstatus(Tox *tox, void (*function)(Tox *tox, int, uint8_t, void *), void *userdata); |
252 | 276 | ||
253 | /* Use this function to bootstrap the client | 277 | /* Use this function to bootstrap the client. |
254 | Sends a get nodes request to the given node with ip port and public_key */ | 278 | * Sends a get nodes request to the given node with ip port and public_key. |
279 | */ | ||
255 | void tox_bootstrap(Tox *tox, tox_IP_Port ip_port, uint8_t *public_key); | 280 | void tox_bootstrap(Tox *tox, tox_IP_Port ip_port, uint8_t *public_key); |
256 | 281 | ||
257 | /* returns 0 if we are not connected to the DHT | 282 | /* returns 0 if we are not connected to the DHT. |
258 | returns 1 if we are */ | 283 | * returns 1 if we are. |
284 | */ | ||
259 | int tox_isconnected(Tox *tox); | 285 | int tox_isconnected(Tox *tox); |
260 | 286 | ||
261 | /* run this at startup | 287 | /* Run this at startup. |
262 | * returns allocated instance of tox on success | 288 | * returns allocated instance of tox on success. |
263 | * returns 0 if there are problems */ | 289 | * returns 0 if there are problems. |
290 | */ | ||
264 | Tox *tox_new(void); | 291 | Tox *tox_new(void); |
265 | 292 | ||
266 | /* run this before closing shop | 293 | /* Run this before closing shop. |
267 | * free all datastructures */ | 294 | * Free all datastructures. */ |
268 | void tox_kill(Tox *tox); | 295 | void tox_kill(Tox *tox); |
269 | 296 | ||
270 | /* the main loop that needs to be run at least 20 times per second */ | 297 | /* The main loop that needs to be run at least 20 times per second. */ |
271 | void tox_do(Tox *tox); | 298 | void tox_do(Tox *tox); |
272 | 299 | ||
273 | /* SAVING AND LOADING FUNCTIONS: */ | 300 | /* SAVING AND LOADING FUNCTIONS: */ |
274 | 301 | ||
275 | /* returns the size of the messenger data (for saving) */ | 302 | /* returns the size of the messenger data (for saving). */ |
276 | uint32_t tox_size(Tox *tox); | 303 | uint32_t tox_size(Tox *tox); |
277 | 304 | ||
278 | /* save the messenger in data (must be allocated memory of size Messenger_size()) */ | 305 | /* Save the messenger in data (must be allocated memory of size Messenger_size()). */ |
279 | void tox_save(Tox *tox, uint8_t *data); | 306 | void tox_save(Tox *tox, uint8_t *data); |
280 | 307 | ||
281 | /* load the messenger from data of size length */ | 308 | /* Load the messenger from data of size length. */ |
282 | int tox_load(Tox *tox, uint8_t *data, uint32_t length); | 309 | int tox_load(Tox *tox, uint8_t *data, uint32_t length); |
283 | 310 | ||
284 | 311 | ||