第37章 RL-TCPnet之FTP客户端

STM32

本帖最后由 lee_st 于 2017-12-19 12:03 编辑

转帖
本章节为大家讲解RL-TCPnet的FTP客户端应用，学习本章节前，务必要优先学习第35章的FTP基础知识。有了这些基础知识之后，再搞本章节会有事半功倍的效果。
   本章教程含STM32F407开发板和STM32F429开发板。
37.1  初学者重要提示
37.2  FTP函数
37.3  FTP配置说明（Net_Config.c）
37.4  FTP调试说明（Net_Debug.c）
37.5  FTP访问方法和板子的操作步骤
37.6  实验例程说明（RTX）
37.7  总结

lee_st · 2017-12-22 08:52:48

37.1 初学者重要提示

1、学习本章节前，务必保证已经学习了第35章的基础知识。
2、本章配套的例子是将开发板作为FTP客户端，使用开发板上面的SD卡作为客户端的存储介质。所以测试本章节的例子，务必要准备一个SD卡。
3、由于配套例子的文件系统是采用的RL-FlashFS，此文件系统的文件名仅支持ASCII字符，不支持中文，特别注意！
4、具体电脑端FTP服务器的创建方法和板子的操作步骤在本章的37.5小节有详细说明。做本章节配套的实验，必须要看！

lee_st · 2017-12-22 08:53:02

37.2 FTP函数

使用如下18个函数可以实现RL-TCPnet的FTP：
（1）ftp_accept_host
（2）ftp_check_account
（3）ftp_fclose
（4）ftp_evt_notify
（5）ftp_fdelete
（6）ftp_ffind
（7）ftp_file_access
（8）ftp_fopen
（9）ftp_fread
（10）ftp_frename Server
（11）ftp_fwrite Server
（12）ftp_get_user_id
（13）ftpc_cbfunc
（14）ftpc_connect
（15）ftpc_fclose
（16）ftpc_fopen
（17）ftpc_fread
（18）ftpc_fwrite

lee_st · 2017-12-22 08:53:20

关于这18个函数的讲解及其使用方法可以看教程第 3 章 3.4 小节里面说的参考资料 rlarm.chm 文件：

lee_st · 2017-12-22 08:53:45

这里我们重点的说以下6个函数，因为本章节配套的例子使用的是这6个函数：
（1）ftpc_cbfunc
（2）ftpc_connect
（3）ftpc_fclose
（4）ftpc_fopen
（5）ftpc_fread
（6）ftpc_fwrite
关于这些函数注意以下三点：
1、FTP的所有函数都不支持重入，也就是不支持多任务调用。
2、以ftp_开头的函数是用于FTP服务器的。
3、以ftpc_开头的函数是用于FTP客户端的。

lee_st · 2017-12-22 08:54:01

37.2.1 函数ftpc_fopen

函数原型：
void *ftpc_fopen (
U8* mode); /* 操作模式 */

lee_st · 2017-12-22 08:54:34

函数描述：
函数ftpc_fopen用于打开本地文件（FTP客户端的文件）。此函数在MDK的安装目录中的FTPC_uif.c文件里面，属于底层接口函数，用户要在此函数里面添加具体的操作。
1、第1个参数是操作模式，可以是读操作或者写操作，具体支持的形参类型如下：

2、返回值，打开文件成功的话，返回指向此文件的指针变量，否则返回NULL。
使用这个函数要注意以下问题：
1. 此接口函数是用于FTP客户端的。

lee_st · 2017-12-22 08:55:28

使用举例：
void *ftpc_fopen (U8 *mode) {
/* 打开文件，如果返回NULL，表示打开失败 */
return (fopen (LOCAL_FILE, (char *)mode));
}

lee_st · 2017-12-22 08:56:23

37.2.2 函数ftpc_fclose

函数原型：
void *ftpc_fclose (
FILE* file); /* 文件句柄地址 */

lee_st · 2017-12-22 08:56:47

函数描述：
函数ftpc_fclose用于关闭文件。此函数在MDK的安装目录中的FTPC_uif.c文件里面，属于底层接口函数，用户要在此函数里面添加具体的操作。
1、第1个参数是要关闭的文件句柄地址。
2、返回值，实际上此函数无需返回任何数值，写成下面使用举例中的形式即可。
使用这个函数要注意以下问题：
1. 此接口函数是用于FTP客户端的。

