X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;ds=sidebyside;f=src%2Fmeshlink.h;h=c54d35f9038d05d6928c8174fc59e8743b93dd03;hb=c3e43398c1d6a31697ea70be30b40e936d4e4e9b;hp=fdf0896e3e51786612ff47b5f61529786bc8c981;hpb=f7966aeb18195987a244e37df49847af5766605d;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index fdf0896e..c54d35f9 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -35,21 +35,26 @@ typedef struct meshlink_node meshlink_node_t; /// Code of most recent error encountered. typedef enum { - MESHLINK_OK, // Everything is fine - MESHLINK_ENOMEM, // Out of memory - MESHLINK_ENOENT, // Node is not known + MESHLINK_OK, ///< Everything is fine + MESHLINK_ENOMEM, ///< Out of memory + MESHLINK_ENOENT, ///< Node is not known } meshlink_errno_t; +typedef struct outpacketqueue { + meshlink_node_t *destination; + const void *data; + unsigned int len; +} outpacketqueue_t; #ifndef MESHLINK_INTERNAL_H struct meshlink_handle { - meshlink_errno_t meshlink_errno; /// Code of the last encountered error. - const char *errstr; /// Textual representation of most recent error encountered. + meshlink_errno_t meshlink_errno; ///< Code of the last encountered error. + const char *errstr; ///< Textual representation of most recent error encountered. }; struct meshlink_node { - const char *name; // Textual name of this node. - void *priv; // Private pointer which the application can set at will. + const char *name; ///< Textual name of this node. + void *priv; ///< Private pointer which the application can set at will. }; #endif // MESHLINK_INTERNAL_H @@ -84,7 +89,7 @@ extern meshlink_handle_t *meshlink_open(const char *confbase, const char *name); /** This function causes MeshLink to open network sockets, make outgoing connections, and * create a new thread, which will handle all network I/O. * - * @param confbase The directory in which MeshLink will store its configuration files. + * @param mesh A handle which represents an instance of MeshLink. * * @return This function will return true if MeshLink has succesfully started its thread, false otherwise. */ @@ -94,7 +99,7 @@ extern bool meshlink_start(meshlink_handle_t *mesh); /** This function causes MeshLink to disconnect from all other nodes, * close all sockets, and shut down its own thread. * - * @param handle A handle which represents an instance of MeshLink. + * @param mesh A handle which represents an instance of MeshLink. */ extern void meshlink_stop(meshlink_handle_t *mesh); @@ -103,12 +108,12 @@ extern void meshlink_stop(meshlink_handle_t *mesh); * and frees all memory allocated by MeshLink. * Afterwards, the handle and any pointers to a struct meshlink_node are invalid. * - * @param handle A handle which represents an instance of MeshLink. + * @param mesh A handle which represents an instance of MeshLink. */ extern void meshlink_close(meshlink_handle_t *mesh); /// A callback for receiving data from the mesh. -/** @param handle A handle which represents an instance of MeshLink. +/** @param mesh A handle which represents an instance of MeshLink. * @param source A pointer to a meshlink_node_t describing the source of the data. * @param data A pointer to a buffer containing the data sent by the source. * @param len The length of the received data. @@ -122,13 +127,13 @@ typedef void (*meshlink_receive_cb_t)(meshlink_handle_t *mesh, meshlink_node_t * * to hand the data over to the application's thread. * The callback should also not block itself and return as quickly as possible. * - * @param handle A handle which represents an instance of MeshLink. + * @param mesh A handle which represents an instance of MeshLink. * @param cb A pointer to the function which will be called when another node sends data to the local node. */ extern void meshlink_set_receive_cb(meshlink_handle_t *mesh, meshlink_receive_cb_t cb); /// A callback reporting node status changes. -/** @param handle A handle which represents an instance of MeshLink. +/** @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. * @param reachable True if the node is reachable, false otherwise. */ @@ -141,22 +146,22 @@ typedef void (*meshlink_node_status_cb_t)(meshlink_handle_t *mesh, meshlink_node * to hand the data over to the application's thread. * The callback should also not block itself and return as quickly as possible. * - * @param handle A handle which represents an instance of MeshLink. + * @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 status changes. */ extern void meshlink_set_node_status_cb(meshlink_handle_t *mesh, meshlink_node_status_cb_t cb); /// Severity of log messages generated by MeshLink. typedef enum { - MESHLINK_DEBUG, // Internal debugging messages. Only useful during application development. - MESHLINK_INFO, // Informational messages. - MESHLINK_WARNING, // Warnings which might indicate problems, but which are not real errors. - MESHLINK_ERROR, // Errors which hamper correct functioning of MeshLink, without causing it to fail completely. - MESHLINK_CRITICAL, // Critical errors which cause MeshLink to fail completely. + MESHLINK_DEBUG, ///< Internal debugging messages. Only useful during application development. + MESHLINK_INFO, ///< Informational messages. + MESHLINK_WARNING, ///< Warnings which might indicate problems, but which are not real errors. + MESHLINK_ERROR, ///< Errors which hamper correct functioning of MeshLink, without causing it to fail completely. + MESHLINK_CRITICAL, ///< Critical errors which cause MeshLink to fail completely. } meshlink_log_level_t; /// A callback for receiving log messages generated by MeshLink. -/** @param handle A handle which represents an instance of MeshLink. +/** @param mesh A handle which represents an instance of MeshLink. * @param level An enum describing the severity level of the message. * @param text A pointer to a string containing the textual log message. */ @@ -169,7 +174,7 @@ typedef void (*meshlink_log_cb_t)(meshlink_handle_t *mesh, meshlink_log_level_t * to hand the data over to the application's thread. * The callback should also not block itself and return as quickly as possible. * - * @param handle A handle which represents an instance of MeshLink. + * @param mesh A handle which represents an instance of MeshLink. * @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. */ @@ -182,7 +187,7 @@ extern void meshlink_set_log_cb(meshlink_handle_t *mesh, meshlink_log_level_t le * and that there is no guarantee that the packet will arrive at the destination. * The application should take care of getting an acknowledgement and retransmission if necessary. * - * @param handle A handle which represents an instance of MeshLink. + * @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. * @param data A pointer to a buffer containing the data to be sent to the source. * @param len The length of the data. @@ -194,7 +199,7 @@ extern bool meshlink_send(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. * - * @param handle A handle which represents an instance of MeshLink. + * @param mesh A handle which represents an instance of MeshLink. * @param name The name of the node for which a handle is requested. * * @return A pointer to a meshlink_node_t which represents the requested node, @@ -205,11 +210,11 @@ extern meshlink_node_t *meshlink_get_node(meshlink_handle_t *mesh, const char *n /// Get a list of all nodes. /** This function returns a list with handles for all known nodes. * - * @param handle A handle which represents an instance of MeshLink. + * @param mesh A handle which represents an instance of MeshLink. * @param nodes A pointer to an array of pointers to meshlink_node_t, which should be allocated by the application. * @param nmemb The maximum number of pointers that can be stored in the nodes array. * - * @param return The number of known nodes. This can be larger than nmemb, in which case not all nodes were stored in the nodes array. + * @return The number of known nodes. This can be larger than nmemb, in which case not all nodes were stored in the nodes array. */ extern size_t meshlink_get_all_nodes(meshlink_handle_t *mesh, meshlink_node_t **nodes, size_t nmemb); @@ -217,7 +222,7 @@ extern size_t meshlink_get_all_nodes(meshlink_handle_t *mesh, meshlink_node_t ** /** This function signs data using the local node's MeshLink key. * The generated signature can be securely verified by other nodes. * - * @param handle A handle which represents an instance of MeshLink. + * @param mesh A handle which represents an instance of MeshLink. * @param data A pointer to a buffer containing the data to be signed. * @param len The length of the data to be signed. * @@ -229,7 +234,7 @@ extern char *meshlink_sign(meshlink_handle_t *mesh, const char *data, size_t len /// Verify the signature generated by another node of a piece of data. /** This function verifies the signature that another node generated for a piece of data. * - * @param handle A handle which represents an instance of MeshLink. + * @param mesh A handle which represents an instance of MeshLink. * @param source A pointer to a meshlink_node_t describing the source of the signature. * @param data A pointer to a buffer containing the data to be verified. * @param len The length of the data to be verified. @@ -239,13 +244,23 @@ extern char *meshlink_sign(meshlink_handle_t *mesh, const char *data, size_t len */ extern bool meshlink_verify(meshlink_handle_t *mesh, meshlink_node_t *source, const char *data, size_t len, const char *signature); +/// Add an Address for the local node. +/** This function adds an Address for the local node, which will be used for invitation URLs. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param address A 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. + */ +extern bool meshlink_add_address(meshlink_handle_t *mesh, const char *address); + /// 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. * This URL should be passed by the application to the invitee in a way that no eavesdroppers can see the URL. * The URL can only be used once, after the user has joined the mesh the URL is no longer valid. * - * @param handle A handle which represents an instance of MeshLink. + * @param mesh A handle which represents an instance of MeshLink. * @param name The name that the invitee will use in the mesh. * * @return This function returns a string that contains the invitation URL. @@ -258,7 +273,7 @@ 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. * - * @param handle A handle which represents an instance of MeshLink. + * @param mesh A handle which represents an instance of MeshLink. * @param invitation A string containing the invitation URL. * * @return This function returns true if the local node joined the mesh it was invited to, false otherwise. @@ -270,7 +285,7 @@ extern bool meshlink_join(meshlink_handle_t *mesh, const char *invitation); * The application can pass it in some way to another node, which can then import it, * granting the local node access to the other node's mesh. * - * @param handle A handle which represents an instance of MeshLink. + * @param mesh A handle which represents an instance of MeshLink. * * @return This function returns a string that contains the exported key and addresses. * The application should call free() after it has finished using this string. @@ -281,7 +296,7 @@ extern char *meshlink_export(meshlink_handle_t *mesh); /** This function accepts a string containing the exported public key and addresses of another node. * By importing this data, the local node grants the other node access to its mesh. * - * @param handle A handle which represents an instance of MeshLink. + * @param mesh A handle which represents an instance of MeshLink. * @param data A string containing the other node's exported key and addresses. * * @return This function returns true if the data was valid and the other node has been granted access to the mesh, false otherwise. @@ -293,7 +308,7 @@ extern bool meshlink_import(meshlink_handle_t *mesh, const char *data); * The local node will drop any existing connections to that node, * and will not send data to it nor accept any data received from it any more. * - * @param handle A handle which represents an instance of MeshLink. + * @param mesh A handle which represents an instance of MeshLink. * @param node A pointer to a meshlink_node_t describing the node to be blacklisted. */ extern void meshlink_blacklist(meshlink_handle_t *mesh, meshlink_node_t *node);