- use tunnel encryption state to select decryption key

[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 af10c59664fff332d9ea90bf6aef0ebdab24e5f7..ed9ca9167c2b3aef9100ec7304a15e56b7f76f11 100644 (file)
--- a/src/include/gnunet_connection_lib.h
+++ b/src/include/gnunet_connection_lib.h
@@ -4,7 +4,7 @@
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
 
      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 2, or (at your
+     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
      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but


@@ -109,9 +109,10 @@ typedef void (*GNUNET_CONNECTION_Receiver) (void *cls, const void *buf,
  * that the underlying socket or fd should never really be closed.
  * Used for indicating process death.
  *
  * that the underlying socket or fd should never really be closed.
  * Used for indicating process death.
  *

- * @param sock the connection to set persistent
+ * @param connection the connection to set persistent

  */
  */

-void GNUNET_CONNECTION_persist_ (struct GNUNET_CONNECTION_Handle *sock);
+void
+GNUNET_CONNECTION_persist_ (struct GNUNET_CONNECTION_Handle *connection);

 
 /**
  * Disable the "CORK" feature for communication with the given socket,
 
 /**
  * Disable the "CORK" feature for communication with the given socket,


@@ -121,172 +122,160 @@ void GNUNET_CONNECTION_persist_ (struct GNUNET_CONNECTION_Handle *sock);
  * Used to make sure that the last messages sent through the connection
  * reach the other side before the process is terminated.
  *
  * Used to make sure that the last messages sent through the connection
  * reach the other side before the process is terminated.
  *

- * @param sock the connection to make flushing and blocking
+ * @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 *sock);
+int
+GNUNET_CONNECTION_disable_corking (struct GNUNET_CONNECTION_Handle *connection);

 
 
 /**
 
 
 /**

- * Create a socket handle by boxing an existing OS socket.  The OS
+ * Create a connection handle by boxing an existing OS socket.  The OS

  * socket should henceforth be no longer used directly.
  * socket should henceforth be no longer used directly.

- * GNUNET_socket_destroy will close it.
+ * GNUNET_CONNECTION_destroy will close it.

  *
  * @param osSocket existing socket to box
  * @return the boxed socket handle
  */
  *
  * @param osSocket existing socket to box
  * @return the boxed socket handle
  */

-struct GNUNET_CONNECTION_Handle *GNUNET_CONNECTION_create_from_existing (struct
-                                                                         GNUNET_NETWORK_Handle
-                                                                         *osSocket);
+struct GNUNET_CONNECTION_Handle *
+GNUNET_CONNECTION_create_from_existing (struct GNUNET_NETWORK_Handle *osSocket);

 
 
 /**
 
 
 /**

- * Create a socket handle by accepting on a listen socket.  This
+ * 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 lsock listen socket
  * 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 lsock listen socket

- * @return the socket handle, NULL on error (for example, access refused)
+ * @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,
-                                           struct GNUNET_NETWORK_Handle *lsock);
+struct GNUNET_CONNECTION_Handle *
+GNUNET_CONNECTION_create_from_accept (GNUNET_CONNECTION_AccessCheck access,
+                                      void *access_cls,
+                                      struct GNUNET_NETWORK_Handle *lsock);

 
 
 /**
 
 
 /**

- * Create a socket handle by (asynchronously) connecting to a host.
+ * 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 cfg configuration to use
  * @param hostname name of the host to connect to
  * @param port port to connect to
  * This function returns immediately, even if the connection has not
  * yet been established.  This function only creates TCP connections.
  *
  * @param cfg configuration to use
  * @param hostname name of the host to connect to
  * @param port port to connect to

- * @return the socket handle
+ * @return the connection handle

  */
  */

-struct GNUNET_CONNECTION_Handle *GNUNET_CONNECTION_create_from_connect (const
-                                                                        struct
-                                                                        GNUNET_CONFIGURATION_Handle
-                                                                        *cfg,
-                                                                        const
-                                                                        char
-                                                                        *hostname,
-                                                                        uint16_t
-                                                                        port);
+struct GNUNET_CONNECTION_Handle *
+GNUNET_CONNECTION_create_from_connect (const struct GNUNET_CONFIGURATION_Handle
+                                       *cfg, const char *hostname,
+                                       uint16_t port);

 
 
 /**
 
 
 /**

- * Create a socket handle by connecting to a UNIX domain service.
+ * Create a connection handle by connecting to a UNIX domain service.

  * This function returns immediately, even if the connection has not
  * yet been established.  This function only creates UNIX connections.
  *
  * @param cfg configuration to use
  * @param unixpath path to connect to)
  * This function returns immediately, even if the connection has not
  * yet been established.  This function only creates UNIX connections.
  *
  * @param cfg configuration to use
  * @param unixpath path to connect to)

- * @return the socket handle, NULL on systems without UNIX support
+ * @return the connection handle, NULL on systems without UNIX support

  */
  */

-struct GNUNET_CONNECTION_Handle
-    *GNUNET_CONNECTION_create_from_connect_to_unixpath (const struct
-                                                        GNUNET_CONFIGURATION_Handle
-                                                        *cfg,
-                                                        const char *unixpath);
+struct GNUNET_CONNECTION_Handle *
+GNUNET_CONNECTION_create_from_connect_to_unixpath (const struct
+                                                   GNUNET_CONFIGURATION_Handle
+                                                   *cfg, const char *unixpath);

 
 
 
 
 /**
 
 
 
 
 /**

- * Create a socket handle by (asynchronously) connecting to a host.
+ * 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 af_family address family to use
  * @param serv_addr server address
  * @param addrlen length of server address
  * This function returns immediately, even if the connection has not
  * yet been established.  This function only creates TCP connections.
  *
  * @param af_family address family to use
  * @param serv_addr server address
  * @param addrlen length of server address

- * @return the socket handle
+ * @return the connection handle

  */
  */

-struct GNUNET_CONNECTION_Handle *GNUNET_CONNECTION_create_from_sockaddr (int
-                                                                         af_family,
-                                                                         const
-                                                                         struct
-                                                                         sockaddr
-                                                                         *serv_addr,
-                                                                         socklen_t
-                                                                         addrlen);
+struct GNUNET_CONNECTION_Handle *
+GNUNET_CONNECTION_create_from_sockaddr (int af_family,
+                                        const struct sockaddr *serv_addr,
+                                        socklen_t addrlen);

 
 /**
 
 /**

- * Check if socket is valid (no fatal errors have happened so far).
- * Note that a socket that is still trying to connect is considered
+ * Check if connection is valid (no fatal errors have happened so far).
+ * Note that a connection that is still trying to connect is considered

  * valid.
  *
  * valid.
  *

- * @param sock socket to check
+ * @param connection handle to check

  * @return GNUNET_YES if valid, GNUNET_NO otherwise
  */
  * @return GNUNET_YES if valid, GNUNET_NO otherwise
  */

-int GNUNET_CONNECTION_check (struct GNUNET_CONNECTION_Handle *sock);
+int
+GNUNET_CONNECTION_check (struct GNUNET_CONNECTION_Handle *connection);

 
 
 /**
  * Obtain the network address of the other party.
  *
 
 
 /**
  * Obtain the network address of the other party.
  *

- * @param sock the client to get the address for
+ * @param connection the client to get the address for

  * @param addr where to store the address
  * @param addrlen where to store the length of the address
  * @return GNUNET_OK on success
  */
  * @param addr where to store the address
  * @param addrlen where to store the length of the address
  * @return GNUNET_OK on success
  */

-int GNUNET_CONNECTION_get_address (struct GNUNET_CONNECTION_Handle *sock,
-                                   void **addr, size_t * addrlen);
+int
+GNUNET_CONNECTION_get_address (struct GNUNET_CONNECTION_Handle *connection,
+                               void **addr, size_t * addrlen);

 
 
 /**
 
 
 /**

- * Close the socket and free associated resources. Pending
- * transmissions may be completed or dropped depending on the
- * arguments.   If a receive call is pending and should 
- * NOT be completed, 'GNUNET_CONNECTION_receive_cancel'
- * should be called explicitly first.
+ * Close the connection and free associated resources.  There must
+ * not be any pending requests for reading or writing to the
+ * connection at this time.

  *
  *

- * @param sock socket to destroy
- * @param finish_pending_write should pending writes be completed or aborted?
- *        (this applies to transmissions where the data has already been
- *        read from the application; all other transmissions should be
- *        aborted using 'GNUNET_CONNECTION_notify_transmit_ready_cancel').
+ * @param connection connection to destroy

  */
  */

-void GNUNET_CONNECTION_destroy (struct GNUNET_CONNECTION_Handle *sock,
-                                int finish_pending_write);
+void
+GNUNET_CONNECTION_destroy (struct GNUNET_CONNECTION_Handle *connection);

 
 
 /**
 
 
 /**

- * Receive data from the given socket.  Note that this function will
+ * Receive data from the given connection.  Note that this function will

  * call "receiver" asynchronously using the scheduler.  It will
  * "immediately" return.  Note that there MUST only be one active
  * call "receiver" asynchronously using the scheduler.  It will
  * "immediately" return.  Note that there MUST only be one active

- * receive call per socket at any given point in time (so do not
+ * receive call per connection at any given point in time (so do not

  * call receive again until the receiver callback has been invoked).
  *
  * call receive again until the receiver callback has been invoked).
  *

- * @param sock socket handle
+ * @param connection connection handle

  * @param max maximum number of bytes to read
  * @param timeout maximum amount of time to wait
  * @param receiver function to call with received data
  * @param receiver_cls closure for receiver
  */
  * @param max maximum number of bytes to read
  * @param timeout maximum amount of time to wait
  * @param receiver function to call with received data
  * @param receiver_cls closure for receiver
  */

-void GNUNET_CONNECTION_receive (struct GNUNET_CONNECTION_Handle *sock,
-                                size_t max, struct GNUNET_TIME_Relative timeout,
-                                GNUNET_CONNECTION_Receiver receiver,
-                                void *receiver_cls);
+void
+GNUNET_CONNECTION_receive (struct GNUNET_CONNECTION_Handle *connection, size_t max,
+                           struct GNUNET_TIME_Relative timeout,
+                           GNUNET_CONNECTION_Receiver receiver,
+                           void *receiver_cls);

 
 
 /**
 
 
 /**

- * Cancel receive job on the given socket.  Note that the
+ * Cancel receive job on the given connection.  Note that the

  * receiver callback must not have been called yet in order
  * for the cancellation to be valid.
  *
  * receiver callback must not have been called yet in order
  * for the cancellation to be valid.
  *

- * @param sock socket handle
+ * @param connection connection handle

  * @return closure of the original receiver callback closure
  */
  * @return closure of the original receiver callback closure
  */

-void *GNUNET_CONNECTION_receive_cancel (struct GNUNET_CONNECTION_Handle *sock);
+void *
+GNUNET_CONNECTION_receive_cancel (struct GNUNET_CONNECTION_Handle *connection);

 
 
 /**
 
 
 /**

- * Function called to notify a client about the socket
+ * Function called to notify a client about the connection

  * begin ready to queue more data.  "buf" will be
  * begin ready to queue more data.  "buf" will be

- * NULL and "size" zero if the socket was closed for
+ * NULL and "size" zero if the connection was closed for

  * writing in the meantime.
  *
  * @param cls closure
  * writing in the meantime.
  *
  * @param cls closure


@@ -305,17 +294,17 @@ typedef size_t (*GNUNET_CONNECTION_TransmitReadyNotify) (void *cls, size_t size,
 struct GNUNET_CONNECTION_TransmitHandle;
 
 /**
 struct GNUNET_CONNECTION_TransmitHandle;
 
 /**

- * Ask the socket to call us once the specified number of bytes
+ * 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
  * this function will abort if "size" is greater than
  * GNUNET_SERVER_MAX_MESSAGE_SIZE.
  *
  * Note that "notify" will be called either when enough
  * are free in the transmission buffer.  May call the notify
  * method immediately if enough space is available.  Note that
  * this function will abort if "size" is greater than
  * GNUNET_SERVER_MAX_MESSAGE_SIZE.
  *
  * Note that "notify" will be called either when enough

- * buffer space is available OR when the socket is destroyed.
+ * buffer space is available OR when the connection is destroyed.

  * The size parameter given to notify is guaranteed to be
  * larger or equal to size if the buffer is ready, or zero
  * The size parameter given to notify is guaranteed to be
  * larger or equal to size if the buffer is ready, or zero

- * if the socket was destroyed (or at least closed for
+ * if the connection was destroyed (or at least closed for

  * writing).  Finally, any time before 'notify' is called, a
  * client may call "notify_transmit_ready_cancel" to cancel
  * the transmission request.
  * writing).  Finally, any time before 'notify' is called, a
  * client may call "notify_transmit_ready_cancel" to cancel
  * the transmission request.


@@ -324,7 +313,7 @@ struct GNUNET_CONNECTION_TransmitHandle;
  * time.  Notify will be run with the same scheduler priority
  * as that of the caller.
  *
  * time.  Notify will be run with the same scheduler priority
  * as that of the caller.
  *

- * @param sock socket
+ * @param connection connection

  * @param size number of bytes to send
  * @param timeout after how long should we give up (and call
  *        notify with buf NULL and size 0)?
  * @param size number of bytes to send
  * @param timeout after how long should we give up (and call
  *        notify with buf NULL and size 0)?


@@ -333,35 +322,26 @@ struct GNUNET_CONNECTION_TransmitHandle;
  * @return non-NULL if the notify callback was queued,
  *         NULL if we are already going to notify someone else (busy)
  */
  * @return non-NULL if the notify callback was queued,
  *         NULL if we are already going to notify someone else (busy)
  */

-struct GNUNET_CONNECTION_TransmitHandle
-    *GNUNET_CONNECTION_notify_transmit_ready (struct GNUNET_CONNECTION_Handle
-                                              *sock, size_t size,
-                                              struct GNUNET_TIME_Relative
-                                              timeout,
-                                              GNUNET_CONNECTION_TransmitReadyNotify
-                                              notify, void *notify_cls);
+struct GNUNET_CONNECTION_TransmitHandle *
+GNUNET_CONNECTION_notify_transmit_ready (struct GNUNET_CONNECTION_Handle *connection,
+                                         size_t size,
+                                         struct GNUNET_TIME_Relative timeout,
+                                         GNUNET_CONNECTION_TransmitReadyNotify
+                                         notify, void *notify_cls);

 
 
 /**
  * Cancel the specified transmission-ready
  * notification.
  *
 
 
 /**
  * Cancel the specified transmission-ready
  * notification.
  *

- * @param h handle for notification to cancel
+ * @param th handle for notification to cancel

  */
  */

-void GNUNET_CONNECTION_notify_transmit_ready_cancel (struct
-                                                     GNUNET_CONNECTION_TransmitHandle
-                                                     *h);
+void
+GNUNET_CONNECTION_notify_transmit_ready_cancel (struct
+                                                GNUNET_CONNECTION_TransmitHandle
+                                                *th);

 
 
 
 

-/**
- * Configure this connection to ignore shutdown signals.
- *
- * @param sock socket handle
- * @param do_ignore GNUNET_YES to ignore, GNUNET_NO to restore default
- */
-void GNUNET_CONNECTION_ignore_shutdown (struct GNUNET_CONNECTION_Handle *sock,
-                                        int do_ignore);
-

 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {