1 /**************************************************************************/ 2 /* */ 3 /* Copyright (c) Microsoft Corporation. All rights reserved. */ 4 /* */ 5 /* This software is licensed under the Microsoft Software License */ 6 /* Terms for Microsoft Azure RTOS. Full text of the license can be */ 7 /* found in the LICENSE file at https://aka.ms/AzureRTOS_EULA */ 8 /* and in the root directory of this software. */ 9 /* */ 10 /**************************************************************************/ 11 12 13 /**************************************************************************/ 14 /**************************************************************************/ 15 /** */ 16 /** NetX Component */ 17 /** */ 18 /** TELNET Server Protocol (TELNET Server) */ 19 /** */ 20 /**************************************************************************/ 21 /**************************************************************************/ 22 23 24 /**************************************************************************/ 25 /* */ 26 /* APPLICATION INTERFACE DEFINITION RELEASE */ 27 /* */ 28 /* nxd_telnet_server.h PORTABLE C */ 29 /* 6.1.9 */ 30 /* AUTHOR */ 31 /* */ 32 /* Yuxin Zhou, Microsoft Corporation */ 33 /* */ 34 /* DESCRIPTION */ 35 /* */ 36 /* This file defines the NetX Duo TELNET Protocol (TELNET) component, */ 37 /* including all data types and external references. */ 38 /* It is assumed that nx_api.h and nx_port.h have already been */ 39 /* included. */ 40 /* */ 41 /* RELEASE HISTORY */ 42 /* */ 43 /* DATE NAME DESCRIPTION */ 44 /* */ 45 /* 05-19-2020 Yuxin Zhou Initial Version 6.0 */ 46 /* 09-30-2020 Yuxin Zhou Modified comment(s), */ 47 /* resulting in version 6.1 */ 48 /* 10-15-2021 Yuxin Zhou Modified comment(s), included */ 49 /* necessary header file, */ 50 /* resulting in version 6.1.9 */ 51 /* */ 52 /**************************************************************************/ 53 54 #ifndef NXD_TELNET_SERVER_H 55 #define NXD_TELNET_SERVER_H 56 57 /* Determine if a C++ compiler is being used. If so, ensure that standard 58 C is used to process the API information. */ 59 60 #ifdef __cplusplus 61 62 /* Yes, C++ compiler is present. Use standard C. */ 63 extern "C" { 64 65 #endif 66 67 #include "nx_api.h" 68 69 /* Define the Server TELNET ID. */ 70 71 #define NX_TELNET_SERVER_ID 0x54454C4EUL 72 73 /* Defined, option negotiation is disabled. 74 #define NX_TELNET_SERVER_OPTION_DISABLE 75 */ 76 77 78 #ifndef NX_TELNET_SERVER_OPTION_DISABLE 79 80 /* If NX_TELNET_SERVER_OPTION_DISABLE is not defined, and Telnet Server 81 needs a packet pool, this option lets the application create the packet 82 pool instead of the Telnet Server. 83 #define NX_TELNET_SERVER_USER_CREATE_PACKET_POOL 84 */ 85 86 #endif /* NX_TELNET_SERVER_OPTION_DISABLE */ 87 88 /* Define the maximum number of clients the TELNET Server can accommodate. */ 89 90 #ifndef NX_TELNET_MAX_CLIENTS 91 #define NX_TELNET_MAX_CLIENTS 4 92 #endif 93 94 95 /* Define TELNET TCP socket create options. */ 96 97 #ifndef NX_TELNET_TOS 98 #define NX_TELNET_TOS NX_IP_NORMAL 99 #endif 100 101 #ifndef NX_TELNET_FRAGMENT_OPTION 102 #define NX_TELNET_FRAGMENT_OPTION NX_DONT_FRAGMENT 103 #endif 104 105 #ifndef NX_TELNET_SERVER_WINDOW_SIZE 106 #define NX_TELNET_SERVER_WINDOW_SIZE 2048 107 #endif 108 109 #ifndef NX_TELNET_TIME_TO_LIVE 110 #define NX_TELNET_TIME_TO_LIVE 0x80 111 #endif 112 113 #ifndef NX_TELNET_SERVER_TIMEOUT 114 #define NX_TELNET_SERVER_TIMEOUT (10 * NX_IP_PERIODIC_RATE) 115 #endif 116 117 #ifndef NX_TELNET_SERVER_PRIORITY 118 #define NX_TELNET_SERVER_PRIORITY 16 119 #endif 120 121 #ifndef NX_TELNET_ACTIVITY_TIMEOUT 122 #define NX_TELNET_ACTIVITY_TIMEOUT 600 /* Seconds allowed with no activity */ 123 #endif 124 125 #ifndef NX_TELNET_TIMEOUT_PERIOD 126 #define NX_TELNET_TIMEOUT_PERIOD 60 /* Number of seconds to check */ 127 #endif 128 129 130 /* Define TELNET commands that are optionally included in the TELNET data. The application is responsible for 131 recognizing and responding to the commands in accordance with the specification. The TELNET option command 132 requires three bytes, as follows: 133 134 IAC, COMMAND, OPTION ID 135 136 */ 137 138 /* Define byte indicating TELNET command follows. */ 139 140 #define NX_TELNET_IAC 255 /* TELNET Command byte - two consecutive -> 255 data */ 141 142 /* Define TELNET Negotiation Commands - Immediately follows IAC. */ 143 144 #define NX_TELNET_WILL 251 /* TELNET WILL - Sender wants to enable the option */ 145 #define NX_TELNET_WONT 252 /* TELNET WONT - Sender wants to disable the option */ 146 #define NX_TELNET_DO 253 /* TELNET DO - Sender wants receiver to enable option */ 147 #define NX_TELNET_DONT 254 /* TELNET DONT - Sender wants receiver to disable option*/ 148 149 150 /* Define the Telnet Server packet payload. */ 151 152 #ifndef NX_TELNET_SERVER_PACKET_PAYLOAD 153 #define NX_TELNET_SERVER_PACKET_PAYLOAD 300 154 #endif 155 156 /* Define the size of the Telnet Server packet pool. This will allow room for about 157 5-6 packets of 300 byte payload. */ 158 159 #ifndef NX_TELNET_SERVER_PACKET_POOL_SIZE 160 #define NX_TELNET_SERVER_PACKET_POOL_SIZE 2048 161 #endif 162 163 164 #ifndef NX_TELNET_SERVER_OPTION_DISABLE 165 166 /* Define TELNET Option IDs. */ 167 #define NX_TELNET_ECHO 1 /* TELNET ECHO Option */ 168 #define NX_TELNET_SGA 3 /* TELNET SGA Option */ 169 #endif /* NX_TELNET_SERVER_OPTION_DISABLE */ 170 171 /* Define Server thread events. */ 172 173 #define NX_TELNET_SERVER_CONNECT 0x01 /* TELNET connection is present */ 174 #define NX_TELNET_SERVER_DISCONNECT 0x02 /* TELNET disconnection is present */ 175 #define NX_TELNET_SERVER_DATA 0x04 /* TELNET receive data is present */ 176 #define NX_TELNET_SERVER_ACTIVITY_TIMEOUT 0x08 /* TELNET activity timeout check */ 177 #define NX_TELNET_STOP_EVENT 0x10 /* TELNET stop service */ 178 #define NX_TELNET_ANY_EVENT 0xFF /* Any TELNET event */ 179 180 181 /* Define return code constants. */ 182 183 #define NX_TELNET_ERROR 0xF0 /* TELNET internal error */ 184 #define NX_TELNET_TIMEOUT 0xF1 /* TELNET timeout occurred */ 185 #define NX_TELNET_FAILED 0xF2 /* TELNET error */ 186 #define NX_TELNET_NOT_CONNECTED 0xF3 /* TELNET not connected error */ 187 #define NX_TELNET_NOT_DISCONNECTED 0xF4 /* TELNET not disconnected error */ 188 #define NX_TELNET_INVALID_PARAMETER 0xF5 /* Invalid non pointer input to Telnet function */ 189 #define NX_TELNET_NO_PACKET_POOL 0xF6 /* Telnet server packet pool not set */ 190 191 /* Define the TELNET Server TCP port numbers. */ 192 193 #ifndef NX_TELNET_SERVER_PORT 194 #define NX_TELNET_SERVER_PORT 23 /* Default Port for TELNET server */ 195 #endif 196 197 198 /* Define the per client request structure for the TELNET Server data structure. */ 199 200 typedef struct NX_TELNET_CLIENT_REQUEST_STRUCT 201 { 202 UINT nx_telnet_client_request_connection; /* Logical connection number */ 203 ULONG nx_telnet_client_request_activity_timeout; /* Timeout for client activity */ 204 ULONG nx_telnet_client_request_total_bytes; /* Total bytes read or written */ 205 NX_TCP_SOCKET nx_telnet_client_request_socket; /* Client request socket */ 206 #ifndef NX_TELNET_SERVER_OPTION_DISABLE 207 USHORT nx_telnet_client_agree_server_will_echo_success; /* True if server will echo negotiation success */ 208 USHORT nx_telnet_client_agree_server_will_SGA_success; /* True if server will SGA negotiation success */ 209 #endif /* NX_TELNET_SERVER_OPTION_DISABLE */ 210 211 } NX_TELNET_CLIENT_REQUEST; 212 213 214 /* Define the TELNET Server data structure. */ 215 216 typedef struct NX_TELNET_SERVER_STRUCT 217 { 218 ULONG nx_telnet_server_id; /* TELNET Server ID */ 219 CHAR *nx_telnet_server_name; /* Name of this TELNET server */ 220 NX_IP *nx_telnet_server_ip_ptr; /* Pointer to associated IP structure */ 221 ULONG nx_telnet_server_connection_requests; /* Number of connection requests */ 222 ULONG nx_telnet_server_disconnection_requests; /* Number of disconnection requests */ 223 ULONG nx_telnet_server_total_bytes_sent; /* Number of total bytes sent */ 224 ULONG nx_telnet_server_total_bytes_received; /* Number of total bytes received */ 225 ULONG nx_telnet_server_relisten_errors; /* Number of relisten errors */ 226 ULONG nx_telnet_server_activity_timeouts; /* Number of activity timeouts */ 227 ULONG nx_telnet_server_open_connections; /* Number of currently open connections */ 228 229 #ifndef NX_TELNET_SERVER_OPTION_DISABLE 230 #ifndef NX_TELNET_SERVER_USER_CREATE_PACKET_POOL 231 UCHAR nx_telnet_server_pool_area[NX_TELNET_SERVER_PACKET_POOL_SIZE]; 232 NX_PACKET_POOL nx_telnet_server_packet_pool; /* Server TCP packet pool 233 for telnet option messages */ 234 #endif /* NX_TELNET_SERVER_USER_CREATE_PACKET_POOL */ 235 NX_PACKET_POOL *nx_telnet_server_packet_pool_ptr; /* Pointer to packet pool */ 236 #endif /* NX_TELNET_SERVER_OPTION_DISABLE */ 237 NX_TELNET_CLIENT_REQUEST /* TELNET client request array */ 238 nx_telnet_server_client_list[NX_TELNET_MAX_CLIENTS]; 239 TX_EVENT_FLAGS_GROUP 240 nx_telnet_server_event_flags; /* TELNET server thread events */ 241 TX_TIMER nx_telnet_server_timer; /* TELNET server activity timeout timer */ 242 TX_THREAD nx_telnet_server_thread; /* TELNET server thread */ 243 void (*nx_telnet_new_connection)(struct NX_TELNET_SERVER_STRUCT *telnet_server_ptr, UINT logical_connection); 244 void (*nx_telnet_receive_data)(struct NX_TELNET_SERVER_STRUCT *telnet_server_ptr, UINT logical_connection, NX_PACKET *packet_ptr); 245 void (*nx_telnet_connection_end)(struct NX_TELNET_SERVER_STRUCT *telnet_server_ptr, UINT logical_connection); 246 void (*nx_telnet_set_echo)(struct NX_TELNET_SERVER_STRUCT *telnet_server_ptr, UINT logical_connection, UINT echo_flag); 247 } NX_TELNET_SERVER; 248 249 #ifndef NX_TELNET_SOURCE_CODE 250 251 /* Application caller is present, perform API mapping. */ 252 253 /* Determine if error checking is desired. If so, map API functions 254 to the appropriate error checking front-ends. Otherwise, map API 255 functions to the core functions that actually perform the work. 256 Note: error checking is enabled by default. */ 257 258 #ifdef NX_DISABLE_ERROR_CHECKING 259 260 /* Services without error checking. */ 261 262 #define nx_telnet_server_create _nx_telnet_server_create 263 #define nx_telnet_server_delete _nx_telnet_server_delete 264 #define nx_telnet_server_disconnect _nx_telnet_server_disconnect 265 #define nx_telnet_server_packet_send _nx_telnet_server_packet_send 266 #ifdef NX_TELNET_SERVER_USER_CREATE_PACKET_POOL 267 #define nx_telnet_server_packet_pool_set _nx_telnet_server_packet_pool_set 268 #endif /* NX_TELNET_SERVER_USER_CREATE_PACKET_POOL */ 269 #define nx_telnet_server_start _nx_telnet_server_start 270 #define nx_telnet_server_stop _nx_telnet_server_stop 271 #define nx_telnet_server_get_open_connection_count _nx_telnet_server_get_open_connection_count 272 273 #else 274 275 /* Services with error checking. */ 276 277 #define nx_telnet_server_create _nxe_telnet_server_create 278 #define nx_telnet_server_delete _nxe_telnet_server_delete 279 #define nx_telnet_server_disconnect _nxe_telnet_server_disconnect 280 #define nx_telnet_server_packet_send _nxe_telnet_server_packet_send 281 #ifdef NX_TELNET_SERVER_USER_CREATE_PACKET_POOL 282 #define nx_telnet_server_packet_pool_set _nxe_telnet_server_packet_pool_set 283 #endif /* NX_TELNET_SERVER_USER_CREATE_PACKET_POOL */ 284 #define nx_telnet_server_start _nxe_telnet_server_start 285 #define nx_telnet_server_stop _nxe_telnet_server_stop 286 #define nx_telnet_server_get_open_connection_count _nxe_telnet_server_get_open_connection_count 287 288 #endif 289 290 /* Define the prototypes accessible to the application software. */ 291 292 UINT nx_telnet_server_create(NX_TELNET_SERVER *server_ptr, CHAR *server_name, NX_IP *ip_ptr, VOID *stack_ptr, ULONG stack_size, 293 void (*new_connection)(struct NX_TELNET_SERVER_STRUCT *telnet_server_ptr, UINT logical_connection), 294 void (*receive_data)(struct NX_TELNET_SERVER_STRUCT *telnet_server_ptr, UINT logical_connection, NX_PACKET *packet_ptr), 295 void (*connection_end)(struct NX_TELNET_SERVER_STRUCT *telnet_server_ptr, UINT logical_connection)); 296 UINT nx_telnet_server_delete(NX_TELNET_SERVER *server_ptr); 297 UINT nx_telnet_server_disconnect(NX_TELNET_SERVER *server_ptr, UINT logical_connection); 298 UINT nx_telnet_server_packet_send(NX_TELNET_SERVER *server_ptr, UINT logical_connection, NX_PACKET *packet_ptr, ULONG wait_option); 299 #ifdef NX_TELNET_SERVER_USER_CREATE_PACKET_POOL 300 UINT nx_telnet_server_packet_pool_set(NX_TELNET_SERVER *server_ptr, NX_PACKET_POOL *pool_ptr); 301 #endif /* NX_TELNET_SERVER_USER_CREATE_PACKET_POOL */ 302 UINT nx_telnet_server_start(NX_TELNET_SERVER *server_ptr); 303 UINT nx_telnet_server_stop(NX_TELNET_SERVER *server_ptr); 304 UINT nx_telnet_server_get_open_connection_count(NX_TELNET_SERVER *server_ptr, UINT *current_connections); 305 306 307 #else 308 309 /* TELNET source code is being compiled, do not perform any API mapping. */ 310 311 UINT _nxe_telnet_server_create(NX_TELNET_SERVER *server_ptr, CHAR *server_name, NX_IP *ip_ptr, VOID *stack_ptr, ULONG stack_size, 312 void (*new_connection)(struct NX_TELNET_SERVER_STRUCT *telnet_server_ptr, UINT logical_connection), 313 void (*receive_data)(struct NX_TELNET_SERVER_STRUCT *telnet_server_ptr, UINT logical_connection, NX_PACKET *packet_ptr), 314 void (*connection_end)(struct NX_TELNET_SERVER_STRUCT *telnet_server_ptr, UINT logical_connection)); 315 UINT _nx_telnet_server_create(NX_TELNET_SERVER *server_ptr, CHAR *server_name, NX_IP *ip_ptr, VOID *stack_ptr, ULONG stack_size, 316 void (*new_connection)(struct NX_TELNET_SERVER_STRUCT *telnet_server_ptr, UINT logical_connection), 317 void (*receive_data)(struct NX_TELNET_SERVER_STRUCT *telnet_server_ptr, UINT logical_connection, NX_PACKET *packet_ptr), 318 void (*connection_end)(struct NX_TELNET_SERVER_STRUCT *telnet_server_ptr, UINT logical_connection)); 319 UINT _nxe_telnet_server_delete(NX_TELNET_SERVER *server_ptr); 320 UINT _nx_telnet_server_delete(NX_TELNET_SERVER *server_ptr); 321 UINT _nxe_telnet_server_disconnect(NX_TELNET_SERVER *server_ptr, UINT logical_connection); 322 UINT _nx_telnet_server_disconnect(NX_TELNET_SERVER *server_ptr, UINT logical_connection); 323 UINT _nxe_telnet_server_packet_send(NX_TELNET_SERVER *server_ptr, UINT logical_connection, NX_PACKET *packet_ptr, ULONG wait_option); 324 UINT _nx_telnet_server_packet_send(NX_TELNET_SERVER *server_ptr, UINT logical_connection, NX_PACKET *packet_ptr, ULONG wait_option); 325 #ifdef NX_TELNET_SERVER_USER_CREATE_PACKET_POOL 326 UINT _nxe_telnet_server_packet_pool_set(NX_TELNET_SERVER *server_ptr, NX_PACKET_POOL *pool_ptr); 327 UINT _nx_telnet_server_packet_pool_set(NX_TELNET_SERVER *server_ptr, NX_PACKET_POOL *pool_ptr); 328 #endif /* NX_TELNET_SERVER_USER_CREATE_PACKET_POOL */ 329 UINT _nxe_telnet_server_start(NX_TELNET_SERVER *server_ptr); 330 UINT _nx_telnet_server_start(NX_TELNET_SERVER *server_ptr); 331 UINT _nxe_telnet_server_stop(NX_TELNET_SERVER *server_ptr); 332 UINT _nx_telnet_server_stop(NX_TELNET_SERVER *server_ptr); 333 UINT _nxe_telnet_server_get_open_connection_count(NX_TELNET_SERVER *server_ptr, UINT *current_connections); 334 UINT _nx_telnet_server_get_open_connection_count(NX_TELNET_SERVER *server_ptr, UINT *current_connections); 335 336 /* Define internal TELNET functions. */ 337 338 VOID _nx_telnet_server_thread_entry(ULONG telnet_server); 339 VOID _nx_telnet_server_connect_process(NX_TELNET_SERVER *server_ptr); 340 VOID _nx_telnet_server_connection_present(NX_TCP_SOCKET *socket_ptr, UINT port); 341 VOID _nx_telnet_server_disconnect_present(NX_TCP_SOCKET *socket_ptr); 342 VOID _nx_telnet_server_disconnect_process(NX_TELNET_SERVER *server_ptr); 343 VOID _nx_telnet_server_data_present(NX_TCP_SOCKET *socket_ptr); 344 VOID _nx_telnet_server_data_process(NX_TELNET_SERVER *server_ptr); 345 VOID _nx_telnet_server_timeout(ULONG telnet_server_address); 346 VOID _nx_telnet_server_timeout_processing(NX_TELNET_SERVER *server_ptr); 347 348 #ifndef NX_TELNET_SERVER_OPTION_DISABLE 349 UINT _nx_telnet_server_send_option_requests(NX_TELNET_SERVER *server_ptr, NX_TELNET_CLIENT_REQUEST *client_req_ptr); 350 VOID _nx_telnet_server_process_option(NX_TELNET_SERVER *server_ptr, NX_PACKET *packet_ptr, UINT *offset, NX_TELNET_CLIENT_REQUEST *client_request_ptr); 351 VOID _nx_telnet_server_create_option_packet(UCHAR option_message_type, UCHAR option_id, UCHAR *stream); 352 #endif /* NX_TELNET_SERVER_OPTION_DISABLE */ 353 #endif 354 355 /* Determine if a C++ compiler is being used. If so, complete the standard 356 C conditional started above. */ 357 #ifdef __cplusplus 358 } 359 #endif 360 361 #endif /* NXD_TELNET_SERVER_H */ 362
