X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink%2B%2B.h;h=7877aeca22becc6d0e32c67abf9e10b67cc99460;hb=c023ad12147aa88810629c110ea6b1ab94267196;hp=8f4a9b003427f0c1e13f8c232ec38b60887fb21f;hpb=1d7554c7b8c632adf86492be9dc7afecb49bca5d;p=meshlink diff --git a/src/meshlink++.h b/src/meshlink++.h index 8f4a9b00..7877aeca 100644 --- a/src/meshlink++.h +++ b/src/meshlink++.h @@ -43,6 +43,13 @@ typedef meshlink_errno_t errno_t; */ typedef void (*receive_cb_t)(mesh *mesh, node *source, const void *data, size_t len); +/// A callback reporting the meta-connection attempt made by the host node to an another node. +/** @param mesh A handle which represents an instance of MeshLink. + * @param node A pointer to a meshlink_node_t describing the node to whom meta-connection is being tried. + * This pointer is valid until meshlink_close() is called. + */ +typedef void (*connection_try_cb_t)(mesh *mesh, node *node); + /// A callback reporting node status changes. /** @param mesh A handle which represents an instance of MeshLink. * @param node A pointer to a meshlink::node describing the node whose status changed. @@ -91,6 +98,29 @@ typedef void (*channel_receive_cb_t)(mesh *mesh, channel *channel, const void *d */ typedef void (*channel_poll_cb_t)(mesh *mesh, channel *channel, size_t len); +/// A callback for cleaning up buffers submitted for asynchronous I/O. +/** This callbacks signals that MeshLink has finished using this buffer. + * The ownership of the buffer is now back into the application's hands. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param channel A handle for the channel which used this buffer. + * @param data A pointer to a buffer containing the enqueued data. + * @param len The length of the buffer. + * @param priv A private pointer which was set by the application when submitting the buffer. + */ +typedef void (*aio_cb_t)(mesh *mesh, channel *channel, const void *data, size_t len, void *priv); + +/// A callback for asynchronous I/O to and from filedescriptors. +/** This callbacks signals that MeshLink has finished using this filedescriptor. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param channel A handle for the channel which used this filedescriptor. + * @param fd The filedescriptor that was used. + * @param len The length of the data that was successfully sent or received. + * @param priv A private pointer which was set by the application when submitting the buffer. + */ +typedef void (*aio_fd_cb_t)(mesh *mesh, channel *channel, int fd, size_t len, void *priv); + /// A class describing a MeshLink node. class node: public meshlink_node_t { }; @@ -106,6 +136,7 @@ public: static const uint32_t ORDERED = MESHLINK_CHANNEL_ORDERED; static const uint32_t FRAMED = MESHLINK_CHANNEL_FRAMED; static const uint32_t DROP_LATE = MESHLINK_CHANNEL_DROP_LATE; + static const uint32_t NO_PARTIAL = MESHLINK_CHANNEL_NO_PARTIAL; static const uint32_t TCP = MESHLINK_CHANNEL_TCP; static const uint32_t UDP = MESHLINK_CHANNEL_UDP; }; @@ -213,6 +244,12 @@ public: (void)message; } + /// This functions is called whenever MeshLink a meta-connection attempt is made. + virtual void connection_try(node *peer) { + /* do nothing */ + (void)peer; + } + /// This functions is called whenever another node attempts to open a channel to the local node. /** * If the channel is accepted, the poll_callback will be set to channel_poll and can be @@ -287,6 +324,7 @@ public: meshlink_set_node_duplicate_cb(handle, &node_duplicate_trampoline); meshlink_set_log_cb(handle, MESHLINK_DEBUG, &log_trampoline); meshlink_set_channel_accept_cb(handle, &channel_accept_trampoline); + meshlink_set_connection_try_cb(handle, &connection_try_trampoline); return meshlink_start(handle); } @@ -519,7 +557,9 @@ public: * If the port is set to 0, then MeshLink will listen on a port * that is randomly assigned by the operating system every time open() is called. * - * @return This function returns true if the port was successfully changed, false otherwise. + * @return This function returns true if the port was successfully changed + * to the desired port, false otherwise. If it returns false, there + * is no guarantee that MeshLink is listening on the old port. */ bool set_port(int port) { return meshlink_set_port(handle, port); @@ -621,6 +661,30 @@ public: meshlink_set_channel_poll_cb(handle, channel, (meshlink_channel_poll_cb_t)cb); } + /// Set the send buffer size of a channel. + /** This function sets the desired size of the send buffer. + * The default size is 128 kB. + * + * @param channel A handle for the channel. + * @param size The desired size for the send buffer. + * If a NULL pointer is given, the callback will be disabled. + */ + void set_channel_sndbuf(channel *channel, size_t size) { + meshlink_set_channel_sndbuf(handle, channel, size); + } + + /// Set the receive buffer size of a channel. + /** This function sets the desired size of the receive buffer. + * The default size is 128 kB. + * + * @param channel A handle for the channel. + * @param size The desired size for the send buffer. + * If a NULL pointer is given, the callback will be disabled. + */ + void set_channel_rcvbuf(channel *channel, size_t size) { + meshlink_set_channel_rcvbuf(handle, channel, size); + } + /// Open a reliable stream channel to another node. /** This function is called whenever a remote node wants to open a channel to the local node. * The application then has to decide whether to accept or reject this channel. @@ -698,11 +762,81 @@ public: * @param len The length of the data. * * @return The amount of data that was queued, which can be less than len, or a negative value in case of an error. + * If MESHLINK_CHANNEL_NO_PARTIAL is set, then the result will either be len, + * 0 if the buffer is currently too full, or -1 if len is too big even for an empty buffer. */ ssize_t channel_send(channel *channel, void *data, size_t len) { return meshlink_channel_send(handle, channel, data, len); } + /// Transmit data on a channel asynchronously + /** This registers a buffer that will be used to send data to the remote node. + * Multiple buffers can be registered, in which case data will be sent in the order the buffers were registered. + * While there are still buffers with unsent data, the poll callback will not be called. + * + * @param channel A handle for the channel. + * @param data A pointer to a buffer containing data sent by the source, or NULL if there is no data to send. + * After meshlink_channel_aio_send() returns, the buffer may not be modified or freed by the application + * until the callback routine is called. + * @param len The length of the data, or 0 if there is no data to send. + * @param cb A pointer to the function which will be called when MeshLink has finished using the buffer. + * + * @return True if the buffer was enqueued, false otherwise. + */ + bool channel_aio_send(channel *channel, const void *data, size_t len, meshlink_aio_cb_t cb, void *priv) { + return meshlink_channel_aio_send(handle, channel, data, len, cb, priv); + } + + /// Transmit data on a channel asynchronously from a filedescriptor + /** This will read up to the specified length number of bytes from the given filedescriptor, and send it over the channel. + * The callback may be returned early if there is an error reading from the filedescriptor. + * While there is still with unsent data, the poll callback will not be called. + * + * @param channel A handle for the channel. + * @param fd A file descriptor from which data will be read. + * @param len The length of the data, or 0 if there is no data to send. + * @param cb A pointer to the function which will be called when MeshLink has finished using the filedescriptor. + * + * @return True if the buffer was enqueued, false otherwise. + */ + bool channel_aio_fd_send(channel *channel, int fd, size_t len, meshlink_aio_fd_cb_t cb, void *priv) { + return meshlink_channel_aio_fd_send(handle, channel, fd, len, cb, priv); + } + + /// Receive data on a channel asynchronously + /** This registers a buffer that will be filled with incoming channel data. + * Multiple buffers can be registered, in which case data will be received in the order the buffers were registered. + * While there are still buffers that have not been filled, the receive callback will not be called. + * + * @param channel A handle for the channel. + * @param data A pointer to a buffer that will be filled with incoming data. + * After meshlink_channel_aio_receive() returns, the buffer may not be modified or freed by the application + * until the callback routine is called. + * @param len The length of the data. + * @param cb A pointer to the function which will be called when MeshLink has finished using the buffer. + * + * @return True if the buffer was enqueued, false otherwise. + */ + bool channel_aio_receive(channel *channel, const void *data, size_t len, meshlink_aio_cb_t cb, void *priv) { + return meshlink_channel_aio_receive(handle, channel, data, len, cb, priv); + } + + /// Receive data on a channel asynchronously and send it to a filedescriptor + /** This will read up to the specified length number of bytes from the channel, and send it to the filedescriptor. + * The callback may be returned early if there is an error writing to the filedescriptor. + * While there is still unread data, the receive callback will not be called. + * + * @param channel A handle for the channel. + * @param fd A file descriptor to which data will be written. + * @param len The length of the data. + * @param cb A pointer to the function which will be called when MeshLink has finished using the filedescriptor. + * + * @return True if the buffer was enqueued, false otherwise. + */ + bool channel_aio_fd_receive(channel *channel, int fd, size_t len, meshlink_aio_fd_cb_t cb, void *priv) { + return meshlink_channel_aio_fd_receive(handle, channel, fd, len, cb, priv); + } + /// 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. @@ -779,6 +913,15 @@ private: that->log(level, message); } + static void connection_try_trampoline(meshlink_handle_t *handle, meshlink_node_t *peer) { + if(!(handle->priv)) { + return; + } + + meshlink::mesh *that = static_cast(handle->priv); + that->connection_try(static_cast(peer)); + } + static bool channel_accept_trampoline(meshlink_handle_t *handle, meshlink_channel *channel, uint16_t port, const void *data, size_t len) { if(!(handle->priv)) { return false;