+#ifndef MESHLINK_H
+#define MESHLINK_H
+
/*
meshlink.h -- MeshLink API
- Copyright (C) 2014 Guus Sliepen <guus@meshlink.io>
+ Copyright (C) 2014, 2017 Guus Sliepen <guus@meshlink.io>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
-#ifndef MESHLINK_H
-#define MESHLINK_H
-
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
/// An edge in the meshlink network.
struct meshlink_edge {
struct meshlink_node *from; ///< Pointer to a node. Node memory is
- // owned by meshlink and should not be
- // deallocated. Node contents may be
- // changed by meshlink.
+ // owned by meshlink and should not be
+ // deallocated. Node contents may be
+ // changed by meshlink.
struct meshlink_node *to; ///< Pointer to a node. Node memory is
- // owned by meshlink and should not be
- // deallocated. Node contents may be
- // changed by meshlink.
+ // owned by meshlink and should not be
+ // deallocated. Node contents may be
+ // changed by meshlink.
struct sockaddr_storage address;///< The address information associated
- // with this edge.
+ // with this edge.
uint32_t options; ///< Edge options. @TODO what are edge options?
int weight; ///< Weight assigned to this edge.
};
* @return A pointer to a meshlink_handle_t which represents this instance of MeshLink, or NULL in case of an error.
* The pointer is valid until meshlink_close() is called.
*/
-extern meshlink_handle_t *meshlink_open(const char *confbase, const char *name, const char* appname, dev_class_t devclass);
+extern meshlink_handle_t *meshlink_open(const char *confbase, const char *name, const char *appname, dev_class_t devclass);
/// Start MeshLink.
/** This function causes MeshLink to open network sockets, make outgoing connections, and
* Also note that if you have a dynamic IP address, or are behind carrier-grade NAT,
* there is no guarantee that the external address will be valid for an extended period of time.
*
+ * This function is blocking. It can take several seconds before it returns.
+ * There is no guarantee it will be able to resolve the external address.
+ * Failures might be because by temporary network outages.
+ *
* @param mesh A handle which represents an instance of MeshLink.
*
* @return This function returns a pointer to a C string containing the discovered external address,
* An invitation can only be used if the local node has never connected to other nodes before.
* After a succesfully accepted invitation, the name of the local node may have changed.
*
+ * 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.
+ *
+ * This function is blocking. It can take several seconds before it returns.
+ * There is no guarantee it will perform a successful join.
+ * Failures might be caused by temporary network outages, or by the invitation having expired.
+ *
* @param mesh A handle which represents an instance of MeshLink.
* @param invitation A nul-terminated C string containing the invitation URL.
* After this function returns, the application is free to overwrite or free @a invitation @a.
*
* @param mesh A handle which represents an instance of MeshLink.
* @param channel A handle for the channel.
- * @param len The maximum amount of data that is guaranteed to be accepted by meshlink_channel_send().
+ * @param len The maximum amount of data that is guaranteed to be accepted by meshlink_channel_send(),
+ * or 0 in case of an error.
*/
typedef void (*meshlink_channel_poll_cb_t)(meshlink_handle_t *mesh, meshlink_channel_t *channel, size_t len);
* @param data A pointer to a buffer containing data to already queue for sending, or NULL if there is no data to send.
* After meshlink_send() returns, the application is free to overwrite or free this buffer.
* @param len The length of the data, or 0 if there is no data to send.
- * @param flags A bitwise-or'd combination of flags that set the semantics for this channel.
+ * @param flags A bitwise-or'd combination of flags that set the semantics for this channel.
*
* @return A handle for the channel, or NULL in case of an error.
* The handle is valid until meshlink_channel_close() is called.
* on the array to change its size.
* The contents of this variable will be changed to reflect
* the new size of the array.
- * @return A pointer to an array containing pointers to all known
+ * @return A pointer to an array containing pointers to all known
* edges, or NULL in case of an error.
* If the @a edges @a argument was not NULL, then the
* retun value can be either the same value or a different
*/
extern meshlink_edge_t **meshlink_get_all_edges_state(meshlink_handle_t *mesh, meshlink_edge_t **edges, size_t *nmemb);
+/// Enable or disable zeroconf discovery of local peers
+
+/** This controls whether zeroconf discovery using the Catta library will be
+ * enabled to search for peers on the local network. By default, it is enabled.
+ *
+ * @param mesh A handle which represents an instance of MeshLink.
+ * @param enable Set to true to enable discovery, false to disable.
+ */
+extern void meshlink_enable_discovery(meshlink_handle_t *mesh, bool enable);
+
#ifdef __cplusplus
}
#endif
-#endif // MESHLINK_H
+#endif