/// A struct containing all parameters used for opening a mesh.
typedef struct meshlink_open_params meshlink_open_params_t;
-/// A handle for a MeshLink sub-mesh.
-typedef struct meshlink_submesh meshlink_submesh_t;
-
/// Code of most recent error encountered.
typedef enum {
MESHLINK_OK, ///< Everything is fine
void *priv; ///< Private pointer which may be set freely by the application, and is never used or modified by MeshLink.
};
-struct meshlink_submesh {
- const char *const name; ///< Textual name of this Sub-Mesh. It is stored in a nul-terminated C string, which is allocated by MeshLink.
- void *priv; ///< Private pointer which may be set freely by the application, and is never used or modified by MeshLink.
-};
-
struct meshlink_channel {
struct meshlink_node *const node; ///< Pointer to the peer of this channel.
void *priv; ///< Private pointer which may be set freely by the application, and is never used or modified by MeshLink.
*/
struct meshlink_handle *meshlink_open_ephemeral(const char *name, const char *appname, dev_class_t devclass) __attribute__((__warn_unused_result__));
-/// Create Sub-Mesh.
-/** This function causes MeshLink to open a new Sub-Mesh network
- * create a new thread, which will handle all network I/O.
- *
- * It is allowed to call this function even if MeshLink is already started, in which case it will return true.
- *
- * \memberof meshlink_handle
- * @param mesh A handle which represents an instance of MeshLink.
- *
- * @param submesh Name of the new Sub-Mesh to create.
- *
- * @return A pointer to a struct meshlink_submesh which represents this instance of SubMesh, or NULL in case of an error.
- * The pointer is valid until meshlink_close() is called.
- */
-struct meshlink_submesh *meshlink_submesh_open(struct meshlink_handle *mesh, const char *submesh) __attribute__((__warn_unused_result__));
-
/// 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.
*/
void meshlink_set_node_status_cb(struct meshlink_handle *mesh, meshlink_node_status_cb_t cb);
-/// A callback reporting node path MTU changes.
-/** @param mesh A handle which represents an instance of MeshLink.
- * @param node A pointer to a struct meshlink_node describing the node whose status changed.
- * This pointer is valid until meshlink_close() is called.
- * @param pmtu The current path MTU to the node, or 0 if UDP communication is not (yet) possible.
- */
-typedef void (*meshlink_node_pmtu_cb_t)(struct meshlink_handle *mesh, struct meshlink_node *node, uint16_t pmtu);
-
-/// Set the node extended status callback.
-/** This functions sets the callback that is called whenever certain connectivity parameters for a node change.
- * The callback is run in MeshLink's own thread.
- * It is therefore important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
- * to hand the data over to the application's thread.
- * The callback should also not block itself and return as quickly as possible.
- *
- * \memberof meshlink_handle
- * @param mesh A handle which represents an instance of MeshLink.
- * @param cb A pointer to the function which will be called when another node's extended status changes.
- * If a NULL pointer is given, the callback will be disabled.
- */
-void meshlink_set_node_pmtu_cb(struct meshlink_handle *mesh, meshlink_node_pmtu_cb_t cb);
-
/// A callback reporting duplicate node detection.
/** @param mesh A handle which represents an instance of MeshLink.
* @param node A pointer to a struct meshlink_node describing the node which is duplicate.
* 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.
* 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.
- * The application should not send packets that are larger than the path MTU, which can be queried with meshlink_get_pmtu().
* The application should take care of getting an acknowledgement and retransmission if necessary.
*
* \memberof meshlink_node
*/
bool meshlink_send(struct meshlink_handle *mesh, struct meshlink_node *destination, const void *data, size_t len) __attribute__((__warn_unused_result__));
-/// Query the maximum packet size that can be sent to a node.
-/** This functions returns the maximum size of packets (path MTU) that can be sent to a specific node with meshlink_send().
- * The path MTU is a property of the path packets will take to the destination node over the Internet.
- * It can be different for different destination nodes.
- * and the path MTU can change at any point in time due to changes in the Internet.
- * Therefore, although this should only occur rarely, it can still happen that packets that do not exceed this size get dropped.
- *
- * \memberof meshlink_node
- * @param mesh A handle which represents an instance of MeshLink.
- * @param destination A pointer to a struct meshlink_node describing the destination for the data.
- *
- * @return The recommended maximum size of packets that are to be sent to the destination node, 0 if the node is unreachable,
- * or a negative value in case of an error.
- */
-ssize_t meshlink_get_pmtu(struct meshlink_handle *mesh, struct meshlink_node *destination) __attribute__((__warn_unused_result__));
-
/// Get a handle for our own node.
/** This function returns a handle for the local node.
*
*/
struct meshlink_node *meshlink_get_node(struct meshlink_handle *mesh, const char *name) __attribute__((__warn_unused_result__));
-/// Get a handle for a specific submesh.
-/** This function returns a handle for the submesh with the given name.
- *
- * \memberof meshlink_handle
- * @param mesh A handle which represents an instance of MeshLink.
- * @param name The name of the submesh for which a handle is requested.
- * After this function returns, the application is free to overwrite or free @a name.
- *
- * @return A pointer to a struct meshlink_submesh which represents the requested submesh,
- * or NULL if the requested submesh does not exist.
- * The pointer is guaranteed to be valid until meshlink_close() is called.
- */
-struct meshlink_submesh *meshlink_get_submesh(struct meshlink_handle *mesh, const char *name) __attribute__((__warn_unused_result__));
-
/// Get the fingerprint of a node's public key.
/** This function returns a fingerprint of the node's public key.
* It should be treated as an opaque blob.
*/
struct meshlink_node **meshlink_get_all_nodes_by_dev_class(struct meshlink_handle *mesh, dev_class_t devclass, struct meshlink_node **nodes, size_t *nmemb) __attribute__((__warn_unused_result__));
-/// Get the list of all nodes by Submesh.
-/** This function returns a list with handles for all the nodes that matches with the given @a Submesh.
- *
- * \memberof meshlink_submesh
- * @param mesh A handle which represents an instance of MeshLink.
- * @param submesh Submesh handle of the nodes for which the list has to be obtained.
- * @param nodes A pointer to a previously allocated array of pointers to struct meshlink_node, or NULL in which case MeshLink will allocate a new array.
- * 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).
- * The application is allowed to call free() on the array whenever it wishes.
- * The pointers in the array are valid until meshlink_close() is called.
- * @param nmemb A pointer to a variable holding the number of nodes with the same @a device class that are stored in the array.
- * In case the @a nodes argument is not NULL, MeshLink might call realloc() 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 nodes of the given Submesh, or NULL in case of an error.
- * 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.
- */
-struct meshlink_node **meshlink_get_all_nodes_by_submesh(struct meshlink_handle *mesh, struct meshlink_submesh *submesh, struct meshlink_node **nodes, size_t *nmemb) __attribute__((__warn_unused_result__));
-
/// Get the list of all nodes by time they were last reachable.
/** This function returns a list with handles for all the nodes whose last known reachability time overlaps with the given time range.
* If the range includes 0, it will count nodes that were never online.
*/
dev_class_t meshlink_get_node_dev_class(struct meshlink_handle *mesh, struct meshlink_node *node) __attribute__((__warn_unused_result__));
-/// Get the node's submesh handle.
-/** This function returns the submesh handle of the given node.
- *
- * \memberof meshlink_node
- * @param mesh A handle which represents an instance of MeshLink.
- * @param node A pointer to a struct meshlink_node describing the node.
- *
- * @return This function returns the submesh handle of the @a node, or NULL in case of an error.
- */
-struct meshlink_submesh *meshlink_get_node_submesh(struct meshlink_handle *mesh, struct meshlink_node *node) __attribute__((__warn_unused_result__));
-
/// 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.
*/
bool meshlink_clear_canonical_address(struct meshlink_handle *mesh, struct meshlink_node *node) __attribute__((__warn_unused_result__));
-/// 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 meshlink_set_canonical_address() and/or meshlink_add_invitation_address().
- *
- * \memberof meshlink_handle
- * @param mesh A handle which represents an instance of MeshLink.
- * @param address A nul-terminated C 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 meshlink_add_address(struct meshlink_handle *mesh, const char *address) __attribute__((__warn_unused_result__, __deprecated__("use meshlink_set_canonical_address() and/or meshlink_add_invitation_address() instead")));
-
-/// Try to discover the external address for the local node.
-/** 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.
- *
- * \memberof meshlink_handle
- * @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,
- * or NULL if there was an error looking up the address.
- * After meshlink_get_external_address() returns, the application is free to overwrite or free this string.
- */
-char *meshlink_get_external_address(struct meshlink_handle *mesh) __attribute__((__warn_unused_result__));
-
-/// Try to discover the external address for the local node.
-/** 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.
- *
- * \memberof meshlink_handle
- * @param mesh A handle which represents an instance of MeshLink.
- * @param address_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 meshlink_get_external_address_for_family() returns, the application is free to overwrite or free this string.
- */
-char *meshlink_get_external_address_for_family(struct meshlink_handle *mesh, int address_family) __attribute__((__warn_unused_result__));
-
-/// Try to discover the local address for the local node.
-/** 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 interface might have more than one address.
- * In that case, there is no control over which address will be selected.
- * Also note that if you have a dynamic IP address,
- * there is no guarantee that the local 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.
- *
- * \memberof meshlink_handle
- * @param mesh A handle which represents an instance of MeshLink.
- * @param address_family The address family to check, for example AF_INET or AF_INET6. If AF_UNSPEC is given,
- * this might return the local address for any working address family.
- *
- * @return This function returns a pointer to a C string containing the discovered local address,
- * or NULL if there was an error looking up the address.
- * After meshlink_get_local_address_for_family() returns, the application is free to overwrite or free this string.
- */
-char *meshlink_get_local_address_for_family(struct meshlink_handle *mesh, int address_family) __attribute__((__warn_unused_result__));
-
-/// Try to discover the external address for the local node, and add it to its list of addresses.
-/** This function is equivalent to:
- *
- * meshlink_set_canonical_address(mesh, meshlink_get_self(mesh), meshlink_get_external_address(mesh), NULL);
- *
- * Read the description of meshlink_get_external_address() for the limitations of this function.
- *
- * \memberof meshlink_handle
- * @param mesh A handle which represents an instance of MeshLink.
- *
- * @return This function returns true if the address was added, false otherwise.
- */
-bool meshlink_add_external_address(struct meshlink_handle *mesh) __attribute__((__warn_unused_result__));
-
-/// Get the network port used by the local node.
-/** This function returns the network port that the local node is listening on.
- *
- * \memberof meshlink_handle
- * @param mesh A handle which represents an instance of MeshLink.
- *
- * @return This function returns the port number, or -1 in case of an error.
- */
-int meshlink_get_port(struct meshlink_handle *mesh) __attribute__((__warn_unused_result__));
-
-/// 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 meshlink_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.
- *
- * Note that if a canonical address has been set for the local node,
- * you might need to call meshlink_set_canonical_address() again to ensure it includes the new port number.
- *
- * \memberof meshlink_handle
- * @param mesh A handle which represents an instance of MeshLink.
- * @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 meshlink_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 meshlink_set_port(struct meshlink_handle *mesh, int port) __attribute__((__warn_unused_result__));
-
/** 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.
*/
void meshlink_hint_address(struct meshlink_handle *mesh, struct meshlink_node *node, const struct sockaddr *addr);
-/// 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.
- *
- * \memberof meshlink_handle
- * @param mesh A handle which represents an instance of MeshLink.
- * @param enable Set to true to enable discovery, false to disable.
- */
-void meshlink_enable_discovery(struct meshlink_handle *mesh, bool 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,
*/
void meshlink_set_inviter_commits_first(struct meshlink_handle *mesh, bool 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.
- *
- * \memberof meshlink_handle
- * @param mesh A handle which represents an instance of MeshLink.
- * @param url The URL to use for external address queries, or NULL to revert back to the default URL.
- */
-void meshlink_set_external_address_discovery_url(struct meshlink_handle *mesh, const char *url);
-
/// 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
projects / meshlink-tiny / blobdiff