X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=be929c29e23680657e14a095064ac652b22ff66e;hb=185a8731839551fc9df7059ac374be5f5e35c086;hp=7e82cb0dfcc508bd1ed78a145a60cd4220327eb4;hpb=c57467057e46be7a2df6534f205c5edc80c9384c;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index 7e82cb0d..be929c29 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -1,6 +1,9 @@ +#ifndef MESHLINK_H +#define MESHLINK_H + /* meshlink.h -- MeshLink API - Copyright (C) 2014 Guus Sliepen + Copyright (C) 2014, 2017 Guus Sliepen 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 @@ -17,9 +20,6 @@ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ -#ifndef MESHLINK_H -#define MESHLINK_H - #include #include #include @@ -77,6 +77,14 @@ typedef enum { _DEV_CLASS_MAX = 3 } dev_class_t; +/// Channel flags +static const uint32_t MESHLINK_CHANNEL_RELIABLE = 1; // Data is retransmitted when packets are lost. +static const uint32_t MESHLINK_CHANNEL_ORDERED = 2; // Data is delivered in-order to the application. +static const uint32_t MESHLINK_CHANNEL_FRAMED = 4; // Data is delivered in chunks of the same length as data was originally sent. +static const uint32_t MESHLINK_CHANNEL_DROP_LATE = 8; // When packets are reordered, late packets are ignored. +static const uint32_t MESHLINK_CHANNEL_TCP = 3; // Select TCP semantics. +static const uint32_t MESHLINK_CHANNEL_UDP = 0; // Select UDP semantics. + /// A variable holding the last encountered error from MeshLink. /** 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. @@ -107,15 +115,15 @@ struct meshlink_channel { /// 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. }; @@ -158,7 +166,7 @@ extern const char *meshlink_strerror(meshlink_errno_t err); * @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 @@ -435,6 +443,10 @@ extern bool meshlink_add_address(meshlink_handle_t *mesh, const char *address); * 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, @@ -503,6 +515,12 @@ extern char *meshlink_invite(meshlink_handle_t *mesh, const char *name); * 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. @@ -620,7 +638,8 @@ typedef void (*meshlink_channel_receive_cb_t)(meshlink_handle_t *mesh, meshlink_ * * @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); @@ -667,6 +686,29 @@ extern void meshlink_set_channel_receive_cb(meshlink_handle_t *mesh, meshlink_ch */ extern void meshlink_set_channel_poll_cb(meshlink_handle_t *mesh, meshlink_channel_t *channel, meshlink_channel_poll_cb_t cb); +/// 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. + * + * This function returns a pointer to a struct meshlink_channel that will be allocated by MeshLink. + * When the application does no longer need to use this channel, it must call meshlink_close() + * to free its resources. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param node The node to which this channel is being initiated. + * @param port The port number the peer wishes to connect to. + * @param cb A pointer to the function which will be called when the remote node sends data to the local node. + * The pointer may be NULL, in which case incoming data is ignored. + * @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. + * + * @return A handle for the channel, or NULL in case of an error. + * The handle is valid until meshlink_channel_close() is called. + */ +extern meshlink_channel_t *meshlink_channel_open_ex(meshlink_handle_t *mesh, meshlink_node_t *node, uint16_t port, meshlink_channel_receive_cb_t cb, const void *data, size_t len, uint32_t flags); + /// 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. @@ -729,6 +771,16 @@ extern void meshlink_channel_close(meshlink_handle_t *mesh, meshlink_channel_t * */ extern ssize_t meshlink_channel_send(meshlink_handle_t *mesh, meshlink_channel_t *channel, const void *data, size_t len); +/// Get channel flags. +/** This returns the flags used when opening this channel. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param channel A handle for the channel. + * + * @return The flags set for this channel. + */ +extern uint32_t meshlink_channel_get_flags(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. @@ -766,7 +818,7 @@ extern void meshlink_hint_address(meshlink_handle_t *mesh, meshlink_node_t *node * 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 @@ -780,8 +832,18 @@ extern void meshlink_hint_address(meshlink_handle_t *mesh, meshlink_node_t *node */ 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