My Project
Data Structures | Macros | Typedefs | Enumerations | Functions
libtelnet.h File Reference

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...
 

Enumerations

enum  telnet_error_t {
  TELNET_EOK = 0, TELNET_EBADVAL, TELNET_ENOMEM, TELNET_EOVERFLOW,
  TELNET_EPROTOCOL, TELNET_ECOMPRESS
}
 
enum  telnet_event_type_t {
  TELNET_EV_DATA = 0, TELNET_EV_SEND, TELNET_EV_IAC, TELNET_EV_WILL,
  TELNET_EV_WONT, TELNET_EV_DO, TELNET_EV_DONT, TELNET_EV_SUBNEGOTIATION,
  TELNET_EV_COMPRESS, TELNET_EV_ZMP, TELNET_EV_TTYPE, TELNET_EV_ENVIRON,
  TELNET_EV_MSSP, TELNET_EV_WARNING, TELNET_EV_ERROR
}
 

Functions

telnet_ttelnet_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...
 

Detailed Description

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.

Version
0.20
Author
Sean Middleditch sean@.nosp@m.sour.nosp@m.cemud.nosp@m..org

Macro Definition Documentation

#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.

Parameters
telnetTelnet 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.

Parameters
telnetTelnet 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.

Parameters
telnetTelnet state tracker object.
#define TELNET_FLAG_PROXY   (1<<0)

Control behavior of telnet state tracker.

#define TELNET_GNU_PRINTF (   f,
 
)

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 Documentation

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.

Parameters
telnetThe telnet object that generated the event
eventEvent structure with details about the event
user_dataUser-supplied pointer

Telnet event object type.

Telnet event type.

typedef struct telnet_t telnet_t

Telnet state tracker object type.

Telnet option table element type.

Enumeration Type Documentation

error codes

Enumerator
TELNET_EOK 

no error

TELNET_EBADVAL 

invalid parameter, or API misuse

TELNET_ENOMEM 

memory allocation failure

TELNET_EOVERFLOW 

data exceeds buffer size

TELNET_EPROTOCOL 

invalid sequence of special bytes

TELNET_ECOMPRESS 

error handling compressed streams

event codes

Enumerator
TELNET_EV_DATA 

raw text data has been received

TELNET_EV_SEND 

data needs to be sent to the peer

TELNET_EV_IAC 

generic IAC code received

TELNET_EV_WILL 

WILL option negotiation received

TELNET_EV_WONT 

WONT option neogitation received

TELNET_EV_DO 

DO option negotiation received

TELNET_EV_DONT 

DONT option negotiation received

TELNET_EV_SUBNEGOTIATION 

sub-negotiation data received

TELNET_EV_COMPRESS 

compression has been enabled

TELNET_EV_ZMP 

ZMP command has been received

TELNET_EV_TTYPE 

TTYPE command has been received

TELNET_EV_ENVIRON 

ENVIRON command has been received

TELNET_EV_MSSP 

MSSP command has been received

TELNET_EV_WARNING 

recoverable error has occured

TELNET_EV_ERROR 

non-recoverable error has occured

Function Documentation

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.

Parameters
telnetTelnet 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.

Parameters
telnetTelnet state tracker object.
typeOne 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.

Parameters
telnetTelnet state tracker object.
teloptOne of the TELNET_TELOPT_* values.
void telnet_begin_zmp ( telnet_t telnet,
const char *  cmd 
)

Begin sending a ZMP command.

Parameters
telnetTelnet state tracker object.
cmdThe 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.

Parameters
telnetTelnet state tracker object.
void telnet_iac ( telnet_t telnet,
unsigned char  cmd 
)

Send a telnet command.

Parameters
telnetTelnet state tracker object.
cmdCommand 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.

Parameters
teloptsTable of TELNET options the application supports.
ehEvent handler function called for every event.
flags0 or TELNET_FLAG_PROXY.
user_dataOptional data pointer that will be passsed to eh.
Returns
Telent state tracker object.
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.

Parameters
telnetTelnet state tracker object.
cmdTELNET_WILL, TELNET_WONT, TELNET_DO, or TELNET_DONT.
optOne 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().

Parameters
telnetTelnet state tracker object.
typeOne of TELNET_ENVIRON_VAR, TELNET_ENVIRON_USERVAR, or TELNET_ENVIRON_VALUE.
stringVariable 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().

Parameters
telnetTelnet state tracker object.
fmtFormat string.
Returns
Number of bytes sent.
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().

Parameters
telnetTelnet state tracker object.
fmtFormat string.
Returns
Number of bytes sent.
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.

Parameters
telnetTelnet state tracker object.
bufferPointer to byte buffer.
sizeNumber 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).

Parameters
telnetTelnet state tracker object.
bufferBuffer of bytes to send.
sizeNumber 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.

Parameters
telnetTelnet state tracker object.
argcNumber of ZMP commands being sent.
argvArray 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.

Parameters
telnetTelnet 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);

Parameters
telnetTelnet state tracker format.
teloptOne of the TELNET_TELOPT_* values.
bufferByte buffer for sub-negotiation data.
sizeNumber 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.

Parameters
telnetTelnet state tracker object.
ttypeName 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.

Parameters
telnetTelnet 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.

Parameters
telnetTelnet state tracker object.
argTelnet argument string.