diff options
Diffstat (limited to 'src/include/gnunet_stream_lib.h')
| -rw-r--r-- | src/include/gnunet_stream_lib.h | 297 |
1 files changed, 297 insertions, 0 deletions
diff --git a/src/include/gnunet_stream_lib.h b/src/include/gnunet_stream_lib.h new file mode 100644 index 0000000..930cc1d --- /dev/null +++ b/src/include/gnunet_stream_lib.h @@ -0,0 +1,297 @@ +/* + This file is part of GNUnet. + (C) 2011, 2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. +*/ + +/** + * @file include/gnunet_stream_lib.h + * @brief stream handling using mesh API + * @author Sree Harsha Totakura + */ + +#ifndef GNUNET_STREAM_LIB_H +#define GNUNET_STREAM_LIB_H + +#ifdef __cplusplus +extern "C" +{ +#if 0 +} +#endif +#endif + +#include "gnunet_util_lib.h" +#include "gnunet_mesh_service.h" + +/** + * Stream status + */ +enum GNUNET_STREAM_Status + { + /** + * All previous read/write operations are successfully done + */ + GNUNET_STREAM_OK = 0, + + /** + * A timeout occured while reading/writing the stream + */ + GNUNET_STREAM_TIMEOUT = 1, + + /** + * Other side has shutdown the socket for this type of operation + * (reading/writing) + */ + GNUNET_STREAM_SHUTDOWN = 2, + + /** + * A serious error occured while operating on this stream + */ + GNUNET_STREAM_SYSERR = 3 + }; + +/** + * Opaque handler for stream + */ +struct GNUNET_STREAM_Socket; + +/** + * Functions of this type will be called when a stream is established + * + * @param cls the closure from GNUNET_STREAM_open + * @param socket socket to use to communicate with the other side (read/write) + */ +typedef void (*GNUNET_STREAM_OpenCallback) (void *cls, + struct GNUNET_STREAM_Socket *socket); + + +/** + * Options for the stream. + */ +enum GNUNET_STREAM_Option + { + /** + * End of the option list. + */ + GNUNET_STREAM_OPTION_END = 0, + + /** + * Option to set the initial retransmission timeout (when do we retransmit + * a packet that did not yield an acknowledgement for the first time?). + * Repeated retransmissions will then use an exponential back-off. + * Takes a 'struct GNUNET_TIME_Relative' as the only argument. A value + * of '0' means to use the round-trip time (plus a tiny grace period); + * this is also the default. + */ + GNUNET_STREAM_OPTION_INITIAL_RETRANSMIT_TIMEOUT + }; + + +/** + * Tries to open a stream to the target peer + * + * @param cfg configuration to use + * @param target the target peer to which the stream has to be opened + * @param app_port the application port number which uniquely identifies this + * stream + * @param open_cb this function will be called after stream has be established + * @param open_cb_cls the closure for open_cb + * @param ... options to the stream, terminated by GNUNET_STREAM_OPTION_END + * @return if successful it returns the stream socket; NULL if stream cannot be + * opened + */ +struct GNUNET_STREAM_Socket * +GNUNET_STREAM_open (const struct GNUNET_CONFIGURATION_Handle *cfg, + const struct GNUNET_PeerIdentity *target, + GNUNET_MESH_ApplicationType app_port, + GNUNET_STREAM_OpenCallback open_cb, + void *open_cb_cls, + ...); + + +/** + * Shutdown the stream for reading or writing (man 2 shutdown). + * + * @param socket the stream socket + * @param how SHUT_RD, SHUT_WR or SHUT_RDWR + */ +void +GNUNET_STREAM_shutdown (struct GNUNET_STREAM_Socket *socket, + int how); + + +/** + * Closes the stream + * + * @param socket the stream socket + */ +void +GNUNET_STREAM_close (struct GNUNET_STREAM_Socket *socket); + + +/** + * Functions of this type are called upon new stream connection from other peers + * + * @param cls the closure from GNUNET_STREAM_listen + * @param socket the socket representing the stream + * @param initiator the identity of the peer who wants to establish a stream + * with us + * @return GNUNET_OK to keep the socket open, GNUNET_SYSERR to close the + * stream (the socket will be invalid after the call) + */ +typedef int (*GNUNET_STREAM_ListenCallback) (void *cls, + struct GNUNET_STREAM_Socket *socket, + const struct + GNUNET_PeerIdentity *initiator); + + +/** + * A socket for listening. + */ +struct GNUNET_STREAM_ListenSocket; + +/** + * Listens for stream connections for a specific application ports + * + * @param cfg the configuration to use + * @param app_port the application port for which new streams will be accepted + * @param listen_cb this function will be called when a peer tries to establish + * a stream with us + * @param listen_cb_cls closure for listen_cb + * @return listen socket, NULL for any error + */ +struct GNUNET_STREAM_ListenSocket * +GNUNET_STREAM_listen (const struct GNUNET_CONFIGURATION_Handle *cfg, + GNUNET_MESH_ApplicationType app_port, + GNUNET_STREAM_ListenCallback listen_cb, + void *listen_cb_cls); + + +/** + * Closes the listen socket + * + * @param socket the listen socket + */ +void +GNUNET_STREAM_listen_close (struct GNUNET_STREAM_ListenSocket *socket); + + +/** + * Functions of this signature are called whenever writing operations + * on a stream are executed + * + * @param cls the closure from GNUNET_STREAM_write + * @param status the status of the stream at the time this function is called + * @param size the number of bytes written + */ +typedef void (*GNUNET_STREAM_CompletionContinuation) (void *cls, + enum GNUNET_STREAM_Status + status, + size_t size); + + +/** + * Handle to cancel IO write operations. + */ +struct GNUNET_STREAM_IOWriteHandle; + + +/** + * Handle to cancel IO read operations. + */ +struct GNUNET_STREAM_IOReadHandle; + +/** + * Tries to write the given data to the stream + * + * @param socket the socket representing a stream + * @param data the data buffer from where the data is written into the stream + * @param size the number of bytes to be written from the data buffer + * @param timeout the timeout period + * @param write_cont the function to call upon writing some bytes into the stream + * @param write_cont_cls the closure + * @return handle to cancel the operation; NULL if a previous write is pending + */ +struct GNUNET_STREAM_IOWriteHandle * +GNUNET_STREAM_write (struct GNUNET_STREAM_Socket *socket, + const void *data, + size_t size, + struct GNUNET_TIME_Relative timeout, + GNUNET_STREAM_CompletionContinuation write_cont, + void *write_cont_cls); + + +/** + * Functions of this signature are called whenever data is available from the + * stream. + * + * @param cls the closure from GNUNET_STREAM_read + * @param status the status of the stream at the time this function is called + * @param data traffic from the other side + * @param size the number of bytes available in data read + * @return number of bytes of processed from 'data' (any data remaining should be + * given to the next time the read processor is called). + */ +typedef size_t (*GNUNET_STREAM_DataProcessor) (void *cls, + enum GNUNET_STREAM_Status status, + const void *data, + size_t size); + + +/** + * Tries to read data from the stream + * + * @param socket the socket representing a stream + * @param timeout the timeout period + * @param proc function to call with data (once only) + * @param proc_cls the closure for proc + * @return handle to cancel the operation + */ +struct GNUNET_STREAM_IOReadHandle * +GNUNET_STREAM_read (struct GNUNET_STREAM_Socket *socket, + struct GNUNET_TIME_Relative timeout, + GNUNET_STREAM_DataProcessor proc, + void *proc_cls); + + +/** + * Cancel pending write operation. + * + * @param ioh handle to operation to cancel + */ +void +GNUNET_STREAM_io_write_cancel (struct GNUNET_STREAM_IOWriteHandle *ioh); + + +/** + * Cancel pending read operation. + * + * @param ioh handle to operation to cancel + */ +void +GNUNET_STREAM_io_read_cancel (struct GNUNET_STREAM_IOReadHandle *ioh); + + +#if 0 +{ +#endif +#ifdef __cplusplus +} +#endif + +#endif /* STREAM_PROTOCOL_H */ |