1 /*************************************************************************** 2 * Copyright (c) 2024 Microsoft Corporation 3 * 4 * This program and the accompanying materials are made available under the 5 * terms of the MIT License which is available at 6 * https://opensource.org/licenses/MIT. 7 * 8 * SPDX-License-Identifier: MIT 9 **************************************************************************/ 10 11 12 /**************************************************************************/ 13 /**************************************************************************/ 14 /** */ 15 /** NetX Component */ 16 /** */ 17 /** Trivial File Transfer Protocol (TFTP) Client */ 18 /** */ 19 /** */ 20 /**************************************************************************/ 21 /**************************************************************************/ 22 23 24 /**************************************************************************/ 25 /* */ 26 /* APPLICATION INTERFACE DEFINITION RELEASE */ 27 /* */ 28 /* nxd_tftp_client.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 Trivial File Transfer Protocol (TFTP) */ 37 /* Client component, including all data types and external references */ 38 /* It is assumed that nx_api.h and nx_port.h have already been */ 39 /* included, along with fx_api.h and fx_port.h. */ 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_TFTP_CLIENT_H 55 #define NXD_TFTP_CLIENT_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 NetX TFTP CLIENT ID. */ 70 71 #define NXD_TFTP_CLIENT_ID 0x54465460UL 72 73 74 /* Define TFTP maximum error string. */ 75 76 #ifndef NX_TFTP_ERROR_STRING_MAX 77 #define NX_TFTP_ERROR_STRING_MAX 64 /* Maximum error sting size */ 78 #endif 79 80 /* Define TFTP UDP socket create options. */ 81 82 #ifndef NX_TFTP_TYPE_OF_SERVICE 83 #define NX_TFTP_TYPE_OF_SERVICE NX_IP_NORMAL 84 #endif 85 86 #ifndef NX_TFTP_FRAGMENT_OPTION 87 #define NX_TFTP_FRAGMENT_OPTION NX_DONT_FRAGMENT 88 #endif 89 90 #ifndef NX_TFTP_TIME_TO_LIVE 91 #define NX_TFTP_TIME_TO_LIVE 0x80 92 #endif 93 94 95 /* If the host application wishes to specify a source port, define it here. The default is to let 96 NetX choose the TFTP Client source port. */ 97 #ifndef NX_TFTP_SOURCE_PORT 98 #define NX_TFTP_SOURCE_PORT NX_ANY_PORT 99 #endif 100 101 #define NX_TFTP_QUEUE_DEPTH 5 102 103 #define NX_TFTP_FILE_TRANSFER_MAX 512 /* 512 byte maximum file transfer */ 104 105 106 /* Define open types. */ 107 108 #define NX_TFTP_OPEN_FOR_READ 0x01 /* TFTP open for reading */ 109 #define NX_TFTP_OPEN_FOR_WRITE 0x02 /* TFTP open for writing */ 110 111 112 /* Define TFTP message codes. */ 113 114 #define NX_TFTP_CODE_READ 0x01 /* TFTP read file request */ 115 #define NX_TFTP_CODE_WRITE 0x02 /* TFTP write file request */ 116 #define NX_TFTP_CODE_DATA 0x03 /* TFTP data packet */ 117 #define NX_TFTP_CODE_ACK 0x04 /* TFTP command/data acknowledgement */ 118 #define NX_TFTP_CODE_ERROR 0x05 /* TFTP error message */ 119 120 121 /* Define TFTP error code constants. */ 122 123 #define NX_TFTP_ERROR_NOT_DEFINED 0x00 /* TFTP not defined error code, see error string */ 124 #define NX_TFTP_ERROR_FILE_NOT_FOUND 0x01 /* TFTP file not found error code */ 125 #define NX_TFTP_ERROR_ACCESS_VIOLATION 0x02 /* TFTP file access violation error code */ 126 #define NX_TFTP_ERROR_DISK_FULL 0x03 /* TFTP disk full error code */ 127 #define NX_TFTP_ERROR_ILLEGAL_OPERATION 0x04 /* TFTP illegal operation error code */ 128 #define NX_TFTP_CODE_ERROR 0x05 /* TFTP client request received error code from server */ 129 #define NX_TFTP_ERROR_FILE_EXISTS 0x06 /* TFTP file already exists error code */ 130 #define NX_TFTP_ERROR_NO_SUCH_USER 0x07 /* TFTP no such user error code */ 131 #define NX_TFTP_INVALID_SERVER_ADDRESS 0x08 /* Invalid TFTP server IP extracted from received packet*/ 132 #define NX_TFTP_NO_ACK_RECEIVED 0x09 /* Did not receive TFTP server ACK response */ 133 #define NX_TFTP_INVALID_BLOCK_NUMBER 0x0A /* Invalid block number received from Server response */ 134 #define NX_TFTP_INVALID_INTERFACE 0x0B /* Invalid interface for TFTP Client */ 135 /* (or multihome not supported) */ 136 #define NX_TFTP_INVALID_IP_VERSION 0x0C /* Invalid or unsupported IP version specified */ 137 138 139 /* Define offsets into the TFTP message buffer. */ 140 141 #define NX_TFTP_CODE_OFFSET 0 /* Offset to TFTP code in buffer */ 142 #define NX_TFTP_FILENAME_OFFSET 2 /* Offset to TFTP filename in message */ 143 #define NX_TFTP_BLOCK_NUMBER_OFFSET 2 /* Offset to TFTP block number in buffer */ 144 #define NX_TFTP_DATA_OFFSET 4 /* Offset to TFTP data in buffer */ 145 #define NX_TFTP_ERROR_CODE_OFFSET 2 /* Offset to TFTP error code */ 146 #define NX_TFTP_ERROR_STRING_OFFSET 4 /* Offset to TFPT error string */ 147 148 149 /* Define return code constants. */ 150 151 #define NX_TFTP_ERROR 0xC0 /* TFTP internal error */ 152 #define NX_TFTP_TIMEOUT 0xC1 /* TFTP timeout occurred */ 153 #define NX_TFTP_FAILED 0xC2 /* TFTP error */ 154 #define NX_TFTP_NOT_OPEN 0xC3 /* TFTP not opened error */ 155 #define NX_TFTP_NOT_CLOSED 0xC4 /* TFTP not closed error */ 156 #define NX_TFTP_END_OF_FILE 0xC5 /* TFTP end of file error */ 157 #define NX_TFTP_POOL_ERROR 0xC6 /* TFTP packet pool size error - less than 560 bytes */ 158 159 160 /* Define TFTP connection states. */ 161 162 #define NX_TFTP_STATE_NOT_OPEN 0 /* TFTP connection not open */ 163 #define NX_TFTP_STATE_OPEN 1 /* TFTP connection open */ 164 #define NX_TFTP_STATE_WRITE_OPEN 2 /* TFTP connection open for writing */ 165 #define NX_TFTP_STATE_END_OF_FILE 3 /* TFTP connection at end of file */ 166 #define NX_TFTP_STATE_ERROR 4 /* TFTP error condition */ 167 #define NX_TFTP_STATE_FINISHED 5 /* TFTP finished writing condition */ 168 169 170 /* Define the TFTP Server UDP port number */ 171 172 #define NX_TFTP_SERVER_PORT 69 /* Port for TFTP server */ 173 174 175 /* Define the basic TFTP Client data structure. */ 176 177 typedef struct NX_TFTP_CLIENT_STRUCT 178 { 179 ULONG nx_tftp_client_id; /* TFTP Client ID */ 180 CHAR *nx_tftp_client_name; /* Name of this TFTP client */ 181 UINT nx_tftp_client_interface_index; /* Index specifying network interface */ 182 NX_IP *nx_tftp_client_ip_ptr; /* Pointer to associated IP structure */ 183 NX_PACKET_POOL *nx_tftp_client_packet_pool_ptr; /* Pointer to TFTP client packet pool */ 184 NXD_ADDRESS nx_tftp_client_server_ip; /* Server's IP address */ 185 UINT nx_tftp_client_server_port; /* Server's port number (69 originally) */ 186 UINT nx_tftp_client_state; /* State of TFTP client */ 187 USHORT nx_tftp_client_block_number; /* Block number in file transfer */ 188 USHORT nx_tftp_client_reserved; /* Reserved for future use */ 189 UINT nx_tftp_client_error_code; /* Error code received */ 190 CHAR nx_tftp_client_error_string[NX_TFTP_ERROR_STRING_MAX + 1]; 191 NX_UDP_SOCKET nx_tftp_client_socket; /* TFTP Socket */ 192 193 } NX_TFTP_CLIENT; 194 195 196 197 #ifndef NX_TFTP_SOURCE_CODE 198 199 /* Application caller is present, perform API mapping. */ 200 201 /* Determine if error checking is desired. If so, map API functions 202 to the appropriate error checking front-ends. Otherwise, map API 203 functions to the core functions that actually perform the work. 204 Note: error checking is enabled by default. */ 205 206 #ifdef NX_DISABLE_ERROR_CHECKING 207 208 /******************* Services without error checking. ***********************/ 209 210 /* NetX (IPv4 supported only) services */ 211 #define nx_tftp_client_file_open _nx_tftp_client_file_open 212 213 /* For NetX applications, map the NetX TFTP service to the NetX Duo TFTP service. */ 214 #define nx_tftp_client_create(a,b,c,d) _nxd_tftp_client_create(a,b,c,d,NX_IP_VERSION_V4) 215 #define nx_tftp_client_packet_allocate(a,b,c) _nxd_tftp_client_packet_allocate(a,b,c, NX_IP_VERSION_V4) 216 #define nx_tftp_client_delete _nxd_tftp_client_delete 217 #define nx_tftp_client_error_info_get _nxd_tftp_client_error_info_get 218 #define nx_tftp_client_file_close(a) _nxd_tftp_client_file_close(a, NX_IP_VERSION_V4) 219 #define nx_tftp_client_file_read(a,b,c) _nxd_tftp_client_file_read(a,b,c,NX_IP_VERSION_V4) 220 #define nx_tftp_client_file_write(a,b,c) _nxd_tftp_client_file_write(a,b,c,NX_IP_VERSION_V4) 221 #define nx_tftp_client_set_interface _nxd_tftp_client_set_interface 222 223 /* NetX Duo TFTP (IPv4 and IPv6 supported) services. */ 224 #define nxd_tftp_client_create _nxd_tftp_client_create 225 #define nxd_tftp_client_delete _nxd_tftp_client_delete 226 #define nxd_tftp_client_file_open _nxd_tftp_client_file_open 227 #define nxd_tftp_client_error_info_get _nxd_tftp_client_error_info_get 228 #define nxd_tftp_client_file_close _nxd_tftp_client_file_close 229 #define nxd_tftp_client_file_read _nxd_tftp_client_file_read 230 #define nxd_tftp_client_file_write _nxd_tftp_client_file_write 231 #define nxd_tftp_client_packet_allocate _nxd_tftp_client_packet_allocate 232 #define nxd_tftp_client_set_interface _nxd_tftp_client_set_interface 233 234 #else 235 236 /*************** Services with error checking. ******************/ 237 238 /* NetX (IPv4 supported only) services */ 239 #define nx_tftp_client_file_open _nxe_tftp_client_file_open 240 241 /* For NetX TFTP applications, map the NetX TFTP service to the equivalent NetX Duo TFTP service. */ 242 #define nx_tftp_client_create(a,b,c,d) _nxde_tftp_client_create(a,b,c,d,NX_IP_VERSION_V4) 243 #define nx_tftp_client_packet_allocate(a,b,c) _nxde_tftp_client_packet_allocate(a,b,c,NX_IP_VERSION_V4) 244 #define nx_tftp_client_delete _nxde_tftp_client_delete 245 #define nx_tftp_client_error_info_get _nxde_tftp_client_error_info_get 246 #define nx_tftp_client_file_close(a) _nxde_tftp_client_file_close(a, NX_IP_VERSION_V4) 247 #define nx_tftp_client_file_read(a,b,c) _nxde_tftp_client_file_read(a,b,c,NX_IP_VERSION_V4) 248 #define nx_tftp_client_file_write(a,b,c) _nxde_tftp_client_file_write(a,b,c,NX_IP_VERSION_V4) 249 #define nx_tftp_client_set_interface _nxde_tftp_client_set_interface 250 251 /* NetX Duo (IPv4 and IPv6 supported) services. */ 252 #define nxd_tftp_client_create _nxde_tftp_client_create 253 #define nxd_tftp_client_delete _nxde_tftp_client_delete 254 #define nxd_tftp_client_file_open _nxde_tftp_client_file_open 255 #define nxd_tftp_client_error_info_get _nxde_tftp_client_error_info_get 256 #define nxd_tftp_client_file_close _nxde_tftp_client_file_close 257 #define nxd_tftp_client_file_read _nxde_tftp_client_file_read 258 #define nxd_tftp_client_file_write _nxde_tftp_client_file_write 259 #define nxd_tftp_client_packet_allocate _nxde_tftp_client_packet_allocate 260 #define nxd_tftp_client_set_interface _nxde_tftp_client_set_interface 261 262 263 #endif /* NX_DISABLE_ERROR_CHECKING */ 264 265 /* Define the prototypes accessible to the application software. */ 266 267 UINT nx_tftp_client_file_open(NX_TFTP_CLIENT *tftp_client_ptr, CHAR *file_name, ULONG server_ip_address, UINT open_type, ULONG wait_option); 268 269 UINT nxd_tftp_client_create(NX_TFTP_CLIENT *tftp_client_ptr, CHAR *tftp_client_name, NX_IP *ip_ptr, NX_PACKET_POOL *pool_ptr, UINT ip_type); 270 UINT nxd_tftp_client_delete(NX_TFTP_CLIENT *tftp_client_ptr); 271 UINT nxd_tftp_client_error_info_get(NX_TFTP_CLIENT *tftp_client_ptr, UINT *error_code, CHAR **error_string); 272 UINT nxd_tftp_client_file_close(NX_TFTP_CLIENT *tftp_client_ptr, UINT ip_type); 273 UINT nxd_tftp_client_file_open(NX_TFTP_CLIENT *tftp_client_ptr, CHAR *file_name, NXD_ADDRESS *server_ip_address, UINT open_type, ULONG wait_option, UINT ip_type); 274 UINT nxd_tftp_client_file_read(NX_TFTP_CLIENT *tftp_client_ptr, NX_PACKET **packet_ptr, ULONG wait_option, UINT ip_type); 275 UINT nxd_tftp_client_file_write(NX_TFTP_CLIENT *tftp_client_ptr, NX_PACKET *packet_ptr, ULONG wait_option, UINT ip_type); 276 UINT nxd_tftp_client_packet_allocate(NX_PACKET_POOL *pool_ptr, NX_PACKET **packet_ptr, ULONG wait_option, UINT ip_type); 277 UINT nxd_tftp_client_set_interface(NX_TFTP_CLIENT *tftpv6_client_ptr, UINT if_index); 278 279 #else 280 281 /* TFTP source code is being compiled, do not perform any API mapping. */ 282 283 UINT _nxe_tftp_client_file_open(NX_TFTP_CLIENT *tftp_client_ptr, CHAR *file_name, ULONG server_ip_address, UINT open_type, ULONG wait_option); 284 UINT _nx_tftp_client_file_open(NX_TFTP_CLIENT *tftp_client_ptr, CHAR *file_name, ULONG server_ip_address, UINT open_type, ULONG wait_option); 285 286 UINT _nxde_tftp_client_create(NX_TFTP_CLIENT *tftp_client_ptr, CHAR *tftp_client_name, NX_IP *ip_ptr, NX_PACKET_POOL *pool_ptr, UINT ip_type); 287 UINT _nxd_tftp_client_create(NX_TFTP_CLIENT *tftp_client_ptr, CHAR *tftp_client_name, NX_IP *ip_ptr, NX_PACKET_POOL *pool_ptr, UINT ip_type); 288 UINT _nxde_tftp_client_delete(NX_TFTP_CLIENT *tftp_client_ptr); 289 UINT _nxd_tftp_client_delete(NX_TFTP_CLIENT *tftp_client_ptr); 290 UINT _nxde_tftp_client_error_info_get(NX_TFTP_CLIENT *tftp_client_ptr, UINT *error_code, CHAR **error_string); 291 UINT _nxd_tftp_client_error_info_get(NX_TFTP_CLIENT *tftp_client_ptr, UINT *error_code, CHAR **error_string); 292 UINT _nxde_tftp_client_file_close(NX_TFTP_CLIENT *tftp_client_ptr, UINT ip_type); 293 UINT _nxd_tftp_client_file_close(NX_TFTP_CLIENT *tftp_client_ptr, UINT ip_type); 294 UINT _nxde_tftp_client_file_open(NX_TFTP_CLIENT *tftp_client_ptr, CHAR *file_name, NXD_ADDRESS *server_ip_address, UINT open_type, ULONG wait_option, UINT ip_type); 295 UINT _nxd_tftp_client_file_open(NX_TFTP_CLIENT *tftp_client_ptr, CHAR *file_name, NXD_ADDRESS *server_ip_address, UINT open_type, ULONG wait_option, UINT ip_type); 296 UINT _nxde_tftp_client_file_read(NX_TFTP_CLIENT *tftp_client_ptr, NX_PACKET **packet_ptr, ULONG wait_option, UINT ip_type); 297 UINT _nxd_tftp_client_file_read(NX_TFTP_CLIENT *tftp_client_ptr, NX_PACKET **packet_ptr, ULONG wait_option, UINT ip_type); 298 UINT _nxde_tftp_client_file_write(NX_TFTP_CLIENT *tftp_client_ptr, NX_PACKET *packet_ptr, ULONG wait_option, UINT ip_type); 299 UINT _nxd_tftp_client_file_write(NX_TFTP_CLIENT *tftp_client_ptr, NX_PACKET *packet_ptr, ULONG wait_option, UINT ip_type); 300 UINT _nxde_tftp_client_packet_allocate(NX_PACKET_POOL *pool_ptr, NX_PACKET **packet_ptr, ULONG wait_option, UINT ip_type); 301 UINT _nxd_tftp_client_packet_allocate(NX_PACKET_POOL *pool_ptr, NX_PACKET **packet_ptr, ULONG wait_option, UINT ip_type); 302 UINT _nxde_tftp_client_set_interface(NX_TFTP_CLIENT *tftp_client_ptr, UINT if_index); 303 UINT _nxd_tftp_client_set_interface(NX_TFTP_CLIENT *tftp_client_ptr, UINT if_index); 304 305 306 307 #endif /* NX_TFTP_SOURCE_CODE */ 308 309 /* Internal functions. */ 310 UINT _nx_tftp_client_file_open_internal(NX_TFTP_CLIENT *tftp_client_ptr, CHAR *file_name, NXD_ADDRESS *server_ip_address, UINT open_type, ULONG wait_option, UINT ip_type); 311 312 313 /* Determine if a C++ compiler is being used. If so, complete the standard 314 C conditional started above. */ 315 #ifdef __cplusplus 316 } 317 #endif 318 319 #endif /* NXD_TFTP_CLIENT_H */ 320
