第 3 章 - Azure RTOS NetX Duo TFTP 服务的说明

本章按字母顺序介绍了所有 NetX Duo TFTP 服务(如下所列)。 除非另行指定,否则所有服务都支持 IPv6 和 IPv4 通信。

在以下 API 说明的“返回值”部分中,以粗体显示的值不受 NX_DISABLE_ERROR_CHECKING 定义(用于禁用 API 错误检查)影响,而不以粗体显示的值会被完全禁用。

注意

NetX Duo TFTP 客户端和服务器中提供了上面列出的所有服务的 IPv4 等效项,例如 nx_tftp_server_create 和 nx_tftp_client_file_open。 以下页面仅提供“Duo”API 说明,例如,以 nxd_ 开头的服务。 如果指定了 NXD_ADDRESS * 输入,IPv4 等效 API 即会需要 ULONG 输入。 否则,使用 API 就没有任何区别。

nxd_tftp_client_create

创建 TFTP 客户端实例

原型

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

说明

此服务用于为之前创建的 IP 实例创建 TFTP 客户端实例。

重要

应用程序必须确保已创建所提供的 IP 和数据包池。 此外,还必须在调用此服务之前为 IP 实例启用 UDP。

输入参数

  • tftp_client_ptr:指向 TFTP 客户端控制块的指针。

  • tftp_client_name:此 TFTP 客户端实例的名称

  • ip_ptr:指向以前所创建 IP 实例的指针。

  • pool_ptr:指向数据包池 TFTP 客户端实例的指针。

返回值

  • NX_SUCCESS (0x00):成功创建 TFTP。

  • NX_TFTP_INVALID_IP_VERSION (0X0C):IP 版本无效或不受支持

  • NX_TFTP_INVALID_SERVER_ADDRESS (0x08):收到的服务器 IP 地址无效

  • NX_TFTP_NO_ACK_RECEIVED (0X09):未收到服务器确认

  • NX_PTR_ERROR (0x16):IP、池或 TFTP 指针无效。

  • NX_INVALID_PARAMETERS (0x4D):非指针输入无效

  • NX_CALLER_ERROR (0x11):此服务的调用方无效。

获准方式

初始化和线程

示例

