第 3 章 - FTP 服务说明

本章按字母顺序（同一服务的 IPv4 和 IPv6 等效项配对在一起时例外）介绍了所有 NetX FTP 服务（如下所列）。

注意

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

nx_ftp_client_connect

通过 IPv4 连接到 FTP 服务器

原型

UINT nx_ftp_client_connect(
    NX_FTP_CLIENT *ftp_client_ptr,
    ULONG server_ip,
    CHAR *username,
    CHAR *password,
    ULONG wait_option);

说明

此服务将以前创建的 NetX FTP 客户端实例连接到位于所提供 IP 地址的 FTP 服务器。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• server_ip：FTP 服务器的 IP 地址。
• username：用于身份验证的客户端用户名。
• password：用于身份验证的客户端密码。
• wait_option：定义服务等待 FTP 客户端连接的时长。 等待选项的定义如下：
  • timeout value (0x00000001 - 0xFFFFFFFE)：选择数值 (1-0xFFFFFFFE) 可指定等待 FTP 服务器响应时保持挂起状态的最大计时器时钟周期数。
  • TX_WAIT_FOREVER (0xFFFFFFFF)：选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。

返回值

• NX_SUCCESS (0x00)：FTP 连接成功。
• NX_TFTP_EXPECTED_22X_CODE (0xDB)：未获得 22X（正常）响应
• NX_FTP_EXPECTED_23X_CODE (0xDC)：未获得 23X（正常）响应
• NX_FTP_EXPECTED_33X_CODE (0xDE)：未获得 33X（正常）响应
• NX_FTP_NOT_DISCONNECTED (0xD4)：客户端已连接。
• NX_PTR_ERROR (0x07)：无效的指针输入。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。
• NX_IP_ADDRESS_ERROR (0x21)：IP 地址无效。

允许来自

线程数

示例

/* Connect the FTP Client instance “my_client” to the FTP Server at

IP address 1.2.3.4. */

status = nx_ftp_client_connect(&my_client, IP_ADDRESS(1,2,3,4), NULL, NULL, 100);

/* If status is NX_SUCCESS an FTP Client instance was successfully  
    connected to the FTP Server. */

另请参阅

nx_ftp_client_create、nx_ftp_client_delete、nx_ftp_client_directory_create、nx_ftp_client_disconnect、nxd_ftp_client_connect

nxd_ftp_client_connect

连接到支持 IPv6 的 FTP 服务器

原型

UINT nxd_ftp_client_connect(
    NX_FTP_CLIENT *ftp_client_ptr,
    NXD_ADDRESS *server_ipduo, 
    CHAR *username,
    CHAR *password,
    ULONG wait_option);

说明

此服务将以前创建的 NetX Duo FTP 客户端实例连接到位于所提供 IP 地址的 FTP 服务器。 同时支持 IPV4 和 IPV6 网络。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• server_ipduo：FTP 服务器的 IP 地址。
• username：用于身份验证的客户端用户名。
• password：用于身份验证的客户端密码。
• wait_option：定义服务等待 FTP 客户端连接的时长。 等待选项的定义如下：
  • timeout value (0x00000001 - 0xFFFFFFFE)：选择数值 (1-0xFFFFFFFE) 可指定等待 FTP 服务器响应时保持挂起状态的最大计时器时钟周期数。
  • TX_WAIT_FOREVER (0xFFFFFFFF)：选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。

返回值

• NX_SUCCESS (0x00)：FTP 连接成功。
• NX_TFTP_EXPECTED_22X_CODE (0xDB)：未获得 22X（正常）响应
• NX_FTP_EXPECTED_23X_CODE (0xDC)：未获得 23X（正常）响应
• NX_FTP_EXPECTED_33X_CODE (0xDE)：未获得 33X（正常）响应
• NX_FTP_NOT_DISCONNECTED (0xD4)：客户端已连接
• NX_PTR_ERROR (0x07)：指针输入输出无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。
• NX_IP_ADDRESS_ERROR (0x21)：IP 地址无效。

允许来自

线程数

示例

/* Connect an FTP Client instance to the FTP Server. */

/* Set up an IPv6 address for the server here.
    Note this could also be an IPv4 address as well*/

