Sean Middleditch | b9e4864 | 2009-03-12 23:33:27 -0400 | [diff] [blame] | 1 | ===================================================================== |
| 2 | libtelnet - TELNET protocol handling library |
| 3 | ===================================================================== |
| 4 | |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 5 | http://github.com/elanthis/libtelnet |
| 6 | |
| 7 | Sean Middleditch |
| 8 | sean@sourcemud.org |
Sean Middleditch | b9e4864 | 2009-03-12 23:33:27 -0400 | [diff] [blame] | 9 | |
| 10 | --------------------------------------------------------------------- |
| 11 | The author or authors of this code dedicate any and all copyright |
| 12 | interest in this code to the public domain. We make this dedication |
| 13 | for the benefit of the public at large and to the detriment of our |
| 14 | heirs and successors. We intend this dedication to be an overt act of |
| 15 | relinquishment in perpetuity of all present and future rights to this |
| 16 | code under copyright law. |
| 17 | --------------------------------------------------------------------- |
| 18 | |
Sean Middleditch | b9e4864 | 2009-03-12 23:33:27 -0400 | [diff] [blame] | 19 | I. INTRODUCTION |
| 20 | ===================================================================== |
| 21 | |
| 22 | libtelnet provides safe and correct handling of the core TELNET |
Sean Middleditch | 8b78896 | 2009-03-16 01:06:27 -0400 | [diff] [blame] | 23 | protocol. In addition to the base TELNET protocol, libtelnet also |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 24 | implements the Q method of TELNET option negotiation. libtelnet can |
| 25 | be used for writing servers, clients, or proxies. |
Sean Middleditch | b9e4864 | 2009-03-12 23:33:27 -0400 | [diff] [blame] | 26 | |
Sean Middleditch | 94d67e8 | 2009-03-22 22:38:02 -0400 | [diff] [blame] | 27 | For more information on the TELNET standards supported by libtelnet, |
| 28 | visit the following websites: |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 29 | |
| 30 | http://www.faqs.org/rfcs/rfc854.html |
Sean Middleditch | 94d67e8 | 2009-03-22 22:38:02 -0400 | [diff] [blame] | 31 | http://www.faqs.org/rfcs/rfc855.html |
| 32 | http://www.faqs.org/rfcs/rfc1091.html |
Sean Middleditch | 8b78896 | 2009-03-16 01:06:27 -0400 | [diff] [blame] | 33 | http://www.faqs.org/rfcs/rfc1143.html |
Sean Middleditch | 94d67e8 | 2009-03-22 22:38:02 -0400 | [diff] [blame] | 34 | http://www.faqs.org/rfcs/rfc1408.html |
| 35 | http://www.faqs.org/rfcs/rfc1572.html |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 36 | |
Sean Middleditch | b9e4864 | 2009-03-12 23:33:27 -0400 | [diff] [blame] | 37 | II. LIBTELNET API |
| 38 | ===================================================================== |
| 39 | |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 40 | The libtelnet API contains several distinct parts. The first part is |
| 41 | the basic initialization and deinitialization routines. The second |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 42 | part is a single function for pushing received data into the telnet |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 43 | processor. The third part is the libtelnet output functions, which |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 44 | generate TELNET commands and ensure data is properly formatted before |
| 45 | sending over the wire. The final part is the event handler |
| 46 | interface. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 47 | |
| 48 | IIa. Initialization |
| 49 | |
Sean Middleditch | bfc641e | 2009-03-22 16:26:06 -0400 | [diff] [blame] | 50 | Using libtelnet requires the initialization of a telnet_t structure |
| 51 | which stores all current state for a single TELNET connection. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 52 | |
Sean Middleditch | bfc641e | 2009-03-22 16:26:06 -0400 | [diff] [blame] | 53 | Initializing a telnet_t structure requires several pieces of data. |
| 54 | One of these is the telopt support table, which specifies which |
| 55 | TELNET options your application supports both locally and remotely. |
| 56 | This table is comprised of telnet_telopt_t structures, one for each |
| 57 | supported option. Each entry specifies the option supported, |
| 58 | whether the option is supported locally or remotely. |
| 59 | |
| 60 | struct telnet_telopt_t { |
| 61 | short telopt; |
| 62 | unsigned char us; |
| 63 | unsigned char him; |
| 64 | }; |
| 65 | |
| 66 | The us field denotes whether your application supporst the telopt |
| 67 | locally. It should be set to TELNET_WILL if you support it and to |
| 68 | TELNET_WONT if you don't. The him field denotes whether the telopt |
| 69 | is supported on the remote end, and should be TELNET_DO if yes and |
| 70 | TELNET_DONT if not. |
| 71 | |
| 72 | When definition the telopt table you must include an end marker |
| 73 | entry, which is simply an entry with telopt set to -1. For |
| 74 | example: |
| 75 | |
| 76 | static const telnet_telopt_t my_telopts[] = { |
| 77 | { TELNET_TELOPT_ECHO, TELNET_WILL, TELNET_DONT }, |
| 78 | { TELNET_TELOPT_TTYPE, TELNET_WILL, TELNET_DONT }, |
| 79 | { TELNET_TELOPT_COMPRESS2, TELNET_WONT, TELNET_DO }, |
| 80 | { TELNET_TELOPT_ZMP, TELNET_WONT, TELNET_DO }, |
| 81 | { TELNET_TELOPT_MSSP, TELNET_WONT, TELNET_DO }, |
| 82 | { TELNET_TELOPT_BINARY, TELNET_WILL, TELNET_DO }, |
| 83 | { TELNET_TELOPT_NAWS, TELNET_WILL, TELNET_DONT }, |
| 84 | { -1, 0, 0 } |
| 85 | }; |
| 86 | |
| 87 | If you need to dynamically alter supported options on a |
| 88 | per-connection basis then you may use a different tables |
| 89 | (dynamically allocated if necessary) per call to telnet_init() or |
| 90 | you share a single constant table like the above example between |
| 91 | all connections if you support a fixed set of options. Most |
| 92 | applications will support only a fixed set of options. |
| 93 | |
| 94 | void telnet_init(telnet_t *telnet, const telnet_telopts_t *telopts, |
| 95 | telnet_event_handler_t handler, unsigned char flags, |
| 96 | void *user_data); |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 97 | The telnet_init() function is responsible for initializing the |
| 98 | data in a telnet_t structure. It must be called immediately after |
| 99 | establishing a connection and before any other libtelnet API calls |
| 100 | are made. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 101 | |
Sean Middleditch | bfc641e | 2009-03-22 16:26:06 -0400 | [diff] [blame] | 102 | The telopts field is the telopt support table as described above. |
| 103 | |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 104 | The handler parameter must be a function matching the |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 105 | telnet_event_handler_t definition. More information about events |
| 106 | can be found in section IId. |
Sean Middleditch | 3032302 | 2009-03-14 21:45:28 -0400 | [diff] [blame] | 107 | |
Sean Middleditch | 9f79cc5 | 2009-03-15 13:39:24 -0400 | [diff] [blame] | 108 | The user_data parameter is passed to the event handler whenver it |
| 109 | is invoked. This will usually be a structure container |
| 110 | information about the connection, including a socket descriptor |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 111 | for implementing TELNET_EV_SEND event handling. |
Sean Middleditch | 9f79cc5 | 2009-03-15 13:39:24 -0400 | [diff] [blame] | 112 | |
Sean Middleditch | 08bb05f | 2009-03-15 23:29:46 -0400 | [diff] [blame] | 113 | The flags parameter can be any of the following flag constants |
| 114 | bit-or'd together, or 0 to leave all options disabled. |
| 115 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 116 | TELNET_FLAG_PROXY |
Sean Middleditch | c337ba6 | 2009-03-16 16:47:27 -0400 | [diff] [blame] | 117 | Operate in proxy mode. This disables the RFC1143 support and |
| 118 | enables automatic detection of COMPRESS2 streams. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 119 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 120 | boid telnet_free(telnet_t *telnet); |
| 121 | Releases any internal memory allocated by libtelnet. This must be |
| 122 | called whenever a connection is closed, or you will incur memory |
| 123 | leaks. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 124 | |
| 125 | IIb. Receiving Data |
| 126 | |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 127 | void telnet_recv(telnet_t *telnet, |
Sean Middleditch | 340a51b | 2009-03-19 02:08:46 -0400 | [diff] [blame] | 128 | const char *buffer, unsigned int size, void *user_data); |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 129 | When your application receives data over the socket from the |
| 130 | remote end, it must pass the received bytes into this function. |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 131 | |
| 132 | As the TELNET stream is parsed, events will be generated and |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 133 | passed to the event handler given to telnet_init(). Of particular |
| 134 | interest for data receiving is the TELNET_EV_DATA event, which is |
| 135 | triggered for any regular data such as user input or server |
| 136 | process output. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 137 | |
| 138 | IIc. Sending Data |
| 139 | |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 140 | All of the output functions will invoke the TELNET_EV_SEND event. |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 141 | |
| 142 | Note: it is very important that ALL data sent to the remote end of |
| 143 | the connection be passed through libtelnet. All user input or |
| 144 | process output that you wish to send over the wire should be given |
Sean Middleditch | 4613e68 | 2009-03-16 17:21:48 -0400 | [diff] [blame] | 145 | to one of the following functions. Do NOT send or buffer |
| 146 | unprocessed output data directly! |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 147 | |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 148 | void telnet_iac(telnet_t *telnet, unsigned char cmd); |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 149 | Sends a single "simple" TELNET command, such as the GO-AHEAD |
| 150 | commands (255 249). |
| 151 | |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 152 | void telnet_negotiate(telnet_t *telnet, unsigned char cmd, |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 153 | unsigned char opt); |
| 154 | Sends a TELNET negotiation command. The cmd parameter must be one |
| 155 | of TELNET_WILL, TELNET_DONT, TELNET_DO, or TELNET_DONT. The opt |
| 156 | parameter is the option to negotiate. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 157 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 158 | Unless in PROXY mode, the RFC1143 support may delay or ellide the |
| 159 | request entirely, as appropriate. It will ignore duplicate |
| 160 | invocations, such as asking for WILL NAWS when NAWS is already on |
| 161 | or is currently awaiting response from the remote end. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 162 | |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 163 | void telnet_send(telnet_t *telnet, const char *buffer, size_t size); |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 164 | Sends raw data, which would be either the process output from a |
| 165 | server or the user input from a client. |
| 166 | |
| 167 | For sending regular text is may be more convenient to use |
| 168 | telnet_printf(). |
Sean Middleditch | 90e79da | 2009-03-19 15:17:13 -0400 | [diff] [blame] | 169 | |
| 170 | void telnet_begin_subnegotiation(telnet_t *telnet, unsigned char |
| 171 | telopt); |
| 172 | Sends the header for a TELNET sub-negotiation command for the |
| 173 | specified option. All send data following this command will be |
| 174 | part of the sub-negotiation data until a call is made to |
| 175 | telnet_finish_subnegotiation(). |
| 176 | |
| 177 | You should not use telnet_printf() for sending subnegotiation |
| 178 | data as it will perform newline translations that usually do not |
| 179 | need to be done for subnegotiation data, and may cause problems. |
| 180 | |
| 181 | void telnet_finish_subnegotiation(telnet_t *telnet); |
| 182 | Sends the end marker for a TELNET sub-negotiation command. This |
| 183 | must be called after (and only after) a call has been made to |
| 184 | telnet_begin_subnegotiation() and any negotiation data has been |
| 185 | sent. |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 186 | |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 187 | void telnet_subnegotiation(telnet_t *telnet, unsigned char telopt, |
| 188 | const char *buffer, unsigned int size); |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 189 | Sends a TELNET sub-negotiation command. The telopt parameter is |
| 190 | the sub-negotiation option. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 191 | |
Sean Middleditch | 90e79da | 2009-03-19 15:17:13 -0400 | [diff] [blame] | 192 | Note that this function is just a shorthand for: |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 193 | telnet_begin_sb(telnet, telopt); |
| 194 | telnet_send(telnet, buffer, size); |
| 195 | telnet_end_sb(telnet); |
Sean Middleditch | 2b4bfc4 | 2009-03-16 01:25:52 -0400 | [diff] [blame] | 196 | |
| 197 | For some subnegotiations that involve a lot of complex formatted |
Sean Middleditch | 90e79da | 2009-03-19 15:17:13 -0400 | [diff] [blame] | 198 | data to be sent, it may be easier to make calls to both |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 199 | telnet_begin_sb() and telnet_finish_sb() and using telnet_send() |
| 200 | or telnet_printf2() to format the data. |
Sean Middleditch | 2b4bfc4 | 2009-03-16 01:25:52 -0400 | [diff] [blame] | 201 | |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 202 | NOTE: telnet_subnegotiation() does have special behavior in |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 203 | PROXY mode, as in that mode this function will automatically |
Sean Middleditch | 2b4bfc4 | 2009-03-16 01:25:52 -0400 | [diff] [blame] | 204 | detect the COMPRESS2 marker and enable zlib compression. |
| 205 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 206 | int telnet_printf(telnet_t *telnet, const char *fmt, ...); |
| 207 | This functions very similarly to fprintf, except that output is |
| 208 | sent through libtelnet for processing. IAC bytes are properly |
| 209 | escaped, C newlines (\n) are translated into CR LF, and C carriage |
| 210 | returns (\r) are translated into CR NUL, all as required by |
| 211 | RFC854. The return code is the length of the formatted text. |
Sean Middleditch | 4613e68 | 2009-03-16 17:21:48 -0400 | [diff] [blame] | 212 | |
| 213 | NOTE: due to an internal implementation detail, the maximum |
| 214 | lenth of the formatted text is 4096 characters. |
| 215 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 216 | int telnet_printf2(telnet_t *telnet, const char *fmt, ...); |
| 217 | Identical to telnet_printf() except that \r and \n are not |
| 218 | translated. This should be used if you are attempting to send |
| 219 | raw data inside a subnegotiation or if you have already manually |
| 220 | escaped newlines. |
Sean Middleditch | eb950a8 | 2009-03-22 23:04:28 -0400 | [diff] [blame^] | 221 | |
| 222 | void telnet_format_sb(telnet_t *telnet, unsigned char telopt, |
| 223 | size_t count, ...); |
| 224 | This is a helper function for sending the specially formatted |
| 225 | data used in the TTYPE, ENVIRON/NEW-ENVIRON, and MSSP telopt |
| 226 | subnegotiations. |
| 227 | |
| 228 | The variadic arguments must be given as a series of pairs of |
| 229 | markers and strings. The markers are different for each telopt; |
| 230 | they are defined in libtelnet.h and include: |
| 231 | |
| 232 | /* TTYPE markers */ |
| 233 | #define TELNET_TTYPE_IS 0 |
| 234 | #define TELNET_TTYPE_SEND 1 |
| 235 | |
| 236 | /* ENVIRON/NEW-ENVIRON markers */ |
| 237 | #define TELNET_ENVIRON_IS 0 |
| 238 | #define TELNET_ENVIRON_SEND 1 |
| 239 | #define TELNET_ENVIRON_INFO 2 |
| 240 | #define TELNET_ENVIRON_VAR 0 |
| 241 | #define TELNET_ENVIRON_VALUE 1 |
| 242 | #define TELNET_ENVIRON_ESC 2 |
| 243 | #define TELNET_ENVIRON_USERVAR 3 |
| 244 | |
| 245 | /* MSSP markers */ |
| 246 | #define TELNET_MSSP_VAR 1 |
| 247 | #define TELNET_MSSP_VAL 2 |
| 248 | |
| 249 | So to send a TTYPE subnegotiation from the server (just an IS |
| 250 | command), you would use: |
| 251 | |
| 252 | telnet_format_sb(&telnet, TELNET_TELOPT_TTYPE, 1, |
| 253 | TELNET_TTYPE_SEND); |
| 254 | |
| 255 | The client response for an xterm-compatible terminal would be: |
| 256 | |
| 257 | telnet_format_sb(&telnet, TELNET_TELOPT_TTYPE, 1, |
| 258 | TELNET_TTYPE_IS, "xterm"); |
| 259 | |
| 260 | For more information on the meaning of the markers and strings, |
| 261 | please refer to the specific RFC for the telopt in question. |
Sean Middleditch | 4613e68 | 2009-03-16 17:21:48 -0400 | [diff] [blame] | 262 | |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 263 | IId. Event Handling |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 264 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 265 | libtelnet relies on an event-handling mechanism for processing the |
| 266 | parsed TELNET protocol stream as well as for buffering and sending |
| 267 | output data. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 268 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 269 | When you initialize a telnet_t structure with telnet_init() you had |
| 270 | to pass in an event handler function. This function must meet the |
| 271 | following prototype: |
Sean Middleditch | 3032302 | 2009-03-14 21:45:28 -0400 | [diff] [blame] | 272 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 273 | void (telnet_t *telnet, telnet_event_t *event, void *user_data); |
Sean Middleditch | 9f79cc5 | 2009-03-15 13:39:24 -0400 | [diff] [blame] | 274 | |
| 275 | The event structure is detailed below. The user_data value is the |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 276 | pointer passed to telnet_init(). |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 277 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 278 | struct telnet_event_t { |
Sean Middleditch | 340a51b | 2009-03-19 02:08:46 -0400 | [diff] [blame] | 279 | const char *buffer; |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 280 | unsigned int size; |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 281 | telnet_event_type_t type; |
Sean Middleditch | 812358d | 2009-03-15 23:24:03 -0400 | [diff] [blame] | 282 | unsigned char command; |
| 283 | unsigned char telopt; |
| 284 | unsigned char accept; |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 285 | }; |
| 286 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 287 | The enumeration values of telnet_event_type_t are described in |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 288 | detail below. Whenever the the event handler is invoked, the |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 289 | application must look at the event->type value and do any necessary |
| 290 | processing. |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 291 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 292 | The only event that MUST be implemented is TELNET_EV_SEND. Most |
| 293 | applications will also always want to implement the event |
| 294 | TELNET_EV_DATA. |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 295 | |
| 296 | Here is an example event handler implementation which includes |
| 297 | handlers for several important events. |
| 298 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 299 | void my_event_handler(telnet_t *telnet, telnet_event_t *ev, |
Sean Middleditch | 812358d | 2009-03-15 23:24:03 -0400 | [diff] [blame] | 300 | void *user_data) { |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 301 | struct user_info *user = (struct user_info *)user_data; |
| 302 | |
| 303 | switch (ev->type) { |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 304 | case TELNET_EV_DATA: |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 305 | process_user_input(user, event->buffer, event->size); |
| 306 | break; |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 307 | case TELNET_EV_SEND: |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 308 | write_to_descriptor(user, event->buffer, event->size); |
| 309 | break; |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 310 | case TELNET_EV_ERROR: |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 311 | fatal_error("TELNET error: %s", event->buffer); |
| 312 | break; |
| 313 | } |
Sean Middleditch | 3032302 | 2009-03-14 21:45:28 -0400 | [diff] [blame] | 314 | } |
| 315 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 316 | TELNET_EV_DATA: |
| 317 | The DATA event is triggered whenever regular data (not part of any |
| 318 | special TELNET command) is received. For a client, this will be |
| 319 | process output from the server. For a server, this will be input |
| 320 | typed by the user. |
Sean Middleditch | 3032302 | 2009-03-14 21:45:28 -0400 | [diff] [blame] | 321 | |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 322 | The event->buffer value will contain the bytes received and the |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 323 | event->size value will contain the number of bytes received. Note |
| 324 | that event->buffer is not NUL terminated! |
Sean Middleditch | 3032302 | 2009-03-14 21:45:28 -0400 | [diff] [blame] | 325 | |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 326 | NOTE: there is no guarantee that user input or server output |
| 327 | will be received in whole lines. If you wish to process data |
| 328 | a line at a time, you are responsible for buffering the data and |
| 329 | checking for line terminators yourself! |
| 330 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 331 | TELNET_EV_SEND: |
| 332 | This event is sent whenever libtelnet has generated data that must |
| 333 | be sent over the wire to the remove end. Generally that means |
| 334 | calling send() or adding the data to your application's output |
| 335 | buffer. |
Sean Middleditch | 3032302 | 2009-03-14 21:45:28 -0400 | [diff] [blame] | 336 | |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 337 | The event->buffer value will contain the bytes to send and the |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 338 | event->size value will contain the number of bytes to send. Note |
| 339 | that event->buffer is not NUL terminated, and may include NUL |
| 340 | characters in its data, so always use event->size! |
Sean Middleditch | 3032302 | 2009-03-14 21:45:28 -0400 | [diff] [blame] | 341 | |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 342 | NOTE: Your SEND event handler must send or buffer the data in |
| 343 | its raw form as provided by libtelnet. If you wish to perform |
| 344 | any kind of preprocessing on data you want to send to the other |
| 345 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 346 | TELNET_EV_IAC: |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 347 | The IAC event is triggered whenever a simple IAC command is |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 348 | received, such as the IAC EOR (end of record, also called go ahead |
| 349 | or GA) command. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 350 | |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 351 | The command received is in the event->command value. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 352 | |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 353 | The necessary processing depends on the specific commands; see |
| 354 | the TELNET RFC for more information. |
| 355 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 356 | TELNET_EV_WILL: |
| 357 | TELNET_EV_DO: |
| 358 | The WILL and DO events are sent when a TELNET negotiation command |
| 359 | of the same name is received. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 360 | |
Sean Middleditch | 5b5bc92 | 2009-03-15 23:02:10 -0400 | [diff] [blame] | 361 | WILL events are sent by the remote end when they wish to be |
| 362 | allowed to turn an option on on their end, or in confirmation |
| 363 | after you have sent a DO command to them. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 364 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 365 | DO events are sent by the remote end when they wish for you to |
| 366 | turn on an option on your end, or in confirmation after you have |
| 367 | sent a WILL command to them. |
Sean Middleditch | 5b5bc92 | 2009-03-15 23:02:10 -0400 | [diff] [blame] | 368 | |
| 369 | In either case, the TELNET option under negotiation will be in |
| 370 | event->telopt field. |
| 371 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 372 | If you support the option and wish for it to be enabled you must |
| 373 | set the event->accept field to 1, unless this event is a |
| 374 | confirmation for a previous WILL/DO command you sent to the remote |
| 375 | end. If you do not set event->field to 1 then libtelnet will send |
| 376 | a rejection command back to the other end. |
Sean Middleditch | 5b5bc92 | 2009-03-15 23:02:10 -0400 | [diff] [blame] | 377 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 378 | libtelnet manages some of the pecularities of negotiation for you. |
| 379 | For information on libtelnet's negotiation method, see: |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 380 | |
| 381 | http://www.faqs.org/rfcs/rfc1143.html |
| 382 | |
Sean Middleditch | 5b5bc92 | 2009-03-15 23:02:10 -0400 | [diff] [blame] | 383 | Examples: |
| 384 | |
| 385 | You want remote end to use TTYPE, so you send DO TTYPE. |
| 386 | Remote accepts and sends WILL TTYPE. |
| 387 | |
| 388 | Remote end wants you to use SGA, so they send DO_SGA. |
| 389 | You do not support SGA and set event->accept = 0. |
| 390 | |
| 391 | Remote end wants to use ZMP, so they send WILL ZMP. |
| 392 | You support ZMP, so you set event->accept = 1 and enable |
| 393 | local ZMP support. |
| 394 | |
| 395 | You want to use MCCP2, so you send WILL COMPRESS2. |
| 396 | Remote end accepts and sends DO COMPRESS2. |
| 397 | |
| 398 | Note that in PROXY mode libtelnet will do no processing of its |
| 399 | own for you. |
| 400 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 401 | TELNET_EV_WONT: |
| 402 | TELNET_EV_DONT: |
Sean Middleditch | 5b5bc92 | 2009-03-15 23:02:10 -0400 | [diff] [blame] | 403 | The WONT and DONT events are sent when the remote end of the |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 404 | connection wishes to disable an option, when they are refusing to |
| 405 | a support an option that you have asked for, or in confirmation of |
| 406 | an option you have asked to be disabled. |
Sean Middleditch | 5b5bc92 | 2009-03-15 23:02:10 -0400 | [diff] [blame] | 407 | |
| 408 | Most commonly WONT and DONT events are sent as rejections of |
| 409 | features you requested by sending DO or WILL events. Receiving |
| 410 | these events means the TELNET option is not or will not be |
| 411 | supported by the remote end, so give up. |
| 412 | |
| 413 | Sometimes WONT or DONT will be sent for TELNET options that are |
| 414 | already enabled, but the remote end wishes to stop using. You |
| 415 | cannot decline. These events are demands that must be complied |
| 416 | with. libtelnet will always send the appropriate response back |
| 417 | without consulting your application. These events are sent to |
| 418 | allow your application to disable its own use of the features. |
| 419 | |
| 420 | In either case, the TELNET option under negotiation will be in |
| 421 | event->telopt field. |
| 422 | |
| 423 | Note that in PROXY mode libtelnet will do no processing of its |
| 424 | own for you. |
| 425 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 426 | TELNET_EV_SUBNEGOTIATION: |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 427 | Triggered whenever a TELNET sub-negotiation has been received. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 428 | Sub-negotiations include the NAWS option for communicating |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 429 | terminal size to a server, the NEW-ENVIRON and TTYPE options for |
| 430 | negotiating terminal features, and MUD-centric protocols such as |
| 431 | ZMP, MSSP, and MCCP2. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 432 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 433 | The event->telopt value is the option under sub-negotiation. The |
| 434 | remaining data (if any) is passed in event->buffer and |
| 435 | event->size. Note that most subnegotiation commands can include |
| 436 | embedded NUL bytes in the subnegotiation data, and the data |
| 437 | event->buffer is not NUL terminated, so always use the event->size |
| 438 | value! |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 439 | |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 440 | The meaning and necessary processing for subnegotiations are |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 441 | defined in various TELNET RFCs and other informal specifications. |
| 442 | A subnegotiation should never be sent unless the specific option |
| 443 | has been enabled through the use of the telnet negotiation |
| 444 | feature. |
Sean Middleditch | 8d50fe8 | 2009-03-22 22:35:17 -0400 | [diff] [blame] | 445 | |
| 446 | TTYPE/ENVIRON/NEW-ENVIRON/MSSP SUPPORT: |
| 447 | These telopts all use a similar format to their subnegotiation |
| 448 | requests. The data is arrnaged as a series of terms, with each |
| 449 | term beginning with a single byte type marker (a small integer in |
| 450 | the range of 0 to 3) followed by zero or more bytes until another |
| 451 | type marker or the end of the subnegotiation data. |
| 452 | |
| 453 | libtelnet parses these. The number of terms found is put in the |
| 454 | ev->argc field. The terms themselves are stored as |
| 455 | NUL-terminated strings in the ev->argv array. The type byte is |
| 456 | always the first byte of these strings, e.g. ev->argv[0][0]. Due |
| 457 | to the fact that 0 is a valid type marker, remember that |
| 458 | accessing the remainder of the term's data as a string must be |
| 459 | done as &ev->argv[term_index][1]. |
| 460 | |
| 461 | Note that libtelnet does not support the ESC byte for ENVIRON/ |
| 462 | NEW-ENVIRON. Data using escaped bytes will not be parsed |
| 463 | correctly. |
Sean Middleditch | b10946c | 2009-03-22 18:21:14 -0400 | [diff] [blame] | 464 | |
| 465 | ZMP SUPPORT: |
| 466 | The event->argc field is the number of ZMP parameters, including |
| 467 | the command name, that have been received. The event->argv field |
| 468 | is an array of strings, one for each ZMP parameter. The command |
| 469 | name will be in event->argv[0]. If the ZMP command could not be |
| 470 | parsed because it was malformed, event->argc will be 0 (zero) and |
| 471 | event->argv will be NULL. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 472 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 473 | TELNET_EV_COMPRESS |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 474 | The COMPRESS event notifies the app that COMPRESS2/MCCP2 |
| 475 | compression has begun or ended. Only servers can send compressed |
| 476 | data, and hence only clients will receive compressed data. |
Sean Middleditch | b9e4864 | 2009-03-12 23:33:27 -0400 | [diff] [blame] | 477 | |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 478 | The event->command value will be 1 if compression has started and |
| 479 | will be 0 if compression has ended. |
Sean Middleditch | 1699227 | 2009-03-15 19:42:03 -0400 | [diff] [blame] | 480 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 481 | TELNET_EV_WARNING |
| 482 | The WARNING event is sent whenever something has gone wrong inside |
| 483 | of libtelnet (possibly due to malformed data sent by the other |
| 484 | end) but which recovery is (likely) possible. It may be safe to |
| 485 | continue using the connection, but some data may have been lost or |
| 486 | incorrectly interpreted. |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 487 | |
| 488 | The event->buffer value will contain a NUL terminated string |
| 489 | explaining the error, and the event->size value containers the |
| 490 | length of the string. |
| 491 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 492 | TELNET_EV_ERROR |
Sean Middleditch | 1699227 | 2009-03-15 19:42:03 -0400 | [diff] [blame] | 493 | Similar to the WARNING event, the ERROR event is sent whenever |
| 494 | something has gone wrong. ERROR events are non-recoverable, |
| 495 | however, and the application should immediately close the |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 496 | connection. Whatever has happened is likely going only to result |
| 497 | in garbage from libtelnet. This is most likely to happen when a |
| 498 | COMPRESS2 stream fails, but other problems can occur. |
Sean Middleditch | 1699227 | 2009-03-15 19:42:03 -0400 | [diff] [blame] | 499 | |
| 500 | The event->buffer value will contain a NUL terminated string |
| 501 | explaining the error, and the event->size value containers the |
| 502 | length of the string. |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 503 | |
| 504 | III. INTEGRATING LIBTELNET WITH COMMON MUDS |
Sean Middleditch | b9e4864 | 2009-03-12 23:33:27 -0400 | [diff] [blame] | 505 | ===================================================================== |
| 506 | |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 507 | FIXME: fill in some notes about how to splice in libtelnet with |
| 508 | common Diku/Merc/Circle/etc. MUD codebases. |
Sean Middleditch | b9e4864 | 2009-03-12 23:33:27 -0400 | [diff] [blame] | 509 | |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 510 | IV. SAFETY AND CORRECTNESS CONSIDERATIONS |
Sean Middleditch | b9e4864 | 2009-03-12 23:33:27 -0400 | [diff] [blame] | 511 | ===================================================================== |
| 512 | |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 513 | Your existing application may make heavy use of its own output |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 514 | buffering and transmission commands, including hand-made routines for |
| 515 | sending TELNET commands and sub-negotiation requests. There are at |
| 516 | times subtle issues that need to be handled when communication over |
| 517 | the TELNET protocol, not least of which is the need to escape any |
| 518 | byte value 0xFF with a special TELNET command. |
Sean Middleditch | b9e4864 | 2009-03-12 23:33:27 -0400 | [diff] [blame] | 519 | |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 520 | For these reasons, it is very important that applications making use |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 521 | of libtelnet always make use of the libtelnet output functions for |
| 522 | all data being sent over the TELNET connection. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 523 | |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 524 | In particular, if you are writing a client, all user input must be |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 525 | passed through to telnet_send(). This also includes any input |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 526 | generated automatically by scripts, triggers, or macros. |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 527 | |
| 528 | For a server, any and all output -- including ANSI/VT100 escape |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 529 | codes, regular text, newlines, and so on -- must be passed through to |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 530 | telnet_send(). |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 531 | |
| 532 | Any TELNET commands that are to be sent must be given to one of the |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 533 | following: telnet_iac, telnet_negotiate, or telnet_subnegotiation(). |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 534 | |
| 535 | If you are attempting to enable COMPRESS2/MCCP2, you must use the |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 536 | telnet_begin_compress2() function. |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 537 | |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 538 | V. MCCP2 COMPRESSION |
Sean Middleditch | b9e4864 | 2009-03-12 23:33:27 -0400 | [diff] [blame] | 539 | ===================================================================== |
| 540 | |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 541 | The MCCP2 (COMPRESS2) TELNET extension allows for the compression of |
| 542 | all traffic sent from server to client. For more information: |
| 543 | |
| 544 | http://www.mudbytes.net/index.php?a=articles&s=mccp |
| 545 | |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 546 | In order for libtelnet to support MCCP2, zlib must be installed and |
| 547 | enabled when compiling libtelnet. Use -DHAVE_ZLIB to enable zlib |
| 548 | when compiling libtelnet.c and pass -lz to the linker to link in the |
| 549 | zlib shared library. |
| 550 | |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 551 | libtelnet transparently supports MCCP2. For a server to support |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 552 | MCCP2, the application must begin negotiation of the COMPRESS2 option |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 553 | using telnet_negotiate(), for example: |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 554 | |
Sean Middleditch | 4f0c37f | 2009-03-20 23:08:55 -0400 | [diff] [blame] | 555 | telnet_negotiate(&telnet, TELNET_WILL, |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 556 | TELNET_OPTION_COMPRESS2, user_data); |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 557 | |
Sean Middleditch | 5b5bc92 | 2009-03-15 23:02:10 -0400 | [diff] [blame] | 558 | If a favorable DO COMPRESS2 is sent back from the client then the |
| 559 | server application can begin compression at any time by calling |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 560 | telnet_begin_compress2(). |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 561 | |
Sean Middleditch | 637df7f | 2009-03-15 12:57:32 -0400 | [diff] [blame] | 562 | If a connection is in PROXY mode and COMPRESS2 support is enabled |
| 563 | then libtelnet will automatically detect the start of a COMPRESS2 |
| 564 | stream, in either the sending or receiving direction. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 565 | |
Sean Middleditch | 1887735 | 2009-03-22 16:57:44 -0400 | [diff] [blame] | 566 | VI. ZENITH MUD PROTOCOL (ZMP) SUPPORT |
| 567 | ===================================================================== |
| 568 | |
| 569 | The Zenith MUD Protocol allows applications to send messages across |
| 570 | the TELNET connection outside of the normal user input/output data |
| 571 | stream. libtelnet offers some limited support for receiving and |
| 572 | sending ZMP commands to make implementing a full ZMP stack easier. |
| 573 | For more information on ZMP: |
| 574 | |
| 575 | http://zmp.sourcemud.org/ |
| 576 | |
| 577 | For a server to enable ZMP, it must send the WILL ZMP negotitaion: |
| 578 | |
| 579 | telnet_negotiate(&telnet, TELNET_WILL, TELNET_TELOPT_ZMP); |
| 580 | |
| 581 | For a client to support ZMP it must include ZMP in the telopt table |
| 582 | passed to telnet_init(), with the him field set to TELNET_DO: |
| 583 | |
| 584 | { TELNET_TELOPT_ZMP, TELNET_WONT, TELNET_DO }, |
| 585 | |
| 586 | Note that while ZMP is a bi-directional protocol, it is only ever |
| 587 | enabled on the server end of the connection. This automatically |
| 588 | enables the client to send ZMP commands. The client must never |
| 589 | attempt to negotiate ZMP directly using telnet_negotiate(). |
| 590 | |
| 591 | Once ZMP is enabled, any ZMP commands received will automatically be |
Sean Middleditch | b10946c | 2009-03-22 18:21:14 -0400 | [diff] [blame] | 592 | sent to the event handler function with the TELNET_EV_SUBNEGOTIATION |
| 593 | event code. The command will automatically be parsed and the ZMP |
| 594 | parameters will be placed in the event->argv array and the number of |
| 595 | parameters will be placed in the event->argc field. |
| 596 | |
| 597 | NOTE: if an error occured while parsing the ZMP command because it |
| 598 | was malformed, the event->argc field will be equal to 0 and the |
| 599 | event->argv field will be NULL. You should always check for this |
| 600 | before attempting to access the parameter array. |
Sean Middleditch | 1887735 | 2009-03-22 16:57:44 -0400 | [diff] [blame] | 601 | |
| 602 | To send ZMP commands to the remote end, use either telnet_send_zmp() |
| 603 | or telnet_send_zmpv(). |
| 604 | |
| 605 | int telnet_send_zmp(telnet_t *telnet, size_t argv, |
| 606 | const char **argv); |
| 607 | Sends a ZMP command to the remote end. The argc parameter is the |
| 608 | number of ZMP parameters (including the command name!) to be sent. |
| 609 | The argv parameter is an array of strings containing the |
| 610 | parameters. The element in argv[0] is the command name itself. |
| 611 | The argv array must have at least as many elements as the value |
| 612 | argc. |
| 613 | |
| 614 | VII. TELNET PROXY UTILITY |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 615 | ===================================================================== |
| 616 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 617 | The telnet-proxy utility is a small application that serves both as a |
| 618 | testbed for libtelnet and as a powerful debugging tool for TELNET |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 619 | servers and clients. |
| 620 | |
| 621 | To use telnet-proxy, you must first compile it using: |
| 622 | |
| 623 | $ make |
| 624 | |
| 625 | If you do not have zlib installed and wish to disable MCCP2 support |
| 626 | then you must first edit the Makefile and remove the -DHAVE_ZLIB and |
| 627 | the -lz from the compile flags. |
| 628 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 629 | To run telnet-proxy, you simply give it the server's host name or IP |
| 630 | address, the server's port number, and the port number that |
Sean Middleditch | d88f183 | 2009-03-15 01:06:17 -0400 | [diff] [blame] | 631 | telnet-proxy should listen on. For example, to connect to the server |
| 632 | on mud.example.com port 7800 and to listen on port 5000, run: |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 633 | |
Sean Middleditch | d88f183 | 2009-03-15 01:06:17 -0400 | [diff] [blame] | 634 | $ ./telnet-proxy mud.example.com 7800 5000 |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 635 | |
| 636 | You can then connect to the host telnet-proxy is running on (e.g. |
Sean Middleditch | d88f183 | 2009-03-15 01:06:17 -0400 | [diff] [blame] | 637 | 127.0.0.1) on port 500 and you will automatically be proxied into |
| 638 | mud.example.com. |
Sean Middleditch | 892c5f1 | 2009-03-14 13:39:07 -0400 | [diff] [blame] | 639 | |
Sean Middleditch | f65f27d | 2009-03-19 02:32:04 -0400 | [diff] [blame] | 640 | telnet-proxy will display status information about the data passing |
| 641 | through both ends of the tunnel. telnet-proxy can only support a |
| 642 | single tunnel at a time. It will continue running until an error |
| 643 | occurs or a terminating signal is sent to the proxy process. |