An abstraction for a Telnet session.
More...
#include <session.hpp>
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 as appropriate.
- Construction
- Session's constructor takes one parameter, which is a function that takes a string and returns a vector of tokens. This function is called when data has been received by the session and did not belong to the Telnet protocol, i.e. application data. In practice, this is where most of the dataflow of an application takes place. It's possible that there is an immediate response to this data, and that is encapsulated in the return value. Note that the return value can include Telnet elements. Example:
std::vector<telnetpp::token> app_fn(std::string const &text)
{
if (text == "COMPRESS")
{
return mccp_server.begin_compression();
}
else if (text == "ECHO")
{
}
...
}
...
- Installation
- It is possible to "install" handlers into the session. The most basic installation is for handling Telnet commands, such as "Are You There?". It is also possible to install client- and server options into the session, which ensures that any negotiations or subnegotiations that are tagged as belonging to those options are forwarded to those option handlers.
{
}
...
session.install(telnetpp::ayt, ayt_handler);
- Sending
- The send() function is used to convert all telnetpp::elements contained in the tokens into sequences of bytes. Note: even if you know the tokens contain only plain strings, they must still pass through this function, since it's necessary to escape any 0xFF bytes so that they are not received as Telnet commands by the remote side. After this operation is complete, the application must write the byte streams over the actual data connection itself.
- Receiving
- The receive() function is used to receive data that has been read from the remote connection and route it to the correct handler, be it the installed options or command handlers, or the text handler registered in the constructor. Note: receiving data frequently has an immediate response. For example, receving bytes that amount to an option negotiation will result in a reply to that negotiation. For this reason, the usual pattern for receiving is to immediately send() the result of the call to receive, and then write that result to the data connection.
| telnetpp::session::session |
( |
std::function< std::vector< token >(std::string const &)> |
on_text | ) |
|
Constructor.
- Parameters
-
| on_text | a function to be called whenever text is received. |
| std::vector< token > telnetpp::session::receive |
( |
u8stream const & |
stream | ) |
|
Receive a stream of bytes.
- Returns
- a stream of tokens generated as a result of receiving this stream.
| std::vector< boost::variant< u8stream, boost::any > > telnetpp::session::send |
( |
std::vector< token > const & |
tokens | ) |
|
"Sends" a stream of tokens by converting them to a stream of bytes.
Any non-element tokens are passed through unchanged. This allows the result of receive() to be passed straight back to generate for immediate transmission.
The documentation for this class was generated from the following files:
1.8.11
