From 04ae1bc73842a2aad9ca73d9abb6875a58cbdd40 Mon Sep 17 00:00:00 2001 From: Sree Harsha Totakura Date: Fri, 9 Dec 2011 15:55:00 +0000 Subject: [PATCH] added API definitions for stream library --- src/include/gnunet_stream_lib.h | 180 ++++++++++++++++++++++++++++++++ src/stream/README | 11 ++ 2 files changed, 191 insertions(+) create mode 100644 src/include/gnunet_stream_lib.h create mode 100644 src/stream/README diff --git a/src/include/gnunet_stream_lib.h b/src/include/gnunet_stream_lib.h new file mode 100644 index 000000000..f6935075a --- /dev/null +++ b/src/include/gnunet_stream_lib.h @@ -0,0 +1,180 @@ +/* + This file is part of GNUnet. + (C) 2011, 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, + + /** + * A serious error occured while operating of this stream + */ + GNUNET_STREAM_SYSERR = 2 + }; + +/** + * 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 + */ +typedef void (*GNUNET_STREAM_OpenCallback) (void *cls); + +/** + * Tries to open a stream to the target peer + * + * @param cls the closure + * @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 + * @return if successful it returns the stream socket; NULL if stream cannot be + * opened + */ +struct GNUNET_STREAM_socket * +GNUNET_STREAM_open (void *cls, + const struct GNUNET_PeerIdentity *target, + GNUNET_MESH_ApplicationType app_port, + GNUNET_STREAM_OpenCallback open_cb); + +/** + * 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); + +/** + * Listens for stream connections for a specific application ports + * + * @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 + * @return GNUNET_OK if we are listening, GNUNET_SYSERR for any error + */ +int +GNUNET_STREAM_listen (GNUNET_MESH_ApplicationType app_port, + GNUNET_STREAM_ListenCallback listen_cb, + void *cls); + +/** + * Functions of this signature are called whenever reading/writing operations + * on a stream are executed + * + * @param cls the closure from GNUNET_STREAM_write/read + * @param status the status of the stream at the time this function is called + * @param size the number of bytes read or written + */ +typedef void (*GNUNET_STREAM_CompletionCallback) (void *cls, + enum GNUNET_STREAM_Status + status, + size_t size); + +/** + * 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 write_cb the function to call upon writing some bytes into the stream + * @param timeout the timeout period + * @param cls the closure + */ +void +GNUNET_STREAM_write (const struct GNUNET_STREAM_socket *socket, + void *data, + size_t size, + GNUNET_STREAM_CompletionCallback write_cb, + struct GNUNET_TIME_Relative timeout, + void *cls); + +/** + * Tries to read data from the stream + * + * @param socket the socket representing a stream + * @param buffer the buffer into which the read data is stored + + * @return + */ +size_t +GNUNET_STREAM_read (const struct GNUNET_STREAM_socket *socket, + void *buffer, + size_t size, + GNUNET_STREAM_CompletionCallback read_cb, + struct GNUNET_TIME_Relative timeout, + void *cls); +/** + * Closes the stream + * + * @param socket the stream socket + */ +void +GNUNET_STREAM_close (struct GNUNET_STREAM_socket *socket); + +#if 0 +{ +#endif +#ifdef __cplusplus +} +#endif + +#endif diff --git a/src/stream/README b/src/stream/README new file mode 100644 index 000000000..9b550b09b --- /dev/null +++ b/src/stream/README @@ -0,0 +1,11 @@ +The aim of the stream library is to provide stream connections between peers in +GNUnet. This is a convenience library which hides the complexity of dividing +data stream into packets, transmitting them and retransmitting them in case of +errors. + +This library's API are similar to unix PIPE API. The user is expected to open a +stream to a listening target peer. Once the stream is established, the user can +use it as a pipe. Any data written into the stream will be readable by the +target peer. + +This library uses mesh API for establishing streams between peers. \ No newline at end of file -- 2.25.1