libtelnet - TELNET protocol handling library More...
#include <stdarg.h>
Go to the source code of this file.
Data Structures | |
struct | telnet_environ_t |
union | telnet_event_t |
struct | telnet_event_t::data_t |
struct | telnet_event_t::error_t |
struct | telnet_event_t::iac_t |
struct | telnet_event_t::negotiate_t |
struct | telnet_event_t::subnegotiate_t |
struct | telnet_event_t::zmp_t |
struct | telnet_event_t::ttype_t |
struct | telnet_event_t::compress_t |
struct | telnet_event_t::environ_t |
struct | telnet_event_t::mssp_t |
struct | telnet_telopt_t |
Macros | |
#define | TELNET_GNU_PRINTF(f, a) |
#define | TELNET_GNU_SENTINEL |
#define | telnet_finish_sb(telnet) telnet_iac((telnet), TELNET_SE) |
Finish a sub-negotiation command. More... | |
#define | telnet_finish_newenviron(telnet) telnet_finish_sb((telnet)) |
Finish a NEW-ENVIRON command. More... | |
#define | telnet_finish_zmp(telnet) telnet_finish_sb((telnet)) |
Finish a ZMP command. More... | |
Telnet commands | |
#define | TELNET_IAC 255 |
#define | TELNET_DONT 254 |
#define | TELNET_DO 253 |
#define | TELNET_WONT 252 |
#define | TELNET_WILL 251 |
#define | TELNET_SB 250 |
#define | TELNET_GA 249 |
#define | TELNET_EL 248 |
#define | TELNET_EC 247 |
#define | TELNET_AYT 246 |
#define | TELNET_AO 245 |
#define | TELNET_IP 244 |
#define | TELNET_BREAK 243 |
#define | TELNET_DM 242 |
#define | TELNET_NOP 241 |
#define | TELNET_SE 240 |
#define | TELNET_EOR 239 |
#define | TELNET_ABORT 238 |
#define | TELNET_SUSP 237 |
#define | TELNET_EOF 236 |
Telnet option values. | |
#define | TELNET_TELOPT_BINARY 0 |
#define | TELNET_TELOPT_ECHO 1 |
#define | TELNET_TELOPT_RCP 2 |
#define | TELNET_TELOPT_SGA 3 |
#define | TELNET_TELOPT_NAMS 4 |
#define | TELNET_TELOPT_STATUS 5 |
#define | TELNET_TELOPT_TM 6 |
#define | TELNET_TELOPT_RCTE 7 |
#define | TELNET_TELOPT_NAOL 8 |
#define | TELNET_TELOPT_NAOP 9 |
#define | TELNET_TELOPT_NAOCRD 10 |
#define | TELNET_TELOPT_NAOHTS 11 |
#define | TELNET_TELOPT_NAOHTD 12 |
#define | TELNET_TELOPT_NAOFFD 13 |
#define | TELNET_TELOPT_NAOVTS 14 |
#define | TELNET_TELOPT_NAOVTD 15 |
#define | TELNET_TELOPT_NAOLFD 16 |
#define | TELNET_TELOPT_XASCII 17 |
#define | TELNET_TELOPT_LOGOUT 18 |
#define | TELNET_TELOPT_BM 19 |
#define | TELNET_TELOPT_DET 20 |
#define | TELNET_TELOPT_SUPDUP 21 |
#define | TELNET_TELOPT_SUPDUPOUTPUT 22 |
#define | TELNET_TELOPT_SNDLOC 23 |
#define | TELNET_TELOPT_TTYPE 24 |
#define | TELNET_TELOPT_EOR 25 |
#define | TELNET_TELOPT_TUID 26 |
#define | TELNET_TELOPT_OUTMRK 27 |
#define | TELNET_TELOPT_TTYLOC 28 |
#define | TELNET_TELOPT_3270REGIME 29 |
#define | TELNET_TELOPT_X3PAD 30 |
#define | TELNET_TELOPT_NAWS 31 |
#define | TELNET_TELOPT_TSPEED 32 |
#define | TELNET_TELOPT_LFLOW 33 |
#define | TELNET_TELOPT_LINEMODE 34 |
#define | TELNET_TELOPT_XDISPLOC 35 |
#define | TELNET_TELOPT_ENVIRON 36 |
#define | TELNET_TELOPT_AUTHENTICATION 37 |
#define | TELNET_TELOPT_ENCRYPT 38 |
#define | TELNET_TELOPT_NEW_ENVIRON 39 |
#define | TELNET_TELOPT_MSSP 70 |
#define | TELNET_TELOPT_COMPRESS2 86 |
#define | TELNET_TELOPT_ZMP 93 |
#define | TELNET_TELOPT_EXOPL 255 |
#define | TELNET_TELOPT_MCCP2 86 |
Protocol codes for TERMINAL-TYPE commands. | |
#define | TELNET_TTYPE_IS 0 |
#define | TELNET_TTYPE_SEND 1 |
Protocol codes for NEW-ENVIRON/ENVIRON commands. | |
#define | TELNET_ENVIRON_IS 0 |
#define | TELNET_ENVIRON_SEND 1 |
#define | TELNET_ENVIRON_INFO 2 |
#define | TELNET_ENVIRON_VAR 0 |
#define | TELNET_ENVIRON_VALUE 1 |
#define | TELNET_ENVIRON_ESC 2 |
#define | TELNET_ENVIRON_USERVAR 3 |
Protocol codes for MSSP commands. | |
#define | TELNET_MSSP_VAR 1 |
#define | TELNET_MSSP_VAL 2 |
Telnet state tracker flags. | |
#define | TELNET_FLAG_PROXY (1<<0) |
#define | TELNET_PFLAG_DEFLATE (1<<7) |
Typedefs | |
typedef struct telnet_t | telnet_t |
typedef union telnet_event_t | telnet_event_t |
typedef struct telnet_telopt_t | telnet_telopt_t |
typedef enum telnet_error_t | telnet_error_t |
typedef enum telnet_event_type_t | telnet_event_type_t |
typedef void(* | telnet_event_handler_t )(telnet_t *telnet, telnet_event_t *event, void *user_data) |
event handler More... | |
Functions | |
telnet_t * | telnet_init (const telnet_telopt_t *telopts, telnet_event_handler_t eh, unsigned char flags, void *user_data) |
Initialize a telnet state tracker. More... | |
void | telnet_free (telnet_t *telnet) |
Free up any memory allocated by a state tracker. More... | |
void | telnet_recv (telnet_t *telnet, const char *buffer, size_t size) |
Push a byte buffer into the state tracker. More... | |
void | telnet_iac (telnet_t *telnet, unsigned char cmd) |
Send a telnet command. More... | |
void | telnet_negotiate (telnet_t *telnet, unsigned char cmd, unsigned char opt) |
Send negotiation command. More... | |
void | telnet_send (telnet_t *telnet, const char *buffer, size_t size) |
void | telnet_begin_sb (telnet_t *telnet, unsigned char telopt) |
Begin a sub-negotiation command. More... | |
void | telnet_subnegotiation (telnet_t *telnet, unsigned char telopt, const char *buffer, size_t size) |
Shortcut for sending a complete subnegotiation buffer. More... | |
void | telnet_begin_compress2 (telnet_t *telnet) |
Begin sending compressed data. More... | |
int | telnet_printf (telnet_t *telnet, const char *fmt,...) TELNET_GNU_PRINTF(2 |
Send formatted data. More... | |
int int | telnet_vprintf (telnet_t *telnet, const char *fmt, va_list va) |
Send formatted data. More... | |
int | telnet_raw_printf (telnet_t *telnet, const char *fmt,...) TELNET_GNU_PRINTF(2 |
Send formatted data (no newline escaping). More... | |
int int | telnet_raw_vprintf (telnet_t *telnet, const char *fmt, va_list va) |
Send formatted data (no newline escaping). More... | |
void | telnet_begin_newenviron (telnet_t *telnet, unsigned char type) |
Begin a new set of NEW-ENVIRON values to request or send. More... | |
void | telnet_newenviron_value (telnet_t *telnet, unsigned char type, const char *string) |
Send a NEW-ENVIRON variable name or value. More... | |
void | telnet_ttype_send (telnet_t *telnet) |
Send the TERMINAL-TYPE SEND command. More... | |
void | telnet_ttype_is (telnet_t *telnet, const char *ttype) |
Send the TERMINAL-TYPE IS command. More... | |
void | telnet_send_zmp (telnet_t *telnet, size_t argc, const char **argv) |
Send a ZMP command. More... | |
void | telnet_send_zmpv (telnet_t *telnet,...) TELNET_GNU_SENTINEL |
Send a ZMP command. More... | |
void | telnet_send_vzmpv (telnet_t *telnet, va_list va) |
Send a ZMP command. More... | |
void | telnet_begin_zmp (telnet_t *telnet, const char *cmd) |
Begin sending a ZMP command. More... | |
void | telnet_zmp_arg (telnet_t *telnet, const char *arg) |
Send a ZMP command argument. More... | |
libtelnet - TELNET protocol handling library
SUMMARY:
libtelnet is a library for handling the TELNET protocol. It includes routines for parsing incoming data from a remote peer as well as formatting data to send to the remote peer.
libtelnet uses a callback-oriented API, allowing application-specific handling of various events. The callback system is also used for buffering outgoing protocol data, allowing the application to maintain control over the actual socket connection.
Features supported include the full TELNET protocol, Q-method option negotiation, ZMP, MCCP2, MSSP, and NEW-ENVIRON.
CONFORMS TO:
RFC854 - http://www.faqs.org/rfcs/rfc854.html RFC855 - http://www.faqs.org/rfcs/rfc855.html RFC1091 - http://www.faqs.org/rfcs/rfc1091.html RFC1143 - http://www.faqs.org/rfcs/rfc1143.html RFC1408 - http://www.faqs.org/rfcs/rfc1408.html RFC1572 - http://www.faqs.org/rfcs/rfc1572.html
LICENSE:
The author or authors of this code dedicate any and all copyright interest in this code to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this code under copyright law.
#define TELNET_ENVIRON_IS 0 |
NEW-ENVIRON/ENVIRON codes.
#define telnet_finish_newenviron | ( | telnet | ) | telnet_finish_sb((telnet)) |
Finish a NEW-ENVIRON command.
This must be called after a call to telnet_begin_newenviron() to finish a NEW-ENVIRON variable list.
telnet | Telnet state tracker object. |
#define telnet_finish_sb | ( | telnet | ) | telnet_iac((telnet), TELNET_SE) |
Finish a sub-negotiation command.
This must be called after a call to telnet_begin_sb() to finish a sub-negotiation command.
telnet | Telnet state tracker object. |
#define telnet_finish_zmp | ( | telnet | ) | telnet_finish_sb((telnet)) |
Finish a ZMP command.
This must be called after a call to telnet_begin_zmp() to finish a ZMP argument list.
telnet | Telnet state tracker object. |
#define TELNET_FLAG_PROXY (1<<0) |
Control behavior of telnet state tracker.
#define TELNET_GNU_PRINTF | ( | f, | |
a | |||
) |
internal helper
#define TELNET_GNU_SENTINEL |
internal helper
#define TELNET_IAC 255 |
Telnet commands and special values.
#define TELNET_MSSP_VAR 1 |
MSSP codes.
#define TELNET_TELOPT_BINARY 0 |
Telnet options.
#define TELNET_TTYPE_IS 0 |
TERMINAL-TYPE codes.
typedef enum telnet_error_t telnet_error_t |
Error code type.
typedef void(* telnet_event_handler_t)(telnet_t *telnet, telnet_event_t *event, void *user_data) |
event handler
This is the type of function that must be passed to telnet_init() when creating a new telnet object. The function will be invoked once for every event generated by the libtelnet protocol parser.
telnet | The telnet object that generated the event |
event | Event structure with details about the event |
user_data | User-supplied pointer |
typedef union telnet_event_t telnet_event_t |
Telnet event object type.
typedef enum telnet_event_type_t telnet_event_type_t |
Telnet event type.
typedef struct telnet_telopt_t telnet_telopt_t |
Telnet option table element type.
enum telnet_error_t |
enum telnet_event_type_t |
event codes
void telnet_begin_compress2 | ( | telnet_t * | telnet | ) |
Begin sending compressed data.
This function will begein sending data using the COMPRESS2 option, which enables the use of zlib to compress data sent to the client. The client must offer support for COMPRESS2 with option negotiation, and zlib support must be compiled into libtelnet.
Only the server may call this command.
telnet | Telnet state tracker object. |
void telnet_begin_newenviron | ( | telnet_t * | telnet, |
unsigned char | type | ||
) |
Begin a new set of NEW-ENVIRON values to request or send.
This function will begin the sub-negotiation block for sending or requesting NEW-ENVIRON values.
The telnet_finish_newenviron() macro must be called after this function to terminate the NEW-ENVIRON command.
telnet | Telnet state tracker object. |
type | One of TELNET_ENVIRON_SEND, TELNET_ENVIRON_IS, or TELNET_ENVIRON_INFO. |
void telnet_begin_sb | ( | telnet_t * | telnet, |
unsigned char | telopt | ||
) |
Begin a sub-negotiation command.
Sends IAC SB followed by the telopt code. All following data sent will be part of the sub-negotiation, until telnet_finish_sb() is called.
telnet | Telnet state tracker object. |
telopt | One of the TELNET_TELOPT_* values. |
void telnet_begin_zmp | ( | telnet_t * | telnet, |
const char * | cmd | ||
) |
Begin sending a ZMP command.
telnet | Telnet state tracker object. |
cmd | The first argument (command name) for the ZMP command. |
void telnet_free | ( | telnet_t * | telnet | ) |
Free up any memory allocated by a state tracker.
This function must be called when a telnet state tracker is no longer needed (such as after the connection has been closed) to release any memory resources used by the state tracker.
telnet | Telnet state tracker object. |
void telnet_iac | ( | telnet_t * | telnet, |
unsigned char | cmd | ||
) |
Send a telnet command.
telnet | Telnet state tracker object. |
cmd | Command to send. |
telnet_t* telnet_init | ( | const telnet_telopt_t * | telopts, |
telnet_event_handler_t | eh, | ||
unsigned char | flags, | ||
void * | user_data | ||
) |
Initialize a telnet state tracker.
This function initializes a new state tracker, which is used for all other libtelnet functions. Each connection must have its own telnet state tracker object.
telopts | Table of TELNET options the application supports. |
eh | Event handler function called for every event. |
flags | 0 or TELNET_FLAG_PROXY. |
user_data | Optional data pointer that will be passsed to eh. |
void telnet_negotiate | ( | telnet_t * | telnet, |
unsigned char | cmd, | ||
unsigned char | opt | ||
) |
Send negotiation command.
Internally, libtelnet uses RFC1143 option negotiation rules. The negotiation commands sent with this function may be ignored if they are determined to be redundant.
telnet | Telnet state tracker object. |
cmd | TELNET_WILL, TELNET_WONT, TELNET_DO, or TELNET_DONT. |
opt | One of the TELNET_TELOPT_* values. |
void telnet_newenviron_value | ( | telnet_t * | telnet, |
unsigned char | type, | ||
const char * | string | ||
) |
Send a NEW-ENVIRON variable name or value.
This can only be called between calls to telnet_begin_newenviron() and telnet_finish_newenviron().
telnet | Telnet state tracker object. |
type | One of TELNET_ENVIRON_VAR, TELNET_ENVIRON_USERVAR, or TELNET_ENVIRON_VALUE. |
string | Variable name or value. |
int telnet_printf | ( | telnet_t * | telnet, |
const char * | fmt, | ||
... | |||
) |
Send formatted data.
This function is a wrapper around telnet_send(). It allows using printf-style formatting.
Additionally, this function will translate \r to the CR NUL construct and \n with CR LF, as well as automatically escaping IAC bytes like telnet_send().
telnet | Telnet state tracker object. |
fmt | Format string. |
int telnet_raw_printf | ( | telnet_t * | telnet, |
const char * | fmt, | ||
... | |||
) |
Send formatted data (no newline escaping).
This behaves identically to telnet_printf(), except that the \r and \n characters are not translated. The IAC byte is still escaped as normal with telnet_send().
telnet | Telnet state tracker object. |
fmt | Format string. |
int int telnet_raw_vprintf | ( | telnet_t * | telnet, |
const char * | fmt, | ||
va_list | va | ||
) |
Send formatted data (no newline escaping).
See telnet_raw_printf().
void telnet_recv | ( | telnet_t * | telnet, |
const char * | buffer, | ||
size_t | size | ||
) |
Push a byte buffer into the state tracker.
Passes one or more bytes to the telnet state tracker for protocol parsing. The byte buffer is most often going to be the buffer that recv() was called for while handling the connection.
telnet | Telnet state tracker object. |
buffer | Pointer to byte buffer. |
size | Number of bytes pointed to by buffer. |
void telnet_send | ( | telnet_t * | telnet, |
const char * | buffer, | ||
size_t | size | ||
) |
Send non-command data (escapes IAC bytes).
telnet | Telnet state tracker object. |
buffer | Buffer of bytes to send. |
size | Number of bytes to send. |
void telnet_send_vzmpv | ( | telnet_t * | telnet, |
va_list | va | ||
) |
Send a ZMP command.
See telnet_send_zmpv().
void telnet_send_zmp | ( | telnet_t * | telnet, |
size_t | argc, | ||
const char ** | argv | ||
) |
Send a ZMP command.
telnet | Telnet state tracker object. |
argc | Number of ZMP commands being sent. |
argv | Array of argument strings. |
void telnet_send_zmpv | ( | telnet_t * | telnet, |
... | |||
) |
Send a ZMP command.
Arguments are listed out in var-args style. After the last argument, a NULL pointer must be passed in as a sentinel value.
telnet | Telnet state tracker object. |
void telnet_subnegotiation | ( | telnet_t * | telnet, |
unsigned char | telopt, | ||
const char * | buffer, | ||
size_t | size | ||
) |
Shortcut for sending a complete subnegotiation buffer.
Equivalent to: telnet_begin_sb(telnet, telopt); telnet_send(telnet, buffer, size); telnet_finish_sb(telnet);
telnet | Telnet state tracker format. |
telopt | One of the TELNET_TELOPT_* values. |
buffer | Byte buffer for sub-negotiation data. |
size | Number of bytes to use for sub-negotiation data. |
void telnet_ttype_is | ( | telnet_t * | telnet, |
const char * | ttype | ||
) |
Send the TERMINAL-TYPE IS command.
Sends the sequence IAC TERMINAL-TYPE IS "string".
According to the RFC, the recipient of a TERMINAL-TYPE SEND shall send the next possible terminal-type the client supports. Upon sending the type, the client should switch modes to begin acting as the terminal type is just sent.
The server may continue sending TERMINAL-TYPE IS until it receives a terminal type is understands. To indicate to the server that it has reached the end of the available optoins, the client must send the last terminal type a second time. When the server receives the same terminal type twice in a row, it knows it has seen all available terminal types.
After the last terminal type is sent, if the client receives another TERMINAL-TYPE SEND command, it must begin enumerating the available terminal types from the very beginning. This allows the server to scan the available types for a preferred terminal type and, if none is found, to then ask the client to switch to an acceptable alternative.
Note that if the client only supports a single terminal type, then simply sending that one type in response to every SEND will satisfy the behavior requirements.
telnet | Telnet state tracker object. |
ttype | Name of the terminal-type being sent. |
void telnet_ttype_send | ( | telnet_t * | telnet | ) |
Send the TERMINAL-TYPE SEND command.
Sends the sequence IAC TERMINAL-TYPE SEND.
telnet | Telnet state tracker object. |
int int telnet_vprintf | ( | telnet_t * | telnet, |
const char * | fmt, | ||
va_list | va | ||
) |
Send formatted data.
See telnet_printf().
void telnet_zmp_arg | ( | telnet_t * | telnet, |
const char * | arg | ||
) |
Send a ZMP command argument.
telnet | Telnet state tracker object. |
arg | Telnet argument string. |