第 3 章 - Azure RTOS NetX FTP 服务说明

  • 项目

本章按字母顺序提供所有 Azure RTOS NetX FTP 服务说明（下面列出的）。

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

nx_ftp_client_connect

连接到 FTP 服务器

原型

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

说明

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

输入参数

  • ftp_client_ptr：指向 FTP 客户端控制块的指针。
  • server_ip：FTP 服务器的 IP 地址。
  • username：用于身份验证的客户端用户名。
  • password：用于身份验证的客户端密码。
  • wait_option：定义服务等待 FTP 客户端连接的时长。 等待选项的定义如下：
    • * 超时值：（0x00000001 到 0xFFFFFFFE）
    • TX_WAIT_FOREVER：(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求*。 选择数值 (1-0xFFFFFFFE) 可指定等待 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

创建 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：(0x16) FTP、IP 指针或数据包池指针无效。 密码指针。

获准方式

初始化和线程

示例

/* 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：(0x16) 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 目录创建的时长。 等待选项定义如下：
    • 超时值*：（0x00000001 到 0xFFFFFFFE）
    • TX_WAIT_FOREVER:(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。 选择数值 (1-0xFFFFFFFE) 可指定等待 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 默认目录设置的时长。 等待选项定义如下：
    • 超时值*：（0x00000001 到 0xFFFFFFFE）
    • TX_WAIT_FOREVER*：(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。 选择数值 (1-0xFFFFFFFE) 可指定等待 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）
    • TX_WAIT_FOREVER：(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。 选择数值 (1-0xFFFFFFFE) 可指定等待 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\combination 进行分隔。 应当调用 nx_ftp_client_directory_listing_continue 来完成目录获取操作。

输入参数

  • ftp_client_ptr：指向 FTP 客户端控制块的指针。
  • directory_name：要获取其内容的目录的名称。
  • packet_ptr：指向目标数据包指针的指针。 如果成功，数据包有效负载将包含一个或多个目录项。
  • wait_option：定义服务等待 FTP 目录列出的时长。 等待选项定义如下：
    • 超时值*：（0x00000001 到 0xFFFFFFFE）
    • TX_WAIT_FOREVER*：(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。 选择数值 (1-0xFFFFFFFE) 可指定等待 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 目录列出的时长。 等待选项定义如下：
    • 超时值*：（0x00000001 到 0xFFFFFFFE）
    • TX_WAIT_FOREVER*：(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。 选择数值 (1-0xFFFFFFFE) 可指定等待 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 客户端断开连接的时长。 等待选项定义如下：
    • 超时值*：（0x00000001 到 0xFFFFFFFE）
    • TX_WAIT_FOREVER*：(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。 选择数值 (1-0xFFFFFFFE) 可指定等待 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 客户端关闭文件的时长。 等待选项定义如下：
    • 超时值*：（0x00000001 到 0xFFFFFFFE）
    • TX_WAIT_FOREVER:(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。 选择数值 (1-0xFFFFFFFE) 可指定等待 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）
    • TX_WAIT_FOREVER：(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。 选择数值 (1-0xFFFFFFFE) 可指定等待 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）
    • TX_WAIT_FOREVER：(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。 选择数值 (1-0xFFFFFFFE) 可指定等待 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）
    • TX_WAIT_FOREVER:(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。 选择数值 (1-0xFFFFFFFE) 可指定等待 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）
    • TX_WAIT_FOREVER：(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。 选择数值 (1-0xFFFFFFFE) 可指定等待 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）
    • TX_WAIT_FOREVER：(0xFFFFFFFF) 选择 TX_WAIT_FOREVER 会导致调用线程无限期挂起，直到 FTP 服务器响应请求。 选择数值 (1-0xFFFFFFFE) 可指定等待 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：(0x16) 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：指向应用程序登录函数的函数指针。 此函数用于获取请求连接的客户端的用户名和密码。 如果此数据有效，应用程序登录函数应返回 NX_SUCCESS。
  • ftp_logout：指向应用程序注销函数的函数指针。 此函数用于获取请求断开连接的客户端的用户名和密码。 如果此数据有效，应用程序登录函数应返回 NX_SUCCESS。

返回值

  • NX_SUCCESS：(0x00) FTP 服务器创建成功。
  • NX_PTR_ERROR：(0x16) 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. */

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：(0x16) 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：(0x16) 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：(0x16) 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. */