server_ip_addr.nxd_ip_address.v6[3] = 0x106;
server_ip_addr.nxd_ip_address.v6[2] = 0x0;
server_ip_addr.nxd_ip_address.v6[1] = 0x0000f101;
server_ip_addr.nxd_ip_address.v6[0] = 0x20010db8;
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V6;

status = nxd_ftp_client_connect(&my_client, server_ip_addr, NULL, NULL, 100);

/* If status is NX_SUCCESS an FTP Client instance was successfully  
    connected to the FTP Server. */

另请参阅

nx_ftp_client_create、nx_ftp_client_delete、nx_ftp_client_directory_create、nx_ftp_client_disconnect、nx_ftp_client_connect

nx_ftp_client_create

创建 FTP 客户端实例

原型

UINT nx_ftp_client_create(
    NX_FTP_CLIENT *ftp_client_ptr,
    CHAR *ftp_client_name,
    NX_IP *ip_ptr,
    ULONG window_size,
    NX_PACKET_POOL *pool_ptr);

说明

此服务可创建 FTP 客户端实例。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• ftp_client_name：FTP 客户端的名称。
• ip_ptr：指向以前所创建 IP 实例的指针。
• window_size：用于此 FTP 客户端 TCP 套接字的播发窗口大小。
• pool_ptr：指向此 FTP 客户端默认数据包池的指针。 请注意，最小数据包有效负载必须足够大，以便容纳完整路径和文件名或目录名。

返回值

• NX_SUCCESS (0x00)：FTP 客户端创建成功。
• NX_PTR_ERROR (0x07)：无效的指针输入。

允许来自

初始化和线程

示例

/* Create the FTP Client instance “my_client.” */
status = nx_ftp_client_create(&my_client, "My Client", &client_ip,
    2000, &client_pool);
/* If status is NX_SUCCESS the FTP Client instance was successfully created. */

nx_ftp_client_delete

删除 FTP 客户端实例

原型

UINT nx_ftp_client_delete(NX_FTP_CLIENT *ftp_client_ptr);

说明

此服务可删除 FTP 客户端实例。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。

返回值

• NX_SUCCESS (0x00)：FTP 客户端删除成功。
• NX_FTP_NOT_DISCONNECTED (0xD4)：FTP 客户端未断开连接
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许来自

线程数

示例

/* Delete the FTP Client instance “my_client.” */

status = nx_ftp_client_delete(&my_client);

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

nx_ftp_client_directory_create

在 FTP 服务器上创建目录

原型

UINT nx_ftp_client_directory_create(
    NX_FTP_CLIENT *ftp_client_ptr,
    CHAR *directory_name,
    ULONG wait_option);

说明

此服务可在连接到指定 FTP 客户端的 FTP 服务器上创建指定目录。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• directory_name：要创建目录的名称。
• wait_option：定义服务等待 FTP 目录创建的时长。 等待选项的定义如下：
  • timeout value (0x00000001 - 0xFFFFFFFE)：选择数值 (1-0xFFFFFFFE) 可指定等待 FTP 服务器响应时保持挂起状态的最大计时器时钟周期数。
  • TX_WAIT_FOREVER (0xFFFFFFFF)：选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。

返回值

• NX_SUCCESS (0x00)：FTP 目录创建成功。
• NX_FTP_NOT_CONNECTED (0xD3)：FTP 客户端未连接。
• NX_FTP_EXPECTED_2XX_CODE (0xDA)：未获得 2XX（正常）响应
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许来自

线程数

示例

/* Create the directory “my_dir” on the FTP Server connected to
    the FTP Client instance “my_client.” */

status = nx_ftp_client_directory_create(&my_client, “my_dir”, 200);

/* If status is NX_SUCCESS the directory “my_dir” was successfully created. */

nx_ftp_client_directory_default_set

在 FTP 服务器上设置默认目录

原型

UINT nx_ftp_client_directory_default_set(
    NX_FTP_CLIENT *ftp_client_ptr,
    CHAR *directory_path,
    ULONG wait_option);

说明

此服务可在连接到指定 FTP 客户端的 FTP 服务器上设置默认目录。 此默认目录仅应用于此客户端的连接。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• directory_path：要设置目录路径的名称。
• wait_option：定义服务等待 FTP 默认目录设置的时长。 等待选项的定义如下：
  • timeout value (0x00000001 - 0xFFFFFFFE)：选择数值 (1-0xFFFFFFFE) 可指定等待 FTP 服务器响应时保持挂起状态的最大计时器时钟周期数。
  • TX_WAIT_FOREVER (0xFFFFFFFF)：选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。

