X-Git-Url: http://git.meshlink.io/?p=meshlink;a=blobdiff_plain;f=src%2Fmeshlink.h;h=43d269cea76492134c08e4c8ffd9684a69502e52;hp=2f2e7f841054e2ea3d21622c09906bb881d95970;hb=ecfe7cbbe08dc99ba6f329ad66bb8ee09ce9539b;hpb=92283d7342fabd882126a892b2636d57ff0458de diff --git a/src/meshlink.h b/src/meshlink.h index 2f2e7f84..43d269ce 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -3,7 +3,7 @@ /* meshlink.h -- MeshLink API - Copyright (C) 2014-2018 Guus Sliepen + Copyright (C) 2014-2019 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 @@ -51,6 +51,12 @@ typedef struct meshlink_node meshlink_node_t; /// A handle for a MeshLink channel. typedef struct meshlink_channel meshlink_channel_t; +/// A struct containing all parameters used for opening a mesh. +typedef struct meshlink_open_params meshlink_open_params_t; + +/// A handle for a MeshLink sub-mesh. +typedef struct meshlink_submesh meshlink_submesh_t; + /// Code of most recent error encountered. typedef enum { MESHLINK_OK, ///< Everything is fine @@ -60,11 +66,11 @@ typedef enum { 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_ESTORAGE, ///< MeshLink could 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_EBUSY, ///< The MeshLink instance is already in use by another process + MESHLINK_EBUSY ///< The MeshLink instance is already in use by another process } meshlink_errno_t; /// Device class @@ -76,6 +82,13 @@ typedef enum { _DEV_CLASS_MAX = 3 } dev_class_t; +/// Invitation flags +static const uint32_t MESHLINK_INVITE_LOCAL = 1; // Only use local addresses in the URL +static const uint32_t MESHLINK_INVITE_PUBLIC = 2; // Only use public or canonical addresses in the URL +static const uint32_t MESHLINK_INVITE_IPV4 = 4; // Only use IPv4 addresses in the URL +static const uint32_t MESHLINK_INVITE_IPV6 = 8; // Only use IPv6 addresses in the URL +static const uint32_t MESHLINK_INVITE_NUMERIC = 16; // Don't look up hostnames + /// 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. @@ -88,7 +101,7 @@ static const uint32_t MESHLINK_CHANNEL_UDP = 0; // Select UDP semantics. /** 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. * The variable is only updated when an error is encountered, and is not reset to MESHLINK_OK - * if a function returned succesfully. + * if a function returned successfully. */ extern __thread meshlink_errno_t meshlink_errno; @@ -104,6 +117,11 @@ struct meshlink_node { void *priv; ///< Private pointer which may be set freely by the application, and is never used or modified by MeshLink. }; +struct meshlink_submesh { + const char *const name; ///< Textual name of this Sub-Mesh. 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 *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. @@ -122,9 +140,54 @@ struct meshlink_channel { */ extern const char *meshlink_strerror(meshlink_errno_t err); +/// Create a new meshlink_open_params_t struct. +/** This function allocates and initializes a new meshlink_open_params_t struct that can be passed to meshlink_open_ex(). + * The resulting struct may be reused for multiple calls to meshlink_open_ex(). + * After the last use, the application must free this struct using meshlink_open_params_free(). + * + * @param confbase The directory in which MeshLink will store its configuration files. + * After the function returns, the application is free to overwrite or free @a confbase. + * @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. + * @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. + * @param devclass The device class which will be used in the mesh. + * + * @return A pointer to a meshlink_open_params_t which can be passed to meshlink_open_ex(), or NULL in case of an error. + * The pointer is valid until meshlink_open_params_free() is called. + */ +extern meshlink_open_params_t *meshlink_open_params_init(const char *confbase, const char *name, const char *appname, dev_class_t devclass); + +/// Free a meshlink_open_params_t struct. +/** This function frees a meshlink_open_params_t struct and all resources associated with it. + * + * @param params A pointer to a meshlink_open_params_t which must have been created earlier with meshlink_open_params_init(). + */ +extern void meshlink_open_params_free(meshlink_open_params_t *params); + /// Open or create a MeshLink instance. /** This function opens or creates a MeshLink instance. - * The state is stored in the configuration directory passed in the variable @a confbase @a. + * All parameters needed by MeshLink are passed via a meshlink_open_params_t struct, + * which must have been initialized earlier by the application. + * + * This function returns a pointer to a struct meshlink_handle that will be allocated by MeshLink. + * When the application does no longer need to use this handle, it must call meshlink_close() to + * free its resources. + * + * This function does not start any network I/O yet. The application should + * first set callbacks, and then call meshlink_start(). + * + * @param params A pointer to a meshlink_open_params_t which must be filled in by the application. + * After the function returns, the application is free to reuse or free @a params. + * + * @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_ex(const meshlink_open_params_t *params); + +/// Open or create a MeshLink instance. +/** This function opens or creates a MeshLink instance. + * The state is stored in the configuration directory passed in the variable @a confbase. * If the configuration directory does not exist yet, for example when it is the first time * this instance is opened, the configuration directory will be automatically created and initialized. * However, the parent directory should already exist, otherwise an error will be returned. @@ -139,11 +202,11 @@ extern const char *meshlink_strerror(meshlink_errno_t err); * first set callbacks, and then call meshlink_start(). * * @param confbase The directory in which MeshLink will store its configuration files. - * After the function returns, the application is free to overwrite or free @a confbase @a. + * After the function returns, the application is free to overwrite or free @a confbase. * @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. + * After the function returns, the application is free to overwrite or free @a name. * @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. + * After the function returns, the application is free to overwrite or free @a name. * @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. @@ -151,6 +214,21 @@ extern const char *meshlink_strerror(meshlink_errno_t err); */ extern meshlink_handle_t *meshlink_open(const char *confbase, const char *name, const char *appname, dev_class_t devclass); +/// Create Sub-Mesh. +/** This function causes MeshLink to open a new Sub-Mesh network + * create a new thread, which will handle all network I/O. + * + * It is allowed to call this function even if MeshLink is already started, in which case it will return true. + * + * @param mesh A handle which represents an instance of MeshLink. + * + * @param submesh Name of the new Sub-Mesh to create. + * + * @return A pointer to a meshlink_submesh_t which represents this instance of SubMesh, or NULL in case of an error. + * The pointer is valid until meshlink_close() is called. + */ +meshlink_submesh_t *meshlink_submesh_open(meshlink_handle_t *mesh, const char *submesh); + /// Start MeshLink. /** This function causes MeshLink to open network sockets, make outgoing connections, and * create a new thread, which will handle all network I/O. @@ -159,7 +237,7 @@ extern meshlink_handle_t *meshlink_open(const char *confbase, const char *name, * * @param mesh A handle which represents an instance of MeshLink. * - * @return This function will return true if MeshLink has succesfully started, false otherwise. + * @return This function will return true if MeshLink has successfully started, false otherwise. */ extern bool meshlink_start(meshlink_handle_t *mesh); @@ -193,9 +271,9 @@ extern void meshlink_close(meshlink_handle_t *mesh); * new instance. * * @param confbase The directory in which MeshLink stores its configuration files. - * After the function returns, the application is free to overwrite or free @a confbase @a. + * After the function returns, the application is free to overwrite or free @a confbase. * - * @return This function will return true if the MeshLink instance was succesfully destroyed, false otherwise. + * @return This function will return true if the MeshLink instance was successfully destroyed, false otherwise. */ extern bool meshlink_destroy(const char *confbase); @@ -269,7 +347,7 @@ typedef enum { 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_CRITICAL ///< Critical errors which cause MeshLink to fail completely. } meshlink_log_level_t; /// A callback for receiving log messages generated by MeshLink. @@ -285,16 +363,16 @@ 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 @a mesh @a parameter can either be a valid MeshLink handle, or NULL. + * The @a mesh 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. + * If @a mesh 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. * - * The @a mesh @a parameter can either be a valid MeshLink handle, or NULL. + * The @a mesh 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. * @@ -318,7 +396,7 @@ extern void meshlink_set_log_cb(meshlink_handle_t *mesh, meshlink_log_level_t le * @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. * After meshlink_send() returns, the application is free to overwrite or free this buffer. - * It is valid to specify a NULL pointer, but only if @a len @a is also 0. + * It is valid to specify a NULL pointer, but only if @a len is also 0. * @param len The length of the data. * @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. @@ -355,7 +433,7 @@ extern meshlink_node_t *meshlink_get_self(meshlink_handle_t *mesh); * * @param mesh A handle which represents an instance of MeshLink. * @param name The name of the node for which a handle is requested. - * After this function returns, the application is free to overwrite or free @a name @a. + * After this function returns, the application is free to overwrite or free @a name. * * @return A pointer to a meshlink_node_t which represents the requested node, * or NULL if the requested node does not exist. @@ -384,12 +462,12 @@ extern char *meshlink_get_fingerprint(meshlink_handle_t *mesh, meshlink_node_t * * The application is allowed to call free() on the array whenever it wishes. * The pointers in the array are valid until meshlink_close() is called. * @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. + * In case the @a nodes 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 nodes, or NULL in case of an error. - * If the @a nodes @a argument was not NULL, then the return value can either be the same value or a different value. - * If it is a new value, the old value of @a nodes @a should not be used anymore. + * If the @a nodes argument was not NULL, then the return value can either be the same value or a different value. + * If it is a new value, the old value of @a nodes should not be used anymore. * If the new value is NULL, then the old array will have been freed by MeshLink. */ extern meshlink_node_t **meshlink_get_all_nodes(meshlink_handle_t *mesh, meshlink_node_t **nodes, size_t *nmemb); @@ -410,6 +488,66 @@ extern meshlink_node_t **meshlink_get_all_nodes(meshlink_handle_t *mesh, meshlin */ extern bool meshlink_sign(meshlink_handle_t *mesh, const void *data, size_t len, void *signature, size_t *siglen); +/// Get the list of all nodes by device class. +/** This function returns a list with handles for all the nodes that matches with the given @a devclass. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param devclass Device class of the nodes for which the list has to be obtained. + * @param nodes A pointer to a previously allocated array of pointers to meshlink_node_t, or NULL in which case MeshLink will allocate a new array. + * The application can supply an array it allocated itself with malloc, or the return value from the previous call to this function (which is the preferred way). + * The application is allowed to call free() on the array whenever it wishes. + * The pointers in the array are valid until meshlink_close() is called. + * @param nmemb A pointer to a variable holding the number of nodes with the same @a device class that are stored in the array. + * In case the @a nodes 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 nodes of the given device class, or NULL in case of an error. + * If the @a nodes argument was not NULL, then the return value can either be the same value or a different value. + * If it is a new value, the old value of @a nodes should not be used anymore. + * If the new value is NULL, then the old array will have been freed by MeshLink. + */ +extern meshlink_node_t **meshlink_get_all_nodes_by_dev_class(meshlink_handle_t *mesh, dev_class_t devclass, meshlink_node_t **nodes, size_t *nmemb); + +/// Get the list of all nodes by Submesh. +/** This function returns a list with handles for all the nodes that matches with the given @a Submesh. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param submesh Submesh handle of the nodes for which the list has to be obtained. + * @param nodes A pointer to a previously allocated array of pointers to meshlink_node_t, or NULL in which case MeshLink will allocate a new array. + * The application can supply an array it allocated itself with malloc, or the return value from the previous call to this function (which is the preferred way). + * The application is allowed to call free() on the array whenever it wishes. + * The pointers in the array are valid until meshlink_close() is called. + * @param nmemb A pointer to a variable holding the number of nodes with the same @a device class that are stored in the array. + * In case the @a nodes 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 nodes of the given Submesh, or NULL in case of an error. + * If the @a nodes argument was not NULL, then the return value can either be the same value or a different value. + * If it is a new value, the old value of @a nodes should not be used anymore. + * If the new value is NULL, then the old array will have been freed by MeshLink. + */ +extern meshlink_node_t **meshlink_get_all_nodes_by_submesh(meshlink_handle_t *mesh, meshlink_submesh_t *submesh, meshlink_node_t **nodes, size_t *nmemb); + +/// Get the node's device class. +/** This function returns the device class of the given node. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param node A pointer to a meshlink_node_t describing the node. + * + * @return This function returns the device class of the @a node, or -1 in case of an error. + */ +extern dev_class_t meshlink_get_node_dev_class(meshlink_handle_t *mesh, meshlink_node_t *node); + +/// Get the node's submesh handle. +/** This function returns the submesh handle of the given node. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param node A pointer to a meshlink_node_t describing the node. + * + * @return This function returns the submesh handle of the @a node, or NULL in case of an error. + */ +extern meshlink_submesh_t *meshlink_get_node_submesh(meshlink_handle_t *mesh, meshlink_node_t *node); + /// 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. * @@ -492,16 +630,38 @@ extern char *meshlink_get_external_address(meshlink_handle_t *mesh); * 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. + * @param mesh A handle which represents an instance of MeshLink. + * @param address_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. + * @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_for_family() 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 local address for the local node. +/** This function performs tries to discover the address of the local interface used for outgoing connection. + * + * Please note that this is function only returns a single address, + * even if the interface might have more than one address. + * In that case, there is no control over which address will be selected. + * Also note that if you have a dynamic IP address, + * there is no guarantee that the local address will be valid for an extended period of time. + * + * This function will fail if it couldn't find a local address for the given address family. + * If hostname resolving is requested, this function may block for a few seconds. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param address_family The address family to check, for example AF_INET or AF_INET6. If AF_UNSPEC is given, + * this might return the local address for any working address family. + * + * @return This function returns a pointer to a C string containing the discovered local address, + * or NULL if there was an error looking up the address. + * After meshlink_get_local_address_for_family() returns, the application is free to overwrite or free this string. + */ +extern char *meshlink_get_local_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: * @@ -537,7 +697,7 @@ extern int meshlink_get_port(meshlink_handle_t *mesh); * If the port is set to 0, then MeshLink will listen on a port * that is randomly assigned by the operating system every time meshlink_open() is called. * - * @return This function returns true if the port was succesfully changed, false otherwise. + * @return This function returns true if the port was successfully changed, false otherwise. */ extern bool meshlink_set_port(meshlink_handle_t *mesh, int port); @@ -559,18 +719,38 @@ extern void meshlink_set_invitation_timeout(meshlink_handle_t *mesh, int timeout * The URL can only be used once, after the user has joined the mesh the URL is no longer valid. * * @param mesh A handle which represents an instance of MeshLink. + * @param submesh A handle which represents an instance of SubMesh. + * @param name A nul-terminated C string containing the name that the invitee will be allowed to use in the mesh. + * After this function returns, the application is free to overwrite or free @a name. + * @param flags A bitwise-or'd combination of flags that controls how the URL is generated. + * + * @return This function returns a nul-terminated C string that contains the invitation URL, or NULL in case of an error. + * The application should call free() after it has finished using the URL. + */ +extern char *meshlink_invite_ex(meshlink_handle_t *mesh, meshlink_submesh_t *submesh, const char *name, uint32_t flags); + +/// 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. + * + * Calling this function is equal to callen meshlink_invite_ex() with flags set to 0. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param submesh A handle which represents an instance of SubMesh. * @param name A nul-terminated C string containing the name that the invitee will be allowed to use in the mesh. - * After this function returns, the application is free to overwrite or free @a name @a. + * After this function returns, the application is free to overwrite or free @a name. * * @return This function returns a nul-terminated C string that contains the invitation URL, or NULL in case of an error. * The application should call free() after it has finished using the URL. */ -extern char *meshlink_invite(meshlink_handle_t *mesh, const char *name); +extern char *meshlink_invite(meshlink_handle_t *mesh, meshlink_submesh_t *submesh, const char *name); /// Use an invitation to join a mesh. /** This function allows the local node to join an existing mesh using an invitation URL generated by another node. * 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. + * After a successfully 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. * @@ -580,7 +760,7 @@ extern char *meshlink_invite(meshlink_handle_t *mesh, const char *name); * * @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. + * After this function returns, the application is free to overwrite or free @a invitation. * * @return This function returns true if the local node joined the mesh it was invited to, false otherwise. */ @@ -610,7 +790,7 @@ extern char *meshlink_export(meshlink_handle_t *mesh); * * @param mesh A handle which represents an instance of MeshLink. * @param data A nul-terminated C string containing the other node's exported key and addresses. - * After this function returns, the application is free to overwrite or free @a data @a. + * After this function returns, the application is free to overwrite or free @a data. * * @return This function returns true if the data was valid and the other node has been granted access to the mesh, false otherwise. */ @@ -678,8 +858,8 @@ typedef bool (*meshlink_channel_accept_cb_t)(meshlink_handle_t *mesh, meshlink_c /** This function is called whenever data is received from a remote node on a channel. * * This function is also called in case the channel has been closed by the remote node, or when the channel is terminated abnormally. - * In both cases, @a data @a will be NULL and @a len @a will be 0, and meshlink_errno will be set. - * In any case, the @a channel @a handle will still be valid until the application calls meshlink_close(). + * In both cases, @a data will be NULL and @a len will be 0, and meshlink_errno will be set. + * In any case, the @a channel handle will still be valid until the application calls meshlink_close(). * * @param mesh A handle which represents an instance of MeshLink. * @param channel A handle for the channel. @@ -774,6 +954,9 @@ extern meshlink_channel_t *meshlink_channel_open_ex(meshlink_handle_t *mesh, mes * When the application does no longer need to use this channel, it must call meshlink_close() * to free its resources. * + * Calling this function is equivalent to calling meshlink_channel_open_ex() + * with the flags set to MESHLINK_CHANNEL_TCP. + * * @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. @@ -838,14 +1021,34 @@ extern ssize_t meshlink_channel_send(meshlink_handle_t *mesh, meshlink_channel_t */ extern uint32_t meshlink_channel_get_flags(meshlink_handle_t *mesh, meshlink_channel_t *channel); +/// Get the amount of bytes in the send buffer. +/** This returns the amount of bytes in the send buffer. + * These bytes have not been received by the peer yet. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param channel A handle for the channel. + * + * @return The amount of un-ACKed bytes in the send buffer. + */ +extern size_t meshlink_channel_get_sendq(meshlink_handle_t *mesh, meshlink_channel_t *channel); + +/// Get the amount of bytes in the receive buffer. +/** This returns the amount of bytes in the receive buffer. + * These bytes have not been processed by the application yet. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param channel A handle for the channel. + * + * @return The amount of bytes in the receive buffer. + */ +extern size_t meshlink_channel_get_recvq(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. * * @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 node A pointer to a meshlink_node_t describing the node to add the address hint for. * @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.