unofficial-rtos-docs

Chapter 3 - Description of NetX Duo TFTP services

This chapter contains a description of all NetX Duo TFTP services (listed below) in alphabetic order. Unless otherwise specified, all services support IPv6 and IPv4 communications.

In the Return Values section in the following API descriptions, values in BOLD are not affected by the NX_DISABLE_ERROR_CHECKING define that is used to disable API error checking, while non-bold values are completely disabled.

Note: The IPv4 equivalents of all the services listed above are available in NetX Duo TFTP Client and Server e.g. nx_tftp_server_create and nx_tftp_client_file_open. Only the ‘Duo’ API descriptions, e.g. services beginning with nxd_, are provided in the following pages. Where an NXD_ADDRESS * input is specified, the IPv4 equivalent API calls for ULONG input. Otherwise there is no difference in using the API.

nxd_tftp_client_create

Create a TFTP Client instance

Prototype

UINT nxd_tftp_client_create(
    NX_TFTP_CLIENT *tftp_client_ptr,
    CHAR *tftp_client_name,
    NX_IP *ip_ptr,
    NX_PACKET_POOL *pool_ptr);

Description

This service creates a TFTP Client instance for the previously created IP instance.

Important: The application must make certain the supplied IP and packet pool are already created. In addition, UDP must be enabled for the IP instance prior to calling this service.

Input Parameters

Return Values

Allowed From

Initialization and Threads

Example

/* Create a TFTP Client instance. */
status =  nxd_tftp_client_create(&my_tftp_client, "My TFTP Client", 
													&my_ip, &pool_ptr);

/* If status is NX_SUCCESS a TFTP Client instance was successfully
   created. */

nxd_tftp_client_delete

Delete a TFTP Client instance

Prototype

UINT nxd_tftp_client_delete(NX_TFTP_CLIENT *tftp_client_ptr);

Description

This service deletes a previously created TFTP Client instance.

Input Parameters

Return Values

Allowed From

Threads

Example

/* Delete a TFTP Client instance. */
status =  nxd_tftp_client_delete(&my_tftp_client);

/* If status is NX_SUCCESS the TFTP Client instance was successfully
   deleted. */

nxd_tftp_client_error_info_get

Get client error information

Prototype

UINT nxd_tftp_client_error_info_get(
    NX_TFTP_CLIENT *tftp_client_ptr,
    UINT *error_code,
    CHAR **error_string);

Description

This service returns the last error code received and sets the pointer to the client’s internal error string. In error conditions, the user can view the last error sent by the server. A null error string indicates no error is present.

Input Parameters

Return Values

Allowed From

Threads

Example

/* Get error information for client. */
status =  nxd_tftp_client_error_info_get(&my_tftp_client, &error_code,
					&error_string_ptr);

/* If status is NX_SUCCESS the error code and error string are available. */

nxd_tftp_client_file_close

Close client file

Prototype

UINT nxd_tftp_client_file_close(
    NX_TFTP_CLIENT *tftp_client_ptr,
    UINT ip_type);

Description

This service closes the previously opened file by this TFTP Client instance. A TFTP Client instance is allowed to have only one file open at a time.

Input Parameters

Return Values

Allowed From

Threads

Example

/* Close the previously opened file associated with "my_client". */
status =  nxd_tftp_client_file_close(&my_tftp_client);

/* If status is NX_SUCCESS the TFTP file is closed. */

nx_tftp_client_file_open

Open TFTP client file

Prototype

UINT nx_tftp_client_file_open(
    NX_TFTP_CLIENT *tftp_client_ptr, 
    CHAR *file_name,
    NXD_ADDRESS *server_ip_address,
    UINT open_type,
    ULONG wait_option);

Description

This service attempts to open the specified file on the TFTP Server at the specified IP address. The file will be opened for either reading or writing.

Note: This is limited to IPv4 packets only, and is intended for supporting NetX TFTP applications. Developers are encouraged to port their applications to using equivalent “duo” service nxd_tftp_client_file_open.

Input Parameters

Return Values

Allowed From

Threads

Example

/* Define the TFTP server address. */
NXD_ADDRESS server_ip_address;

server_ip_address.nxd_ip_version = NX_IP_VERSION_V6;
server _ip_address.nxd_ip_address.v6[0] = 0x20010db8;
server _ip_address.nxd_ip_address.v6[1] = 0xf101;
server _ip_address.nxd_ip_address.v6[2] = 0;
server _ip_address.nxd_ip_address.v6[3] = 0x101;

/* Open file "test.txt" for reading on the TFTP Server. */
status =  nxd_tftp_client_file_open(&my_tftp_client, "test.txt",
 		& server_ip_address, NX_TFTP_OPEN_FOR_READ, 200);

/* If status is NX_SUCCESS the "test.txt" file is now open for reading. */

nxd_tftp_client_file_open

Open TFTP client file

Prototype

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

Description

This service attempts to open the specified file on the TFTP Server at the specified IPv6 address. The file will be opened for either reading or writing.

Input Parameters

Return Values

Allowed From

Threads

Example

/* Define the TFTP server address. */
NXD_ADDRESS server_ip_address;

server_ip_address.nxd_ip_version = NX_IP_VERSION_V6;
server _ip_address.nxd_ip_address.v6[0] = 0x20010db8;
server _ip_address.nxd_ip_address.v6[1] = 0xf101;
server _ip_address.nxd_ip_address.v6[2] = 0;
server _ip_address.nxd_ip_address.v6[3] = 0x101;

/* Open file "test.txt" for reading on the TFTP Server. */
status =  nxd_tftp_client_file_open(&my_tftp_client, "test.txt",
				& server_ip_address, NX_TFTP_OPEN_FOR_READ, 200);