返回值

• NX_SUCCESS (0x00)：FTP 默认设置成功。
• NX_FTP_NOT_CONNECTED (0xD3)：FTP 客户端未连接。
• NX_FTP_EXPECTED_2XX_CODE (0xDA)：未获得 2XX（正常）响应
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许来自

线程数

示例

/* Set the default directory to “my_dir” on the FTP Server connected to
    the FTP Client instance “my_client.” */

status = nx_ftp_client_directory_default_set(&my_client, “my_dir”, 200);

/* If status is NX_SUCCESS the directory “my_dir” is the default directory. */

nx_ftp_client_directory_delete

在 FTP 服务器上删除目录

原型

UINT nx_ftp_client_directory_delete(
    NX_FTP_CLIENT *ftp_client_ptr,
    CHAR *directory_name,
    ULONG wait_option);

说明

此服务可在连接到指定 FTP 客户端的 FTP 服务器上删除指定目录。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• directory_name：要删除目录的名称。
• wait_option：定义服务等待 FTP 目录删除的时长。 等待选项的定义如下：
  • timeout value (0x00000001 - 0xFFFFFFFE)：选择数值 (1-0xFFFFFFFE) 可指定等待 FTP 服务器响应时保持挂起状态的最大计时器时钟周期数。
  • TX_WAIT_FOREVER (0xFFFFFFFF)：选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。

返回值

• NX_SUCCESS (0x00)：FTP 目录删除成功。
• NX_FTP_NOT_CONNECTED (0xD3)：FTP 客户端未连接。
• NX_FTP_EXPECTED_2XX_CODE (0xDA)：未获得 2XX（正常）响应
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许来自

线程数

示例

/* Delete directory “my_dir” on the FTP Server connected to
    the FTP Client instance “my_client.” */

status = nx_ftp_client_directory_delete(&my_client, “my_dir”, 200);

/* If status is NX_SUCCESS the directory “my_dir” is deleted. */

nx_ftp_client_directory_listing_get

从 FTP 服务器获取目录列表

原型

UINT nx_ftp_client_directory_listing_get(
    NX_FTP_CLIENT *ftp_client_ptr,
    CHAR *directory_name,
    NX_PACKET **packet_ptr,
    ULONG wait_option);

说明

此服务可在连接到指定 FTP 客户端的 FTP 服务器上获取指定目录的内容。 提供的数据包指针将包含一个或多个目录项。 各目录项用 <cr/lf> 组合进行分隔。 应当调用 nx_ftp_client_directory_listing_continue 来完成目录获取操作。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• directory_name：要获取其内容的目录的名称。
• packet_ptr：指向目标数据包指针的指针。 如果成功，数据包有效负载将包含一个或多个目录项。
• wait_option：定义服务等待 FTP 目录列出的时长。 等待选项的定义如下：
  • timeout value (0x00000001 - 0xFFFFFFFE)：选择数值 (1-0xFFFFFFFE) 可指定等待 FTP 服务器响应时保持挂起状态的最大计时器时钟周期数。
  • TX_WAIT_FOREVER (0xFFFFFFFF)：选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。

返回值

• NX_SUCCESS (0x00)：FTP 目录列出成功。
• NX_FTP_NOT_CONNECTED (0xD3)：FTP 客户端未连接。
• NX_NOT_ENABLED (0x14)：服务 (IPv6) 未启用
• NX_FTP_EXPECTED_1XX_CODE (0xD9)：未获得 1XX（正常）响应
• NX_FTP_EXPECTED_2XX_CODE (0xDA)：未获得 2XX（正常）响应
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许来自

线程数

示例

/* Get the contents of directory “my_dir” on the FTP Server connected to
    the FTP Client instance “my_client.” */

status = nx_ftp_client_directory_listing_get(&my_client, “my_dir”, &my_packet,
    200);

/* If status is NX_SUCCESS, one or more entries of the directory “my_dir”
    can be found in “my_packet”. */

nx_ftp_client_directory_listing_continue

从 FTP 服务器继续获取目录列表

原型

