+ /// Start MeshLink.
+ /** This function causes MeshLink to open network sockets, make outgoing connections, and
+ * create a new thread, which will handle all network I/O.
+ *
+ * @return This function will return true if MeshLink has successfully started its thread, false otherwise.
+ */
+ bool start() {
+ meshlink_set_receive_cb(handle, &receive_trampoline);
+ meshlink_set_node_status_cb(handle, &node_status_trampoline);
+ meshlink_set_node_pmtu_cb(handle, &node_pmtu_trampoline);
+ meshlink_set_node_duplicate_cb(handle, &node_duplicate_trampoline);
+ meshlink_set_log_cb(handle, MESHLINK_DEBUG, &log_trampoline);
+ meshlink_set_error_cb(handle, &error_trampoline);
+ meshlink_set_blacklisted_cb(handle, &blacklisted_trampoline);
+ meshlink_set_channel_listen_cb(handle, &channel_listen_trampoline);
+ meshlink_set_channel_accept_cb(handle, &channel_accept_trampoline);
+ meshlink_set_connection_try_cb(handle, &connection_try_trampoline);
+ return meshlink_start(handle);
+ }
+
+ /// Stop MeshLink.
+ /** This function causes MeshLink to disconnect from all other nodes,
+ * close all sockets, and shut down its own thread.
+ */
+ void stop() {
+ meshlink_stop(handle);
+ }
+
+ /// Send data to another node.
+ /** This functions sends one packet of data to another node in the mesh.
+ * The packet is sent using UDP semantics, which means that
+ * the packet is sent as one unit and is received as one unit,
+ * and that there is no guarantee that the packet will arrive at the destination.
+ * The application should take care of getting an acknowledgement and retransmission if necessary.
+ *
+ * @param destination A pointer to a meshlink::node describing the destination for the data.
+ * @param data A pointer to a buffer containing the data to be sent to the source.
+ * @param len The length of the data.
+ * @return This function will return true if MeshLink has queued the message for transmission, and false otherwise.
+ * A return value of true does not guarantee that the message will actually arrive at the destination.
+ */
+ bool send(node *destination, const void *data, unsigned int len) {
+ return meshlink_send(handle, destination, data, len);
+ }
+
+ /// Get a handle for a specific node.
+ /** This function returns a handle for the node with the given name.
+ *
+ * @param name The name of the node for which a handle is requested.
+ *
+ * @return A pointer to a meshlink::node which represents the requested node,
+ * or NULL if the requested node does not exist.
+ */
+ node *get_node(const char *name) {
+ return (node *)meshlink_get_node(handle, name);
+ }
+
+ /// Get a node's reachability status.
+ /** This function returns the current reachability of a given node, and the times of the last state changes.
+ * If a given state change never happened, the time returned will be 0.
+ *
+ * @param node A pointer to a meshlink::node describing the node.
+ * @param last_reachable A pointer to a time_t variable that will be filled in with the last time the node became reachable.
+ * @param last_unreachable A pointer to a time_t variable that will be filled in with the last time the node became unreachable.
+ *
+ * @return This function returns true if the node is currently reachable, false otherwise.
+ */
+ bool get_node_reachability(node *node, time_t *last_reachable = NULL, time_t *last_unreachable = NULL) {
+ return meshlink_get_node_reachability(handle, node, last_reachable, last_unreachable);
+ }
+
+ /// Get a node's blacklist status.
+ /** This function returns the current blacklist status of a given node.
+ *
+ * @param node A pointer to a meshlink::node describing the node.
+ *
+ * @return This function returns true if the node is currently blacklisted, false otherwise.
+ */
+ bool get_node_blacklisted(node *node) {
+ return meshlink_get_node_blacklisted(handle, node);
+ }
+
+ /// Get a handle for a specific submesh.
+ /** This function returns a handle for the submesh with the given name.
+ *
+ * @param name The name of the submesh for which a handle is requested.
+ *
+ * @return A pointer to a meshlink::submesh which represents the requested submesh,
+ * or NULL if the requested submesh does not exist.
+ */
+ submesh *get_submesh(const char *name) {
+ return (submesh *)meshlink_get_submesh(handle, name);
+ }
+
+ /// Get a handle for our own node.
+ /** This function returns a handle for the local node.
+ *
+ * @return A pointer to a meshlink::node which represents the local node.
+ */
+ node *get_self() {
+ return (node *)meshlink_get_self(handle);
+ }
+
+ /// Get a list of all nodes.
+ /** This function returns a list with handles for all known nodes.
+ *
+ * @param nodes A pointer to an array of pointers to meshlink::node, which should be allocated by the application.
+ * @param nmemb The maximum number of pointers that can be stored in the nodes array.
+ *
+ * @return The number of known nodes, or -1 in case of an error.
+ * This can be larger than nmemb, in which case not all nodes were stored in the nodes array.
+ */
+ node **get_all_nodes(node **nodes, size_t *nmemb) {
+ return (node **)meshlink_get_all_nodes(handle, (meshlink_node_t **)nodes, nmemb);
+ }
+
+ /// Get a list of all nodes by blacklist status.
+ /** This function returns a list with handles for all the nodes who were either blacklisted or whitelisted.
+ *
+ * @param blacklisted If true, a list of blacklisted nodes will be returned, otherwise whitelisted nodes.
+ * @param nodes A pointer to an array of pointers to meshlink::node, which should be allocated by the application.
+ * @param nmemb The maximum number of pointers that can be stored in the nodes array.
+ *
+ * @return A pointer to an array containing pointers to all known nodes with the given blacklist status.
+ * If the @a nodes argument was not NULL, then the return value can either be the same value or a different value.
+ * If it is a new value, the old value of @a nodes should not be used anymore.
+ * If the new value is NULL, then the old array will have been freed by MeshLink.
+ */
+ node **get_all_nodes_by_blacklisted(bool blacklisted, node **nodes, size_t *nmemb) {
+ return (node **)meshlink_get_all_nodes_by_blacklisted(handle, blacklisted, (meshlink_node_t **)nodes, nmemb);
+ }
+
+ /// Sign data using the local node's MeshLink key.
+ /** This function signs data using the local node's MeshLink key.
+ * The generated signature can be securely verified by other nodes.
+ *
+ * @param data A pointer to a buffer containing the data to be signed.
+ * @param len The length of the data to be signed.
+ * @param signature A pointer to a buffer where the signature will be stored.
+ * @param siglen The size of the signature buffer. Will be changed after the call to match the size of the signature itself.
+ *
+ * @return This function returns true if the signature is valid, false otherwise.
+ */
+ bool sign(const void *data, size_t len, void *signature, size_t *siglen) {
+ return meshlink_sign(handle, data, len, signature, siglen);
+ }
+
+ /// Verify the signature generated by another node of a piece of data.
+ /** This function verifies the signature that another node generated for a piece of data.
+ *
+ * @param source A pointer to a meshlink_node_t describing the source of the signature.
+ * @param data A pointer to a buffer containing the data to be verified.
+ * @param len The length of the data to be verified.
+ * @param signature A pointer to a string containing the signature.
+ * @param siglen The size of the signature.
+ *
+ * @return This function returns true if the signature is valid, false otherwise.
+ */
+ bool verify(node *source, const void *data, size_t len, const void *signature, size_t siglen) {
+ return meshlink_verify(handle, source, data, len, signature, siglen);
+ }
+
+ /// Set the canonical Address for a node.
+ /** This function sets the canonical Address for a node.
+ * This address is stored permanently until it is changed by another call to this function,
+ * unlike other addresses associated with a node,
+ * such as those added with meshlink_hint_address() or addresses discovered at runtime.
+ *
+ * If a canonical Address is set for the local node,
+ * it will be used for the hostname part of generated invitation URLs.
+ *
+ * @param node A pointer to a meshlink_node_t describing the node.
+ * @param address A nul-terminated C string containing the address, which can be either in numeric format or a hostname.
+ * @param port A nul-terminated C string containing the port, which can be either in numeric or symbolic format.
+ * If it is NULL, the listening port's number will be used.
+ *
+ * @return This function returns true if the address was added, false otherwise.
+ */
+ bool set_canonical_address(node *node, const char *address, const char *port = NULL) {
+ return meshlink_set_canonical_address(handle, node, address, port);
+ }
+
+ /// Clear the canonical Address for a node.
+ /** This function clears the canonical Address for a node.
+ *
+ * @param node A pointer to a struct meshlink_node describing the node.
+ *
+ * @return This function returns true if the address was removed, false otherwise.
+ */
+ bool clear_canonical_address(node *node) {
+ return meshlink_clear_canonical_address(handle, node);
+ }
+
+ /// Add an invitation address for the local node.
+ /** This function adds an address for the local node, which will be used only for invitation URLs.
+ * This address is not stored permanently.
+ * Multiple addresses can be added using multiple calls to this function.
+ *
+ * @param address A nul-terminated C string containing the address, which can be either in numeric format or a hostname.
+ * @param port A nul-terminated C string containing the port, which can be either in numeric or symbolic format.
+ * If it is NULL, the listening port's number will be used.
+ *
+ * @return This function returns true if the address was added, false otherwise.
+ */
+ bool add_invitation_address(const char *address, const char *port) {
+ return meshlink_add_invitation_address(handle, address, port);
+ }
+
+ /// Clears all invitation address for the local node.
+ /** This function removes all addresses added with meshlink_add_invitation_address().
+ */
+ void clear_invitation_addresses() {
+ return meshlink_clear_invitation_addresses(handle);
+ }
+
+ /// Add an Address for the local node.
+ /** This function adds an Address for the local node, which will be used for invitation URLs.
+ * @deprecated This function is deprecated, use set_canonical_address() and/or add_invitation_address().
+ *
+ * @param address A string containing the address, which can be either in numeric format or a hostname.
+ *
+ * @return This function returns true if the address was added, false otherwise.
+ */
+ bool add_address(const char *address) __attribute__((__deprecated__("use set_canonical_address() and/or add_invitation_address() instead"))) {
+ return meshlink_set_canonical_address(handle, get_self(), address, NULL);
+ }
+
+ /** This function performs tries to discover the local node's external address
+ * by contacting the meshlink.io server. If a reverse lookup of the address works,
+ * the FQDN associated with the address will be returned.
+ *
+ * Please note that this is function only returns a single address,
+ * even if the local node might have more than one external address.
+ * In that case, there is no control over which address will be selected.
+ * 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 family The address family to check, for example AF_INET or AF_INET6. If AF_UNSPEC is given,
+ * this might return the external address for any working address family.
+ *
+ * @return This function returns a pointer to a C string containing the discovered external address,
+ * or NULL if there was an error looking up the address.
+ * After get_external_address() returns, the application is free to overwrite or free this string.
+ */
+ bool get_external_address(int family = AF_UNSPEC) {
+ return meshlink_get_external_address_for_family(handle, family);
+ }
+
+ /** This function performs tries to discover the address of the local interface used for outgoing connection.
+ *
+ * Please note that this is function only returns a single address,
+ * even if the local node might have more than one external address.
+ * In that case, there is no control over which address will be selected.
+ * 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 will fail if it couldn't find a local address for the given address family.
+ * If hostname resolving is requested, this function may block for a few seconds.
+ *
+ * @param family The address family to check, for example AF_INET or AF_INET6. If AF_UNSPEC is given,
+ * this might return the external address for any working address family.
+ *
+ * @return This function returns a pointer to a C string containing the discovered external address,
+ * or NULL if there was an error looking up the address.
+ * After get_external_address() returns, the application is free to overwrite or free this string.
+ */
+ bool get_local_address(int family = AF_UNSPEC) {
+ return meshlink_get_local_address_for_family(handle, family);
+ }
+
+ /// Try to discover the external address for the local node, and add it to its list of addresses.
+ /** This function is equivalent to:
+ *
+ * mesh->add_address(mesh->get_external_address());
+ *
+ * Read the description of get_external_address() for the limitations of this function.
+ *
+ * @return This function returns true if the address was added, false otherwise.
+ */
+ bool add_external_address() {
+ return meshlink_add_external_address(handle);
+ }
+
+ /// Get the network port used by the local node.
+ /** This function returns the network port that the local node is listening on.
+ *
+ * @return This function returns the port number, or -1 in case of an error.
+ */
+ int get_port() {
+ return meshlink_get_port(handle);
+ }
+
+ /// Set the network port used by the local node.
+ /** This function sets the network port that the local node is listening on.
+ * It may only be called when the mesh is not running.
+ * If unsure, call stop() before calling this function.
+ * Also note that if your node is already part of a mesh with other nodes,
+ * that the other nodes may no longer be able to initiate connections to the local node,
+ * since they will try to connect to the previously configured port.
+ *
+ * @param port The port number to listen on. This must be between 0 and 65535.
+ * If the port is set to 0, then MeshLink will listen on a port
+ * that is randomly assigned by the operating system every time open() is called.
+ *
+ * @return This function returns true if the port was successfully changed
+ * to the desired port, false otherwise. If it returns false, there
+ * is no guarantee that MeshLink is listening on the old port.
+ */
+ bool set_port(int port) {
+ return meshlink_set_port(handle, port);
+ }
+
+ /// Set the timeout for invitations.
+ /** This function sets the timeout for invitations.
+ * The timeout is retroactively applied to all outstanding invitations.
+ *
+ * @param timeout The timeout for invitations in seconds.
+ */
+ void set_invitation_timeout(int timeout) {
+ meshlink_set_invitation_timeout(handle, timeout);
+ }
+
+ /// Set the scheduling granularity of the application
+ /** This should be set to the effective scheduling granularity for the application.
+ * This depends on the scheduling granularity of the operating system, the application's
+ * process priority and whether it is running as realtime or not.
+ * The default value is 10000 (10 milliseconds).
+ *
+ * @param granularity The scheduling granularity of the application in microseconds.
+ */
+ void set_granularity(long granularity) {
+ meshlink_set_scheduling_granularity(handle, granularity);
+ }
+
+ /// Invite another node into the mesh.
+ /** This function generates an invitation that can be used by another node to join the same mesh as the local node.
+ * The generated invitation is a string containing a URL.
+ * This URL should be passed by the application to the invitee in a way that no eavesdroppers can see the URL.
+ * The URL can only be used once, after the user has joined the mesh the URL is no longer valid.
+ *
+ * @param submesh A handle to the submesh to put the invitee in.
+ * @param name The name that the invitee will use in the mesh.
+ * @param flags A bitwise-or'd combination of flags that controls how the URL is generated.
+ *
+ * @return This function returns a string that contains the invitation URL.
+ * The application should call free() after it has finished using the URL.
+ */
+ char *invite(submesh *submesh, const char *name, uint32_t flags = 0) {
+ return meshlink_invite_ex(handle, submesh, name, flags);
+ }
+
+ /// Use an invitation to join a mesh.
+ /** This function allows the local node to join an existing mesh using an invitation URL generated by another node.
+ * An invitation can only be used if the local node has never connected to other nodes before.
+ * After a successfully 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 invitation A string containing the invitation URL.
+ *
+ * @return This function returns true if the local node joined the mesh it was invited to, false otherwise.
+ */
+ bool join(const char *invitation) {
+ return meshlink_join(handle, invitation);
+ }