X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink%2B%2B.h;h=8287e0382632777df5d4c0f1a7e59d4c398259ad;hb=HEAD;hp=b88746e39a548ba356c88a470a93849674c21168;hpb=0b08024d7834a915163a7b6a298ca109cf03db8c;p=meshlink diff --git a/src/meshlink++.h b/src/meshlink++.h index b88746e3..9e97fc82 100644 --- a/src/meshlink++.h +++ b/src/meshlink++.h @@ -79,6 +79,15 @@ typedef void (*duplicate_cb_t)(mesh *mesh, node *node); */ typedef void (*log_cb_t)(mesh *mesh, log_level_t level, const char *text); +/// A callback for listening for incoming channels. +/** @param mesh A handle which represents an instance of MeshLink. + * @param node A handle for the node that wants to open a channel. + * @param port The port number the peer wishes to connect to. + * + * @return This function should return true if the application listens for the incoming channel, false otherwise. + */ +typedef bool (*meshlink_channel_listen_cb_t)(struct meshlink_handle *mesh, struct meshlink_node *node, uint16_t port); + /// A callback for accepting incoming channels. /** @param mesh A handle which represents an instance of MeshLink. * @param channel A handle for the incoming channel. @@ -259,12 +268,49 @@ public: (void)message; } + /// This functions is called whenever MeshLink has encountered a serious error. + virtual void error(meshlink_errno_t meshlink_errno) { + /* do nothing */ + (void)meshlink_errno; + } + + /// This functions is called whenever MeshLink is blacklisted by another node. + virtual void blacklisted(node *peer) { + /* do nothing */ + (void)peer; + } + + /// This functions is called whenever the MeshLink thread status changes. + virtual void thread_status(bool status) { + /* do nothing */ + (void)status; + } + /// This functions is called whenever MeshLink a meta-connection attempt is made. virtual void connection_try(node *peer) { /* do nothing */ (void)peer; } + /// This functions is called to determine if we are listening for incoming channels. + /** + * The function is run in MeshLink's own thread. + * It is therefore important that the callback uses apprioriate methods (queues, pipes, locking, etc.) + * to pass data to or from the application's thread. + * The callback should also not block itself and return as quickly as possible. + * + * @param node A handle for the node that wants to open a channel. + * @param port The port number the peer wishes to connect to. + * + * @return This function should return true if the application accepts the incoming channel, false otherwise. + */ + virtual bool channel_listen(node *node, uint16_t port) { + /* by default accept all channels */ + (void)node; + (void)port; + return true; + } + /// This functions is called whenever another node attempts to open a channel to the local node. /** * If the channel is accepted, the poll_callback will be set to channel_poll and can be @@ -339,6 +385,10 @@ public: 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_thread_status_cb(handle, &thread_status_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); @@ -381,6 +431,43 @@ public: 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 the node's tiny status. + /** This function returns true if the given node is a tiny node. + * Note that the tiny status of a node will only be known if the node has been reachable at least once. + * + * @param node A pointer to a meshlink::node describing the node. + * + * @return This function returns true if the node is a tiny node. + */ + bool get_node_tiny(node *node) { + return meshlink_get_node_tiny(handle, node); + } + /// Get a handle for a specific submesh. /** This function returns a handle for the submesh with the given name. * @@ -415,6 +502,22 @@ public: 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. @@ -465,11 +568,21 @@ public: return meshlink_set_canonical_address(handle, node, address, port); } - /// Set the canonical Address for the local node. - /** This function sets the canonical Address for the local 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. + /// 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. @@ -477,19 +590,27 @@ public: * * @return This function returns true if the address was added, false otherwise. */ - bool set_canonical_address(const char *address, const char *port = NULL) { - return meshlink_set_canonical_address(handle, get_self(), address, port); + 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) { - return meshlink_add_address(handle, address); + 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 @@ -591,6 +712,31 @@ public: 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); + } + + /// Sets the storage policy used by MeshLink + /** This sets the policy MeshLink uses when it has new information about nodes. + * By default, all udpates will be stored to disk (unless an ephemeral instance has been opened). + * Setting the policy to MESHLINK_STORAGE_KEYS_ONLY, only updates that contain new keys for nodes + * are stored, as well as blacklist/whitelist settings. + * By setting the policy to MESHLINK_STORAGE_DISABLED, no updates will be stored. + * + * @param policy The storage policy to use. + */ + void set_storage_policy(meshlink_storage_policy_t policy) { + meshlink_set_storage_policy(handle, policy); + } + /// 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. @@ -651,17 +797,87 @@ public: return meshlink_import(handle, data); } + /// Forget any information about a node. + /** This function allows the local node to forget any information it has about a node, + * and if possible will remove any data it has stored on disk about the node. + * + * Any open channels to this node must be closed before calling this function. + * + * After this call returns, the node handle is invalid and may no longer be used, regardless + * of the return value of this call. + * + * Note that this function does not prevent MeshLink from actually forgetting about a node, + * or re-learning information about a node at a later point in time. It is merely a hint that + * the application does not care about this node anymore and that any resources kept could be + * cleaned up. + * + * \memberof meshlink_node + * @param node A pointer to a struct meshlink_node describing the node to be forgotten. + * + * @return This function returns true if all currently known data about the node has been forgotten, false otherwise. + */ + bool forget_node(node *node) { + return meshlink_forget_node(handle, node); + } + /// Blacklist a node from the mesh. /** This function causes the local node to blacklist another node. * The local node will drop any existing connections to that node, * and will not send data to it nor accept any data received from it any more. * * @param node A pointer to a meshlink::node describing the node to be blacklisted. + * + * @return This function returns true if the node has been whitelisted, false otherwise. */ - void blacklist(node *node) { + bool blacklist(node *node) { return meshlink_blacklist(handle, node); } + /// Blacklist a node from the mesh by name. + /** This function causes the local node to blacklist another node by name. + * The local node will drop any existing connections to that node, + * and will not send data to it nor accept any data received from it any more. + * + * If no node by the given name is known, it is created. + * + * @param name The name of the node to blacklist. + * + * @return This function returns true if the node has been blacklisted, false otherwise. + */ + bool blacklist_by_name(const char *name) { + return meshlink_blacklist_by_name(handle, name); + } + + /// Whitelist a node on the mesh. + /** This function causes the local node to whitelist another node. + * The local node will allow connections to and from that node, + * and will send data to it and accept any data received from it. + * + * @param node A pointer to a meshlink::node describing the node to be whitelisted. + * + * @return This function returns true if the node has been whitelisted, false otherwise. + */ + bool whitelist(node *node) { + return meshlink_whitelist(handle, node); + } + + /// Whitelist a node on the mesh by name. + /** This function causes the local node to whitelist a node by name. + * The local node will allow connections to and from that node, + * and will send data to it and accept any data received from it. + * + * If no node by the given name is known, it is created. + * This is useful if new nodes are blacklisted by default. + * + * \memberof meshlink_node + * @param name The name of the node to whitelist. + * + * @return This function returns true if the node has been whitelisted, false otherwise. + */ + bool whitelist_by_name(const char *name) { + return meshlink_whitelist_by_name(handle, name); + } + /// Set the poll callback. /** This functions sets the callback that is called whenever data can be sent to another node. * The callback is run in MeshLink's own thread. @@ -701,6 +917,55 @@ public: meshlink_set_channel_rcvbuf(handle, channel, size); } + /// Set the flags of a channel. + /** This function allows changing some of the channel flags. + * Currently only MESHLINK_CHANNEL_NO_PARTIAL and MESHLINK_CHANNEL_DROP_LATE are supported, other flags are ignored. + * These flags only affect the local side of the channel with the peer. + * The changes take effect immediately. + * + * @param channel A handle for the channel. + * @param flags A bitwise-or'd combination of flags that set the semantics for this channel. + */ + void set_channel_flags(channel *channel, uint32_t flags) { + meshlink_set_channel_flags(handle, channel, flags); + } + + /// Set the send buffer storage of a channel. + /** This function provides MeshLink with a send buffer allocated by the application. + * + * @param channel A handle for the channel. + * @param buf A pointer to the start of the buffer. + * If a NULL pointer is given, MeshLink will use its own internal buffer again. + * @param size The size of the buffer. + */ + void set_channel_sndbuf_storage(channel *channel, void *buf, size_t size) { + meshlink_set_channel_sndbuf_storage(handle, channel, buf, size); + } + + /// Set the receive buffer storage of a channel. + /** This function provides MeshLink with a receive buffer allocated by the application. + * + * @param channel A handle for the channel. + * @param buf A pointer to the start of the buffer. + * If a NULL pointer is given, MeshLink will use its own internal buffer again. + * @param size The size of the buffer. + */ + void set_channel_rcvbuf_storage(channel *channel, void *buf, size_t size) { + meshlink_set_channel_rcvbuf_storage(handle, channel, buf, size); + } + + /// Set the connection timeout used for channels to the given node. + /** This sets the timeout after which unresponsive channels will be reported as closed. + * The timeout is set for all current and future channels to the given node. + * + * @param node The node to set the channel timeout for. + * @param timeout The timeout in seconds after which unresponsive channels will be reported as closed. + * The default is 60 seconds. + */ + void set_node_channel_timeout(node *node, int timeout) { + meshlink_set_node_channel_timeout(handle, node, timeout); + } + /// Open a reliable stream channel to another node. /** This function is called whenever a remote node wants to open a channel to the local node. * The application then has to decide whether to accept or reject this channel. @@ -713,6 +978,7 @@ public: * @param cb A pointer to the function which will be called when the remote node sends data to the local node. * @param data A pointer to a buffer containing data to already queue for sending. * @param len The length of the data. + * If len is 0, the data pointer is copied into the channel's priv member. * @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. @@ -737,6 +1003,7 @@ public: * @param port The port number the peer wishes to connect to. * @param data A pointer to a buffer containing data to already queue for sending. * @param len The length of the data. + * If len is 0, the data pointer is copied into the channel's priv member. * @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. @@ -764,12 +1031,30 @@ public: * It also causes the local node to stop accepting incoming data from the remote node. * Afterwards, the channel handle is invalid and must not be used any more. * + * It is allowed to call this function at any time on a valid handle, even inside callback functions. + * If called with a valid handle, this function always succeeds, otherwise the result is undefined. + * * @param channel A handle for the channel. */ void channel_close(meshlink_channel_t *channel) { return meshlink_channel_close(handle, channel); } + /// Abort a reliable stream channel. + /** This aborts a channel. + * Data that was in the send and receive buffers is dropped, so potentially there is some data that + * was sent on this channel that will not be received by the peer. + * Afterwards, the channel handle is invalid and must not be used any more. + * + * It is allowed to call this function at any time on a valid handle, even inside callback functions. + * If called with a valid handle, this function always succeeds, otherwise the result is undefined. + * + * @param channel A handle for the channel. + */ + void channel_abort(meshlink_channel_t *channel) { + return meshlink_channel_abort(handle, channel); + } + /// Transmit data on a channel /** This queues data to send to the remote node. * @@ -881,6 +1166,17 @@ public: return meshlink_channel_get_recvq(handle, channel); } + /// Get the maximum segment size of a channel. + /** This returns the amount of bytes that can be sent at once for channels with UDP semantics. + * + * @param channel A handle for the channel. + * + * @return The amount of bytes in the receive buffer. + */ + size_t channel_get_mss(channel *channel) { + return meshlink_channel_get_mss(handle, channel); + }; + /// 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. @@ -891,6 +1187,15 @@ public: meshlink_enable_discovery(handle, enable); } + /// Inform MeshLink that the local network configuration might have changed + /** This is intended to be used when there is no way for MeshLink to get notifications of local network changes. + * It forces MeshLink to scan all network interfaces for changes in up/down status and new/removed addresses, + * and will immediately check if all connections to other nodes are still alive. + */ + void hint_network_change() { + meshlink_hint_network_change(handle); + } + /// Set device class timeouts /** This sets the ping interval and timeout for a given device class. * @@ -899,7 +1204,52 @@ public: * @param pingtimeout The required time within which a peer should respond, in seconds. The default is 5. * The timeout must be smaller than the interval. */ - void set_dev_class_timeouts(dev_class_t devclass, int pinginterval, int pingtimeout); + void set_dev_class_timeouts(dev_class_t devclass, int pinginterval, int pingtimeout) { + meshlink_set_dev_class_timeouts(handle, devclass, pinginterval, pingtimeout); + } + + /// Set device class fast retry period + /** This sets the fast retry period for a given device class. + * During this period after the last time the mesh becomes unreachable, connections are tried once a second. + * + * @param devclass The device class to update + * @param fast_retry_period The period during which fast connection retries are done. The default is 0. + */ + void set_dev_class_fast_retry_period(dev_class_t devclass, int fast_retry_period) { + meshlink_set_dev_class_fast_retry_period(handle, devclass, fast_retry_period); + } + + /// Set device class maximum timeout + /** This sets the maximum timeout for outgoing connection retries for a given device class. + * + * @param devclass The device class to update + * @param maxtimeout The maximum timeout between reconnection attempts, in seconds. The default is 900. + */ + void set_dev_class_maxtimeout(dev_class_t devclass, int maxtimeout) { + meshlink_set_dev_class_maxtimeout(handle, devclass, maxtimeout); + } + + /// Set which order invitations are committed + /** This determines in which order configuration files are written to disk during an invitation. + * By default, the invitee saves the configuration to disk first, then the inviter. + * By calling this function with @a inviter_commits_first set to true, the order is reversed. + * + * @param inviter_commits_first If true, then the node that invited a peer will commit data to disk first. + */ + void set_inviter_commits_first(bool inviter_commits_first) { + meshlink_set_inviter_commits_first(handle, inviter_commits_first); + } + + /// Set the URL used to discover the host's external address + /** For generating invitation URLs, MeshLink can look up the externally visible address of the local node. + * It does so by querying an external service. By default, this is http://meshlink.io/host.cgi. + * Only URLs starting with http:// are supported. + * + * @param url The URL to use for external address queries, or NULL to revert back to the default URL. + */ + void set_external_address_discovery_url(const char *url) { + meshlink_set_external_address_discovery_url(handle, url); + } private: // non-copyable: @@ -952,6 +1302,33 @@ private: that->log(level, message); } + static void error_trampoline(meshlink_handle_t *handle, meshlink_errno_t meshlink_errno) { + if(!(handle->priv)) { + return; + } + + meshlink::mesh *that = static_cast(handle->priv); + that->error(meshlink_errno); + } + + static void blacklisted_trampoline(meshlink_handle_t *handle, meshlink_node_t *peer) { + if(!(handle->priv)) { + return; + } + + meshlink::mesh *that = static_cast(handle->priv); + that->blacklisted(static_cast(peer)); + } + + static void thread_status_trampoline(meshlink_handle_t *handle, bool status) { + if(!(handle->priv)) { + return; + } + + meshlink::mesh *that = static_cast(handle->priv); + that->thread_status(status); + } + static void connection_try_trampoline(meshlink_handle_t *handle, meshlink_node_t *peer) { if(!(handle->priv)) { return; @@ -961,6 +1338,15 @@ private: that->connection_try(static_cast(peer)); } + static bool channel_listen_trampoline(meshlink_handle_t *handle, meshlink_node_t *node, uint16_t port) { + if(!(handle->priv)) { + return false; + } + + meshlink::mesh *that = static_cast(handle->priv); + return that->channel_listen(static_cast(node), port); + } + static bool channel_accept_trampoline(meshlink_handle_t *handle, meshlink_channel *channel, uint16_t port, const void *data, size_t len) { if(!(handle->priv)) { return false;