X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;ds=sidebyside;f=src%2Fmeshlink.h;h=24651836f43424b66cff98d58e58bb44b4a0c385;hb=ba799a101d57c55d4cbf602511aa24c32a5b735e;hp=ebd330368dda43727b645c535b3e345cc0394e11;hpb=57b227500ff9daf865e70c95d5837bd3103d6be5;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index ebd33036..24651836 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -25,6 +25,13 @@ #include #include +#if defined(_WIN32) +#include +#else +#include +#include +#endif + #ifdef __cplusplus extern "C" { #endif @@ -32,6 +39,9 @@ extern "C" { /// The length in bytes of a signature made with meshlink_sign() #define MESHLINK_SIGLEN (64) +// The maximum length of fingerprints +#define MESHLINK_FINGERPRINTLEN (64) + /// A handle for an instance of MeshLink. typedef struct meshlink_handle meshlink_handle_t; @@ -44,10 +54,24 @@ typedef struct meshlink_channel meshlink_channel_t; /// Code of most recent error encountered. typedef enum { MESHLINK_OK, ///< Everything is fine + MESHLINK_EINVAL, ///< Invalid parameter(s) to function call MESHLINK_ENOMEM, ///< Out of memory MESHLINK_ENOENT, ///< Node is not known + 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_ENETWORK, ///< MeshLink encountered a network error + MESHLINK_EPEER, ///< A peer caused an error } meshlink_errno_t; +// Device class +typedef enum { + BACKBONE = 1, + STATIONARY = 2, + PORTABLE = 3 +} dclass_t; + /// 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. @@ -59,6 +83,8 @@ extern __thread meshlink_errno_t meshlink_errno; #ifndef MESHLINK_INTERNAL_H struct meshlink_handle { + const char *name; + void *priv; }; struct meshlink_node { @@ -102,11 +128,17 @@ extern const char *meshlink_strerror(meshlink_errno_t err); * After the function returns, the application is free to overwrite or free @a confbase @a. * @param name The name which this instance of the application will use in the mesh. * After the function returns, the application is free to overwrite or free @a name @a. + * @param appname The application name which will be used in the mesh. + * After the function returns, the application is free to overwrite or free @a name @a. + * @param dclass The device class which will be used in the mesh. * * @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); +extern meshlink_handle_t *meshlink_open(const char *confbase, const char *name, const char* appname, dclass_t dclass); + +/// is used by the C++ wrapper to allocate more memory behind the handle +extern meshlink_handle_t *meshlink_open_with_size(const char *confbase, const char *name, const char* appname, dclass_t dclass, size_t size); /// Start MeshLink. /** This function causes MeshLink to open network sockets, make outgoing connections, and @@ -197,7 +229,7 @@ typedef enum { } meshlink_log_level_t; /// A callback for receiving log messages generated by MeshLink. -/** @param mesh A handle which represents an instance of MeshLink. +/** @param mesh A handle which represents an instance of MeshLink, or NULL. * @param level An enum describing the severity level of the message. * @param text A pointer to a nul-terminated C string containing the textual log message. * This pointer is only valid for the duration of the callback. @@ -208,12 +240,21 @@ typedef void (*meshlink_log_cb_t)(meshlink_handle_t *mesh, meshlink_log_level_t /// Set the log callback. /** This functions sets the callback that is called whenever MeshLink has some information to log. - * The callback is run in MeshLink's own thread. + * + * The @a mesh @a parameter can either be a valid MeshLink handle, or NULL. + * In case it is NULL, the callback will be called for errors that happen outside the context of a valid mesh instance. + * Otherwise, it will be called for errors that happen in the context of the given mesh instance. + * + * If @a mesh @a is not NULL, then the callback is run in MeshLink's own thread. * It is 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. + * The @a mesh @a parameter can either be a valid MeshLink handle, or NULL. + * In case it is NULL, the callback will be called for errors that happen outside the context of a valid mesh instance. + * Otherwise, it will be called for errors that happen in the context of the given mesh instance. + * + * @param mesh A handle which represents an instance of MeshLink, or NULL. * @param level An enum describing the minimum severity level. Debugging information with a lower level will not trigger the callback. * @param cb A pointer to the function which will be called when another node sends data to the local node. * If a NULL pointer is given, the callback will be disabled. @@ -238,7 +279,22 @@ extern void meshlink_set_log_cb(meshlink_handle_t *mesh, meshlink_log_level_t le * @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. */ -extern bool meshlink_send(meshlink_handle_t *mesh, meshlink_node_t *destination, const void *data, unsigned int len); +extern bool meshlink_send(meshlink_handle_t *mesh, meshlink_node_t *destination, const void *data, size_t len); + +/// 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. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param destination A pointer to a meshlink_node_t 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. + */ +extern ssize_t meshlink_get_pmtu(meshlink_handle_t *mesh, meshlink_node_t *destination); /// Get a handle for a specific node. /** This function returns a handle for the node with the given name. @@ -253,6 +309,18 @@ extern bool meshlink_send(meshlink_handle_t *mesh, meshlink_node_t *destination, */ extern meshlink_node_t *meshlink_get_node(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. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param node A pointer to a meshlink_node_t describing the node. + * + * @return A nul-terminated C string containing the fingerprint of the node's public key in a printable ASCII format. + * The application should call free() after it is done using this string. + */ +extern char *meshlink_get_fingerprint(meshlink_handle_t *mesh, meshlink_node_t *node); + /// Get a list of all nodes. /** This function returns a list with handles for all known nodes. * @@ -526,6 +594,20 @@ 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); +/// 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. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param hostname The hostname which can be found at the given address. + * The caller is free to overwrite or free this string + * once meshlink returns. + * @param addr The IP address and port which should be tried for the + * given hostname. The caller is free to overwrite or free + * this memory once meshlink returns. + */ +extern void meshlink_hint_address(meshlink_handle_t *mesh, meshlink_node_t *node, struct sockaddr *addr); + #ifdef __cplusplus } #endif