- 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 33afb0386c08d38a83b97b03d4355dfe96b9f351..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


@@ -52,18 +52,39 @@ extern "C"
 struct GNUNET_CONNECTION_Handle;
 
 
 struct GNUNET_CONNECTION_Handle;
 
 

+/**
+ * Credentials for UNIX domain sockets.
+ */
+struct GNUNET_CONNECTION_Credentials
+{
+  /**
+   * UID of the other end of the connection.
+   */
+  uid_t uid;
+
+  /**
+   * GID of the other end of the connection.
+   */
+  gid_t gid;
+};
+
+

 /**
  * Function to call for access control checks.
  *
  * @param cls closure
 /**
  * Function to call for access control checks.
  *
  * @param cls closure

+ * @param ucred credentials, if available, otherwise NULL

  * @param addr address
  * @param addrlen length of address
  * @return GNUNET_YES to allow, GNUNET_NO to deny, GNUNET_SYSERR
  *   for unknown address family (will be denied).
  */
 typedef int (*GNUNET_CONNECTION_AccessCheck) (void *cls,
  * @param addr address
  * @param addrlen length of address
  * @return GNUNET_YES to allow, GNUNET_NO to deny, GNUNET_SYSERR
  *   for unknown address family (will be denied).
  */
 typedef int (*GNUNET_CONNECTION_AccessCheck) (void *cls,

-                                           const struct sockaddr * addr,
-                                           socklen_t addrlen);
+                                              const struct
+                                              GNUNET_CONNECTION_Credentials *
+                                              ucred,
+                                              const struct sockaddr * addr,
+                                              socklen_t addrlen);

 
 
 /**
 
 
 /**


@@ -78,184 +99,183 @@ typedef int (*GNUNET_CONNECTION_AccessCheck) (void *cls,
  * @param addrlen size of addr
  * @param errCode value of errno (on errors receiving)
  */
  * @param addrlen size of addr
  * @param errCode value of errno (on errors receiving)
  */

-typedef void (*GNUNET_CONNECTION_Receiver) (void *cls,
-                                         const void *buf,
-                                         size_t available,
-                                         const struct sockaddr * addr,
-                                         socklen_t addrlen, int errCode);
+typedef void (*GNUNET_CONNECTION_Receiver) (void *cls, const void *buf,
+                                            size_t available,
+                                            const struct sockaddr * addr,
+                                            socklen_t addrlen, int errCode);

 
 /**
  * Set the persist option on this connection handle.  Indicates
  * that the underlying socket or fd should never really be closed.
  * Used for indicating process death.
  *
 
 /**
  * Set the persist option on this connection handle.  Indicates
  * 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
  */
 void

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

 
 /**
 
 /**

- * Create a socket handle by boxing an existing OS socket.  The OS
+ * Disable the "CORK" feature for communication with the given socket,
+ * forcing the OS to immediately flush the buffer on transmission
+ * instead of potentially buffering multiple messages.  Essentially
+ * reduces the OS send buffers to zero.
+ * Used to make sure that the last messages sent through the connection
+ * reach the other side before the process is terminated.
+ *
+ * @param connection the connection to make flushing and blocking
+ * @return GNUNET_OK on success
+ */
+int
+GNUNET_CONNECTION_disable_corking (struct GNUNET_CONNECTION_Handle *connection);
+
+
+/**
+ * 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
  */
 struct GNUNET_CONNECTION_Handle *
 GNUNET_CONNECTION_create_from_connect_to_unixpath (const struct

-                                                  GNUNET_CONFIGURATION_Handle *cfg,
-                                                  const char *unixpath);
+                                                   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
  */
 void

-GNUNET_CONNECTION_destroy (struct GNUNET_CONNECTION_Handle *sock,
-                          int finish_pending_write);
+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
  */
 void
  * @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);
+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


@@ -263,8 +283,8 @@ void *GNUNET_CONNECTION_receive_cancel (struct
  * @param buf where the callee should write the message
  * @return number of bytes written to buf
  */
  * @param buf where the callee should write the message
  * @return number of bytes written to buf
  */

-typedef size_t (*GNUNET_CONNECTION_TransmitReadyNotify) (void *cls,
-                                                        size_t size, void *buf);
+typedef size_t (*GNUNET_CONNECTION_TransmitReadyNotify) (void *cls, size_t size,
+                                                         void *buf);

 
 
 /**
 
 
 /**


@@ -274,17 +294,17 @@ typedef size_t (*GNUNET_CONNECTION_TransmitReadyNotify) (void *cls,
 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.


@@ -293,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)?


@@ -302,39 +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
  */
 void
 GNUNET_CONNECTION_notify_transmit_ready_cancel (struct

-                                                        GNUNET_CONNECTION_TransmitHandle
-                                                        *h);
+                                                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 */
 {