X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=8ec7b50835fedbadb94704a871689ebffc7dc471;hb=2fd608c4111ef4d48a649401d918f5981856cc44;hp=b4fb16c9f2f7edaec5051bc2a6417b8df8e91a4d;hpb=1f9c1231139d2a93ef4ace9891013d2c23cdf4ae;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index b4fb16c9..8ec7b508 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -66,7 +66,7 @@ typedef enum { MESHLINK_EEXIST, ///< Node already exists MESHLINK_EINTERNAL, ///< MeshLink internal error MESHLINK_ERESOLV, ///< MeshLink could not resolve a hostname - MESHLINK_ESTORAGE, ///< MeshLink coud not load or write data from/to disk + MESHLINK_ESTORAGE, ///< MeshLink could not load or write data from/to disk MESHLINK_ENETWORK, ///< MeshLink encountered a network error MESHLINK_EPEER, ///< A peer caused an error MESHLINK_ENOTSUP, ///< The operation is not supported in the current configuration of MeshLink @@ -101,7 +101,7 @@ static const uint32_t MESHLINK_CHANNEL_UDP = 0; // Select UDP semantics. /** This is a thread local variable that contains the error code of the most recent error * encountered by a MeshLink API function called in the current thread. * The variable is only updated when an error is encountered, and is not reset to MESHLINK_OK - * if a function returned succesfully. + * if a function returned successfully. */ extern __thread meshlink_errno_t meshlink_errno; @@ -237,7 +237,7 @@ meshlink_submesh_t *meshlink_submesh_open(meshlink_handle_t *mesh, const char * * * @param mesh A handle which represents an instance of MeshLink. * - * @return This function will return true if MeshLink has succesfully started, false otherwise. + * @return This function will return true if MeshLink has successfully started, false otherwise. */ extern bool meshlink_start(meshlink_handle_t *mesh); @@ -273,7 +273,7 @@ extern void meshlink_close(meshlink_handle_t *mesh); * @param confbase The directory in which MeshLink stores its configuration files. * After the function returns, the application is free to overwrite or free @a confbase. * - * @return This function will return true if the MeshLink instance was succesfully destroyed, false otherwise. + * @return This function will return true if the MeshLink instance was successfully destroyed, false otherwise. */ extern bool meshlink_destroy(const char *confbase); @@ -300,6 +300,26 @@ typedef void (*meshlink_receive_cb_t)(meshlink_handle_t *mesh, meshlink_node_t * */ extern void meshlink_set_receive_cb(meshlink_handle_t *mesh, meshlink_receive_cb_t cb); +/// A callback reporting the meta-connection attempt made by the host node to an another node. +/** @param mesh A handle which represents an instance of MeshLink. + * @param node A pointer to a meshlink_node_t describing the node to whom meta-connection is being tried. + * This pointer is valid until meshlink_close() is called. + */ +typedef void (*meshlink_connection_try_cb_t)(meshlink_handle_t *mesh, meshlink_node_t *node); + +/// Set the meta-connection try callback. +/** This functions sets the callback that is called whenever a connection attempt is happened to another node. + * 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. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param cb A pointer to the function which will be called when host node attempts to make + * the connection to another node. If a NULL pointer is given, the callback will be disabled. + */ +extern void meshlink_set_connection_try_cb(meshlink_handle_t *mesh, meshlink_connection_try_cb_t cb); + /// A callback reporting node status changes. /** @param mesh A handle which represents an instance of MeshLink. * @param node A pointer to a meshlink_node_t describing the node whose status changed. @@ -441,6 +461,19 @@ extern meshlink_node_t *meshlink_get_self(meshlink_handle_t *mesh); */ extern meshlink_node_t *meshlink_get_node(meshlink_handle_t *mesh, const char *name); +/// Get a handle for a specific submesh. +/** This function returns a handle for the submesh with the given name. + * + * @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 @a. + * + * @return A pointer to a meshlink_submesh_t 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. + */ +extern meshlink_submesh_t *meshlink_get_submesh(meshlink_handle_t *mesh, const char *name); + /// 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. @@ -697,7 +730,7 @@ extern int meshlink_get_port(meshlink_handle_t *mesh); * 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 succesfully changed, false otherwise. + * @return This function returns true if the port was successfully changed, false otherwise. */ extern bool meshlink_set_port(meshlink_handle_t *mesh, int port); @@ -750,7 +783,7 @@ extern char *meshlink_invite(meshlink_handle_t *mesh, meshlink_submesh_t *submes /// 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 succesfully accepted invitation, the name of the local node may have changed. + * 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. * @@ -1021,6 +1054,28 @@ extern ssize_t meshlink_channel_send(meshlink_handle_t *mesh, meshlink_channel_t */ extern uint32_t meshlink_channel_get_flags(meshlink_handle_t *mesh, meshlink_channel_t *channel); +/// Get the amount of bytes in the send buffer. +/** This returns the amount of bytes in the send buffer. + * These bytes have not been received by the peer yet. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param channel A handle for the channel. + * + * @return The amount of un-ACKed bytes in the send buffer. + */ +extern size_t meshlink_channel_get_sendq(meshlink_handle_t *mesh, meshlink_channel_t *channel); + +/// Get the amount of bytes in the receive buffer. +/** This returns the amount of bytes in the receive buffer. + * These bytes have not been processed by the application yet. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param channel A handle for the channel. + * + * @return The amount of bytes in the receive buffer. + */ +extern size_t meshlink_channel_get_recvq(meshlink_handle_t *mesh, meshlink_channel_t *channel); + /// Hint that a hostname may be found at an address /** This function indicates to meshlink that the given hostname is likely found * at the given IP address and port.