第 3 章 - FTP 服务说明

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

注意

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

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