UINT nx_ftp_client_directory_listing_continue(
    NX_FTP_CLIENT *ftp_client_ptr,
    NX_PACKET **packet_ptr,
    ULONG wait_option);

说明

此服务可在连接到指定 FTP 客户端的 FTP 服务器上继续获取指定目录的内容。 此服务应紧跟在 nx_ftp_client_directory_listing_get 调用之后。 如果成功，提供的数据包指针将包含一个或多个目录项。 用户应在收到 NX_FTP_END_OF_LISTING 状态之前，调用此例程。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• packet_ptr：指向目标数据包指针的指针。 如果成功，数据包有效负载将包含一个或多个用 <cr/lf> 分隔的目录项。
• wait_option：定义服务等待 FTP 目录列出的时长。 等待选项的定义如下：
  • timeout value (0x00000001 - 0xFFFFFFFE)：选择数值 (1-0xFFFFFFFE) 可指定等待 FTP 服务器响应时保持挂起状态的最大计时器时钟周期数。
  • TX_WAIT_FOREVER (0xFFFFFFFF)：选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。

返回值

• NX_SUCCESS (0x00)：FTP 目录列出成功。
• NX_FTP_END_OF_LISTING (0xD8)：此目录中没有更多条目。
• NX_FTP_NOT_CONNECTED (0xD3)：FTP 客户端未连接。
• NX_FTP_EXPECTED_2XX_CODE (0xDA)：未获得 2XX（正常）响应
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许调用自

线程数

示例

/* Continue getting the contents of directory “my_dir” on the FTP Server
    connected to the FTP Client instance “my_client.” */

status = nx_ftp_client_directory_listing_continue(&my_client, &my_packet,
    200);

/* If status is NX_SUCCESS, one or more entries of the directory “my_dir”
    can be found in “my_packet”. */

nx_ftp_client_disconnect

断开与 FTP 服务器的连接

原型

UINT nx_ftp_client_disconnect(
    NX_FTP_CLIENT *ftp_client_ptr,
    ULONG wait_option);

说明

此服务可断开以前建立的 FTP 服务器与指定 FTP 客户端的连接。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• wait_option：定义服务等待 FTP 客户端断开连接的时长。 等待选项的定义如下：
  • timeout value (0x00000001 - 0xFFFFFFFE)：选择数值 (1-0xFFFFFFFE) 可指定等待 FTP 服务器响应时保持挂起状态的最大计时器时钟周期数。
  • TX_WAIT_FOREVER (0xFFFFFFFF)：选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。

返回值

• NX_SUCCESS (0x00)：FTP 断开连接成功。
• NX_FTP_NOT_CONNECTED (0xD3)：FTP 客户端未连接。
• NX_FTP_EXPECTED_2XX_CODE (0xDA)：未获得 2XX（正常）响应
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许调用自

线程数

示例

/* Disconnect “my_client” from the FTP Server. */

status = nx_ftp_client_disconnect(&my_client, 200);

/* If status is NX_SUCCESS, “my_client” has been disconnected. */

nx_ftp_client_file_close

关闭客户端文件

原型

UINT nx_ftp_client_file_close(
    NX_FTP_CLIENT *ftp_client_ptr,
    ULONG wait_option);

说明

此服务可关闭以前在 FTP 服务器上打开的文件。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• wait_option：定义服务等待 FTP 客户端关闭文件的时长。 等待选项的定义如下：
  • timeout value (0x00000001 - 0xFFFFFFFE)：选择数值 (1-0xFFFFFFFE) 可指定等待 FTP 服务器响应时保持挂起状态的最大计时器时钟周期数。
  • TX_WAIT_FOREVER (0xFFFFFFFF)：选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。

返回值

• NX_SUCCESS (0x00)：FTP 文件关闭成功。
• NX_FTP_NOT_CONNECTED (0xD3)：FTP 客户端未连接。
• NX_FTP_NOT_OPEN (0xD5)：文件未打开；无法关闭
• NX_FTP_EXPECTED_2XX_CODE (0xDA)：未获得 2XX（正常）响应
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许调用自

线程数

示例

/* Close previously opened file of client “my_client” on the FTP Server. */

status = nx_ftp_client_file_close(&my_client, 200);

/* If status is NX_SUCCESS, the file opened previously in the “my_client” FTP
    connection has been closed. */

