telnetpp::options::mccp Namespace Reference

An implementation of the Mud Client Compression Protocol. More...

Namespaces
	zlib
	Implementation of the compressor/decompressor functionality for use with a telnetpp::options::mccp::codec.

Classes
class	client
	A server option responsible for negotiating the client part of the MCCP protocol. More...
class	codec
	Represents an object that can transform (encode or decode) arbitrary byte sequences. For this option, this implies compression and decompression. More...
class	corrupted_stream_error
	An exception that is thrown in the case that a stream of data cannot be decompressed. More...
class	server
	A server option responsible for negotiating the server part of the MCCP protocol. More...

Detailed Description

An implementation of the Mud Client Compression Protocol.

Overview

MCCP is used to control whether data should be transmitted as compressed or uncompressed data. A telnetpp::options::mccp::server controls compression of an output stream, and telnetpp::options::mccp::client controls compression of an input stream.

Codec

This implementation of the MCCP comprises two distinct parts: the client/server pair, and the codec. Where the client/server pair are used to control when compression/decompression should happen, it is the codec that actually performs the compression and decompression. It does this with the aid of a compressor and a decompressor object. In principle, any API that conforms to the ZLIB compressed data format can be used to perform the compression/decompression functions. Telnet++ bundles compressors for the common zlib library "libz".

Usage - Server

Assuming you want to use an MCCP server in order to send compressed data, you first need to instantiate your server and codec objects:

telnetpp::options::mccp::server mccp_server;
 
telnetpp::options::mccp::codec mccp_codec(
    std::make_shared<telnetpp::options::mccp::zlib::compressor>(),
    std::make_shared<telnetpp::options::mccp::zlib::decompressor>());

Install the server into your telnet session.

telnet_session.install(mccp_server);

Run through the normal negotiations to make the MCCP server active. To begin compression, ensure that you call begin_compression() on the server and write the result to your lower layer

my_lower_layer_write(telnet_session.send(
    mccp_server.begin_compression()));

Finally, ensure that your lower layer write function passes the data through the codec.

void my_lower_layer_write(std::vector<telnetpp::stream_token> const &d)
{
    static telnetpp::byte_converter byte_converter;
    // Compress (if necessary) the data.
    auto const &compressed_data = mccp_codec.send(d);
    // Flatten the stream_tokens to a single byte_stream.
    auto const &stream = byte_converter.send(compressed_data);
    // Output the byte_stream to your socket (or whatever).
    socket_->write({stream.begin(), stream.end()});
}

Usage - Client

If you want to use the client to ensure that data is decompressed, then the implementation is very similar. Of particular note is that the codec must still be in my_lower_layer_write, and also in my_lower_layer_read.

See also

http://tintin.sourceforge.net/mccp/

https://www.ietf.org/rfc/rfc1950.txt