-peer review

[oweals/gnunet.git] / src / include / gnunet_stream_lib.h

diff --git a/src/include/gnunet_stream_lib.h b/src/include/gnunet_stream_lib.h
index 099f37ab2eebd61d0e9435bea1fdb8c4c71ec19e..ac106593728da0e452eae00dd5f3018a78642115 100644 (file)
--- a/src/include/gnunet_stream_lib.h
+++ b/src/include/gnunet_stream_lib.h
@@ -62,7 +62,12 @@ enum GNUNET_STREAM_Status
     /**
      * A serious error occured while operating on this stream
      */
-    GNUNET_STREAM_SYSERR = 3
+    GNUNET_STREAM_SYSERR = 3,
+    
+    /**
+     * An error resulted in an unusable stream
+     */
+    GNUNET_STREAM_BROKEN
   };
 
 /**
@@ -80,6 +85,13 @@ typedef void (*GNUNET_STREAM_OpenCallback) (void *cls,
                                            struct GNUNET_STREAM_Socket *socket);
 
 
+/**
+ * Callback for signalling stream listen success; See
+ * GNUNET_STREAM_OPTION_SIGNAL_LISTEN_SUCCESS
+ */
+typedef void (*GNUNET_STREAM_ListenSuccessCallback) (void);
+
+
 /**
  * Options for the stream.
  */
@@ -98,7 +110,33 @@ enum GNUNET_STREAM_Option
      * 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
+    GNUNET_STREAM_OPTION_INITIAL_RETRANSMIT_TIMEOUT,
+
+    /**
+     * Option to set the write sequence number. Takes a uint32_t as parameter
+     * to set the value of the write sequence number
+     */
+    GNUNET_STREAM_OPTION_TESTING_SET_WRITE_SEQUENCE_NUMBER,
+
+    /**
+     * Listen socket timeout in milliseconds given as uint32_t
+     */
+    GNUNET_STREAM_OPTION_LISTEN_TIMEOUT,
+
+    /**
+     * Option to register a callback when stream listening is
+     * successfull. Takes parameter of the form
+     * GNUNET_STREAM_ListenSuccessCallback. The callback is only called if
+     * listen is successful
+     */
+    GNUNET_STREAM_OPTION_SIGNAL_LISTEN_SUCCESS,
+
+    /**
+     * Option to set the maximum payload size in bytes of a stream data
+     * packets. Takes an uint16_t as argument. Note that this should be less
+     * than 64000 and cannot be zero. Default is 64000 bytes.
+     */
+    GNUNET_STREAM_OPTION_MAX_PAYLOAD_SIZE
   };
 
 
@@ -109,7 +147,8 @@ enum GNUNET_STREAM_Option
  * @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 this function will be called after stream has be established;
+ *          cannot be NULL
  * @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
@@ -181,9 +220,9 @@ 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 socket the socket representing the stream; NULL on binding error
  * @param initiator the identity of the peer who wants to establish a stream
- *            with us
+ *            with us; NULL on binding error
  * @return GNUNET_OK to keep the socket open, GNUNET_SYSERR to close the
  *             stream (the socket will be invalid after the call)
  */
@@ -202,17 +241,24 @@ 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 app_port the application port for which new streams will be
+ *         accepted. If another stream is listening on the same port the
+ *         listen_cb will be called to signal binding error and the returned
+ *         ListenSocket will be invalidated.
+ *
  * @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
+ * @param ... options to the stream, terminated by GNUNET_STREAM_OPTION_END
  * @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);
+                      void *listen_cb_cls,
+                      ...);
 
 
 /**