X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=37eeac81ed0b74a43ebb1ae981bffb2042c46c79;hb=f13d66f20a227a87075f6456f41b83ce269b67f4;hp=a768d435a9875da2c917f5095a562585e94dd882;hpb=5dec7459d9920c930bdfb3ac0f2a3740a6247ec0;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index a768d435..37eeac81 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -3,7 +3,7 @@ /* meshlink.h -- MeshLink API - Copyright (C) 2014, 2017 Guus Sliepen + Copyright (C) 2014-2018 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 @@ -37,10 +37,10 @@ extern "C" { #endif /// The length in bytes of a signature made with meshlink_sign() -#define MESHLINK_SIGLEN (64) +#define MESHLINK_SIGLEN (64ul) // The maximum length of fingerprints -#define MESHLINK_FINGERPRINTLEN (64) +#define MESHLINK_FINGERPRINTLEN (64ul) /// A handle for an instance of MeshLink. typedef struct meshlink_handle meshlink_handle_t; @@ -48,9 +48,6 @@ typedef struct meshlink_handle meshlink_handle_t; /// A handle for a MeshLink node. typedef struct meshlink_node meshlink_node_t; -/// A handle for a MeshLink edge. -typedef struct meshlink_edge meshlink_edge_t; - /// A handle for a MeshLink channel. typedef struct meshlink_channel meshlink_channel_t; @@ -66,6 +63,7 @@ typedef enum { 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_ENOTSUP, ///< The operation is not supported in the current configuration of MeshLink } meshlink_errno_t; /// Device class @@ -96,38 +94,22 @@ extern __thread meshlink_errno_t meshlink_errno; #ifndef MESHLINK_INTERNAL_H struct meshlink_handle { - char *name; ///< Textual name of ourself. 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. + const char *const name; ///< Textual name of ourself. 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_node { - char *name; ///< Textual name of this node. 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. + const char *const name; ///< Textual name of this node. 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 *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_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. }; #endif // MESHLINK_INTERNAL_H -/// 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. - 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. - struct sockaddr_storage address;///< The address information associated - // with this edge. - uint32_t options; ///< Edge options. @TODO what are edge options? - int weight; ///< Weight assigned to this edge. -}; - /// Get the text for the given MeshLink error code. /** This function returns a pointer to the string containing the description of the given error code. * @@ -166,7 +148,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 @@ -422,6 +404,25 @@ extern bool meshlink_sign(meshlink_handle_t *mesh, const void *data, size_t len, */ extern bool meshlink_verify(meshlink_handle_t *mesh, meshlink_node_t *source, const void *data, size_t len, const void *signature, size_t siglen); +/// Set the canonical Address for a node. +/** This function sets the canonical Address for a 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. + * + * If a canonical Address is set for the local node, + * it will be used for the hostname part of generated invitation URLs. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param node A pointer to a meshlink_node_t describing the node. + * @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. + * If it is NULL, the listening port's number will be used. + * + * @return This function returns true if the address was added, false otherwise. + */ +extern bool meshlink_set_canonical_address(meshlink_handle_t *mesh, meshlink_node_t *node, const char *address, const char *port); + /// Add an Address for the local node. /** This function adds an Address for the local node, which will be used for invitation URLs. * @@ -455,6 +456,31 @@ extern bool meshlink_add_address(meshlink_handle_t *mesh, const char *address); */ extern char *meshlink_get_external_address(meshlink_handle_t *mesh); +/// 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. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param 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() returns, the application is free to overwrite or free this string. + */ +extern char *meshlink_get_external_address_for_family(meshlink_handle_t *mesh, int address_family); + /// Try to discover the external address for the local node, and add it to its list of addresses. /** This function is equivalent to: * @@ -495,6 +521,16 @@ extern int meshlink_get_port(meshlink_handle_t *mesh); extern bool meshlink_set_port(meshlink_handle_t *mesh, int port); +/// Set the timeout for invitations. +/** This function sets the timeout for invitations. + * Note that timeouts are only checked at the time a node tries to join using an invitation. + * The default timeout for invitations is 1 week. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param timeout The timeout for invitations in seconds. + */ +extern void meshlink_set_invitation_timeout(meshlink_handle_t *mesh, int timeout); + /// 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. @@ -795,43 +831,6 @@ extern uint32_t meshlink_channel_get_flags(meshlink_handle_t *mesh, meshlink_cha */ extern void meshlink_hint_address(meshlink_handle_t *mesh, meshlink_node_t *node, const struct sockaddr *addr); -/// Get a list of edges. -/** This function returns an array with copies of all known bidirectional edges. - * The edges are copied to capture the mesh state at call time, since edges - * mutate frequently. The nodes pointed to within the meshlink_edge_t type - * are not copies; these are the same pointers that one would get from a call - * to meshlink_get_all_nodes(). - * - * @param mesh A handle which represents an instance of MeshLink. - * @param edges A pointer to a previously allocated array of pointers to - * meshlink_edge_t, or NULL in which case MeshLink will - * allocate a new array. The application CANNOT supply an - * array it allocated itself with malloc, but CAN use - * the return value from the previous call to this function - * (which is the preferred way). - * The pointers in the array are valid until meshlink_close() is called. - * ATTENTION: The pointers and values should never be modified - * by the application!!! - * @param nmemb A pointer to a variable holding the number of nodes that - * are stored in the array. In case the @a nodes @a - * 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 - * 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 - * value. If the new values is NULL, then the old array - * will have been freed by Meshlink. - * The caller must call free() on each element of this - * array (but not the contents of said elements), - * as well as the array itself when it is finished. - * ATTENTION: The pointers and values should never be modified - * by the application!!! - */ -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