includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::ClientSocket)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
                    (Client Socket)

manpagename(FBB::ClientSocket)
            (Client Socket connecting to a Server in the Internet)

manpagesynopsis()
    bf(#include <bobcat/clientsocket>)nl()
    Linking option: tt(-lbobcat) 

manpagedescription()
    An bf(FBB::ClientSocket) may be constructed to connect to some server
process in the internet. The socket made available by the bf(FBB:ClientSocket)
may be used to initialize a bf(std::istream) and/or bf(std::ostream). The
bf(std::istream) is used to read information from the server process to which
the bf(FBB::ClientSocket) connects, The bf(std::ostream) is used to send
information to the server process to which the bf(FBB::ClientSocket) connects.
Since a socket may be considered a em(file descriptor) the available
bf(FBB::IFdStream), bf(FBB::IFdStreamBuf), bf(FBB::OFdStream), and
bf(FBB::OFdStreamBuf) classes may be used profitably here. Note that having
available a socket does not mean that this defines the communication
protocol. It is (still) the responsibility of the programmer to comply with an
existing protocol or to implement a tailor-made protocol. The latter situation
implies that the sequence of input- and output operations is defined by the
programmer. 

    A Unix Domain client socket can be defined using
tt(FBB::LocalClientSocket).

includefile(include/namespace)

manpagesection(INHERITS FROM)
    bf(FBB::SocketBase)

manpagesection(CONSTRUCTOR)
    itemization(
    itb(ClientSocket(std::string const &host, uint16_t port))
        This constructor initializes an bf(FBB::ClientSocket) object,
preparing it for a connection to the specified port at the given host.  An
bf(FBB::Exception) is thrown if the socket could not be constructed. The
construction of the socket does not mean that a connection has actually been
established. In order to connect to the server, the member bf(connect()) (see
below) should be used.
    )

    Copy and move constructors (and assignment operators) are not available.

manpagesection(MEMBER FUNCTIONS)
     All members of bf(FBB::SocketBase) (and thus of bf(FBB::InetAddress)) are
available, as bf(FBB::ClientSocket) inherits from these classes.
    itemization(
    itb(int connect())
        This member returns a socket that can be used to communicate with the
server process. An bf(FBB::Exception) exception is thrown if the connection
could not be established or if the bf(SocketBase) base class could not
properly be constructed.
    )

manpagesection(EXAMPLE)
    See also the bf(serversocket)(3bobcat) example.
        verb(
    #include <iostream>
    #include <string>
    #include <bobcat/clientsocket>
    #include <bobcat/ifdstream>
    #include <bobcat/ofdstream>
    
    using namespace std;
    using namespace FBB;
    
    int main(int argc, char **argv)
    try
    {
        if (argc == 1)
        {
            cerr << "Provide servername and port number\n";
            return 1;
        }
    
        size_t     port = stoul(argv[2]);
        ClientSocket client(argv[1], port);
        int fd = client.connect();
        string line;
    
        cout << "Connecting to socket " << fd << endl <<
                "address = " << client.dottedDecimalAddress() << ", " << 
                                                                 endl <<
                "communication through port " << client.port() << endl;
    
        IFdStream in(fd);                 // stream to read from        
        OFdStream out(fd);                // stream to write to
    
        while (true)
        {
                                    // Ask for a textline, stop if 
            cout << "? ";           // empty / none
            if (!getline(cin, line) || line.length() == 0)
                return 0;
            cout << "Line read: " << line << endl;

                                    // Return the line to the server
            out << line.c_str() << endl;    
            cout << "wrote line\n";
    
            getline(in, line);      // Wait for a reply from the server
            cout << "Answer: " << line << endl;
        }
    }
    catch (Exception const &err)
    {
        cerr << err.what() << "\n" <<
                "Can't connect to " << argv[1] << ", port " << 
                argv[2] << endl;
        return 1;
    }
        )

manpagefiles()
    em(bobcat/clientsocket) - defines the class interface

manpageseealso()
    bf(bobcat)(7), bf(ifdstream)(3bobcat), bf(ifdbuf)(3bobcat),
bf(inetaddress)(3bobcat), bf(localclientsocket)(3bobcat),
bf(ofdstream)(3bobcat), bf(ofdstream)(3bobcat), bf(serversocket)(3bobcat),
bf(socketbase)(3bobcat)

manpagebugs()
    None Reported.

includefile(include/trailer)