nx_ftp_client_file_delete

删除 FTP 服务器上的文件

原型

UINT nx_ftp_client_file_delete(
    NX_FTP_CLIENT *ftp_client_ptr,
    CHAR *file_name,
    ULONG wait_option);

说明

此服务可删除 FTP 服务器上的指定文件。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• file_name：要删除文件的名称。
• wait_option：定义服务等待 FTP 客户端删除文件的时长。 等待选项的定义如下：
  • timeout value (0x00000001 - 0xFFFFFFFE)：选择数值 (1-0xFFFFFFFE) 可指定等待 FTP 服务器响应时保持挂起状态的最大计时器时钟周期数。
  • TX_WAIT_FOREVER (0xFFFFFFFF)：选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。

返回值

• NX_SUCCESS (0x00)：FTP 文件删除成功。
• NX_FTP_NOT_CONNECTED (0xD3)：FTP 客户端未连接。
• NX_FTP_EXPECTED_2XX_CODE (0xDA)：未获得 2XX（正常）响应
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许来自

线程数

示例

/* Delete the file “my_file.txt” on the FTP Server using the previously
    connected client “my_client.” */

status = nx_ftp_client_file_delete(&my_client, “my_file.txt”, 200);

/* If status is NX_SUCCESS, the file “my_file.txt” on the FTP Server is
    deleted. */

nx_ftp_client_file_open

打开 FTP 服务器上的文件

原型

UINT nx_ftp_client_file_open(
    NX_FTP_CLIENT *ftp_client_ptr,
    CHAR *file_name,
    UINT open_type,
    ULONG wait_option);

说明

此服务可在以前连接到指定客户端实例的 FTP 服务器上打开指定文件，以供读取或写入。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• file_name：要打开文件的名称。
• open_type：NX_FTP_OPEN_FOR_READ 或 NX_FTP_OPEN_FOR_WRITE。
• wait_option：定义服务等待 FTP 客户端打开文件的时长。 等待选项的定义如下：
  • timeout value (0x00000001 - 0xFFFFFFFE)：选择数值 (1-0xFFFFFFFE) 可指定等待 FTP 服务器响应时保持挂起状态的最大计时器时钟周期数。
  • TX_WAIT_FOREVER (0xFFFFFFFF)：选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。

返回值

• NX_SUCCESS (0x00)：FTP 文件打开成功。
• NX_OPTION_ERROR (0x0A)：打开类型无效。
• NX_FTP_NOT_CONNECTED (0xD3)：FTP 客户端未连接。
• NX_FTP_NOT_CLOSED (0xD6)：FTP 客户端已打开。
• NX_NO_FREE_PORTS (0x45)：没有 TCP 端口可供分配
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许来自

线程数

示例

/* Open the file “my_file.txt” for reading on the FTP Server using the previously
    connected client “my_client.” */

status = nx_ftp_client_file_open(&my_client, “my_file.txt”, NX_FTP_OPEN_FOR_READ,
    200);

/* If status is NX_SUCCESS, the file “my_file.txt” on the FTP Server is
    open for reading. */

nx_ftp_client_file_read

从文件中读取

原型

UINT nx_ftp_client_file_read(
    NX_FTP_CLIENT *ftp_client_ptr,
    NX_PACKET **packet_ptr,
    ULONG wait_option);

说明

此服务可从以前打开的文件中读取数据包。 在收到 NX_FTP_END_OF_FILE 状态之前，应重复调用此服务。

请注意，调用方不会为此服务分配数据包。  只需要提供指向数据包指针的指针。 此服务会更新该数据包指针，使之指向从套接字接收队列中检索到的数据包。  如果返回“成功”状态，则表示有可用数据包，调用方会负责在使用后释放数据包。

如果返回非零状态（错误状态或 NX_FTP_END_OF_FILE），则调用方无法释放数据包。 否则，在数据包指针为 NULL 时，会生成错误。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• packet_ptr：指向要存储的数据包指针的目标的指针。 如果成功，则数据包会包含文件的部分或全部内容。
• wait_option：定义服务等待 FTP 客户端读取文件的时长。 等待选项的定义如下：
  • timeout value (0x00000001 - 0xFFFFFFFE)：选择数值 (1-0xFFFFFFFE) 可指定等待 FTP 服务器响应时保持挂起状态的最大计时器时钟周期数。
  • TX_WAIT_FOREVER (0xFFFFFFFF)：选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。

