-/*\r
- This file is part of GNUnet.\r
- (C) 2009 Christian Grothoff (and other contributing authors)\r
-\r
- GNUnet is free software; you can redistribute it and/or modify\r
- it under the terms of the GNU General Public License as published\r
- by the Free Software Foundation; either version 2, or (at your\r
- option) any later version.\r
-\r
- GNUnet is distributed in the hope that it will be useful, but\r
- WITHOUT ANY WARRANTY; without even the implied warranty of\r
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU\r
- General Public License for more details.\r
-\r
- You should have received a copy of the GNU General Public License\r
- along with GNUnet; see the file COPYING. If not, write to the\r
- Free Software Foundation, Inc., 59 Temple Place - Suite 330,\r
- Boston, MA 02111-1307, USA.\r
-*/\r
-\r
-/**\r
- * @file include/gnunet_connection_lib.h\r
- * @brief basic, low-level TCP networking interface\r
- * @author Christian Grothoff\r
- */\r
-#ifndef GNUNET_CONNECTION_LIB_H\r
-#define GNUNET_CONNECTION_LIB_H\r
-\r
-#ifdef __cplusplus\r
-extern "C"\r
-{\r
-#if 0 /* keep Emacsens' auto-indent happy */\r
-}\r
-#endif\r
-#endif\r
-\r
-#include "gnunet_network_lib.h"\r
-#include "gnunet_scheduler_lib.h"\r
-#include "gnunet_time_lib.h"\r
-\r
-/**\r
- * Timeout we use on TCP connect before trying another\r
- * result from the DNS resolver. 5s.\r
- */\r
-#define GNUNET_CONNECTION_CONNECT_RETRY_TIMEOUT GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_SECONDS, 5)\r
-\r
-/**\r
- * @brief handle for a network connection\r
- */\r
-struct GNUNET_CONNECTION_Handle;\r
-\r
-\r
-/**\r
- * Function to call for access control checks.\r
- *\r
- * @param cls closure\r
- * @param addr address\r
- * @param addrlen length of address\r
- * @return GNUNET_YES to allow, GNUNET_NO to deny, GNUNET_SYSERR\r
- * for unknown address family (will be denied).\r
- */\r
-typedef int (*GNUNET_CONNECTION_AccessCheck) (void *cls,\r
- const struct sockaddr * addr,\r
- socklen_t addrlen);\r
-\r
-\r
-/**\r
- * Callback function for data received from the network. Note that\r
- * both "available" and "err" would be 0 if the read simply timed out.\r
- *\r
- * @param cls closure\r
- * @param buf pointer to received data\r
- * @param available number of bytes availabe in "buf",\r
- * possibly 0 (on errors)\r
- * @param addr address of the sender\r
- * @param addrlen size of addr\r
- * @param errCode value of errno (on errors receiving)\r
- */\r
-typedef void (*GNUNET_CONNECTION_Receiver) (void *cls,\r
- const void *buf,\r
- size_t available,\r
- const struct sockaddr * addr,\r
- socklen_t addrlen, int errCode);\r
-\r
-\r
-/**\r
- * Create a socket handle by boxing an existing OS socket. The OS\r
- * socket should henceforth be no longer used directly.\r
- * GNUNET_socket_destroy will close it.\r
- *\r
- * @param sched scheduler to use\r
- * @param osSocket existing socket to box\r
- * @param maxbuf maximum write buffer size for the socket (use\r
- * 0 for sockets that need no write buffers, such as listen sockets)\r
- * @return the boxed socket handle\r
- */\r
-struct GNUNET_CONNECTION_Handle\r
- *GNUNET_CONNECTION_create_from_existing (struct\r
- GNUNET_SCHEDULER_Handle\r
- *sched,\r
- struct\r
- GNUNET_NETWORK_Handle\r
- *osSocket, size_t maxbuf);\r
-\r
-\r
-/**\r
- * Create a socket handle by accepting on a listen socket. This\r
- * function may block if the listen socket has no connection ready.\r
- *\r
- * @param sched scheduler to use\r
- * @param access function to use to check if access is allowed\r
- * @param access_cls closure for access\r
- * @param lsock listen socket\r
- * @param maxbuf maximum write buffer size for the socket (use\r
- * 0 for sockets that need no write buffers, such as listen sockets)\r
- * @return the socket handle, NULL on error (for example, access refused)\r
- */\r
-struct GNUNET_CONNECTION_Handle\r
- *GNUNET_CONNECTION_create_from_accept (struct\r
- GNUNET_SCHEDULER_Handle\r
- *sched,\r
- GNUNET_CONNECTION_AccessCheck\r
- access, void *access_cls,\r
- struct\r
- GNUNET_NETWORK_Handle\r
- *lsock, size_t maxbuf);\r
-\r
-\r
-/**\r
- * Create a socket handle by (asynchronously) connecting to a host.\r
- * This function returns immediately, even if the connection has not\r
- * yet been established. This function only creates TCP connections.\r
- *\r
- * @param sched scheduler to use\r
- * @param hostname name of the host to connect to\r
- * @param port port to connect to\r
- * @param maxbuf maximum write buffer size for the socket (use\r
- * 0 for sockets that need no write buffers, such as listen sockets)\r
- * @return the socket handle\r
- */\r
-struct GNUNET_CONNECTION_Handle\r
- *GNUNET_CONNECTION_create_from_connect (struct\r
- GNUNET_SCHEDULER_Handle\r
- *sched,\r
- const char *hostname,\r
- uint16_t port,\r
- size_t maxbuf);\r
-\r
-\r
-\r
-/**\r
- * Create a socket handle by (asynchronously) connecting to a host.\r
- * This function returns immediately, even if the connection has not\r
- * yet been established. This function only creates TCP connections.\r
- *\r
- * @param sched scheduler to use\r
- * @param af_family address family to use\r
- * @param serv_addr server address\r
- * @param addrlen length of server address\r
- * @param maxbuf maximum write buffer size for the socket (use\r
- * 0 for sockets that need no write buffers, such as listen sockets)\r
- * @return the socket handle\r
- */\r
-struct GNUNET_CONNECTION_Handle\r
- *GNUNET_CONNECTION_create_from_sockaddr (struct\r
- GNUNET_SCHEDULER_Handle\r
- *sched, int af_family,\r
- const struct sockaddr\r
- *serv_addr,\r
- socklen_t addrlen,\r
- size_t maxbuf);\r
-\r
-/**\r
- * Check if socket is valid (no fatal errors have happened so far).\r
- * Note that a socket that is still trying to connect is considered\r
- * valid.\r
- *\r
- * @param sock socket to check\r
- * @return GNUNET_YES if valid, GNUNET_NO otherwise\r
- */\r
-int GNUNET_CONNECTION_check (struct GNUNET_CONNECTION_Handle\r
- *sock);\r
-\r
-\r
-/**\r
- * Obtain the network address of the other party.\r
- *\r
- * @param sock the client to get the address for\r
- * @param addr where to store the address\r
- * @param addrlen where to store the length of the address\r
- * @return GNUNET_OK on success\r
- */\r
-int GNUNET_CONNECTION_get_address (struct\r
- GNUNET_CONNECTION_Handle\r
- *sock, void **addr,\r
- size_t * addrlen);\r
-\r
-/**\r
- * Close the socket and free associated resources. Pending\r
- * transmissions are simply dropped. A pending receive call will be\r
- * called with an error code of "EPIPE".\r
- *\r
- * @param sock socket to destroy\r
- */\r
-void GNUNET_CONNECTION_destroy (struct GNUNET_CONNECTION_Handle\r
- *sock);\r
-\r
-\r
-/**\r
- * Receive data from the given socket. Note that this function will\r
- * call "receiver" asynchronously using the scheduler. It will\r
- * "immediately" return. Note that there MUST only be one active\r
- * receive call per socket at any given point in time (so do not\r
- * call receive again until the receiver callback has been invoked).\r
- *\r
- * @param sock socket handle\r
- * @param max maximum number of bytes to read\r
- * @param timeout maximum amount of time to wait\r
- * @param receiver function to call with received data\r
- * @param receiver_cls closure for receiver\r
- * @return scheduler task ID used for receiving, GNUNET_SCHEDULER_NO_TASK on error\r
- */\r
-GNUNET_SCHEDULER_TaskIdentifier\r
-GNUNET_CONNECTION_receive (struct GNUNET_CONNECTION_Handle\r
- *sock, size_t max,\r
- struct GNUNET_TIME_Relative timeout,\r
- GNUNET_CONNECTION_Receiver receiver,\r
- void *receiver_cls);\r
-\r
-\r
-/**\r
- * Cancel receive job on the given socket. Note that the\r
- * receiver callback must not have been called yet in order\r
- * for the cancellation to be valid.\r
- *\r
- * @param sock socket handle\r
- * @param task task identifier returned from the receive call\r
- * @return closure of the original receiver callback\r
- */\r
-void *GNUNET_CONNECTION_receive_cancel (struct\r
- GNUNET_CONNECTION_Handle\r
- *sock,\r
- GNUNET_SCHEDULER_TaskIdentifier\r
- task);\r
-\r
-\r
-/**\r
- * Function called to notify a client about the socket\r
- * begin ready to queue more data. "buf" will be\r
- * NULL and "size" zero if the socket was closed for\r
- * writing in the meantime.\r
- *\r
- * @param cls closure\r
- * @param size number of bytes available in buf\r
- * @param buf where the callee should write the message\r
- * @return number of bytes written to buf\r
- */\r
-typedef size_t (*GNUNET_CONNECTION_TransmitReadyNotify) (void *cls,\r
- size_t size, void *buf);\r
-\r
-\r
-/**\r
- * Opaque handle that can be used to cancel\r
- * a transmit-ready notification.\r
- */\r
-struct GNUNET_CONNECTION_TransmitHandle;\r
-\r
-/**\r
- * Ask the socket to call us once the specified number of bytes\r
- * are free in the transmission buffer. May call the notify\r
- * method immediately if enough space is available. Note that\r
- * this function will abort if "size" is greater than\r
- * "maxbuf" (as specified when the socket handle was created).\r
- *\r
- * Note that "notify" will be called either when enough\r
- * buffer space is available OR when the socket is destroyed.\r
- * The size parameter given to notify is guaranteed to be\r
- * larger or equal to size if the buffer is ready, or zero\r
- * if the socket was destroyed (or at least closed for\r
- * writing). Finally, any time before 'notify' is called, a\r
- * client may call "notify_transmit_ready_cancel" to cancel\r
- * the transmission request.\r
- *\r
- * Only one transmission request can be scheduled at the same\r
- * time. Notify will be run with the same scheduler priority\r
- * as that of the caller.\r
- *\r
- * @param sock socket\r
- * @param size number of bytes to send\r
- * @param timeout after how long should we give up (and call\r
- * notify with buf NULL and size 0)?\r
- * @param notify function to call when buffer space is available\r
- * @param notify_cls closure for notify\r
- * @return non-NULL if the notify callback was queued,\r
- * NULL if we are already going to notify someone else (busy)\r
- */\r
-struct GNUNET_CONNECTION_TransmitHandle\r
- *GNUNET_CONNECTION_notify_transmit_ready (struct\r
- GNUNET_CONNECTION_Handle\r
- *sock, size_t size,\r
- struct\r
- GNUNET_TIME_Relative\r
- timeout,\r
- GNUNET_CONNECTION_TransmitReadyNotify\r
- notify, void *notify_cls);\r
-\r
-\r
-/**\r
- * Cancel the specified transmission-ready\r
- * notification.\r
- *\r
- * @param h handle for notification to cancel\r
- */\r
-void\r
-GNUNET_CONNECTION_notify_transmit_ready_cancel (struct\r
- GNUNET_CONNECTION_TransmitHandle\r
- *h);\r
-\r
-\r
-#if 0 /* keep Emacsens' auto-indent happy */\r
-{\r
-#endif\r
-#ifdef __cplusplus\r
-}\r
-#endif\r
-\r
-\r
-/* ifndef GNUNET_CONNECTION_LIB_H */\r
-#endif\r
-/* end of gnunet_connection_lib.h */\r
+/*
+ This file is part of GNUnet.
+ (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
+ 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_connection_lib.h
+ * @brief basic, low-level TCP networking interface
+ * @author Christian Grothoff
+ */
+#ifndef GNUNET_CONNECTION_LIB_H
+#define GNUNET_CONNECTION_LIB_H
+
+#ifdef __cplusplus
+extern "C"
+{
+#if 0 /* keep Emacsens' auto-indent happy */
+}
+#endif
+#endif
+
+#include "gnunet_network_lib.h"
+#include "gnunet_scheduler_lib.h"
+#include "gnunet_time_lib.h"
+
+/**
+ * Timeout we use on TCP connect before trying another
+ * result from the DNS resolver. Actual value used
+ * is this value divided by the number of address families.
+ * Default is 5s.
+ */
+#define GNUNET_CONNECTION_CONNECT_RETRY_TIMEOUT GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_SECONDS, 5)
+
+/**
+ * @brief handle for a network connection
+ */
+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
+ * @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,
+ const struct
+ GNUNET_CONNECTION_Credentials *
+ ucred,
+ const struct sockaddr * addr,
+ socklen_t addrlen);
+
+
+/**
+ * Callback function for data received from the network. Note that
+ * both "available" and "err" would be 0 if the read simply timed out.
+ *
+ * @param cls closure
+ * @param buf pointer to received data
+ * @param available number of bytes availabe in "buf",
+ * possibly 0 (on errors)
+ * @param addr address of the sender
+ * @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);
+
+/**
+ * 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 connection the connection to set persistent
+ */
+void
+GNUNET_CONNECTION_persist_ (struct GNUNET_CONNECTION_Handle *connection);
+
+/**
+ * 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.
+ * GNUNET_CONNECTION_destroy will close it.
+ *
+ * @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);
+
+
+/**
+ * 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
+ * @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);
+
+
+/**
+ * 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
+ * @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);
+
+
+/**
+ * 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)
+ * @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);
+
+
+
+
+/**
+ * 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
+ * @return the connection handle
+ */
+struct GNUNET_CONNECTION_Handle *
+GNUNET_CONNECTION_create_from_sockaddr (int af_family,
+ const struct sockaddr *serv_addr,
+ socklen_t addrlen);
+
+/**
+ * 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.
+ *
+ * @param connection handle to check
+ * @return GNUNET_YES if valid, GNUNET_NO otherwise
+ */
+int
+GNUNET_CONNECTION_check (struct GNUNET_CONNECTION_Handle *connection);
+
+
+/**
+ * Obtain the network address of the other party.
+ *
+ * @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
+ */
+int
+GNUNET_CONNECTION_get_address (struct GNUNET_CONNECTION_Handle *connection,
+ void **addr, size_t * addrlen);
+
+
+/**
+ * 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 connection connection to destroy
+ */
+void
+GNUNET_CONNECTION_destroy (struct GNUNET_CONNECTION_Handle *connection);
+
+
+/**
+ * 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
+ * receive call per connection at any given point in time (so do not
+ * call receive again until the receiver callback has been invoked).
+ *
+ * @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
+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 connection. Note that the
+ * receiver callback must not have been called yet in order
+ * for the cancellation to be valid.
+ *
+ * @param connection connection handle
+ * @return closure of the original receiver callback closure
+ */
+void *
+GNUNET_CONNECTION_receive_cancel (struct GNUNET_CONNECTION_Handle *connection);
+
+
+/**
+ * Function called to notify a client about the connection
+ * begin ready to queue more data. "buf" will be
+ * NULL and "size" zero if the connection was closed for
+ * writing in the meantime.
+ *
+ * @param cls closure
+ * @param size number of bytes available in 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);
+
+
+/**
+ * Opaque handle that can be used to cancel
+ * a transmit-ready notification.
+ */
+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
+ * 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 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
+ * 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.
+ *
+ * Only one transmission request can be scheduled at the same
+ * time. Notify will be run with the same scheduler priority
+ * as that of the caller.
+ *
+ * @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 notify function to call when buffer space is available
+ * @param notify_cls closure for notify
+ * @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 *connection,
+ size_t size,
+ struct GNUNET_TIME_Relative timeout,
+ GNUNET_CONNECTION_TransmitReadyNotify
+ notify, void *notify_cls);
+
+
+/**
+ * Cancel the specified transmission-ready
+ * notification.
+ *
+ * @param th handle for notification to cancel
+ */
+void
+GNUNET_CONNECTION_notify_transmit_ready_cancel (struct
+ GNUNET_CONNECTION_TransmitHandle
+ *th);
+
+
+
+#if 0 /* keep Emacsens' auto-indent happy */
+{
+#endif
+#ifdef __cplusplus
+}
+#endif
+
+
+/* ifndef GNUNET_CONNECTION_LIB_H */
+#endif
+/* end of gnunet_connection_lib.h */
projects / oweals / gnunet.git / blobdiff