// Copyright (c) 1999-2000 David Muse
// See the COPYING file for more information.

#ifndef SERVERSOCKET_H
#define SERVERSOCKET_H

#include <rudiments/genericsocket.h>

// The serversocket class allows you to write programs that can talk to other
// programs over TCP connections.
//
// The class supports TCP connections over Inet and Unix domain sockets.
// Inet sockets allow clients and servers on different machines to talk over a
// network.  Unix sockets allow clients and servers on the same machine to 
// talk.  Inet sockets can be used by clients and servers on the same machine
// but Unix sockets generally perform better.
//
// The serversocket class provides methods for setting up sockets and accepting
// client connections.  Its parent class: genericsocket, provides methods for 
// reading and writing data and error management.
//
// If you need to listen on more than 1 socket at a time, you should use the 
// serversocketpool class.

class serversocket : public genericsocket {
        public:
                        serversocket();

                // Simple Socket Initialization Interface:
                //
                // The following 3 methods provide a simplified interface to
                // socket initialization.
                //
                // If you need to set socket options or do anything special
                // between the discrete steps of socket initialization, you
                // should use a combination of the methods following these 2.
                int     listenOnInetPort(unsigned short int port, int backlog);
                                // Listen on inet port: "port" and allow 
                                // "backlog" connections to pile up before 
                                // refusing them.
                                // Entering a value of 0 for the "port" causes
                                // the server to listen on an arbitrary port.
                                // The getPort() method can be used later to 
                                // discover this port.
                                //
                                // Returns 1 on success and 0 on failure.
                int     listenOnUnixPort(char *port, mode_t mode, int backlog);
                                // Listen on unix port: "port" and allow 
                                // "backlog" connections to pile up before 
                                // refusing them.  Set the permissions on
                                // "port" to "permissions".
                                //
                                // Returns 1 on success and 0 on failure.


                // Complex Socket Initialization Interface:
                //
                // The following 7 methods provide discrete control over socket
                // initialization.
                //
                // If you need to set socket options or do anything special
                // between the discrete steps of socket initialization, you
                // should use a combination of these methods.
                int     initInetPort(unsigned short int port);
                        // Associates the socket with inet port "port".
                        //
                        // Returns 1 on success and 0 on failure.
                int     initUnixPort(char *port, mode_t mode);
                        // Associates the socket with unix port "port".
                        //
                        // Returns 1 on success and 0 on failure.

                int     lingerOnClose(int timeout);
                        // Instructs the connection to the client to stay open
                        // for "timeout" seconds even after closeSocket()
                        // is called if the client hasn't received all of the
                        // data yet.
                        //
                        // Returns 1 on success and 0 on failure.
                int     reuseAddresses();
                        // Allows sockets in the TIME_WAIT state to be reused
                        //
                        // Returns 1 on success and 0 on failure.

                int             bindSocket();
                                // Associates the socket with an address.
                                //
                                // Returns 1 on success and 0 on failure.
                int             listenForClientConnection(int backlog);
                                // Waits until a client connects then places
                                // that connection in queue.  Up to "backlog"
                                // connections may be queued before future
                                // conenctions are refused.
                                //
                                // Returns 1 on success and 0 on failure.
                genericsocket   *acceptClientConnection();
                                // Removes the client connection from the queue
                                // and associates a new socket with that
                                // connection.  Communication with the client
                                // may be done over this new socket.  
                                //
                                // Returns a genericsocket on success and NULL
                                // on failure.

                int             stopListening();
                                // Disconnects the server process from the 
                                // port it's listening on.

                unsigned short int      getPort();
                                        // Returns the inet port number that
                                        // the socket is listening on.  If the
                                        // port has not been set or if the
                                        // socket is a unix socket, 0 is 
                                        // returned instead.

                static int      getClientAddress(genericsocket *sock, 
                                                        char *buffer);
                                // Writes the address of the client at
                                // the other end of "sock" to "buffer".

        protected:
                #include <rudiments/private/serversocket.h>

};

#endif