telnetpp::session Class Reference

An abstraction for a Telnet session. More...

#include <session.hpp>

Classes
struct	impl

Public Member Functions
template<typename Channel >
	session (Channel &channel)
	Constructor.
	~session ()
	Destructor.
bool	is_alive () const
	Returns whether the session is still alive.
void	close ()
	Closes the session.
void	async_read (std::function< void(telnetpp::bytes)> const &callback)
	Requests data from the underlying channel, acting on any Telnet primitives that are received. More...
void	write (telnetpp::element const &elem)
	Sends a Telnet data element. Translates the element into a sequence of bytes, that is then sent to the continuation. More...
void	install (telnetpp::command_type cmd, std::function< void(telnetpp::command)> const &handler)
	Installs a handler for the given command.
void	install (telnetpp::client_option &option)
	Installs a client option.
void	install (telnetpp::server_option &option)
	Installs a server option.

Detailed Description

An abstraction for a Telnet session.

Overview

The session is the heart of the library, and ties all of the other components together. It manages all of the options that a session wishes to implement and ensures that data flows to them appropriately.

The Channel

To be as agnostic as possible as to how to send and receive data, the session exposes a channel concept, which is fulfilled by any object that contains the functions: write, async_read, is_alive, close. Classes that expose these functions, such as tcp_socket in Server++, can be dropped in here without any extra work. Otherwise it may be necessary to write a small wrapper.

Sending and Receiving Plain Data

The first part of using a telnetpp::session is understanding how to send and receive data. Even if no options are used during a session, this is still necessary because some data needs special handling.

Note

According to the Telnet protocol, the 0xFF byte has to be transmitted as IAC IAC (0xFF 0xFF) so that it is not understood to be part of a Telnet protocol sequence. Likewise, it is necessary to parse IAC IAC into a single 0xFF byte.

Sending data uses the telnetpp::session::write function. This handles any such special sequences and then passes that data onto the continuation supplied. Example:

using namespace terminalpp::literals;
struct my_channel
{
    void async_read(std::function<void (telnetpp::bytes)>);
    void write(telnetpp::bytes);
    // ...
};
 
my_channel channel;
telnetpp::session session{channel};
 
auto const message = "Hello" "\xFF" "World"_tb;
session.send(message);
// sends "Hello\xFF\xFFWorld" to channel.write().
// Notice the duplicated \xFF byte as required by the Telnet protocol.

Receiving data works using a continuation; a function that is called once the data is received. This means that it is non-blocking. Example:

my_channel channel;
telnetpp::session session{channel};
 
// A user-specified function that transmits data up to the application
// Note that the second argument is used to tell the application how
// it may send a respond to the data it receives.
void my_application_receive(telnetpp::bytes data);
 
session.async_read([&](telnetpp::bytes data) {
    my_application_receive(data);
});

Using Telnet Options

Now that we can send and receive data over a Telnet connection, the next step is to install some options. This allows the session to automatically route messages to and from these options as part of the normal data flow. Example:

telnetpp::session session{channel};
telnetpp::options::echo::client echo_client{session};
telnetpp::options::naws::server naws_server{session};
session.install(echo_client);
session.install(naws_server);

With these options installed, the normal message as implemented above will automatically activate or deactivate the options if this is requested by the remote. It is, of course, just fine if you want to activate these options yourself. Example:

Transmits IAC WILL NAWS to the remote.
naws_server.activate();

Likewise, any functions that cause option-specific negotiation (subnegotiations) to occur use a similar pattern:

// Will transmit IAC SB NAWS 00 80 00 24 IAC SE to the
// remote.
naws_server.set_window_size(80, 24);

Using Telnet Commands

There also exist a small number of Telnet commands, such as AYT (Are You There), BRK (Break) and NOP (No Operation). These can be sent using the telnetpp::session::send function in a similar way to plain text. Example:

session.write(telnetpp::command{telnetpp::ayt});

They can also have handlers registered in order to respond to them:

session.install(
    telnetpp::command{telnetpp::ayt},
    [&]()
    {
        using telnetpp::literals;
        auto const message = "Yes, I'm here"_tb;
        session.write(message);
    });

Member Function Documentation

async_read()

void telnetpp::session::async_read

(

std::function< void(telnetpp::bytes)> const &

callback

)

Requests data from the underlying channel, acting on any Telnet primitives that are received.

Note: the callback may be called several times for any async_read. For an example, it may contain two pieces of regular text surrounding a block of negotiation, which may change the way those two pieces of text are interpreted. For this reason, after an async_read is complete, the callback will always be called with an empty parameter to indicate that a new read request can be made.

write()

void telnetpp::session::write

(

telnetpp::element const &

elem

)

Sends a Telnet data element. Translates the element into a sequence of bytes, that is then sent to the continuation.

Parameters

content

The data to send

---

The documentation for this class was generated from the following files:

• /home/runner/work/telnetpp/telnetpp/include/telnetpp/session.hpp
• /home/runner/work/telnetpp/telnetpp/src/session.cpp