doxygen.hpp

Go to the documentation of this file.

/*
 * Copyright (C) 2013 Evidence Srl - www.evidence.eu.com
 *
 * Boost Software License - Version 1.0 - August 17th, 2003
 *
 * Permission is hereby granted, free of charge, to any person or organization
 * obtaining a copy of the software and accompanying documentation covered by
 * this license (the "Software") to use, reproduce, display, distribute,
 * execute, and transmit the Software, and to prepare derivative works of the
 * Software, and to permit third-parties to whom the Software is furnished to
 * do so, all subject to the following:
 * 
 * The copyright notices in the Software and this entire statement, including
 * the above license grant, this restriction and the following disclaimer,
 * must be included in all copies of the Software, in whole or in part, and
 * all derivative works of the Software, unless such copies or derivative
 * works are solely in the form of machine-executable object code generated by
 * a source language processor.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
 * SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
 * FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */

/** 
 *
 * \htmlonly
 * <br>
 * <center>
 * <img src="netcpp.png" width="300"></img><br>
 * A tiny C++ network library
 * </center>
 * <br>
 * \endhtmlonly
 *
 * @mainpage NetCpp
 * 
 * @author Evidence Srl - <a href="http://www.evidence.eu.com" target="_blank">www.evidence.eu.com</a>
 *
 *
 *
 * <br>
 * <br>
 * <h1>Table of contents</h1>
 * <ol>
 * <li><a href="#rationale">Rationale</a>
 * <li><a href="#requirements">Requirements</a>
 * <li><a href="#build">How to build the library</a>
 * <li><a href="#usage">Usage</a>
 * <li><a href="#platforms">Supported platforms</a>
 * <li><a href="#protocols">Adding further network protocols</a>
 * <li><a href="#license">License</a>
 * <li><a href="#support">Support</a>
 * <li><a href="#todo">To do</a>
 * </ol>
 *
 * <br>
 * <br>
 * <a name="rationale"><h2>Rationale</h2></a>
 *
 * The C++ standard library is known to be less comprehensive than the libraries
 * traditionally available for other programming languages (e.g., Java, Python,
 * etc.). The C++11 standard began to fill this gap by adding several features
 * like support for multithreading, smart pointers, etc. Incredibly, however, a
 * basic support for networking is still missing.
 *
 * During the last years, a number of C++ libraries have been proposed to have
 * portable networking in C++, the most important being
 * <a href="http://www.boost.org/libs/asio/" target="_blank">Boost::asio</a>
 * and <a href="http://cpp-netlib.org" target="_blank">cpp-netlib</a>.
 * However, we believe that the syntax of both these libraries is still more
 * complicated than necessary.
 * In particular, we believe that an ideal C++ networking library should be:
 * <ul>
 * <li> easy to use
 * <li> easy to extend (either in terms of protocols and of supported architectures)
 * </ul>
 *
 * NetCpp is a proof of concept to show that such a networking library can be
 * made easily designed in C++. This tiny library has been built after the
 * experience with the <a href="http://onposix.sourceforge.net" target="_blank">OnPosix library</a>.
 * The syntax of the library is straightforward. The modular design given by the
 * adoption of design patterns (i.e., <i>Abstract Factory</i> and <i>Bridge</i>) allows to easily
 * add new protocols and supported platforms.
 *
 *
 * <br>
 * <br>
 * <a name="requirements"><h2>Requirements</h2></a> 
 *
 * To build NetCpp you need both:
 * <ul>
 * <li> <a href="http://www.cmake.org" target="_blank">cmake</a>
 * <li> a C++11 compiler (e.g., gcc 4.7+ or LLVM 3.3+)
 * </ul>
 * 
 * Currently, only Posix systems (e.g., Linux). However, porting the library to
 * different platforms is very easy thanks to its modular design.
 *
 *
 * <br>
 * <br>
 * <a name="build"><h2>How to build the library</h2></a>
 *
 * Compile through the following commands:
 *
 * \code
 * git clone https://github.com/claudioscordino/netcpp.git
 * cd netcpp/build
 * cmake ..
 * make
 * make install
 * \endcode
 *
 * The library is put in the <i>netcpp/bin/</i> directory.
 * The include files are available in the <i>netcpp/include/</i> directory.
 *
 * Documentation is generated through
 * <a href="htttp://www.doxygen.org" target="_blank">Doxygen</a>.
 * To generate the documentation, type:
 *
 * \code
 * git clone https://github.com/claudioscordino/netcpp.git
 * cd netcpp/build
 * cmake ..
 * make doc
 * \endcode
 *
 * Start reading documentation by opening <i>doc/html/index.html</i>.
 *  
 *
 *
 * <br>
 * <br>
 * <a name="usage"> <h2>Usage</h2></a>
 *
 * Usage of the library is straightforward:
 *
 * <h3>TCP client/server</h3>
 * 
 * Example of TCP server:
 * \code
 * net::ip4::tcp::address addr (std::string("127.0.0.1"), 1234);
 * net::ip4::tcp::server main_srv;
 * net::ip4::tcp::server srv(&main_srv); // accept()
 * srv.open(&addr);
 * std::array<char, 5> buf;
 * srv.receive(net::buffer(buf), 5);
 * \endcode
 *
 * Example of TCP client:
 * \code
 * net::ip4::tcp::address addr (std::string("127.0.0.1"), 1234);
 * net::ip4::tcp::client clt;
 * clt.open(&addr);
 * std::array<char, 5> b {'h', 'e', 'l', 'l', 'o'};
 * clt.send(net::buffer(b), 3);
 * \endcode
 *
 *
 * <h3>UDP client/server</h3>
 * 
 * Example of UDP server:
 * \code
 * net::ip4::udp::address addr (std::string("127.0.0.1"), 1234);
 * net::ip4::udp::server srv;
 * srv.open(&addr);
 * std::array<char, 5> buf;
 * srv.receive(net::buffer(buf), 5);
 * \endcode
 *
 * Example of UDP client:
 * \code
 * net::ip4::udp::address addr (std::string("127.0.0.1"), 1234);
 * net::ip4::udp::client clt;
 * clt.open(&addr);
 * std::array<char, 5> b {'h', 'e', 'l', 'l', 'o'};
 * clt.send(net::buffer(b), 3);
 * \endcode
 *
 * <br>
 * <br>
 * <a name="platforms"><h2>Supported platforms</h2></a>
 *
 * The library has a modular internal design which, thanks to the design patterns 
 * used, allows to decouple specific platform-dependent code (which is on the
 * net::AbstractSystemSocket hierarchy) from any protocol design (which is on the
 * net::AbstractSocket hierarchy). Modularity is especially given by the <i>Bridge</i>
 * pattern, which allows two class hierarchies to vary independently.
 *
 * Thus, to add a new supported platform, you only need to:
 * <ol>
 * <li> inherit your platform-specific class from class net::AbstractSystemSocket.
 * <li> change the concrete class allocated by net::createSocket().
 * </ol>
 * The build system, based on cmake, can be easily ported among all supported
 * platforms.
 *
 * See the following picture to understand the collaboration between classes:
 *
 * <center>
 * <img src="netcpp-architecture.png" width="800"></img>
 * </center>
 *
 * <br>
 * <br>
 * <a name="protocols"><h2>Adding further network protocols</h2></a>
 *
 * To add a new protocol:
 * <ul>
 * <li> Create a proper namespace (like net::ip4::tcp)
 * <li> Then, inside the new namespace:
 * <ul>
 * <li> Create an address class inheriting from class Address
 * <li> Create server and client classes inheriting from class net::AbstractSocket
 * </ul>
 * </ul>
 *
 * <br>
 * <br>
 * <a name="license"><h2>License</h2></a>
 *
 * The library is under the
 * <a href="http://www.boost.org/users/license.html" target="_blank">Boost license</a>.
 * Read the LICENSE file for more information.
 *
 *
 * <br>
 * <br>
 * <a name="support"><h2>Support</h2></a>
 *
 * For reporting bugs or proposing new patches, use 
 * <a href="https://github.com/claudioscordino/netcpp/issues" target="_blank">
 * the issues link of GitHub</a>.
 *
 *
 * <br>
 * <br>
 * <a name="todo"><h2>Todo</h2></a>
 * <ul>
 * <li> Add recvfrom and sendto for dgram connections
 * <li> Add asynchronous operations
 * </ul>
 */