返回值

• NX_SUCCESS (0x00)：FTP 文件读取成功。
• NX_FTP_NOT_OPEN (0xD5)：FTP 客户端未打开。
• NX_FTP_END_OF_FILE (0xD7)：文件结尾条件。
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许来自

线程数

示例

NX_PACKET   *my_packet;

/* Read a packet of data from the file “my_file.txt” that was previously opened
    from the client “my_client.” */

status = nx_ftp_client_file_read(&my_client, &my_packet, 200);

/* Check status.  */
if (status != NX_SUCCESS)
{
    error_counter++;
}
else
{
    /* Release packet when done with it. */
    nx_packet_release(my_packet);
}

/* If status is NX_SUCCESS, the packet pointer, “my_packet” points to the packet
    that contains the next bytes from the file. If the file is completely
    downloaded, an NX_FTP_END_OF_FILE status is returned (no packet retrieved). */

nx_ftp_client_file_rename

重命名 FTP 服务器上的文件

原型

UINT nx_ftp_client_file_rename(
    NX_FTP_CLIENT *ftp_ptr,
    CHAR *filename,
    CHAR *new_filename,
    ULONG wait_option);

说明

此服务可重命名 FTP 服务器上的文件。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• filename：文件的当前名称。
• new_filename：文件的新名称。
• wait_option：定义服务等待 FTP 客户端重命名文件的时长。 等待选项的定义如下：
  • timeout value (0x00000001 - 0xFFFFFFFE)：选择数值 (1-0xFFFFFFFE) 可指定等待 FTP 服务器响应时保持挂起状态的最大计时器时钟周期数。
  • TX_WAIT_FOREVER (0xFFFFFFFF)：选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。

返回值

• NX_SUCCESS (0x00)：FTP 文件重命名成功。
• NX_FTP_NOT_CONNECTED (0xD3)：FTP 客户端未连接。
• NX_FTP_EXPECTED_3XX_CODE (0XDD)：未获得 3XX（正常）响应
• NX_FTP_EXPECTED_2XX_CODE (0xDA)：未获得 2XX（正常）响应
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许来自

线程数

示例

/* Rename file “my_file.txt” to “new_file.txt” on the previously connected
    Client instance “my_client.” */

status = nx_ftp_client_file_rename(&my_client, “my_file.txt”, “new_file.txt”,
    200);

/* If status is NX_SUCCESS, the file has been renamed. */

nx_ftp_client_file_write

写入到文件

原型

UINT nx_ftp_client_file_write(
    NX_FTP_CLIENT *ftp_client_ptr,
    NX_PACKET *packet_ptr,
    ULONG wait_option);

说明

此服务可将数据包的数据写入 FTP 服务器上以前打开的文件。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• packet_ptr：包含要写入数据的数据包指针。
• wait_option：定义服务等待 FTP 客户端写入文件的时长。 等待选项的定义如下：
  • timeout value (0x00000001 - 0xFFFFFFFE)：选择数值 (1-0xFFFFFFFE) 可指定等待 FTP 服务器响应时保持挂起状态的最大计时器时钟周期数。
  • TX_WAIT_FOREVER (0xFFFFFFFF)：选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。

返回值

• NX_SUCCESS (0x00)：FTP 文件写入成功。
• NX_FTP_NOT_OPEN (0xD5)：FTP 客户端未打开。
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许来自

线程数

示例

/* Write the data contained in “my_packet” to the previously opened file
    “my_file.txt”. */

status = nx_ftp_client_file_write(&my_client, my_packet, 200);

/* If status is NX_SUCCESS, the file has been written to. */

nx_ftp_client_passive_mode_set

启用或禁用被动传输模式

原型

UINT nx_ftp_client_passive_mode_set(
    NX_FTP_CLIENT *ftp_client_ptr,
    UINT passive_mode_enabled);

说明

如果在以前创建的 FTP 客户端实例中 passive_mode_enabled 输入设置为 NX_TRUE，则此服务会启用被动传输模式，以使读取或写入文件（RETR、STOR）或下载目录列表 (NLST) 的后续调用操作均在传输模式下完成。 若要禁用被动传输模式并返回主动传输模式默认行为，请在调用此函数时，将 passive_mode_enabled 输入设置为 NX_FALSE。

