summaryrefslogtreecommitdiff
path: root/core/tox.h
diff options
context:
space:
mode:
Diffstat (limited to 'core/tox.h')
-rw-r--r--core/tox.h289
1 files changed, 0 insertions, 289 deletions
diff --git a/core/tox.h b/core/tox.h
deleted file mode 100644
index bdfac1d6..00000000
--- a/core/tox.h
+++ /dev/null
@@ -1,289 +0,0 @@
1/* tox.h
2 *
3 * The Tox public API.
4 *
5 * Copyright (C) 2013 Tox project All Rights Reserved.
6 *
7 * This file is part of Tox.
8 *
9 * Tox is free software: you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation, either version 3 of the License, or
12 * (at your option) any later version.
13 *
14 * Tox is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with Tox. If not, see <http://www.gnu.org/licenses/>.
21 *
22 */
23
24#ifndef TOX_H
25#define TOX_H
26
27#include <stdint.h>
28
29#ifdef __cplusplus
30extern "C" {
31#endif
32
33#define TOX_MAX_NAME_LENGTH 128
34#define TOX_MAX_STATUSMESSAGE_LENGTH 128
35#define TOX_CLIENT_ID_SIZE 32
36
37#define TOX_FRIEND_ADDRESS_SIZE (TOX_CLIENT_ID_SIZE + sizeof(uint32_t) + sizeof(uint16_t))
38
39
40typedef union {
41 uint8_t c[4];
42 uint16_t s[2];
43 uint32_t i;
44} tox_IP;
45
46typedef struct {
47 tox_IP ip;
48 uint16_t port;
49 /* not used for anything right now */
50 uint16_t padding;
51} tox_IP_Port;
52
53/* status definitions */
54enum {
55 TOX_NOFRIEND,
56 TOX_FRIEND_ADDED,
57 TOX_FRIEND_REQUESTED,
58 TOX_FRIEND_CONFIRMED,
59 TOX_FRIEND_ONLINE,
60};
61
62/* errors for m_addfriend
63 * FAERR - Friend Add Error */
64enum {
65 TOX_FAERR_TOOLONG = -1,
66 TOX_FAERR_NOMESSAGE = -2,
67 TOX_FAERR_OWNKEY = -3,
68 TOX_FAERR_ALREADYSENT = -4,
69 TOX_FAERR_UNKNOWN = -5,
70 TOX_FAERR_BADCHECKSUM = -6,
71 TOX_FAERR_SETNEWNOSPAM = -7,
72 TOX_FAERR_NOMEM = -8
73};
74/* USERSTATUS
75 * Represents userstatuses someone can have. */
76
77typedef enum {
78 TOX_USERSTATUS_NONE,
79 TOX_USERSTATUS_AWAY,
80 TOX_USERSTATUS_BUSY,
81 TOX_USERSTATUS_INVALID
82}
83TOX_USERSTATUS;
84
85typedef void Tox;
86
87/*
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 *
91 */
92void tox_getaddress(Tox *tox, uint8_t *address);
93
94/*
95 * add a friend
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.
98 * data is the data and length is the length
99 * returns the friend number if success
100 * return TOX_FA_TOOLONG if message length is too long
101 * return TOX_FAERR_NOMESSAGE if no message (message length must be >= 1 byte)
102 * return TOX_FAERR_OWNKEY if user's own key
103 * return TOX_FAERR_ALREADYSENT if friend request already sent or already a friend
104 * return TOX_FAERR_UNKNOWN for unknown error
105 * 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
107 * (the nospam for that friend was set to the new one)
108 * return TOX_FAERR_NOMEM if increasing the friend list size fails
109 */
110int tox_addfriend(Tox *tox, uint8_t *address, uint8_t *data, uint16_t length);
111
112
113/* add a friend without sending a friendrequest.
114 returns the friend number if success
115 return -1 if failure. */
116int tox_addfriend_norequest(Tox *tox, uint8_t *client_id);
117
118/* return the friend id associated to that client id.
119 return -1 if no such friend */
120int tox_getfriend_id(Tox *tox, uint8_t *client_id);
121
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.
124 return 0 if success
125 return -1 if failure */
126int tox_getclient_id(Tox *tox, int friend_id, uint8_t *client_id);
127
128/* remove a friend */
129int tox_delfriend(Tox *tox, int friendnumber);
130
131/* return TOX_FRIEND_ONLINE if friend is online
132 return TOX_FRIEND_CONFIRMED if friend is confirmed
133 return TOX_FRIEND_REQUESTED if the friend request was sent
134 return TOX_FRIEND_ADDED if the friend was added
135 return TOX_NOFRIEND if there is no friend with that number */
136int tox_friendstatus(Tox *tox, int friendnumber);
137
138/* send a text chat message to an online friend
139 returns the message id if packet was successfully put into the send queue
140 return 0 if it was not
141 you will want to retain the return value, it will be passed to your read receipt callback
142 if one is received.
143 m_sendmessage_withid will send a message with the id of your choosing,
144 however we can generate an id for you by calling plain m_sendmessage. */
145uint32_t tox_sendmessage(Tox *tox, int friendnumber, uint8_t *message, uint32_t length);
146uint32_t tox_sendmessage_withid(Tox *tox, int friendnumber, uint32_t theid, uint8_t *message, uint32_t length);
147
148/* send an action to an online friend
149 returns 1 if packet was successfully put into the send queue
150 return 0 if it was not */
151int tox_sendaction(Tox *tox, int friendnumber, uint8_t *action, uint32_t length);
152
153/* Set our nickname
154 name must be a string of maximum MAX_NAME_LENGTH length.
155 length must be at least 1 byte
156 length is the length of name with the NULL terminator
157 return 0 if success
158 return -1 if failure */
159int tox_setname(Tox *tox, uint8_t *name, uint16_t length);
160
161/*
162 Get your nickname.
163 m The messanger context to use.
164 name Pointer to a string for the name.
165 nlen The length of the string buffer.
166 returns Return the length of the name, 0 on error.
167*/
168uint16_t tox_getselfname(Tox *tox, uint8_t *name, uint16_t nlen);
169
170/* get name of friendnumber
171 put it in name
172 name needs to be a valid memory location with a size of at least MAX_NAME_LENGTH (128) bytes.
173 return 0 if success
174 return -1 if failure */
175int tox_getname(Tox *tox, int friendnumber, uint8_t *name);
176
177/* set our user status
178 you are responsible for freeing status after
179 returns 0 on success, -1 on failure */
180int tox_set_statusmessage(Tox *tox, uint8_t *status, uint16_t length);
181int tox_set_userstatus(Tox *tox, TOX_USERSTATUS status);
182
183/* return the length of friendnumber's status message,
184 including null
185 pass it into malloc */
186int tox_get_statusmessage_size(Tox *tox, int friendnumber);
187
188/* 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
190 The self variant will copy our own status message. */
191int tox_copy_statusmessage(Tox *tox, int friendnumber, uint8_t *buf, uint32_t maxlen);
192int tox_copy_self_statusmessage(Tox *tox, uint8_t *buf, uint32_t maxlen);
193
194/* Return one of USERSTATUS values.
195 * Values unknown to your application should be represented as USERSTATUS_NONE.
196 * As above, the self variant will return our own USERSTATUS.
197 * If friendnumber is invalid, this shall return USERSTATUS_INVALID. */
198TOX_USERSTATUS tox_get_userstatus(Tox *tox, int friendnumber);
199TOX_USERSTATUS tox_get_selfuserstatus(Tox *tox);
200
201/* 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).*/
203void tox_set_sends_receipts(Tox *tox, int friendnumber, int yesno);
204
205/* 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) */
207void tox_callback_friendrequest(Tox *tox, void (*function)(uint8_t *, uint8_t *, uint16_t, void *), void *userdata);
208
209/* 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) */
211void tox_callback_friendmessage(Tox *tox, void (*function)(Tox *tox, int, uint8_t *, uint16_t, void *),
212 void *userdata);
213
214/* 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) */
216void tox_callback_action(Tox *tox, void (*function)(Tox *tox, int, uint8_t *, uint16_t, void *), void *userdata);
217
218/* set the callback for name changes
219 function(int friendnumber, uint8_t *newname, uint16_t length)
220 you are not responsible for freeing newname */
221void tox_callback_namechange(Tox *tox, void (*function)(Tox *tox, int, uint8_t *, uint16_t, void *),
222 void *userdata);
223
224/* set the callback for status message changes
225 function(int friendnumber, uint8_t *newstatus, uint16_t length)
226 you are not responsible for freeing newstatus */
227void tox_callback_statusmessage(Tox *tox, void (*function)(Tox *tox, int, uint8_t *, uint16_t, void *),
228 void *userdata);
229
230/* set the callback for status type changes
231 function(int friendnumber, USERSTATUS kind) */
232void tox_callback_userstatus(Tox *tox, void (*function)(Tox *tox, int, TOX_USERSTATUS, void *), void *userdata);
233
234/* set the callback for read receipts
235 function(int friendnumber, uint32_t receipt)
236 if you are keeping a record of returns from m_sendmessage,
237 receipt might be one of those values, and that means the message
238 has been received on the other side. since core doesn't
239 track ids for you, receipt may not correspond to any message
240 in that case, you should discard it. */
241void tox_callback_read_receipt(Tox *tox, void (*function)(Tox *tox, int, uint32_t, void *), void *userdata);
242
243/* set the callback for connection status changes
244 function(int friendnumber, uint8_t status)
245 status:
246 0 -- friend went offline after being previously online
247 1 -- friend went online
248 note that this callback is not called when adding friends, thus the "after
249 being previously online" part. it's assumed that when adding friends,
250 their connection status is offline. */
251void tox_callback_connectionstatus(Tox *tox, void (*function)(Tox *tox, int, uint8_t, void *), void *userdata);
252
253/* Use this function to bootstrap the client
254 Sends a get nodes request to the given node with ip port and public_key */
255void tox_bootstrap(Tox *tox, tox_IP_Port ip_port, uint8_t *public_key);
256
257/* returns 0 if we are not connected to the DHT
258 returns 1 if we are */
259int tox_isconnected(Tox *tox);
260
261/* run this at startup
262 * returns allocated instance of tox on success
263 * returns 0 if there are problems */
264Tox *tox_new(void);
265
266/* run this before closing shop
267 * free all datastructures */
268void tox_kill(Tox *tox);
269
270/* the main loop that needs to be run at least 20 times per second */
271void tox_do(Tox *tox);
272
273/* SAVING AND LOADING FUNCTIONS: */
274
275/* returns the size of the messenger data (for saving) */
276uint32_t tox_size(Tox *tox);
277
278/* save the messenger in data (must be allocated memory of size Messenger_size()) */
279void tox_save(Tox *tox, uint8_t *data);
280
281/* load the messenger from data of size length */
282int tox_load(Tox *tox, uint8_t *data, uint32_t length);
283
284
285#ifdef __cplusplus
286}
287#endif
288
289#endif