/* If status is NX_SUCCESS the "test.txt" file is now open for reading. */

nxd_tftp_client_file_read

Read a block from client file

Prototype

UINT nxd_tftp_client_file_read(
    NX_TFTP_CLIENT *tftp_client_ptr,
    NX_PACKET **packet_ptr,
    ULONG wait_option,
    UINT ip_type);

Description

This service reads a 512-byte block from the previously opened TFTP Client file. A block containing fewer than 512 bytes signals the end of the file.

Input Parameters

Return Values

Allowed From

Threads

Example

/* Read a block from a previously opened file of "my_client". */
status =  nxd_tftp_client_file_read(&my_tftp_client, &return_packet_ptr, 200);

/* If status is NX_SUCCESS a block of the TFTP file is in the payload of
   "return_packet_ptr". */

nxd_tftp_client_file_write

Write a block to Client file

Prototype

UINT nxd_tftp_client_file_write(
    NX_TFTP_CLIENT *tftp_client_ptr,
    NX_PACKET *packet_ptr,
    ULONG wait_option, UINT ip_type);

Description

This service writes a 512-byte block to the previously opened TFTP Client file. Specifying a block containing fewer than 512 bytes signals the end of the file.

Input Parameters

Return Values

Allowed From

Threads

Example

/* Write a block to the previously opened file of "my_client". */
status =  nxd_tftp_client_file_write(&my_tftp_client, packet_ptr, 200);

/* If status is NX_SUCCESS the block in the payload of "packet_ptr" was 
   written to the TFTP file opened by "my_client". */

nxd_tftp_client_packet_allocate

Allocate packet for Client file write

Prototype

UINT nxd_tftp_client_packet_allocate(
    NX_PACKET_POOL *pool_ptr,
    NX_PACKET **packet_ptr,
    ULONG wait_option,
    UINT ip_type);

Description

This service allocates a UDP packet from the specified packet pool and makes room for the 4-byte TFTP header before the packet is returned to the caller. The caller can then build a buffer for writing to a client file.

Input Parameters

Return Values

Allowed From

Threads

Example

/* Allocate a packet for TFTP file write. */
status =  nxd_tftp_client_packet_allocate(&my_pool, &packet_ptr, 200);

/* If status is NX_SUCCESS "packet_ptr" contains the new packet. */

nxd_tftp_client_set_interface

Set physical interface for TFTP requests

Prototype

UINT nxd_tftp_client_set_interface(
    NX_TFTP_CLIENT *tftp_client_ptr,
    UINT if_index);

Description

This service uses the input interface index to set the physical interface for the TFTP Client to send and receive TFTP packets. The default value is zero, for the primary interface.

Note: NetX Duo must support multihome addressing (v5.6 or later) to use this service.

Input Parameters

Return Values

Allowed From

Threads

Example

/* Specify the primary interface for TFTP requests. */
status =  nxd_tftp_client_set_interface(&client, 0);

/* If status is NX_SUCCESS the primary interface will be use for TFTP communications. */

nxd_tftp_server_create

Create TFTP server

Prototype

UINT nxd_tftp_server_create(
    NX_TFTP_SERVER *tftp_server_ptr,
    CHAR *tftp_server_name,
    NX_IP *ip_ptr,
    FX_MEDIA *media_ptr, 
    VOID *stack_ptr,
    ULONG stack_size,
    NX_PACKET_POOL *pool_ptr);

Description

This service creates a TFTP Server that responds to TFTP Client requests on port 69. The Server must be started by a subsequent call to nxd_tftp_server_start.

Important: The application must make certain the supplied IP instance, packet pool, and FileX media instance are already created. In addition, UDP must be enabled for the IP instance prior to calling this service.

Input Parameters

Note: The supplied pool must have packet payloads at least 580 bytes in size.1

1 The data portion of a packet is exactly 512 bytes, but the packet payload size must be at least 572 bytes. The remaining bytes are used for the UDP, IPv6, and Ethernet headers and potential trailing bytes required by the driver for alignment.

Return Values

Allowed From

Initialization, Threads

Example

/* Create a TFTP Server called "my_server". */
status =  nxd_tftp_server_create(&my_server, "My TFTP Server", &server_ip, 
				&ram_disk, stack_ptr, 2048, pool_ptr);

/* If status is NX_SUCCESS the TFTP Server is created. */

nxd_tftp_server_delete

Delete TFTP Server

Prototype

UINT nxd_tftp_server_delete(NX_TFTP_SERVER *tftp_server_ptr);

Description

This service deletes a previously created TFTP Server.

Input Parameters

Return Values

Allowed From

Threads

Example

/* Delete the TFTP Server called "my_server". */
status =  nxd_tftp_server_delete(&my_server);

/* If status is NX_SUCCESS the TFTP Server is deleted. */

nxd_tftp_server_start

Start TFTP server

Prototype

UINT nxd_tftp_server_start(NX_TFTP_SERVER *tftp_server_ptr);

Description

This service starts the previously created TFTP Server.

Input Parameters

Return Values

Allowed From

Initialization, threads

Example

/* Start the TFTP Server called "my_server". */
status =  nxd_tftp_server_start(&my_server);

/* If status is NX_SUCCESS the TFTP Server is started. */

nxd_tftp_server_stop

Stop TFTP Server

Prototype

UINT nxd_tftp_server_stop(NX_TFTP_SERVER *tftp_server_ptr);

Description

This service stops the previously created TFTP Server.

Input Parameters

Return Values

Allowed From

Threads

Example

/* Stop the TFTP Server called "my_server". */
status =  nxd_tftp_server_stop(&my_server);

/* If status is NX_SUCCESS the TFTP Server is stopped. */
This site is open source. Improve this page.