SYNOPSIS
#include <bobcat/localserversocket>Linking option: -lbobcat
DESCRIPTION
An FBB::LocalServerSocket defines a Unix Domain server socket, listening for connection requests from the local host using a Unix Domain socket. Connection requests may be accepted in either blocking or non-blocking modes. When a connection is accepted a socket is returned which may be used to read information from or write information to the client requesting the connection. The socket that is made available is a file descriptor which may be used to initialize a std::istream and/or std::ostream. The std::istream is used to read information from the client process; the std::ostream is used to send information to the client process. Since a socket may be considered a file descriptor the available FBB::IFdStream, FBB::IFdStreamBuf, FBB::OFdStream, and 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.
NAMESPACE
FBBAll constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.
INHERITS FROM
FBB::LocalSocketBase
ENUMERATION
The following enumeration is defined in th class FBB::LocalServerSocket:
enum Socket
This enumeration holds two values:
-
KEEP:
When this value is specified at construction time, the file representing the Unix Domain Socket is not removed when the LocalServerSocket is destroyed. -
UNLINK:
When this value is specified at construction time, the file representing the Unix Domain Socket is removed when the LocalServerSocket is destroyed. As a socket cannot be reused, this is the default value used with the LocalServerSocket constructor.
CONSTRUCTOR
-
LocalServerSocket():
This constructor creates an empty (non-functioning) FBB::LocalServerSocket object. Before it can be used, the open() member must be called (see below). -
LocalServerSocket(string const &name, Socket action = UNLINK)
throw (Exception):
This constructor initializes an FBB::LocalServerSocket object, which will listen for connection requests using the named Unix Domain socket. An FBB::Exception is thrown if the socket could not be constructed. If the constructor is given a second argument FBB::LocalServerSocket::KEEP, the constructed socket is not unlinked when the FBB::LocalServerSocket object is destroyed. The construction of the socket does not mean that the FBB::LocalServerSocket object is actually listening for connections. To start listening, the member listen() should be called. The copy constructor is not available.
MEMBER FUNCTIONS
-
size_t accept():
The accept() member returns an size_t which is a file descriptor (socket) that may be used to communicate with the client requesting the connection. In more complex programs the returned file descriptor (socket) could be passed to a class derived from FBB::Fork, handling the communication with the child as a separate (child) process. -
void listen(size_t backlog = 5, bool blocking = true):
The listen() member defines the way the FBB::LocalServerSocket will listen for clients requesting a connection. It can be used only once with a FBB::LocalServerSocket. An FBB::Exception object is thrown if listening fails. - The listen() member's backlog parameter defines the size of the FBB::LocalServerSocket's internal queue in which connection requests may be stored waiting for their turn to be serviced. When backlog requests are waiting and another request arrives, then that request is lost.
- The member's second parameter, blocking, is used to control the blocking mode. By default, blocking is used, and listen() will wait until a connection is established. This is ok in situations where clients connect infrquently and for relatively short time intervals. Otherwise, in more complex programs, an FBB::Selector object can be used to sense input on the server socket and/or on various client sockets.
-
void open(string const &name, Socket action = UNLINK):
This member prepares a FBB::LocalServerSocket object for use. It should only be used in combination with the default constructor. Following open() the FBB:::LocalServerSocket object will be able to listen for connection requests using the named Unix Domain socket. An FBB::Exception is thrown if the socket could not be constructed. If the a second argument FBB::LocalServerSocket::KEEP, is provided the constructed socket is not unlinked when the FBB::LocalServerSocket object is destroyed. The construction of the socket does not mean that the FBB::LocalServerSocket object is actually listening for connections. To start listening, the member listen() should be called next.
EXAMPLE
See also the localclientsocket(3bobcat) example.#include <iostream> #include <bobcat/localserversocket> #include <bobcat/ifdstream> #include <bobcat/ofdstream> using namespace std; using namespace FBB; int main(int argc, char **argv) try { if (argc == 1) { cerr << "Provide local filename, e.g., /tmp/uds\n"; return 1; } LocalServerSocket server(argv[1]); cerr << "server using `" << argv[1] << "'" << endl; cout << "The server terminates when it receives a single `q' on a line\n" "A connection is terminated when no input is received anymore.\n" "Then another connection is possible" << endl; server.listen(); // listen in blocking mode while (true) { int fd = server.accept(); cerr << "Client FD = " << fd << ", " << endl; IFdStream in(fd); // stream to read from client OFdStream out(fd); // stream to write to client string cmd; while (getline(in, cmd)) { cout << "Got: " << cmd << endl; out << "Got: " << cmd << "\r" << endl; if (cmd[0] == 'q') return 0; } cout << "Ready for another connection\n"; } } catch (Exception const &err) { cerr << err.what() << endl << "Server socket on port " << argv[1] << " can't be opened" << endl; return -1; }
FILES
bobcat/serversocket - defines the class interface
BUGS
None Reported.
DISTRIBUTION FILES
- bobcat_4.02.00-x.dsc: detached signature;
- bobcat_4.02.00-x.tar.gz: source archive;
- bobcat_4.02.00-x_i386.changes: change log;
- libbobcat1_4.02.00-x_*.deb: debian package holding the libraries;
- libbobcat1-dev_4.02.00-x_*.deb: debian package holding the libraries, headers and manual pages;
-
http://sourceforge.net/projects/bobcat: public archive location;
BOBCAT
Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License (GPL).