lee_st · 2017-12-22 09:35:11

使用举例：
void ftpc_fclose (void *file) {
/* 关闭文件 */
fclose (file);
}

lee_st · 2017-12-27 08:19:47

37.2.3 函数ftpc_fread
函数原型：
U16 ftpc_fread (
FILE* file, /* 文件句柄地址 */
U8* buf, /* 数据缓冲地址 */
U16 len ); /* 要读取的字节数 */

lee_st · 2017-12-27 08:20:17

函数描述：
函数ftpc_fread用于从文件中读出len个字节数据。此函数在MDK的安装目录中的FTPC_uif.c文件里面，属于底层接口函数，用户要在此函数里面添加具体的操作。
1、第1个参数是要读取数据的文件句柄地址。
2、第2个参数是数据缓冲地址，用于存储读取出来的数据。
3、第3个参数是要读取出来的数据大小，单位字节。
4、返回值，返回从文件中实际读出的字节数。
使用这个函数要注意以下问题：
1. 设置读取函数时，必须设置指定大小的字节数。如果实际读出的字节数小于len，将停止读取并关闭文件，这种情况一般都是文件已经读取完毕。
2. 此接口函数是用于FTP客户端的。

lee_st · 2017-12-27 08:20:35

使用举例：
U16 ftpc_fread (void *file, U8 *buf, U16 len) {
/* 读取len字节到buf中，返回值是实际读取的字节数，返回0的话，表示文件已经读取完毕，文件将被关闭 */
return (fread (buf, 1, len, file));
}

lee_st · 2017-12-27 08:20:51

37.2.4 函数ftpc_fwrite
函数原型：
U16 ftpc_fwrite (
FILE* file, /* 文件句柄地址 */
U8* buf, /* 数据缓冲地址 */
U16 len ); /* 要写入的字节数 */

lee_st · 2017-12-27 08:21:09

函数描述：
函数ftpc_fwrite用于往文件中写入len个字节数据。此函数在MDK的安装目录中的FTPC_uif.c文件里面，属于底层接口函数，用户要在此函数里面添加具体的操作。
1、第1个参数是要写入数据的文件句柄地址。
2、第2个参数是数据缓冲地址，存储要写入的数据。
3、第3个参数是要写入的数据大小，单位字节。
4、返回值，返回实际写入文件的字节数。
使用这个函数要注意以下问题：
1. 设置写函数时，必须设置指定大小的字节数。如果实际写入的字节数小于len，FTP客户端将停止写入，终止数据传输并关闭FTP会话，这种情况一般是写操作出错了。
2. 此接口函数是用于FTP客户端的。

lee_st · 2017-12-27 08:21:54

使用举例：
U16 ftpc_fwrite (void *file, U8 *buf, U16 len) {
/* 将buf中的len字节写入到文件中，如果返回数值（实际写入的字节数）不等于len，数据传输将终止 */
return (fwrite (buf, 1, len, file));
}

lee_st · 2017-12-27 08:22:10

37.2.5 函数ftpc_cbfunc
函数原型：
U16 ftpc_cbfunc (
U8 code,    /* 消息类型 */
U8*  buf,    /* 输出缓冲区地址 */
U16  buflen );  /* 输出缓冲区大小 */

lee_st · 2017-12-27 08:22:31

函数描述：

函数ftpc_cbfunc是FTP客户端的回调函数，用于为FTP客户端会话提供额外参数，如登录FTP服务器的用户名和密码、本地和远程文件名等。FTP客户端多次调用此函数才可完成文件操作请求。

1、第1个参数是FTP客户端所需的附加信息（用户，密码，文件名等）类型，具体支持的参数类型如下：

lee_st · 2017-12-27 08:22:51

2、第2个参数是输出缓冲区地址，用于将请求的数据写入到输出缓冲区。
3、第3个参数是输出缓冲区大小，单位字节。
4、返回值，返回使用的输出缓冲区大小，单位字节。
使用这个函数要注意以下问题：
1. 每次通信，数据缓冲区的大小会有所不同，因为它是由TCP Socket的MSS最大报文段协商决定的，局域网中一般是1400字节左右。
2. 写到输出缓冲区的数据，不可以超过第三个参数buflen的大小，否则会造成内存指针链表的损坏，从而很容易造成系统崩溃。