X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=17545ed289b4c464dadc9e0ba53ca7108a74348b;hb=ed545c8ca7b674b5e851567f2b6630ed3e4bfac0;hp=6f104abe5fcb5cc29bedb9f7e048dd465e211e37;hpb=b9eb3647186bf697e4bdc8f60fd05cc15a99c18b;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index 6f104abe..17545ed2 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -68,12 +68,14 @@ typedef enum { MESHLINK_EPEER, ///< A peer caused an error } meshlink_errno_t; -// Device class +/// Device class typedef enum { - BACKBONE = 1, - STATIONARY = 2, - PORTABLE = 3 -} dclass_t; + DEV_CLASS_BACKBONE = 0, + DEV_CLASS_STATIONARY = 1, + DEV_CLASS_PORTABLE = 2, + DEV_CLASS_UNKNOWN = 3, + _DEV_CLASS_MAX = 3 +} dev_class_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 @@ -86,16 +88,18 @@ extern __thread meshlink_errno_t meshlink_errno; #ifndef MESHLINK_INTERNAL_H struct meshlink_handle { - const char *name; - void *priv; + 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. }; struct meshlink_node { - const char *name; ///< Textual name of this node. It is stored in a nul-terminated C string, which is allocated by MeshLink. + 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. }; 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. }; #endif // MESHLINK_INTERNAL_H @@ -149,15 +153,15 @@ extern const char *meshlink_strerror(meshlink_errno_t err); * 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. + * @param devclass 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, const char* appname, dclass_t dclass); +extern meshlink_handle_t *meshlink_open(const char *confbase, const char *name, const char* appname, dev_class_t devclass); /// 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); +extern meshlink_handle_t *meshlink_open_with_size(const char *confbase, const char *name, const char* appname, dev_class_t devclass, size_t size); /// Start MeshLink. /** This function causes MeshLink to open network sockets, make outgoing connections, and @@ -493,8 +497,6 @@ extern void meshlink_blacklist(meshlink_handle_t *mesh, meshlink_node_t *node); * If the application rejects the incoming channel by returning false, * then this handle is invalid after the callback returns * (the callback does not need to call meshlink_channel_close() itself in this case). - * @param node The node from which this channel is being initiated. - * The pointer is guaranteed to be valid until meshlink_close() is called. * @param port The port number the peer wishes to connect to. * @param data A pointer to a buffer containing data already received, or NULL in case no data has been received yet. (Not yet used.) * The pointer is only valid during the lifetime of the callback. @@ -504,7 +506,7 @@ extern void meshlink_blacklist(meshlink_handle_t *mesh, meshlink_node_t *node); * @return This function should return true if the application accepts the incoming channel, false otherwise. * If returning false, the channel is invalid and may not be used anymore. */ -typedef bool (*meshlink_channel_accept_cb_t)(meshlink_handle_t *mesh, meshlink_channel_t *channel, meshlink_node_t *node, uint16_t port, const void *data, size_t len); +typedef bool (*meshlink_channel_accept_cb_t)(meshlink_handle_t *mesh, meshlink_channel_t *channel, uint16_t port, const void *data, size_t len); /// A callback for receiving data from a channel. /** This function is called whenever data is received from a remote node on a channel. @@ -636,28 +638,31 @@ extern void meshlink_hint_address(meshlink_handle_t *mesh, meshlink_node_t *node * * @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). + * 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. + * 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. + * 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);