/* 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

删除 TFTP 客户端实例

原型

UINT nxd_tftp_client_delete(NX_TFTP_CLIENT *tftp_client_ptr);

说明

此服务用于删除以前创建的 TFTP 客户端实例。

输入参数

  • tftp_client_ptr:指向之前创建的 TFTP 客户端实例的指针。

返回值

  • NX_SUCCESS (0x00):成功删除 TFTP 客户端。

  • NX_PTR_ERROR (0x16):指针输入无效。

  • NX_CALLER_ERROR (0x11):此服务的调用方无效。

获准方式

线程数

示例

/* 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

获取客户端错误信息

原型

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

说明

此服务用于返回收到的最后一个错误代码,并设置指向客户端内部错误字符串的指针。 在出现错误的情况下,用户可以查看服务器发送的最后一个错误。 空错误字符串表示不存在错误。

输入参数

  • tftp_client_ptr:指向之前创建的 TFTP 客户端实例的指针。

  • error_code:指向错误代码的目标区域的指针

  • error_string:指向错误字符串的目标的指针

返回值

  • NX_SUCCESS (0X00):成功获取 TFTP 错误信息。

  • NX_PTR_ERROR (0x16):TFTP 客户端指针无效。

  • NX_CALLER_ERROR (0x11):此服务的调用方无效。

获准方式

线程数

示例

/* 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

关闭客户端文件

原型

UINT nxd_tftp_client_file_close(
    NX_TFTP_CLIENT *tftp_client_ptr,
    UINT ip_type);

说明

此服务通过此 TFTP 客户端实例关闭之前打开的文件。 TFTP 客户端实例一次只能打开一个文件。

输入参数

  • tftp_client_ptr:指向之前创建的 TFTP 客户端实例的指针。

  • ip_type:表示要使用的 IP 协议。 有效选项为 IPv4 (4) 或 IPv6 (6)。

返回值

  • NX_SUCCESS (0x00):成功关闭 TFTP 文件。

  • NX_PTR_ERROR (0x16):指针输入无效。

  • NX_CALLER_ERROR (0x11):此服务的调用方无效。

  • NX_INVALID_PARAMETERS (0x4D):非指针输入无效。

允许来自

线程数

示例

/* 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

打开 TFTP 客户端文件

原型

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

说明

此服务用于尝试在 TFTP 服务器上打开指定 IP 地址的指定文件。 系统将打开此文件进行读取或写入。

注意

此服务仅限于 IPv4 数据包,可用于支持 NetX TFTP 应用程序。 建议开发人员移植其应用程序,以便使用等效的“Duo”服务 nxd_tftp_client_file_open。

输入参数

  • tftp_client_ptr:指向 TFTP 控制块的指针。

  • file_name:ASCII 文件名,以 NULL 结尾并带有相应的路径信息。

  • server_ip_address:服务器 TFTP 地址。

  • open_type:开放式请求的类型,可以是:

    • NX_TFTP_OPEN_FOR_READ (0x01)

    • NX_TFTP_OPEN_FOR_WRITE (0x02)

  • wait_option:定义此服务等待 TFTP 客户端打开文件的时长。 等待选项的定义如下:

    • timeout value:(0x00000001 至 0xFFFFFFFE)

    • TX_WAIT_FOREVER (0xFFFFFFFF)

    • 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起,直到 TFTP 服务器响应此请求。

    • 选择数值 (1-0xFFFFFFFE) 可指定等待 TFTP 服务器响应时调用线程保持挂起状态的最大计时器时钟周期数。

  • ip_type:表示要使用的 IP 协议。 有效选项为 IPv4 (4) 或 IPv6 (6)。

返回值

  • NX_SUCCESS (0x00):成功打开客户端文件

  • NX_TFTP_NOT_CLOSED (0XC3):客户端已打开文件

  • NX_INVALID_TFTP_SERVER_ADDRESS (0x08):收到的服务器地址无效

  • NX_TFTP_NO_ACK_RECEIVED (0X09):未收到服务器的确认

  • NX_TFTP_INVALID_SERVER_ADDRESS (0x08):收到的服务器 IP 地址无效

  • NX_TFTP_CODE_ERROR (0X05):已收到错误代码

  • NX_PTR_ERROR (0x16):指针输入无效。

  • NX_CALLER_ERROR (0x11):此服务的调用方无效

  • NX_IP_ADDRESS_ERROR (0x21):服务器 IP 地址无效

  • NX_OPTION_ERROR (0x0A):打开类型无效

允许来自

线程数

示例

/* 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

打开 TFTP 客户端文件

原型

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

说明

此服务用于尝试在 TFTP 服务器上打开指定 IPv6 地址的指定文件。 系统将打开此文件进行读取或写入。

输入参数

  • tftp_client_ptr:指向 TFTP 控制块的指针。

  • file_name:ASCII 文件名,以 NULL 结尾并带有相应的路径信息。

  • server_ip_address:服务器 TFTP 地址。

  • open_type:开放式请求的类型,可以是:

    • NX_TFTP_OPEN_FOR_READ (0x01)

    • NX_TFTP_OPEN_FOR_WRITE (0x02)

  • wait_option:定义此服务等待 TFTP 客户端打开文件的时长。 等待选项的定义如下:

    • timeout value:(0x00000001 至 0xFFFFFFFE)

    • TX_WAIT_FOREVER (0xFFFFFFFF)

    • 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起,直到 TFTP 服务器响应此请求。

    • 选择数值 (1-0xFFFFFFFE) 可指定等待 TFTP 服务器响应时调用线程保持挂起状态的最大计时器时钟周期数。

  • ip_type:表示要使用的 IP 协议。 有效选项为 IPv4 (4) 或 IPv6 (6)。

返回值

  • NX_SUCCESS (0x00):成功打开客户端文件

  • NX_TFTP_NOT_CLOSED (0XC3):客户端已打开文件

  • NX_INVALID_TFTP_SERVER_ADDRESS (0x08):收到的服务器地址无效

  • NX_TFTP_NO_ACK_RECEIVED (0X09):未收到服务器的确认

  • NX_TFTP_INVALID_IP_VERSION (0x0C):IP 版本无效

  • NX_TFTP_INVALID_SERVER_ADDRESS (0x08):收到的服务器 IP 地址无效

  • NX_TFTP_CODE_ERROR (0X05):已收到错误代码

  • NX_PTR_ERROR (0x16):指针输入无效。

  • NX_CALLER_ERROR (0x11):此服务的调用方无效

  • NX_IP_ADDRESS_ERROR (0x21):服务器 IP 地址无效

  • NX_OPTION_ERROR (0x0A):打开类型无效

  • NX_INVALID_PARAMETERS (0x4D):非指针输入无效

允许来自

线程数

示例

/* 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

从客户端文件读取块

原型

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

说明

此服务用于从之前打开的 TFTP 客户端文件读取 512 字节的块。 所含字节数小于 512 字节的块表示文件结束。

输入参数

  • tftp_client_ptr:指向 TFTP 客户端控制块的指针。

  • packet_ptr:包含从该文件读取的块的数据包的目标。

  • wait_option:定义服务等待读取完成的时长。 等待选项的定义如下:

    • timeout value:(0x00000001 至 0xFFFFFFFE)

    • TX_WAIT_FOREVER (0xFFFFFFFF)

    • 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起,直到 TFTP 服务器响应此请求。

    • 选择数值 (1-0xFFFFFFFE) 可指定等待 TFTP 服务器发送文件块时调用线程保持挂起状态的最大计时器时钟周期数。

  • ip_type:表示要使用的 IP 协议。 有效选项为 IPv4 (4) 或 IPv6 (6)。

返回值

  • NX_SUCCESS (0x00):成功读取客户端块

  • NX_TFTP_NOT_OPEN (0XC3):未打开要读取的指定客户端文件

  • NX_NO_PACKET (0X01):没有收到来自服务器的数据包。

  • NX_INVALID_TFTP_SERVER_ADDRESS (0x08):收到的服务器地址无效

  • NX_TFTP_NO_ACK_RECEIVED (0X09):未收到服务器的确认

  • NX_TFTP_END_OF_FILE (0xC5):检测到文件结束(不是错误)。

  • NX_TFTP_INVALID_IP_VERSION (0x0C):IP 版本无效

  • NX_TFTP_CODE_ERROR (0x05):收到错误代码

  • NX_TFTP_FAILED (0xC2):收到未知的 TFTP 代码

  • NX_TFTP_INVALID_BLOCK_NUMBER (0x0A):收到的块编号无效

  • NX_PTR_ERROR (0x16):指针输入无效。

  • NX_CALLER_ERROR (0x11):此服务的调用方无效

  • NX_INVALID_PARAMETERS (0x4D):非指针输入无效

允许来自

线程数

示例

/* 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

将块写入客户端文件

原型

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

说明

此服务用于将 512 字节的块写入之前打开的 TFTP 客户端文件。 指定所含字节数小于 512 个字节的块将表示文件结束。

输入参数

  • tftp_client_ptr:指向 TFTP 客户端控制块的指针。

  • packet_ptr:包含要写入文件的块的数据包。

  • wait_option:定义服务等待写入完成的时长。 等待选项的定义如下:

    • timeout value:(0x00000001 至 0xFFFFFFFE)

    • TX_WAIT_FOREVER (0xFFFFFFFF)

    • 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起,直到 TFTP 服务器响应此请求。

    • 选择数值 (1-0xFFFFFFFE) 可指定等待 TFTP 服务器发送写入请求的确认时调用线程保持挂起状态的最大计时器时钟周期数。

  • ip_type:表示要使用的 IP 协议。 有效选项为 IPv4 (4) 或 IPv6 (6)。

返回值

  • NX_SUCCESS (0x00):成功写入客户端块

  • NX_TFTP_NOT_OPEN (0XC3):未打开要写入的指定客户端文件

  • NX_TFTP_TIMEOUT (0xC1):等待服务器确认时超时

  • NX_INVALID_TFTP_SERVER_ADDRESS (0x08):收到的服务器地址无效

  • NX_TFTP_NO_ACK_RECEIVED (0X09):未收到服务器的确认

  • NX_TFTP_INVALID_IP_VERSION (0x0C):IP 版本无效

  • NX_INVALID_TFTP_SERVER_ADDRESS (0x08):收到的服务器地址无效

  • NX_TFTP_CODE_ERROR (0x05):收到错误代码

  • NX_PTR_ERROR (0x16):指针输入无效。

  • NX_CALLER_ERROR (0x11):此服务的调用方无效

  • NX_INVALID_PARAMETERS (0x4D):非指针输入无效

允许来自

线程数

示例

/* 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

分配数据包以执行客户端文件写入

原型

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

说明

此服务用于分配来自指定数据包池的 UDP 数据包,并在数据包返回到调用方之前为 4 字节 TFTP 标头腾出空间。 然后,调用方可以生成一个缓冲区,用于写入客户端文件。

输入参数

  • pool_ptr:指向数据包池的指针。

  • packet_ptr:指向已分配数据包的指针。

  • wait_option:定义服务等待数据包完成分配的时长。 等待选项的定义如下:

    • timeout value:(0x00000001 至 0xFFFFFFFE)

    • TX_WAIT_FOREVER (0xFFFFFFFF)

    • 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起,直到分配完成。

    • 选择数值 (1-0xFFFFFFFE) 可指定等待数据包分配时调用线程保持挂起状态的最大计时器时钟周期数。

  • ip_type:表示要使用的 IP 协议。 有效选项为 IPv4 (4) 或 IPv6 (6)。

返回值

  • NX_SUCCESS (0X00):成功分配数据包

  • NX_PTR_ERROR (0x16):指针输入无效。

  • NX_CALLER_ERROR (0x11):此服务的调用方无效

  • NX_INVALID_PARAMETERS (0x4D):非指针输入无效

允许来自

线程数

示例

/* 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

为 TFTP 请求设置物理接口

原型

UINT nxd_tftp_client_set_interface(
    NX_TFTP_CLIENT *tftp_client_ptr,
    UINT if_index);

说明

此服务使用输入接口索引为 TFTP 客户端设置用于发送和接收 TFTP 数据包的物理接口。 主接口的默认值为零。

注意

NetX Duo 必须支持多宿主寻址(5.6 或更高版本),才能使用此服务。

输入参数

  • tftp_client_ptr:指向 TFTP 客户端实例的指针

  • if_index:要使用的物理接口的索引

返回值

  • NX_SUCCESS (0X00):成功设置接口 (0x0B) 接口输入无效

  • NX_PTR_ERROR (0x16):指针输入无效。

  • NX_CALLER_ERROR (0x11):此服务的调用方无效

  • NX_TFTP_INVALID_INTERFACE (0x0B):接口输入无效

允许来自

线程数

示例

/* 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

创建 TFTP 服务器

原型

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

说明

此服务会创建一个 TFTP 服务器,用于响应端口 69 上的 TFTP 客户端请求。 此服务器必须通过对 nxd_tftp_server_start 的后续调用启动。

重要

应用程序必须确保已创建所提供的 IP 实例、数据包池和 FileX 媒体实例。 此外,还必须在调用此服务之前为 IP 实例启用 UDP。

输入参数

  • tftp_server_ptr:指向 TFTP 服务器控制块的指针。

  • tftp_server_name:此 TFTP 服务器实例的名称

  • ip_ptr:指向以前所创建 IP 实例的指针。

  • media_ptr:指向 FileX 媒体实例的指针。

  • stack_ptr:指向 TFTP 服务器堆栈区域的指针。

  • stack_size:TFTP 服务器堆栈中的字节数。

  • pool_ptr:指向 TFTP 数据包池的指针。

注意

提供的池必须包含大小至少为 580 字节的数据包有效负载。1

1 数据包的数据部分正好为 512 字节,但数据包有效负载的大小必须至少为 572 字节。 其余字节用于 UDP、IPv6 和以太网标头以及驱动程序对齐可能需要的结尾字节。

返回值

  • NX_SUCCESS (0x00):成功创建服务器

  • NX_TFTP_POOL_ERROR (0XC6):数据包池包含大小小于 560 字节的数据包

  • NX_PTR_ERROR (0x16):指针输入无效。

允许来自

初始化、线程

示例

/* 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

删除 TFTP 服务器

原型

UINT nxd_tftp_server_delete(NX_TFTP_SERVER *tftp_server_ptr);

说明

此服务用于删除以前创建的 TFTP 服务器。

输入参数

  • tftp_server_ptr:指向 TFTP 服务器控制块的指针。

返回值

  • NX_SUCCESS (0x00):成功删除服务器。

  • NX_PTR_ERROR (0x16):指针输入无效。

  • NX_CALLER_ERROR (0x11):此服务的调用方无效

获准方式

线程数

示例

/* 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

启动 TFTP 服务器

原型

UINT nxd_tftp_server_start(NX_TFTP_SERVER *tftp_server_ptr);

说明

此服务用于启动以前创建的 TFTP 服务器。

输入参数

  • tftp_server_ptr:指向 TFTP 服务器控制块的指针。

返回值

  • NX_SUCCESS (0x00):成功启动服务器

  • NX_PTR_ERROR (0x16):指针输入无效。

允许来自

初始化、线程

示例

/* 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

停止 TFTP 服务器

原型

UINT nxd_tftp_server_stop(NX_TFTP_SERVER *tftp_server_ptr);

说明

此服务用于停止以前创建的 TFTP 服务器。

输入参数

  • tftp_server_ptr:指向 TFTP 服务器控制块的指针。

返回值

  • NX_SUCCESS (0x00):成功停止服务器

  • NX_PTR_ERROR (0x16):指针输入无效。

  • NX_CALLER_ERROR (0x11):此服务的调用方无效

获准方式

线程数

示例

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

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