X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink%2B%2B.h;h=5550a9e302339c02a2ce5a66862072384d86ee62;hb=9e46fee1c71faad5e6f0b69ff9a92d01d0dad899;hp=48eabf3fbf5fdf80cfb3586c6a5001e808a7e208;hpb=2fd608c4111ef4d48a649401d918f5981856cc44;p=meshlink diff --git a/src/meshlink++.h b/src/meshlink++.h index 48eabf3f..5550a9e3 100644 --- a/src/meshlink++.h +++ b/src/meshlink++.h @@ -98,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 { }; @@ -113,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; }; @@ -533,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); @@ -635,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. @@ -712,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. @@ -751,6 +871,16 @@ public: meshlink_enable_discovery(handle, enable); } + /// Set device class timeouts + /** This sets the ping interval and timeout for a given device class. + * + * @param devclass The device class to update + * @param pinginterval The interval between keepalive packets, in seconds. The default is 60. + * @param pingtimeout The required time within which a peer should respond, in seconds. The default is 5. + * The timeout must be smaller than the interval. + */ + void set_dev_class_timeouts(dev_class_t devclass, int pinginterval, int pingtimeout); + private: // non-copyable: mesh(const mesh &) /* TODO: C++11: = delete */;