X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=2763ad8d214ff2d52d2ec3b0ec373c8a0cb12a07;hb=5f2e8877486869471041b0eca1aaed841c41a1a9;hp=385c12cec44b17f5a5609e62d5ad42b6607ba507;hpb=d65ff28f38ba779fbd6f970fb3c84b0ed98daa28;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index 385c12ce..2763ad8d 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -151,6 +151,7 @@ extern const char *meshlink_strerror(meshlink_errno_t err) __attribute__((__warn * 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. + * If NULL is passed as the name, the name used last time the MeshLink instance was initialized is used. * @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. @@ -228,6 +229,7 @@ extern struct meshlink_handle *meshlink_open_ex(const meshlink_open_params_t *pa * 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. + * If NULL is passed as the name, the name used last time the MeshLink instance was initialized is used. * @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. @@ -257,6 +259,7 @@ extern struct meshlink_handle *meshlink_open(const char *confbase, const char *n * 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. + * If NULL is passed as the name, the name used last time the MeshLink instance was initialized is used. * @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. @@ -810,8 +813,32 @@ extern bool meshlink_verify(struct meshlink_handle *mesh, struct meshlink_node * */ extern bool meshlink_set_canonical_address(struct meshlink_handle *mesh, struct meshlink_node *node, const char *address, const char *port) __attribute__((__warn_unused_result__)); +/// Add an invitation address for the local node. +/** This function adds an address for the local node, which will be used only for invitation URLs. + * This address is not stored permanently. + * Multiple addresses can be added using multiple calls to this function. + * + * \memberof meshlink_handle + * @param mesh A handle which represents an instance of MeshLink. + * @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_add_invitation_address(struct meshlink_handle *mesh, const char *address, const char *port) __attribute__((__warn_unused_result__)); + +/// Clears all invitation address for the local node. +/** This function removes all addresses added with meshlink_add_invitation_address(). + * + * \memberof meshlink_handle + * @param mesh A handle which represents an instance of MeshLink. + */ +extern void meshlink_clear_invitation_addresses(struct meshlink_handle *mesh); + /// Add an Address for the local node. /** This function adds an Address for the local node, which will be used for invitation URLs. + * @deprecated This function is deprecated, use meshlink_set_canonical_address() and/or meshlink_add_invitation_address(). * * \memberof meshlink_handle * @param mesh A handle which represents an instance of MeshLink. @@ -819,7 +846,7 @@ extern bool meshlink_set_canonical_address(struct meshlink_handle *mesh, struct * * @return This function returns true if the address was added, false otherwise. */ -extern bool meshlink_add_address(struct meshlink_handle *mesh, const char *address) __attribute__((__warn_unused_result__)); +extern bool meshlink_add_address(struct meshlink_handle *mesh, const char *address) __attribute__((__warn_unused_result__, __deprecated__("use meshlink_set_canonical_address() and/or meshlink_add_invitation_address() instead"))); /// Try to discover the external address for the local node. /** This function performs tries to discover the local node's external address @@ -897,7 +924,7 @@ extern char *meshlink_get_local_address_for_family(struct meshlink_handle *mesh, /// Try to discover the external address for the local node, and add it to its list of addresses. /** This function is equivalent to: * - * meshlink_add_address(mesh, meshlink_get_external_address(mesh)); + * meshlink_set_canonical_address(mesh, meshlink_get_self(mesh), meshlink_get_external_address(mesh), NULL); * * Read the description of meshlink_get_external_address() for the limitations of this function. * @@ -1112,7 +1139,7 @@ extern bool meshlink_whitelist(struct meshlink_handle *mesh, struct meshlink_nod * * \memberof meshlink_node * @param mesh A handle which represents an instance of MeshLink. - * @param node A pointer to a struct meshlink_node describing the node to be whitelisted. + * @param name The name of the node to whitelist. * * @return This function returns true if the node has been whitelisted, false otherwise. */ @@ -1480,13 +1507,24 @@ extern size_t meshlink_channel_get_sendq(struct meshlink_handle *mesh, struct me */ extern size_t meshlink_channel_get_recvq(struct meshlink_handle *mesh, struct meshlink_channel *channel) __attribute__((__warn_unused_result__)); +/// Get the maximum segment size of a channel. +/** This returns the amount of bytes that can be sent at once for channels with UDP semantics. + * + * \memberof meshlink_channel + * @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_mss(struct meshlink_handle *mesh, struct meshlink_channel *channel) __attribute__((__warn_unused_result__)); + /// Set the connection timeout used for channels to the given node. /** This sets the timeout after which unresponsive channels will be reported as closed. * The timeout is set for all current and future channels to the given node. * * \memberof meshlink_node * @param mesh A handle which represents an instance of MeshLink. - * @param channel A handle for the channel. + * @param node A pointer to a struct meshlink_node describing the node to set the channel connection timeout for. * @param timeout The timeout in seconds after which unresponsive channels will be reported as closed. * The default is 60 seconds. */ @@ -1562,6 +1600,29 @@ extern void meshlink_set_dev_class_fast_retry_period(struct meshlink_handle *mes */ extern void meshlink_set_inviter_commits_first(struct meshlink_handle *mesh, bool inviter_commits_first); +/// Set the URL used to discover the host's external address +/** For generating invitation URLs, MeshLink can look up the externally visible address of the local node. + * It does so by querying an external service. By default, this is http://meshlink.io/host.cgi. + * Only URLs starting with http:// are supported. + * + * \memberof meshlink_handle + * @param mesh A handle which represents an instance of MeshLink. + * @param url The URL to use for external address queries, or NULL to revert back to the default URL. + */ +extern void meshlink_set_external_address_discovery_url(struct meshlink_handle *mesh, const char *url); + +/// Set the scheduling granularity of the application +/** This should be set to the effective scheduling granularity for the application. + * This depends on the scheduling granularity of the operating system, the application's + * process priority and whether it is running as realtime or not. + * The default value is 10000 (10 milliseconds). + * + * \memberof meshlink_handle + * @param mesh A handle which represents an instance of MeshLink. + * @param granularity The scheduling granularity of the application in microseconds. + */ +extern void meshlink_set_scheduling_granularity(struct meshlink_handle *mesh, long granularity); + #ifdef __cplusplus } #endif