cnsuhao / asio-extensions

Additional functionality built on top of (Boost.)Asio

Asio Extensions (AsioExt)

AsioExt is a collection of various components and functionality that builds on (Boost.)Asio. It is compatible with standalone Asio, as well as the Boost version.

Feature overview

Filesystem:

• File handle types with support for:
  • Asio's *Stream concepts (SyncReadStream, SyncRandomAccessReadDevice, ...)
  • Querying/altering file metadata (size, permissions, attributes, file times)
• Asynchronous file I/O with different implementations.
• Utility functions for writing/reading files.

Networking:

• SOCKS 5 client library
• Utility functions that simplify common operations (e.g. resolve and connect)

This is a very coarse overview of the project's features. The documentation has all the details.

Simple example

#include <asioext/unique_file_handle.hpp>
#include <asioext/read_file.hpp>
#include <asioext/write_file.hpp>
#include <asioext/open.hpp>

#include <asio/read.hpp>

#include <iostream>
#include <cassert>

int main(int argc, const char* argv[])
{
  const std::string test_content("Hello world");

  try {
    // Utility functions write/read containers and buffer sequences to/from files.
    const std::array<asio::const_buffer, 2> buffers_to_write = {
      asio::buffer(test_content),
      asio::buffer(test_content),
    };
    asioext::write_file("myfile.txt", buffers_to_write);

    std::string read_content;
    asioext::read_file("myfile.txt", read_content);

    assert(read_content == test_content + test_content);

    // (unique_)file_handle simply wraps a native file handle.
    // (There's also basic_file, which needs an asio::io_service and provides
    // asynchronous I/O.)
    asioext::unique_file_handle file =
        asioext::open("myfile.txt", asioext::open_flags::access_read |
                                    asioext::open_flags::open_existing);

    assert(file.size() == test_content.size() * 2);

    std::string read_content2(test_content.size(), '\0');
    asio::read(file, asio::buffer(&read_content2[0], read_content2.size()));

    assert(read_content2 == test_content);
    return 0;
  } catch (std::exception& e) {
    // Exceptions are used for error reporting here.
    // All functions also offer a non-throwing overload,
    // which takes an asio::error_code& instead.
    std::cerr << "error: " << e.what() << std::endl;
    return 1;
  }
}

Take a look at the examples directory for more!

Documentation

The documentation can be found at http://timniederhausen.github.io/asio-extensions, or inside the gh-pages branch.

Additionally, the documentation can be generated by building the special asioext.doc target. Note that this target is only available if you have Doxygen installed.

License

Please see LICENSE_1_0.txt.