输入参数

• ftp_client_ptr：指向 FTP 客户端控制块的指针。
• passive_mode_enabled：如果设置为 NX_TRUE，则会启用被动模式。 如果设置为 NX_FALSE，则会禁用被动模式。

返回值

• NX_SUCCESS (0x00)：被动模式设置成功。
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_INVALID_PARAMETERS (0x4D)：无效的非指针输入

允许来自

线程数

示例

/* Enable the FTP Client to exchange data with the FTP server in passive mode. */

status = nx_ftp_client_passive_mode_set(&my_client, NX_TRUE);

/* If status is NX_SUCCESS, the FTP client is in passive transfer mode. */

nx_ftp_server_create

创建 FTP 服务器

原型

UINT nx_ftp_server_create(
    NX_FTP_SERVER *ftp_server_ptr,
    CHAR *ftp_server_name,
    NX_IP *ip_ptr,
    FX_MEDIA *media_ptr,
    VOID *stack_ptr,
    ULONG stack_size,
    NX_PACKET_POOL *pool_ptr,
    UINT (*ftp_login)(
        struct NX_FTP_SERVER_STRUCT *ftp_server_ptr,
        ULONG client_ip_address,
        UINT client_port,
        CHAR *name,
        CHAR *password,
        CHAR *extra_info),
    UINT (*ftp_logout)(
        struct NX_FTP_SERVER_STRUCT *ftp_server_ptr,
        ULONG client_ip_address,
        UINT client_port,
        CHAR *name,
        CHAR *password,
        CHAR *extra_info));

说明

此服务可在以前创建的指定 NetX IP 实例中创建 FTP 服务器实例。 请注意，FTP 服务器需要先通过调用 nx_ftp_server_start 启动，然后才能开始运行。

输入参数

• ftp_server_ptr：指向 FTP 服务器控制块的指针。
• ftp_server_name：FTP 服务器的名称。
• ip_ptr：指向关联 NetX IP 实例的指针。 请注意，IP 实例只能有一个 FTP 服务器。
• media_ptr：指向关联 FileX 媒体实例的指针。
• stack_ptr：指向内部 FTP 服务器线程堆栈区域内存的指针。
• stack_size：stack_ptr 所指定堆栈区域的大小。
• pool_ptr：指向默认 NetX 数据包池的指针。 请注意，池中数据包的有效负载必须足够大，以便容纳最长文件名/路径。
• ftp_login：指向应用程序的登录函数的函数指针。 需要向此函数提供请求连接的客户端的用户名和密码，以及采用 ULONG 数据类型的客户端地址。 如果此数据有效，则应用程序的登录函数应返回 NX_SUCCESS。
• ftp_logout：指向应用程序的注销函数的函数指针。 需要向此函数提供请求断开连接的客户端的用户名和密码，以及 ULONG 数据类型的客户端地址。 如果此数据有效，则应用程序的登录函数应返回 NX_SUCCESS。

返回值

• NX_SUCCESS (0x00)：FTP 服务器创建成功。
• NX_PTR_ERROR (0x07)：FTP 指针无效。

允许来自

初始化和线程

示例

/* Create the FTP Server “my_server” on the IP instance “ip_0” using the
    “ram_disk” media. */

status = nx_ftp_server_create(&my_server, “My Server Name”, &ip_0, &ram_disk,
    stack_ptr, stack_size, &pool_0,
    my_login, my_logout);

/* If status is NX_SUCCESS, the FTP Server has been created. */

nxd_ftp_server_create

创建支持 IPv4 和 IPv6 的 FTP 服务器

原型

UINT nxd_ftp_server_create(
    NX_FTP_SERVER *ftp_server_ptr,
    CHAR *ftp_server_name,
    NX_IP *ip_ptr,
    FX_MEDIA *media_ptr,
    VOID *stack_ptr,
    ULONG stack_size,
    NX_PACKET_POOL *pool_ptr,
    UINT (*ftp_login_duo)(
        struct NX_FTP_SERVER_STRUCT *ftp_server_ptr,
        NXD_ADDRESS *client_ip_address,
        UINT client_port,
        CHAR *name,
        CHAR *password,
        CHAR *extra_info),
    UINT (*ftp_logout_duo)(
        struct NX_FTP_SERVER_STRUCT *ftp_server_ptr,
        NXD_ADDRESS *client_ip_address,
        UINT client_port,
        CHAR *name,
        CHAR *password,
        CHAR *extra_info));

