adding number of preferences to allow iterating over preferences

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

diff --git a/src/include/gnunet_connection_lib.h b/src/include/gnunet_connection_lib.h
index 0051e5fb5c3135c1c5bcb6f45557c8c14309bcb9..c4c76a7eb100ddb7f561728e25be92d14671c5ef 100644 (file)
--- a/src/include/gnunet_connection_lib.h
+++ b/src/include/gnunet_connection_lib.h
@@ -1,6 +1,6 @@
 /*
      This file is part of GNUnet.
-     (C) 2009 Christian Grothoff (and other contributing authors)
+     Copyright (C) 2009 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
@@ -123,16 +123,32 @@ GNUNET_CONNECTION_persist_ (struct GNUNET_CONNECTION_Handle *connection);
  * reach the other side before the process is terminated.
  *
  * @param connection the connection to make flushing and blocking
- * @return GNUNET_OK on success
+ * @return #GNUNET_OK on success
  */
 int
 GNUNET_CONNECTION_disable_corking (struct GNUNET_CONNECTION_Handle *connection);
 
 
+/**
+ * Create a connection handle by (asynchronously) connecting to a host.
+ * This function returns immediately, even if the connection has not
+ * yet been established.  This function only creates TCP connections.
+ *
+ * @param s socket to connect
+ * @param serv_addr server address
+ * @param addrlen length of server address
+ * @return the connection handle
+ */
+struct GNUNET_CONNECTION_Handle *
+GNUNET_CONNECTION_connect_socket (struct GNUNET_NETWORK_Handle *s,
+                                  const struct sockaddr *serv_addr,
+                                  socklen_t addrlen);
+
+
 /**
  * Create a connection handle by boxing an existing OS socket.  The OS
  * socket should henceforth be no longer used directly.
- * GNUNET_CONNECTION_destroy will close it.
+ * #GNUNET_CONNECTION_destroy() will close it.
  *
  * @param osSocket existing socket to box
  * @return the boxed socket handle
@@ -145,14 +161,14 @@ GNUNET_CONNECTION_create_from_existing (struct GNUNET_NETWORK_Handle *osSocket);
  * Create a connection handle by accepting on a listen socket.  This
  * function may block if the listen socket has no connection ready.
  *
- * @param access function to use to check if access is allowed
- * @param access_cls closure for access
+ * @param access_cb function to use to check if access is allowed
+ * @param access_cb_cls closure for @a access_cb
  * @param lsock listen socket
  * @return the connection handle, NULL on error (for example, access refused)
  */
 struct GNUNET_CONNECTION_Handle *
-GNUNET_CONNECTION_create_from_accept (GNUNET_CONNECTION_AccessCheck access,
-                                      void *access_cls,
+GNUNET_CONNECTION_create_from_accept (GNUNET_CONNECTION_AccessCheck access_cb,
+                                      void *access_cb_cls,
                                       struct GNUNET_NETWORK_Handle *lsock);
 
 
@@ -296,8 +312,8 @@ struct GNUNET_CONNECTION_TransmitHandle;
 
 /**
  * Ask the connection to call us once the specified number of bytes
- * are free in the transmission buffer.  May call the notify
- * method immediately if enough space is available.  Note that
+ * are free in the transmission buffer.  Will never call the @a notify
+ * callback in this task, but always first go into the scheduler.  Note that
  * this function will abort if "size" is greater than
  * #GNUNET_SERVER_MAX_MESSAGE_SIZE.
  *