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