说明

此服务可在以前创建的指定 NetX IP 实例中创建 FTP 服务器实例。 请注意，FTP 服务器仍需通过调用 nx_ftp_server_start 来启动，以便在创建服务器后开始操作。

输入参数

• ftp_server_ptr：指向 FTP 服务器控制块的指针。
• ftp_server_name：FTP 服务器的名称。
• ip_ptr：指向关联 NetX IP 实例的指针。 请注意，IP 实例只能有一个 FTP 服务器。
• media_ptr：指向关联 FileX 媒体实例的指针。
• stack_ptr：指向内部 FTP 服务器线程堆栈区域内存的指针。
• stack_size：stack_ptr 所指定堆栈区域的大小。
• pool_ptr：指向默认 NetX 数据包池的指针。 请注意，池中数据包的有效负载必须足够大，以便容纳最长文件名/路径。
• ftp_login_duo：指向应用程序的登录函数的函数指针。 需要向此函数提供请求连接的客户端的用户名和密码，以及指向 NXD_ADDRESS 数据类型的客户端地址的指针。 如果此数据有效，则应用程序的登录函数应返回 NX_SUCCESS。
• ftp_logout_duo：指向应用程序的注销函数的函数指针。 需要向此函数提供请求断开连接的客户端的用户名和密码，以及指向 NXD_ADDRESS 数据类型的客户端地址的指针。 如果此数据有效，则应用程序的登录函数应返回 NX_SUCCESS。

返回值

• NX_SUCCESS (0x00)：FTP 服务器创建成功。
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许调用自

初始化和线程

示例

/* Create the FTP Server “my_server” on the IP instance “ip_0” using the
    “ram_disk” media. */

status = nxd_ftp_server_create(&my_server, “My Server Name”, &ip_0, &ram_disk,
    stack_ptr, stack_size, &pool_0,
    my_duo_login, my_duo_logout);

/* If status is NX_SUCCESS, the FTP Server has been created. */

nx_ftp_server_delete

删除 FTP 服务器

原型

UINT nx_ftp_server_delete(NX_FTP_SERVER *ftp_server_ptr);

说明

此服务可删除以前创建的 FTP 服务器实例。

输入参数

• ftp_server_ptr：指向 FTP 服务器控制块的指针。

返回值

• NX_SUCCESS (0x00)：FTP 服务器删除成功。
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许调用自

线程数

示例

/* Delete the FTP Server “my_server”. */

status = nx_ftp_server_delete(&my_server);

/* If status is NX_SUCCESS, the FTP Server has been deleted. */

nx_ftp_server_start

启动 FTP 服务器

原型

UINT nx_ftp_server_start(NX_FTP_SERVER *ftp_server_ptr);

说明

此服务可启动以前创建的 FTP 服务器实例。

输入参数

• ftp_server_ptr：指向 FTP 服务器控制块的指针。

返回值

• NX_SUCCESS (0x00)：FTP 服务器启动成功。
• NX_PTR_ERROR (0x07)：FTP 指针无效。

允许来自

线程数

示例

/* Start the FTP Server “my_server”. */

status = nx_ftp_server_start(&my_server);

/* If status is NX_SUCCESS, the FTP Server has been started. */

nx_ftp_server_stop

停止 FTP 服务器

原型

UINT nx_ftp_server_stop(NX_FTP_SERVER *ftp_server_ptr);

说明

此服务可停止以前创建和启动的 FTP 服务器实例。

输入参数

• ftp_server_ptr：指向 FTP 服务器控制块的指针。

返回值

• NX_SUCCESS (0x00)：FTP 服务器停止成功。
• NX_PTR_ERROR (0x07)：FTP 指针无效。
• NX_CALLER_ERROR (0x11)：此服务的调用方无效。

允许调用自

线程数

示例

/* Stop the FTP Server “my_server”. */

status = nx_ftp_server_stop(&my_server);

/* If status is NX_SUCCESS, the FTP Server has been stopped. */