]> git.meshlink.io Git - meshlink/blob - src/meshlink.h
Re-enable building the chatpp example.
[meshlink] / src / meshlink.h
1 #ifndef MESHLINK_H
2 #define MESHLINK_H
3
4 /*
5     meshlink.h -- MeshLink API
6     Copyright (C) 2014-2019 Guus Sliepen <guus@meshlink.io>
7
8     This program is free software; you can redistribute it and/or modify
9     it under the terms of the GNU General Public License as published by
10     the Free Software Foundation; either version 2 of the License, or
11     (at your option) any later version.
12
13     This program is distributed in the hope that it will be useful,
14     but WITHOUT ANY WARRANTY; without even the implied warranty of
15     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16     GNU General Public License for more details.
17
18     You should have received a copy of the GNU General Public License along
19     with this program; if not, write to the Free Software Foundation, Inc.,
20     51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
21 */
22
23 #include <stdint.h>
24 #include <stdbool.h>
25 #include <stddef.h>
26 #include <unistd.h>
27
28 #if defined(_WIN32)
29 #include <winsock2.h>
30 #else
31 #include <sys/types.h>
32 #include <sys/socket.h>
33 #endif
34
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38
39 /// The length in bytes of a signature made with meshlink_sign()
40 #define MESHLINK_SIGLEN (64ul)
41
42 // The maximum length of fingerprints
43 #define MESHLINK_FINGERPRINTLEN (64ul)
44
45 /// A handle for an instance of MeshLink.
46 typedef struct meshlink_handle meshlink_handle_t;
47
48 /// A handle for a MeshLink node.
49 typedef struct meshlink_node meshlink_node_t;
50
51 /// A handle for a MeshLink channel.
52 typedef struct meshlink_channel meshlink_channel_t;
53
54 /// A struct containing all parameters used for opening a mesh.
55 typedef struct meshlink_open_params meshlink_open_params_t;
56
57 /// A handle for a MeshLink sub-mesh.
58 typedef struct meshlink_submesh meshlink_submesh_t;
59
60 /// Code of most recent error encountered.
61 typedef enum {
62         MESHLINK_OK,        ///< Everything is fine
63         MESHLINK_EINVAL,    ///< Invalid parameter(s) to function call
64         MESHLINK_ENOMEM,    ///< Out of memory
65         MESHLINK_ENOENT,    ///< Node is not known
66         MESHLINK_EEXIST,    ///< Node already exists
67         MESHLINK_EINTERNAL, ///< MeshLink internal error
68         MESHLINK_ERESOLV,   ///< MeshLink could not resolve a hostname
69         MESHLINK_ESTORAGE,  ///< MeshLink could not load or write data from/to disk
70         MESHLINK_ENETWORK,  ///< MeshLink encountered a network error
71         MESHLINK_EPEER,     ///< A peer caused an error
72         MESHLINK_ENOTSUP,   ///< The operation is not supported in the current configuration of MeshLink
73         MESHLINK_EBUSY      ///< The MeshLink instance is already in use by another process
74 } meshlink_errno_t;
75
76 /// Device class
77 typedef enum {
78         DEV_CLASS_BACKBONE = 0,
79         DEV_CLASS_STATIONARY = 1,
80         DEV_CLASS_PORTABLE = 2,
81         DEV_CLASS_UNKNOWN = 3,
82         _DEV_CLASS_MAX = 3
83 } dev_class_t;
84
85 /// Invitation flags
86 static const uint32_t MESHLINK_INVITE_LOCAL = 1;    // Only use local addresses in the URL
87 static const uint32_t MESHLINK_INVITE_PUBLIC = 2;   // Only use public or canonical addresses in the URL
88 static const uint32_t MESHLINK_INVITE_IPV4 = 4;     // Only use IPv4 addresses in the URL
89 static const uint32_t MESHLINK_INVITE_IPV6 = 8;     // Only use IPv6 addresses in the URL
90 static const uint32_t MESHLINK_INVITE_NUMERIC = 16; // Don't look up hostnames
91
92 /// Channel flags
93 static const uint32_t MESHLINK_CHANNEL_RELIABLE = 1;   // Data is retransmitted when packets are lost.
94 static const uint32_t MESHLINK_CHANNEL_ORDERED = 2;    // Data is delivered in-order to the application.
95 static const uint32_t MESHLINK_CHANNEL_FRAMED = 4;     // Data is delivered in chunks of the same length as data was originally sent.
96 static const uint32_t MESHLINK_CHANNEL_DROP_LATE = 8;  // When packets are reordered, late packets are ignored.
97 static const uint32_t MESHLINK_CHANNEL_TCP = 3;        // Select TCP semantics.
98 static const uint32_t MESHLINK_CHANNEL_UDP = 0;        // Select UDP semantics.
99
100 /// A variable holding the last encountered error from MeshLink.
101 /** This is a thread local variable that contains the error code of the most recent error
102  *  encountered by a MeshLink API function called in the current thread.
103  *  The variable is only updated when an error is encountered, and is not reset to MESHLINK_OK
104  *  if a function returned successfully.
105  */
106 extern __thread meshlink_errno_t meshlink_errno;
107
108 #ifndef MESHLINK_INTERNAL_H
109
110 struct meshlink_handle {
111         const char *const name; ///< Textual name of ourself. It is stored in a nul-terminated C string, which is allocated by MeshLink.
112         void *priv;             ///< Private pointer which may be set freely by the application, and is never used or modified by MeshLink.
113 };
114
115 struct meshlink_node {
116         const char *const name; ///< Textual name of this node. It is stored in a nul-terminated C string, which is allocated by MeshLink.
117         void *priv;             ///< Private pointer which may be set freely by the application, and is never used or modified by MeshLink.
118 };
119
120 struct meshlink_submesh {
121         const char *const name; ///< Textual name of this Sub-Mesh. It is stored in a nul-terminated C string, which is allocated by MeshLink.
122         void *priv;             ///< Private pointer which may be set freely by the application, and is never used or modified by MeshLink.
123 };
124
125 struct meshlink_channel {
126         struct meshlink_node *const node; ///< Pointer to the peer of this channel.
127         void *priv;                       ///< Private pointer which may be set freely by the application, and is never used or modified by MeshLink.
128 };
129
130 #endif // MESHLINK_INTERNAL_H
131
132 /// Get the text for the given MeshLink error code.
133 /** This function returns a pointer to the string containing the description of the given error code.
134  *
135  *  @param err      An error code returned by MeshLink.
136  *
137  *  @return         A pointer to a string containing the description of the error code.
138  *                  The pointer is to static storage that is valid for the lifetime of the application.
139  *                  This function will always return a valid pointer, even if an invalid error code has been passed.
140  */
141 extern const char *meshlink_strerror(meshlink_errno_t err);
142
143 /// Create a new meshlink_open_params_t struct.
144 /** This function allocates and initializes a new meshlink_open_params_t struct that can be passed to meshlink_open_ex().
145  *  The resulting struct may be reused for multiple calls to meshlink_open_ex().
146  *  After the last use, the application must free this struct using meshlink_open_params_free().
147  *
148  *  @param confbase The directory in which MeshLink will store its configuration files.
149  *                  After the function returns, the application is free to overwrite or free @a confbase.
150  *  @param name     The name which this instance of the application will use in the mesh.
151  *                  After the function returns, the application is free to overwrite or free @a name.
152  *  @param appname  The application name which will be used in the mesh.
153  *                  After the function returns, the application is free to overwrite or free @a name.
154  *  @param devclass The device class which will be used in the mesh.
155  *
156  *  @return         A pointer to a meshlink_open_params_t which can be passed to meshlink_open_ex(), or NULL in case of an error.
157  *                  The pointer is valid until meshlink_open_params_free() is called.
158  */
159 extern meshlink_open_params_t *meshlink_open_params_init(const char *confbase, const char *name, const char *appname, dev_class_t devclass);
160
161 /// Free a meshlink_open_params_t struct.
162 /** This function frees a meshlink_open_params_t struct and all resources associated with it.
163  *
164  *  @param params   A pointer to a meshlink_open_params_t which must have been created earlier with meshlink_open_params_init().
165  */
166 extern void meshlink_open_params_free(meshlink_open_params_t *params);
167
168 /// Open or create a MeshLink instance.
169 /** This function opens or creates a MeshLink instance.
170  *  All parameters needed by MeshLink are passed via a meshlink_open_params_t struct,
171  *  which must have been initialized earlier by the application.
172  *
173  *  This function returns a pointer to a struct meshlink_handle that will be allocated by MeshLink.
174  *  When the application does no longer need to use this handle, it must call meshlink_close() to
175  *  free its resources.
176  *
177  *  This function does not start any network I/O yet. The application should
178  *  first set callbacks, and then call meshlink_start().
179  *
180  *  @param params   A pointer to a meshlink_open_params_t which must be filled in by the application.
181  *                  After the function returns, the application is free to reuse or free @a params.
182  *
183  *  @return         A pointer to a meshlink_handle_t which represents this instance of MeshLink, or NULL in case of an error.
184  *                  The pointer is valid until meshlink_close() is called.
185  */
186 extern meshlink_handle_t *meshlink_open_ex(const meshlink_open_params_t *params);
187
188 /// Open or create a MeshLink instance.
189 /** This function opens or creates a MeshLink instance.
190  *  The state is stored in the configuration directory passed in the variable @a confbase.
191  *  If the configuration directory does not exist yet, for example when it is the first time
192  *  this instance is opened, the configuration directory will be automatically created and initialized.
193  *  However, the parent directory should already exist, otherwise an error will be returned.
194  *
195  *  The name given should be a unique identifier for this instance.
196  *
197  *  This function returns a pointer to a struct meshlink_handle that will be allocated by MeshLink.
198  *  When the application does no longer need to use this handle, it must call meshlink_close() to
199  *  free its resources.
200  *
201  *  This function does not start any network I/O yet. The application should
202  *  first set callbacks, and then call meshlink_start().
203  *
204  *  @param confbase The directory in which MeshLink will store its configuration files.
205  *                  After the function returns, the application is free to overwrite or free @a confbase.
206  *  @param name     The name which this instance of the application will use in the mesh.
207  *                  After the function returns, the application is free to overwrite or free @a name.
208  *  @param appname  The application name which will be used in the mesh.
209  *                  After the function returns, the application is free to overwrite or free @a name.
210  *  @param devclass The device class which will be used in the mesh.
211  *
212  *  @return         A pointer to a meshlink_handle_t which represents this instance of MeshLink, or NULL in case of an error.
213  *                  The pointer is valid until meshlink_close() is called.
214  */
215 extern meshlink_handle_t *meshlink_open(const char *confbase, const char *name, const char *appname, dev_class_t devclass);
216
217 /// Create Sub-Mesh.
218 /** This function causes MeshLink to open a new Sub-Mesh network
219  *  create a new thread, which will handle all network I/O.
220  *
221  *  It is allowed to call this function even if MeshLink is already started, in which case it will return true.
222  *
223  *  @param mesh     A handle which represents an instance of MeshLink.
224   *
225  *  @param submesh  Name of the new Sub-Mesh to create.
226  *
227  *  @return         A pointer to a meshlink_submesh_t which represents this instance of SubMesh, or NULL in case of an error.
228  *                  The pointer is valid until meshlink_close() is called.
229  */
230 meshlink_submesh_t *meshlink_submesh_open(meshlink_handle_t  *mesh, const char *submesh);
231
232 /// Start MeshLink.
233 /** This function causes MeshLink to open network sockets, make outgoing connections, and
234  *  create a new thread, which will handle all network I/O.
235  *
236  *  It is allowed to call this function even if MeshLink is already started, in which case it will return true.
237  *
238  *  @param mesh     A handle which represents an instance of MeshLink.
239  *
240  *  @return         This function will return true if MeshLink has successfully started, false otherwise.
241  */
242 extern bool meshlink_start(meshlink_handle_t *mesh);
243
244 /// Stop MeshLink.
245 /** This function causes MeshLink to disconnect from all other nodes,
246  *  close all sockets, and shut down its own thread.
247  *
248  *  This function always succeeds. It is allowed to call meshlink_stop() even if MeshLink is already stopped or has never been started.
249  *  Channels that are still open will remain valid, but any communication via channels will stop as well.
250  *
251  *  @param mesh     A handle which represents an instance of MeshLink.
252  */
253 extern void meshlink_stop(meshlink_handle_t *mesh);
254
255 /// Close the MeshLink handle.
256 /** This function calls meshlink_stop() if necessary,
257  *  and frees the struct meshlink_handle and all associacted memory allocated by MeshLink, including all channels.
258  *  Afterwards, the handle and any pointers to a struct meshlink_node or struct meshlink_channel are invalid.
259  *
260  *  It is allowed to call this function at any time on a valid handle, except inside callback functions.
261  *  If called at a proper time with a valid handle, this function always succeeds.
262  *  If called within a callback or with an invalid handle, the result is undefined.
263  *
264  *  @param mesh     A handle which represents an instance of MeshLink.
265  */
266 extern void meshlink_close(meshlink_handle_t *mesh);
267
268 /// Destroy a MeshLink instance.
269 /** This function remove all configuration files of a MeshLink instance. It should only be called when the application
270  *  does not have an open handle to this instance. Afterwards, a call to meshlink_open() will create a completely
271  *  new instance.
272  *
273  *  @param confbase The directory in which MeshLink stores its configuration files.
274  *                  After the function returns, the application is free to overwrite or free @a confbase.
275  *
276  *  @return         This function will return true if the MeshLink instance was successfully destroyed, false otherwise.
277  */
278 extern bool meshlink_destroy(const char *confbase);
279
280 /// A callback for receiving data from the mesh.
281 /** @param mesh      A handle which represents an instance of MeshLink.
282  *  @param source    A pointer to a meshlink_node_t describing the source of the data.
283  *  @param data      A pointer to a buffer containing the data sent by the source, or NULL in case there is no data (an empty packet was received).
284  *                   The pointer is only valid during the lifetime of the callback.
285  *                   The callback should mempcy() the data if it needs to be available outside the callback.
286  *  @param len       The length of the received data, or 0 in case there is no data.
287  */
288 typedef void (*meshlink_receive_cb_t)(meshlink_handle_t *mesh, meshlink_node_t *source, const void *data, size_t len);
289
290 /// Set the receive callback.
291 /** This functions sets the callback that is called whenever another node sends data to the local node.
292  *  The callback is run in MeshLink's own thread.
293  *  It is therefore important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
294  *  to hand the data over to the application's thread.
295  *  The callback should also not block itself and return as quickly as possible.
296  *
297  *  @param mesh      A handle which represents an instance of MeshLink.
298  *  @param cb        A pointer to the function which will be called when another node sends data to the local node.
299  *                   If a NULL pointer is given, the callback will be disabled.
300  */
301 extern void meshlink_set_receive_cb(meshlink_handle_t *mesh, meshlink_receive_cb_t cb);
302
303 /// A callback reporting the meta-connection attempt made by the host node to an another node.
304 /** @param mesh      A handle which represents an instance of MeshLink.
305  *  @param node      A pointer to a meshlink_node_t describing the node to whom meta-connection is being tried.
306  *                   This pointer is valid until meshlink_close() is called.
307  */
308 typedef void (*meshlink_connection_try_cb_t)(meshlink_handle_t *mesh, meshlink_node_t *node);
309
310 /// Set the meta-connection try callback.
311 /** This functions sets the callback that is called whenever a connection attempt is happened to another node.
312  *  The callback is run in MeshLink's own thread.
313  *  It is therefore important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
314  *  to hand the data over to the application's thread.
315  *  The callback should also not block itself and return as quickly as possible.
316  *
317  *  @param mesh      A handle which represents an instance of MeshLink.
318  *  @param cb        A pointer to the function which will be called when host node attempts to make
319  *                   the connection to another node. If a NULL pointer is given, the callback will be disabled.
320  */
321 extern void meshlink_set_connection_try_cb(meshlink_handle_t *mesh, meshlink_connection_try_cb_t cb);
322
323 /// A callback reporting node status changes.
324 /** @param mesh       A handle which represents an instance of MeshLink.
325  *  @param node       A pointer to a meshlink_node_t describing the node whose status changed.
326  *                    This pointer is valid until meshlink_close() is called.
327  *  @param reachable  True if the node is reachable, false otherwise.
328  */
329 typedef void (*meshlink_node_status_cb_t)(meshlink_handle_t *mesh, meshlink_node_t *node, bool reachable);
330
331 /// Set the node status callback.
332 /** This functions sets the callback that is called whenever another node's status changed.
333  *  The callback is run in MeshLink's own thread.
334  *  It is therefore important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
335  *  to hand the data over to the application's thread.
336  *  The callback should also not block itself and return as quickly as possible.
337  *
338  *  @param mesh      A handle which represents an instance of MeshLink.
339  *  @param cb        A pointer to the function which will be called when another node's status changes.
340  *                   If a NULL pointer is given, the callback will be disabled.
341  */
342 extern void meshlink_set_node_status_cb(meshlink_handle_t *mesh, meshlink_node_status_cb_t cb);
343
344 /// A callback reporting duplicate node detection.
345 /** @param mesh       A handle which represents an instance of MeshLink.
346  *  @param node       A pointer to a meshlink_node_t describing the node which is duplicate.
347  *                    This pointer is valid until meshlink_close() is called.
348  */
349 typedef void (*meshlink_node_duplicate_cb_t)(meshlink_handle_t *mesh, meshlink_node_t *node);
350
351 /// Set the node duplicate callback.
352 /** This functions sets the callback that is called whenever a duplicate node is detected.
353  *  The callback is run in MeshLink's own thread.
354  *  It is therefore important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
355  *  to hand the data over to the application's thread.
356  *  The callback should also not block itself and return as quickly as possible.
357  *
358  *  @param mesh      A handle which represents an instance of MeshLink.
359  *  @param cb        A pointer to the function which will be called when a duplicate node is detected.
360  *                   If a NULL pointer is given, the callback will be disabled.
361  */
362 extern void meshlink_set_node_duplicate_cb(meshlink_handle_t *mesh, meshlink_node_duplicate_cb_t cb);
363
364 /// Severity of log messages generated by MeshLink.
365 typedef enum {
366         MESHLINK_DEBUG,    ///< Internal debugging messages. Only useful during application development.
367         MESHLINK_INFO,     ///< Informational messages.
368         MESHLINK_WARNING,  ///< Warnings which might indicate problems, but which are not real errors.
369         MESHLINK_ERROR,    ///< Errors which hamper correct functioning of MeshLink, without causing it to fail completely.
370         MESHLINK_CRITICAL  ///< Critical errors which cause MeshLink to fail completely.
371 } meshlink_log_level_t;
372
373 /// A callback for receiving log messages generated by MeshLink.
374 /** @param mesh      A handle which represents an instance of MeshLink, or NULL.
375  *  @param level     An enum describing the severity level of the message.
376  *  @param text      A pointer to a nul-terminated C string containing the textual log message.
377  *                   This pointer is only valid for the duration of the callback.
378  *                   The application must not free() this pointer.
379  *                   The application should strdup() the text if it has to be available outside the callback.
380  */
381 typedef void (*meshlink_log_cb_t)(meshlink_handle_t *mesh, meshlink_log_level_t level, const char *text);
382
383 /// Set the log callback.
384 /** This functions sets the callback that is called whenever MeshLink has some information to log.
385  *
386  *  The @a mesh parameter can either be a valid MeshLink handle, or NULL.
387  *  In case it is NULL, the callback will be called for errors that happen outside the context of a valid mesh instance.
388  *  Otherwise, it will be called for errors that happen in the context of the given mesh instance.
389  *
390  *  If @a mesh is not NULL, then the callback is run in MeshLink's own thread.
391  *  It is important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
392  *  to hand the data over to the application's thread.
393  *  The callback should also not block itself and return as quickly as possible.
394  *
395  *  The @a mesh parameter can either be a valid MeshLink handle, or NULL.
396  *  In case it is NULL, the callback will be called for errors that happen outside the context of a valid mesh instance.
397  *  Otherwise, it will be called for errors that happen in the context of the given mesh instance.
398  *
399  *  @param mesh      A handle which represents an instance of MeshLink, or NULL.
400  *  @param level     An enum describing the minimum severity level. Debugging information with a lower level will not trigger the callback.
401  *  @param cb        A pointer to the function which will be called when another node sends data to the local node.
402  *                   If a NULL pointer is given, the callback will be disabled.
403  */
404 extern void meshlink_set_log_cb(meshlink_handle_t *mesh, meshlink_log_level_t level, meshlink_log_cb_t cb);
405
406 /// Send data to another node.
407 /** This functions sends one packet of data to another node in the mesh.
408  *  The packet is sent using UDP semantics, which means that
409  *  the packet is sent as one unit and is received as one unit,
410  *  and that there is no guarantee that the packet will arrive at the destination.
411  *  Packets that are too big to be sent over the network as one unit might be dropped, and this function may return an error if this situation can be detected beforehand.
412  *  The application should not send packets that are larger than the path MTU, which can be queried with meshlink_get_pmtu().
413  *  The application should take care of getting an acknowledgement and retransmission if necessary.
414  *
415  *  @param mesh         A handle which represents an instance of MeshLink.
416  *  @param destination  A pointer to a meshlink_node_t describing the destination for the data.
417  *  @param data         A pointer to a buffer containing the data to be sent to the source.
418  *                      After meshlink_send() returns, the application is free to overwrite or free this buffer.
419  *                      It is valid to specify a NULL pointer, but only if @a len is also 0.
420  *  @param len          The length of the data.
421  *  @return             This function will return true if MeshLink has queued the message for transmission, and false otherwise.
422  *                      A return value of true does not guarantee that the message will actually arrive at the destination.
423  */
424 extern bool meshlink_send(meshlink_handle_t *mesh, meshlink_node_t *destination, const void *data, size_t len);
425
426 /// Query the maximum packet size that can be sent to a node.
427 /** This functions returns the maximum size of packets (path MTU) that can be sent to a specific node with meshlink_send().
428  *  The path MTU is a property of the path packets will take to the destination node over the Internet.
429  *  It can be different for different destination nodes.
430  *  and the path MTU can change at any point in time due to changes in the Internet.
431  *  Therefore, although this should only occur rarely, it can still happen that packets that do not exceed this size get dropped.
432  *
433  *  @param mesh         A handle which represents an instance of MeshLink.
434  *  @param destination  A pointer to a meshlink_node_t describing the destination for the data.
435  *
436  *  @return             The recommended maximum size of packets that are to be sent to the destination node, 0 if the node is unreachable,
437  *                      or a negative value in case of an error.
438  */
439 extern ssize_t meshlink_get_pmtu(meshlink_handle_t *mesh, meshlink_node_t *destination);
440
441 /// Get a handle for our own node.
442 /** This function returns a handle for the local node.
443  *
444  *  @param mesh         A handle which represents an instance of MeshLink.
445  *
446  *  @return             A pointer to a meshlink_node_t which represents the local node.
447  *                      The pointer is guaranteed to be valid until meshlink_close() is called.
448  */
449 extern meshlink_node_t *meshlink_get_self(meshlink_handle_t *mesh);
450
451 /// Get a handle for a specific node.
452 /** This function returns a handle for the node with the given name.
453  *
454  *  @param mesh         A handle which represents an instance of MeshLink.
455  *  @param name         The name of the node for which a handle is requested.
456  *                      After this function returns, the application is free to overwrite or free @a name.
457  *
458  *  @return             A pointer to a meshlink_node_t which represents the requested node,
459  *                      or NULL if the requested node does not exist.
460  *                      The pointer is guaranteed to be valid until meshlink_close() is called.
461  */
462 extern meshlink_node_t *meshlink_get_node(meshlink_handle_t *mesh, const char *name);
463
464 /// Get a handle for a specific submesh.
465 /** This function returns a handle for the submesh with the given name.
466  *
467  *  @param mesh         A handle which represents an instance of MeshLink.
468  *  @param name         The name of the submesh for which a handle is requested.
469  *                      After this function returns, the application is free to overwrite or free @a name @a.
470  *
471  *  @return             A pointer to a meshlink_submesh_t which represents the requested submesh,
472  *                      or NULL if the requested submesh does not exist.
473  *                      The pointer is guaranteed to be valid until meshlink_close() is called.
474  */
475 extern meshlink_submesh_t *meshlink_get_submesh(meshlink_handle_t *mesh, const char *name);
476
477 /// Get the fingerprint of a node's public key.
478 /** This function returns a fingerprint of the node's public key.
479  *  It should be treated as an opaque blob.
480  *
481  *  @param mesh         A handle which represents an instance of MeshLink.
482  *  @param node         A pointer to a meshlink_node_t describing the node.
483  *
484  *  @return             A nul-terminated C string containing the fingerprint of the node's public key in a printable ASCII format.
485  *                      The application should call free() after it is done using this string.
486  */
487 extern char *meshlink_get_fingerprint(meshlink_handle_t *mesh, meshlink_node_t *node);
488
489 /// Get a list of all nodes.
490 /** This function returns a list with handles for all known nodes.
491  *
492  *  @param mesh         A handle which represents an instance of MeshLink.
493  *  @param nodes        A pointer to a previously allocated array of pointers to meshlink_node_t, or NULL in which case MeshLink will allocate a new array.
494  *                      The application can supply an array it allocated itself with malloc, or the return value from the previous call to this function (which is the preferred way).
495  *                      The application is allowed to call free() on the array whenever it wishes.
496  *                      The pointers in the array are valid until meshlink_close() is called.
497  *  @param nmemb        A pointer to a variable holding the number of nodes that are stored in the array.
498  *                      In case the @a nodes argument is not NULL, MeshLink might call realloc() on the array to change its size.
499  *                      The contents of this variable will be changed to reflect the new size of the array.
500  *
501  *  @return             A pointer to an array containing pointers to all known nodes, or NULL in case of an error.
502  *                      If the @a nodes argument was not NULL, then the return value can either be the same value or a different value.
503  *                      If it is a new value, the old value of @a nodes should not be used anymore.
504  *                      If the new value is NULL, then the old array will have been freed by MeshLink.
505  */
506 extern meshlink_node_t **meshlink_get_all_nodes(meshlink_handle_t *mesh, meshlink_node_t **nodes, size_t *nmemb);
507
508 /// Sign data using the local node's MeshLink key.
509 /** This function signs data using the local node's MeshLink key.
510  *  The generated signature can be securely verified by other nodes.
511  *
512  *  @param mesh         A handle which represents an instance of MeshLink.
513  *  @param data         A pointer to a buffer containing the data to be signed.
514  *  @param len          The length of the data to be signed.
515  *  @param signature    A pointer to a buffer where the signature will be stored.
516  *                      The buffer must be allocated by the application, and should be at least MESHLINK_SIGLEN bytes big.
517  *                      The signature is a binary blob, and is not nul-terminated.
518  *  @param siglen       The size of the signature buffer. Will be changed after the call to match the size of the signature itself.
519  *
520  *  @return             This function returns true if the signature was correctly generated, false otherwise.
521  */
522 extern bool meshlink_sign(meshlink_handle_t *mesh, const void *data, size_t len, void *signature, size_t *siglen);
523
524 /// Get the list of all nodes by device class.
525 /** This function returns a list with handles for all the nodes that matches with the given @a devclass.
526  *
527  *  @param mesh         A handle which represents an instance of MeshLink.
528  *  @param devclass     Device class of the nodes for which the list has to be obtained.
529  *  @param nodes        A pointer to a previously allocated array of pointers to meshlink_node_t, or NULL in which case MeshLink will allocate a new array.
530  *                      The application can supply an array it allocated itself with malloc, or the return value from the previous call to this function (which is the preferred way).
531  *                      The application is allowed to call free() on the array whenever it wishes.
532  *                      The pointers in the array are valid until meshlink_close() is called.
533  *  @param nmemb        A pointer to a variable holding the number of nodes with the same @a device class that are stored in the array.
534  *                      In case the @a nodes argument is not NULL, MeshLink might call realloc() on the array to change its size.
535  *                      The contents of this variable will be changed to reflect the new size of the array.
536  *
537  *  @return             A pointer to an array containing pointers to all known nodes of the given device class, or NULL in case of an error.
538  *                      If the @a nodes argument was not NULL, then the return value can either be the same value or a different value.
539  *                      If it is a new value, the old value of @a nodes should not be used anymore.
540  *                      If the new value is NULL, then the old array will have been freed by MeshLink.
541  */
542 extern meshlink_node_t **meshlink_get_all_nodes_by_dev_class(meshlink_handle_t *mesh, dev_class_t devclass, meshlink_node_t **nodes, size_t *nmemb);
543
544 /// Get the list of all nodes by Submesh.
545 /** This function returns a list with handles for all the nodes that matches with the given @a Submesh.
546  *
547  *  @param mesh         A handle which represents an instance of MeshLink.
548  *  @param submesh      Submesh handle of the nodes for which the list has to be obtained.
549  *  @param nodes        A pointer to a previously allocated array of pointers to meshlink_node_t, or NULL in which case MeshLink will allocate a new array.
550  *                      The application can supply an array it allocated itself with malloc, or the return value from the previous call to this function (which is the preferred way).
551  *                      The application is allowed to call free() on the array whenever it wishes.
552  *                      The pointers in the array are valid until meshlink_close() is called.
553  *  @param nmemb        A pointer to a variable holding the number of nodes with the same @a device class that are stored in the array.
554  *                      In case the @a nodes argument is not NULL, MeshLink might call realloc() on the array to change its size.
555  *                      The contents of this variable will be changed to reflect the new size of the array.
556  *
557  *  @return             A pointer to an array containing pointers to all known nodes of the given Submesh, or NULL in case of an error.
558  *                      If the @a nodes argument was not NULL, then the return value can either be the same value or a different value.
559  *                      If it is a new value, the old value of @a nodes should not be used anymore.
560  *                      If the new value is NULL, then the old array will have been freed by MeshLink.
561  */
562 extern meshlink_node_t **meshlink_get_all_nodes_by_submesh(meshlink_handle_t *mesh, meshlink_submesh_t *submesh, meshlink_node_t **nodes, size_t *nmemb);
563
564 /// Get the node's device class.
565 /** This function returns the device class of the given node.
566  *
567  *  @param mesh          A handle which represents an instance of MeshLink.
568  *  @param node         A pointer to a meshlink_node_t describing the node.
569  *
570  *  @return              This function returns the device class of the @a node, or -1 in case of an error.
571  */
572 extern dev_class_t meshlink_get_node_dev_class(meshlink_handle_t *mesh, meshlink_node_t *node);
573
574 /// Get the node's submesh handle.
575 /** This function returns the submesh handle of the given node.
576  *
577  *  @param mesh          A handle which represents an instance of MeshLink.
578  *  @param node          A pointer to a meshlink_node_t describing the node.
579  *
580  *  @return              This function returns the submesh handle of the @a node, or NULL in case of an error.
581  */
582 extern meshlink_submesh_t *meshlink_get_node_submesh(meshlink_handle_t *mesh, meshlink_node_t *node);
583
584 /// Verify the signature generated by another node of a piece of data.
585 /** This function verifies the signature that another node generated for a piece of data.
586  *
587  *  @param mesh         A handle which represents an instance of MeshLink.
588  *  @param source       A pointer to a meshlink_node_t describing the source of the signature.
589  *  @param data         A pointer to a buffer containing the data to be verified.
590  *  @param len          The length of the data to be verified.
591  *  @param signature    A pointer to a buffer where the signature is stored.
592  *  @param siglen       A pointer to a variable holding the size of the signature buffer.
593  *                      The contents of the variable will be changed by meshlink_sign() to reflect the actual size of the signature.
594  *
595  *  @return             This function returns true if the signature is valid, false otherwise.
596  */
597 extern bool meshlink_verify(meshlink_handle_t *mesh, meshlink_node_t *source, const void *data, size_t len, const void *signature, size_t siglen);
598
599 /// Set the canonical Address for a node.
600 /** This function sets the canonical Address for a node.
601  *  This address is stored permanently until it is changed by another call to this function,
602  *  unlike other addresses associated with a node,
603  *  such as those added with meshlink_hint_address() or addresses discovered at runtime.
604  *
605  *  If a canonical Address is set for the local node,
606  *  it will be used for the hostname part of generated invitation URLs.
607  *
608  *  @param mesh         A handle which represents an instance of MeshLink.
609  *  @param node         A pointer to a meshlink_node_t describing the node.
610  *  @param address      A nul-terminated C string containing the address, which can be either in numeric format or a hostname.
611  *  @param port         A nul-terminated C string containing the port, which can be either in numeric or symbolic format.
612  *                      If it is NULL, the listening port's number will be used.
613  *
614  *  @return             This function returns true if the address was added, false otherwise.
615  */
616 extern bool meshlink_set_canonical_address(meshlink_handle_t *mesh, meshlink_node_t *node, const char *address, const char *port);
617
618 /// Add an Address for the local node.
619 /** This function adds an Address for the local node, which will be used for invitation URLs.
620  *
621  *  @param mesh         A handle which represents an instance of MeshLink.
622  *  @param address      A nul-terminated C string containing the address, which can be either in numeric format or a hostname.
623  *
624  *  @return             This function returns true if the address was added, false otherwise.
625  */
626 extern bool meshlink_add_address(meshlink_handle_t *mesh, const char *address);
627
628 /// Try to discover the external address for the local node.
629 /** This function performs tries to discover the local node's external address
630  *  by contacting the meshlink.io server. If a reverse lookup of the address works,
631  *  the FQDN associated with the address will be returned.
632  *
633  *  Please note that this is function only returns a single address,
634  *  even if the local node might have more than one external address.
635  *  In that case, there is no control over which address will be selected.
636  *  Also note that if you have a dynamic IP address, or are behind carrier-grade NAT,
637  *  there is no guarantee that the external address will be valid for an extended period of time.
638  *
639  *  This function is blocking. It can take several seconds before it returns.
640  *  There is no guarantee it will be able to resolve the external address.
641  *  Failures might be because by temporary network outages.
642  *
643  *  @param mesh         A handle which represents an instance of MeshLink.
644  *
645  *  @return             This function returns a pointer to a C string containing the discovered external address,
646  *                      or NULL if there was an error looking up the address.
647  *                      After meshlink_get_external_address() returns, the application is free to overwrite or free this string.
648  */
649 extern char *meshlink_get_external_address(meshlink_handle_t *mesh);
650
651 /// Try to discover the external address for the local node.
652 /** This function performs tries to discover the local node's external address
653  *  by contacting the meshlink.io server. If a reverse lookup of the address works,
654  *  the FQDN associated with the address will be returned.
655  *
656  *  Please note that this is function only returns a single address,
657  *  even if the local node might have more than one external address.
658  *  In that case, there is no control over which address will be selected.
659  *  Also note that if you have a dynamic IP address, or are behind carrier-grade NAT,
660  *  there is no guarantee that the external address will be valid for an extended period of time.
661  *
662  *  This function is blocking. It can take several seconds before it returns.
663  *  There is no guarantee it will be able to resolve the external address.
664  *  Failures might be because by temporary network outages.
665  *
666  *  @param mesh            A handle which represents an instance of MeshLink.
667  *  @param address_family  The address family to check, for example AF_INET or AF_INET6. If AF_UNSPEC is given,
668  *                         this might return the external address for any working address family.
669  *
670  *  @return                This function returns a pointer to a C string containing the discovered external address,
671  *                         or NULL if there was an error looking up the address.
672  *                         After meshlink_get_external_address_for_family() returns, the application is free to overwrite or free this string.
673  */
674 extern char *meshlink_get_external_address_for_family(meshlink_handle_t *mesh, int address_family);
675
676 /// Try to discover the local address for the local node.
677 /** This function performs tries to discover the address of the local interface used for outgoing connection.
678  *
679  *  Please note that this is function only returns a single address,
680  *  even if the interface might have more than one address.
681  *  In that case, there is no control over which address will be selected.
682  *  Also note that if you have a dynamic IP address,
683  *  there is no guarantee that the local address will be valid for an extended period of time.
684  *
685  *  This function will fail if it couldn't find a local address for the given address family.
686  *  If hostname resolving is requested, this function may block for a few seconds.
687  *
688  *  @param mesh            A handle which represents an instance of MeshLink.
689  *  @param address_family  The address family to check, for example AF_INET or AF_INET6. If AF_UNSPEC is given,
690  *                         this might return the local address for any working address family.
691  *
692  *  @return                This function returns a pointer to a C string containing the discovered local address,
693  *                         or NULL if there was an error looking up the address.
694  *                         After meshlink_get_local_address_for_family() returns, the application is free to overwrite or free this string.
695  */
696 extern char *meshlink_get_local_address_for_family(meshlink_handle_t *mesh, int address_family);
697
698 /// Try to discover the external address for the local node, and add it to its list of addresses.
699 /** This function is equivalent to:
700  *
701  *    meshlink_add_address(mesh, meshlink_get_external_address(mesh));
702  *
703  *  Read the description of meshlink_get_external_address() for the limitations of this function.
704  *
705  *  @param mesh         A handle which represents an instance of MeshLink.
706  *
707  *  @return             This function returns true if the address was added, false otherwise.
708  */
709 extern bool meshlink_add_external_address(meshlink_handle_t *mesh);
710
711 /// Get the network port used by the local node.
712 /** This function returns the network port that the local node is listening on.
713  *
714  *  @param mesh          A handle which represents an instance of MeshLink.
715  *
716  *  @return              This function returns the port number, or -1 in case of an error.
717  */
718 extern int meshlink_get_port(meshlink_handle_t *mesh);
719
720 /// Set the network port used by the local node.
721 /** This function sets the network port that the local node is listening on.
722  *  It may only be called when the mesh is not running.
723  *  If unsure, call meshlink_stop() before calling this function.
724  *  Also note that if your node is already part of a mesh with other nodes,
725  *  that the other nodes may no longer be able to initiate connections to the local node,
726  *  since they will try to connect to the previously configured port.
727  *
728  *  @param mesh          A handle which represents an instance of MeshLink.
729  *  @param port          The port number to listen on. This must be between 0 and 65535.
730  *                       If the port is set to 0, then MeshLink will listen on a port
731  *                       that is randomly assigned by the operating system every time meshlink_open() is called.
732  *
733  *  @return              This function returns true if the port was successfully changed, false otherwise.
734  */
735
736 extern bool meshlink_set_port(meshlink_handle_t *mesh, int port);
737
738 /// Set the timeout for invitations.
739 /** This function sets the timeout for invitations.
740  *  Note that timeouts are only checked at the time a node tries to join using an invitation.
741  *  The default timeout for invitations is 1 week.
742  *
743  *  @param mesh         A handle which represents an instance of MeshLink.
744  *  @param timeout      The timeout for invitations in seconds.
745  */
746 extern void meshlink_set_invitation_timeout(meshlink_handle_t *mesh, int timeout);
747
748 /// Invite another node into the mesh.
749 /** This function generates an invitation that can be used by another node to join the same mesh as the local node.
750  *  The generated invitation is a string containing a URL.
751  *  This URL should be passed by the application to the invitee in a way that no eavesdroppers can see the URL.
752  *  The URL can only be used once, after the user has joined the mesh the URL is no longer valid.
753  *
754  *  @param mesh         A handle which represents an instance of MeshLink.
755  *  @param submesh      A handle which represents an instance of SubMesh.
756  *  @param name         A nul-terminated C string containing the name that the invitee will be allowed to use in the mesh.
757  *                      After this function returns, the application is free to overwrite or free @a name.
758  *  @param flags        A bitwise-or'd combination of flags that controls how the URL is generated.
759  *
760  *  @return             This function returns a nul-terminated C string that contains the invitation URL, or NULL in case of an error.
761  *                      The application should call free() after it has finished using the URL.
762  */
763 extern char *meshlink_invite_ex(meshlink_handle_t *mesh, meshlink_submesh_t *submesh, const char *name, uint32_t flags);
764
765 /// Invite another node into the mesh.
766 /** This function generates an invitation that can be used by another node to join the same mesh as the local node.
767  *  The generated invitation is a string containing a URL.
768  *  This URL should be passed by the application to the invitee in a way that no eavesdroppers can see the URL.
769  *  The URL can only be used once, after the user has joined the mesh the URL is no longer valid.
770  *
771  *  Calling this function is equal to callen meshlink_invite_ex() with flags set to 0.
772  *
773  *  @param mesh         A handle which represents an instance of MeshLink.
774  *  @param submesh      A handle which represents an instance of SubMesh.
775  *  @param name         A nul-terminated C string containing the name that the invitee will be allowed to use in the mesh.
776  *                      After this function returns, the application is free to overwrite or free @a name.
777  *
778  *  @return             This function returns a nul-terminated C string that contains the invitation URL, or NULL in case of an error.
779  *                      The application should call free() after it has finished using the URL.
780  */
781 extern char *meshlink_invite(meshlink_handle_t *mesh, meshlink_submesh_t *submesh, const char *name);
782
783 /// Use an invitation to join a mesh.
784 /** This function allows the local node to join an existing mesh using an invitation URL generated by another node.
785  *  An invitation can only be used if the local node has never connected to other nodes before.
786  *  After a successfully accepted invitation, the name of the local node may have changed.
787  *
788  *  This function may only be called on a mesh that has not been started yet and which is not already part of an existing mesh.
789  *
790  *  This function is blocking. It can take several seconds before it returns.
791  *  There is no guarantee it will perform a successful join.
792  *  Failures might be caused by temporary network outages, or by the invitation having expired.
793  *
794  *  @param mesh         A handle which represents an instance of MeshLink.
795  *  @param invitation   A nul-terminated C string containing the invitation URL.
796  *                      After this function returns, the application is free to overwrite or free @a invitation.
797  *
798  *  @return             This function returns true if the local node joined the mesh it was invited to, false otherwise.
799  */
800 extern bool meshlink_join(meshlink_handle_t *mesh, const char *invitation);
801
802 /// Export the local node's key and addresses.
803 /** This function generates a string that contains the local node's public key and one or more IP addresses.
804  *  The application can pass it in some way to another node, which can then import it,
805  *  granting the local node access to the other node's mesh.
806  *  The exported data does not contain any secret keys, it is therefore safe to transmit this data unencrypted over public networks.
807  *
808  *  Note that to create a working connection between two nodes, both must call meshink_export() and both must meshlink_import() each other's data.
809  *
810  *  @param mesh         A handle which represents an instance of MeshLink.
811  *
812  *  @return             This function returns a nul-terminated C string that contains the exported key and addresses, or NULL in case of an error.
813  *                      The application should call free() after it has finished using this string.
814  */
815 extern char *meshlink_export(meshlink_handle_t *mesh);
816
817 /// Import another node's key and addresses.
818 /** This function accepts a string containing the exported public key and addresses of another node.
819  *  By importing this data, the local node grants the other node access to its mesh.
820  *  The application should make sure that the data it imports is really coming from the node it wants to import,
821  *
822  *  Note that to create a working connection between two nodes, both must call meshink_export() and both must meshlink_import() each other's data.
823  *
824  *  @param mesh         A handle which represents an instance of MeshLink.
825  *  @param data         A nul-terminated C string containing the other node's exported key and addresses.
826  *                      After this function returns, the application is free to overwrite or free @a data.
827  *
828  *  @return             This function returns true if the data was valid and the other node has been granted access to the mesh, false otherwise.
829  */
830 extern bool meshlink_import(meshlink_handle_t *mesh, const char *data);
831
832 /// Blacklist a node from the mesh.
833 /** This function causes the local node to blacklist another node.
834  *  The local node will drop any existing connections to that node,
835  *  and will not send data to it nor accept any data received from it any more.
836  *
837  *  @param mesh         A handle which represents an instance of MeshLink.
838  *  @param node         A pointer to a meshlink_node_t describing the node to be blacklisted.
839  */
840 extern void meshlink_blacklist(meshlink_handle_t *mesh, meshlink_node_t *node);
841
842 /// Whitelist a node on the mesh.
843 /** This function causes the local node to whitelist a previously blacklisted node.
844  *  The local node will allow connections to and from that node,
845  *  and will send data to it and accept any data received from it.
846  *
847  *  @param mesh         A handle which represents an instance of MeshLink.
848  *  @param node         A pointer to a meshlink_node_t describing the node to be whitelisted.
849  */
850 extern void meshlink_whitelist(meshlink_handle_t *mesh, meshlink_node_t *node);
851
852 /// Set whether new nodes are blacklisted by default.
853 /** This function sets the blacklist behaviour for newly discovered nodes.
854  *  If set to true, new nodes will be automatically blacklisted.
855  *  If set to false, which is the default, new nodes are automatically whitelisted.
856  *  The whitelist/blacklist status of a node may be changed afterwards with the
857  *  meshlink_whitelist() and meshlink_blacklist() functions.
858  *
859  *  @param mesh         A handle which represents an instance of MeshLink.
860  *  @param blacklist    True if new nodes are to be blacklisted, false if whitelisted.
861  */
862 extern void meshlink_set_default_blacklist(meshlink_handle_t *mesh, bool blacklist);
863
864 /// A callback for accepting incoming channels.
865 /** This function is called whenever a remote node wants to open a channel to the local node.
866  *  The application then has to decide whether to accept or reject this channel.
867  *
868  *  The callback is run in MeshLink's own thread.
869  *  It is therefore important that the callback return quickly and uses apprioriate methods (queues, pipes, locking, etc.)
870  *  to hand any data over to the application's thread.
871  *
872  *  @param mesh         A handle which represents an instance of MeshLink.
873  *  @param channel      A handle for the incoming channel.
874  *                      If the application accepts the incoming channel by returning true,
875  *                      then this handle is valid until meshlink_channel_close() is called on it.
876  *                      If the application rejects the incoming channel by returning false,
877  *                      then this handle is invalid after the callback returns
878  *                      (the callback does not need to call meshlink_channel_close() itself in this case).
879  *  @param port         The port number the peer wishes to connect to.
880  *  @param data         A pointer to a buffer containing data already received, or NULL in case no data has been received yet. (Not yet used.)
881  *                      The pointer is only valid during the lifetime of the callback.
882  *                      The callback should mempcy() the data if it needs to be available outside the callback.
883  *  @param len          The length of the data, or 0 in case no data has been received yet. (Not yet used.)
884  *
885  *  @return             This function should return true if the application accepts the incoming channel, false otherwise.
886  *                      If returning false, the channel is invalid and may not be used anymore.
887  */
888 typedef bool (*meshlink_channel_accept_cb_t)(meshlink_handle_t *mesh, meshlink_channel_t *channel, uint16_t port, const void *data, size_t len);
889
890 /// A callback for receiving data from a channel.
891 /** This function is called whenever data is received from a remote node on a channel.
892  *
893  *  This function is also called in case the channel has been closed by the remote node, or when the channel is terminated abnormally.
894  *  In both cases, @a data will be NULL and @a len will be 0, and meshlink_errno will be set.
895  *  In any case, the @a channel handle will still be valid until the application calls meshlink_close().
896  *
897  *  @param mesh         A handle which represents an instance of MeshLink.
898  *  @param channel      A handle for the channel.
899  *  @param data         A pointer to a buffer containing data sent by the source, or NULL in case of an error.
900  *                      The pointer is only valid during the lifetime of the callback.
901  *                      The callback should mempcy() the data if it needs to be available outside the callback.
902  *  @param len          The length of the data, or 0 in case of an error.
903  */
904 typedef void (*meshlink_channel_receive_cb_t)(meshlink_handle_t *mesh, meshlink_channel_t *channel, const void *data, size_t len);
905
906 /// A callback informing the application when data can be sent on a channel.
907 /** This function is called whenever there is enough free buffer space so a call to meshlink_channel_send() will succeed.
908  *
909  *  @param mesh         A handle which represents an instance of MeshLink.
910  *  @param channel      A handle for the channel.
911  *  @param len          The maximum amount of data that is guaranteed to be accepted by meshlink_channel_send(),
912  *                      or 0 in case of an error.
913  */
914 typedef void (*meshlink_channel_poll_cb_t)(meshlink_handle_t *mesh, meshlink_channel_t *channel, size_t len);
915
916 /// Set the accept callback.
917 /** This functions sets the callback that is called whenever another node sends data to the local node.
918  *  The callback is run in MeshLink's own thread.
919  *  It is therefore important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
920  *  to hand the data over to the application's thread.
921  *  The callback should also not block itself and return as quickly as possible.
922  *
923  *  If no accept callback is set, incoming channels are rejected.
924  *
925  *  @param mesh      A handle which represents an instance of MeshLink.
926  *  @param cb        A pointer to the function which will be called when another node sends data to the local node.
927  *                   If a NULL pointer is given, the callback will be disabled.
928  */
929 extern void meshlink_set_channel_accept_cb(meshlink_handle_t *mesh, meshlink_channel_accept_cb_t cb);
930
931 /// Set the receive callback.
932 /** This functions sets the callback that is called whenever another node sends data to the local node.
933  *  The callback is run in MeshLink's own thread.
934  *  It is therefore important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
935  *  to hand the data over to the application's thread.
936  *  The callback should also not block itself and return as quickly as possible.
937  *
938  *  @param mesh      A handle which represents an instance of MeshLink.
939  *  @param channel   A handle for the channel.
940  *  @param cb        A pointer to the function which will be called when another node sends data to the local node.
941  *                   If a NULL pointer is given, the callback will be disabled and incoming data is ignored.
942  */
943 extern void meshlink_set_channel_receive_cb(meshlink_handle_t *mesh, meshlink_channel_t *channel, meshlink_channel_receive_cb_t cb);
944
945 /// Set the poll callback.
946 /** This functions sets the callback that is called whenever data can be sent to another node.
947  *  The callback is run in MeshLink's own thread.
948  *  It is therefore important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
949  *  to pass data to or from the application's thread.
950  *  The callback should also not block itself and return as quickly as possible.
951  *
952  *  @param mesh      A handle which represents an instance of MeshLink.
953  *  @param channel   A handle for the channel.
954  *  @param cb        A pointer to the function which will be called when data can be sent to another node.
955  *                   If a NULL pointer is given, the callback will be disabled.
956  */
957 extern void meshlink_set_channel_poll_cb(meshlink_handle_t *mesh, meshlink_channel_t *channel, meshlink_channel_poll_cb_t cb);
958
959 /// Open a reliable stream channel to another node.
960 /** This function is called whenever a remote node wants to open a channel to the local node.
961  *  The application then has to decide whether to accept or reject this channel.
962  *
963  *  This function returns a pointer to a struct meshlink_channel that will be allocated by MeshLink.
964  *  When the application does no longer need to use this channel, it must call meshlink_close()
965  *  to free its resources.
966  *
967  *  @param mesh         A handle which represents an instance of MeshLink.
968  *  @param node         The node to which this channel is being initiated.
969  *  @param port         The port number the peer wishes to connect to.
970  *  @param cb           A pointer to the function which will be called when the remote node sends data to the local node.
971  *                      The pointer may be NULL, in which case incoming data is ignored.
972  *  @param data         A pointer to a buffer containing data to already queue for sending, or NULL if there is no data to send.
973  *                      After meshlink_send() returns, the application is free to overwrite or free this buffer.
974  *  @param len          The length of the data, or 0 if there is no data to send.
975  *  @param flags        A bitwise-or'd combination of flags that set the semantics for this channel.
976  *
977  *  @return             A handle for the channel, or NULL in case of an error.
978  *                      The handle is valid until meshlink_channel_close() is called.
979  */
980 extern meshlink_channel_t *meshlink_channel_open_ex(meshlink_handle_t *mesh, meshlink_node_t *node, uint16_t port, meshlink_channel_receive_cb_t cb, const void *data, size_t len, uint32_t flags);
981
982 /// Open a reliable stream channel to another node.
983 /** This function is called whenever a remote node wants to open a channel to the local node.
984  *  The application then has to decide whether to accept or reject this channel.
985  *
986  *  This function returns a pointer to a struct meshlink_channel that will be allocated by MeshLink.
987  *  When the application does no longer need to use this channel, it must call meshlink_close()
988  *  to free its resources.
989  *
990  *  Calling this function is equivalent to calling meshlink_channel_open_ex()
991  *  with the flags set to MESHLINK_CHANNEL_TCP.
992  *
993  *  @param mesh         A handle which represents an instance of MeshLink.
994  *  @param node         The node to which this channel is being initiated.
995  *  @param port         The port number the peer wishes to connect to.
996  *  @param cb           A pointer to the function which will be called when the remote node sends data to the local node.
997  *                      The pointer may be NULL, in which case incoming data is ignored.
998  *  @param data         A pointer to a buffer containing data to already queue for sending, or NULL if there is no data to send.
999  *                      After meshlink_send() returns, the application is free to overwrite or free this buffer.
1000  *  @param len          The length of the data, or 0 if there is no data to send.
1001  *
1002  *  @return             A handle for the channel, or NULL in case of an error.
1003  *                      The handle is valid until meshlink_channel_close() is called.
1004  */
1005 extern meshlink_channel_t *meshlink_channel_open(meshlink_handle_t *mesh, meshlink_node_t *node, uint16_t port, meshlink_channel_receive_cb_t cb, const void *data, size_t len);
1006
1007 /// Partially close a reliable stream channel.
1008 /** This shuts down the read or write side of a channel, or both, without closing the handle.
1009  *  It can be used to inform the remote node that the local node has finished sending all data on the channel,
1010  *  but still allows waiting for incoming data from the remote node.
1011  *
1012  *  Shutting down the receive direction is also possible, and is equivalent to setting the receive callback to NULL.
1013  *
1014  *  @param mesh         A handle which represents an instance of MeshLink.
1015  *  @param channel      A handle for the channel.
1016  *  @param direction    Must be one of SHUT_RD, SHUT_WR or SHUT_RDWR, otherwise this call will not have any affect.
1017  */
1018 extern void meshlink_channel_shutdown(meshlink_handle_t *mesh, meshlink_channel_t *channel, int direction);
1019
1020 /// Close a reliable stream channel.
1021 /** This informs the remote node that the local node has finished sending all data on the channel.
1022  *  It also causes the local node to stop accepting incoming data from the remote node.
1023  *  It will free the struct meshlink_channel and all associated resources.
1024  *  Afterwards, the channel handle is invalid and must not be used any more.
1025  *
1026  *  It is allowed to call this function at any time on a valid handle, even inside callback functions.
1027  *  If called with a valid handle, this function always succeeds, otherwise the result is undefined.
1028  *
1029  *  @param mesh         A handle which represents an instance of MeshLink.
1030  *  @param channel      A handle for the channel.
1031  */
1032 extern void meshlink_channel_close(meshlink_handle_t *mesh, meshlink_channel_t *channel);
1033
1034 /// Transmit data on a channel
1035 /** This queues data to send to the remote node.
1036  *
1037  *  @param mesh         A handle which represents an instance of MeshLink.
1038  *  @param channel      A handle for the channel.
1039  *  @param data         A pointer to a buffer containing data sent by the source, or NULL if there is no data to send.
1040  *                      After meshlink_send() returns, the application is free to overwrite or free this buffer.
1041  *  @param len          The length of the data, or 0 if there is no data to send.
1042  *
1043  *  @return             The amount of data that was queued, which can be less than len, or a negative value in case of an error.
1044  */
1045 extern ssize_t meshlink_channel_send(meshlink_handle_t *mesh, meshlink_channel_t *channel, const void *data, size_t len);
1046
1047 /// Get channel flags.
1048 /** This returns the flags used when opening this channel.
1049  *
1050  *  @param mesh         A handle which represents an instance of MeshLink.
1051  *  @param channel      A handle for the channel.
1052  *
1053  *  @return             The flags set for this channel.
1054  */
1055 extern uint32_t meshlink_channel_get_flags(meshlink_handle_t *mesh, meshlink_channel_t *channel);
1056
1057 /// Get the amount of bytes in the send buffer.
1058 /** This returns the amount of bytes in the send buffer.
1059  *  These bytes have not been received by the peer yet.
1060  *
1061  *  @param mesh         A handle which represents an instance of MeshLink.
1062  *  @param channel      A handle for the channel.
1063  *
1064  *  @return             The amount of un-ACKed bytes in the send buffer.
1065  */
1066 extern size_t meshlink_channel_get_sendq(meshlink_handle_t *mesh, meshlink_channel_t *channel);
1067
1068 /// Get the amount of bytes in the receive buffer.
1069 /** This returns the amount of bytes in the receive buffer.
1070  *  These bytes have not been processed by the application yet.
1071  *
1072  *  @param mesh         A handle which represents an instance of MeshLink.
1073  *  @param channel      A handle for the channel.
1074  *
1075  *  @return             The amount of bytes in the receive buffer.
1076  */
1077 extern size_t meshlink_channel_get_recvq(meshlink_handle_t *mesh, meshlink_channel_t *channel);
1078
1079 /// Hint that a hostname may be found at an address
1080 /** This function indicates to meshlink that the given hostname is likely found
1081  *  at the given IP address and port.
1082  *
1083  *  @param mesh     A handle which represents an instance of MeshLink.
1084  *  @param node     A pointer to a meshlink_node_t describing the node to add the address hint for.
1085  *  @param addr     The IP address and port which should be tried for the
1086  *                  given hostname. The caller is free to overwrite or free
1087  *                  this memory once meshlink returns.
1088  */
1089 extern void meshlink_hint_address(meshlink_handle_t *mesh, meshlink_node_t *node, const struct sockaddr *addr);
1090
1091 /// Enable or disable zeroconf discovery of local peers
1092
1093 /** This controls whether zeroconf discovery using the Catta library will be
1094  *  enabled to search for peers on the local network. By default, it is enabled.
1095  *
1096  *  @param mesh    A handle which represents an instance of MeshLink.
1097  *  @param enable  Set to true to enable discovery, false to disable.
1098  */
1099 extern void meshlink_enable_discovery(meshlink_handle_t *mesh, bool enable);
1100
1101 #ifdef __cplusplus
1102 }
1103 #endif
1104
1105 #endif