1. Moved several macros from the header to the implementation file. They aren't...
[OpenSRF.git] / include / opensrf / socket_bundle.h
index b8eb3ce..e64a013 100644 (file)
@@ -1,6 +1,23 @@
 #ifndef SOCKET_BUNDLE_H
 #define SOCKET_BUNDLE_H
 
+/**
+       @file socket_bundle.h
+       @brief Header for socket routines.
+
+       These routines cover most of the low-level tedium involved in the use of sockets.
+
+       They support UDP, TCP, and UNIX domain sockets, for both clients and servers.  That's six
+       different combinations.  They also support the spawning of sockets from a listener
+       by calls to accept(),
+
+       Support for UPD is nominal at best.  UDP sockets normally involve the use of calls to
+       recvfrom() or sendto(), but neither of those functions appears here.  In practice the
+       functions for opening UDP sockets are completely unused at this writing.
+
+       All socket traffic is expected to consist of text; i.e. binary data is not supported.
+*/
+
 #include <opensrf/utils.h>
 #include <opensrf/log.h>
 
 extern "C" {
 #endif
 
-#define SERVER_SOCKET                  1
-#define CLIENT_SOCKET                  2
-
-#define INET 10 
-#define UNIX 11 
-
-
 /* models a single socket connection */
 struct socket_node;
 typedef struct socket_node_struct socket_node;
 
 
 /* Maintains the socket set */
+/**
+       @brief Manages a collection of sockets.
+*/
 struct socket_manager_struct {
-       /* callback for passing up any received data.  sock_fd is the socket
-               that read the data.  parent_id (if > 0) is the socket id of the 
-               server that this socket spawned from (i.e. it's a new client connection) */
-       void (*data_received) 
-               (void* blob, struct socket_manager_struct*, 
-                int sock_fd, char* data, int parent_id);
-
-       void (*on_socket_closed) (void* blob, int sock_fd);
-
-       socket_node* socket;
-       void* blob;
+       /** @brief Callback for passing any received data up to the calling code.
+       Parameters:
+       - @em blob  Opaque pointer from the calling code.
+       - @em mgr Pointer to the socket_manager that manages the socket.
+       - @em sock_fd File descriptor of the socket that read the data.
+       - @em data Pointer to the data received.
+       - @em parent_id (if > 0) listener socket from which the data socket was spawned.
+       */
+       void (*data_received) (
+               void* blob,
+               struct socket_manager_struct* mgr,
+               int sock_fd,
+               char* data,
+               int parent_id
+       );
+
+       /** @brief Callback for closing the socket.
+       Parameters:
+       - @em blob Opaque pointer from the calling code.
+       - @em sock_fd File descriptor of the socket that was closed.
+       */
+       void (*on_socket_closed) (  
+               void* blob,
+               int sock_fd
+       );
+
+       socket_node* socket;       /**< Linked list of managed sockets. */
+       void* blob;                /**< Opaque pointer from the calling code .*/
 };
 typedef struct socket_manager_struct socket_manager;
 
 void socket_manager_free(socket_manager* mgr);
 
-/* creates a new server socket node and adds it to the socket set.
-       returns socket id on success.  -1 on failure.
-       socket_type is one of INET or UNIX  */
 int socket_open_tcp_server(socket_manager*, int port, const char* listen_ip );
 
 int socket_open_unix_server(socket_manager* mgr, const char* path);
 
 int socket_open_udp_server( socket_manager* mgr, int port, const char* listen_ip );
 
-/* creates a client TCP socket and adds it to the socket set.
-       returns 0 on success.  -1 on failure.  */
 int socket_open_tcp_client(socket_manager*, int port, const char* dest_addr);
 
-/* creates a client UNIX socket and adds it to the socket set.
-       returns 0 on success.  -1 on failure.  */
 int socket_open_unix_client(socket_manager*, const char* sock_path);
 
 int socket_open_udp_client( socket_manager* mgr );
 
-/* sends the given data to the given socket. returns 0 on success, -1 otherwise */
 int socket_send(int sock_fd, const char* data);
 
-/* waits at most usecs microseconds for the socket buffer to
- * be available */
 int socket_send_timeout( int sock_fd, const char* data, int usecs );
 
-/* disconnects the node with the given sock_fd and removes
-       it from the socket set */
 void socket_disconnect(socket_manager*, int sock_fd);
 
-/* XXX This only works if 'sock_fd' is a client socket... */
 int socket_wait(socket_manager* mgr, int timeout, int sock_fd);
 
-/* waits on all sockets for incoming data.  
-       timeout == -1   | block indefinitely
-       timeout == 0    | don't block, just read any available data off all sockets
-       timeout == x    | block for at most x seconds */
 int socket_wait_all(socket_manager* mgr, int timeout);
 
-/* utility function for displaying the currently attached sockets */
 void _socket_print_list(socket_manager* mgr);
 
 int socket_connected(int sock_fd);