EC600G/components/ql-kernel/inc/ql_ftp_client.h

/**  
  @file
  ql_ftp_client.h

  @brief
  This file provides the definitions for ftp client, and declares the 
  API functions.

*/
/*============================================================================
  Copyright (c) 2017 Quectel Wireless Solution, Co., Ltd.  All Rights Reserved.
  Quectel Wireless Solution Proprietary and Confidential.
 =============================================================================*/
/*===========================================================================

                        EDIT HISTORY FOR MODULE

This section contains comments describing changes made to the module.
Notice that changes are listed in reverse chronological order.


WHEN        WHO            WHAT, WHERE, WHY
----------  ------------   ----------------------------------------------------

=============================================================================*/


#ifndef __QL_FTP_CLIENT_H__
#define __QL_FTP_CLIENT_H__

#include <time.h>
#include "ql_api_common.h"

#ifdef __cplusplus
extern "C" {
#endif


#define MAX_FILE_NAME_SIZE		256
#define MAX_OWNER_SIZE		64
#define QL_FTP_CLIENT_FREE(p)   if(p){free(p);p=NULL;}
#define QL_FTP_ERRCODE_BASE     (QL_COMPONENT_LWIP_FTP << 16)

typedef enum
{
	QL_FTP_ERR_OK 						= 0,							/*Operation successful*/
	QL_FTP_ERR_UNKNOWN 					= 601 | QL_FTP_ERRCODE_BASE,	/*Unknown error*/
	QL_FTP_ERR_WOULDBLOCK 				= 602 | QL_FTP_ERRCODE_BASE,	/*FTP(S) server blocked*/
	QL_FTP_ERR_BUSY 					= 603 | QL_FTP_ERRCODE_BASE,	/*FTP(S) server busy*/
	QL_FTP_ERR_DNS 						= 604 | QL_FTP_ERRCODE_BASE,	/*failed to parse domain name*/
	QL_FTP_ERR_NETWORK 					= 605 | QL_FTP_ERRCODE_BASE, 	/*failed to establish socket or the network is deactivated*/
	QL_FTP_ERR_CTRL_CLOSE 				= 606 | QL_FTP_ERRCODE_BASE,	/*the ftp session has been closed by the ftp server*/
	QL_FTP_ERR_DATA_CLOSE 				= 607 | QL_FTP_ERRCODE_BASE,	/*the data connection was closed by the ftp server*/
	QL_FTP_ERR_BEARER_FAIL 				= 608 | QL_FTP_ERRCODE_BASE,	/*Socket closed by peer*/
	QL_FTP_ERR_TIMEOUT 					= 609 | QL_FTP_ERRCODE_BASE,	/*Timeout error*/
	QL_FTP_ERR_INVALID_PARAM 			= 610 | QL_FTP_ERRCODE_BASE,	/*Invalid parameter*/
	QL_FTP_ERR_FILE_NOT_FOUND 			= 611 | QL_FTP_ERRCODE_BASE,	/*Failed to open file*/
	QL_FTP_ERR_FILE_POINT_ERR 			= 612 | QL_FTP_ERRCODE_BASE,	/*File position invalid*/
	QL_FTP_ERR_FS_FILE_ERROR 			= 613 | QL_FTP_ERRCODE_BASE,	/*File error*/
	QL_FTP_ERR_SERVICE_END 				= 614 | QL_FTP_ERRCODE_BASE,	/*Service not available, closing control connection*/
	QL_FTP_ERR_DATA_FAILED 				= 615 | QL_FTP_ERRCODE_BASE,	/*Open data connection failed*/
	QL_FTP_ERR_CLOSE_CONN 				= 616 | QL_FTP_ERRCODE_BASE,	/*Connection closed; transfer aborted*/
	QL_FTP_ERR_FILE_UNOPER 				= 617 | QL_FTP_ERRCODE_BASE,	/*Requested file action not taken*/
	QL_FTP_ERR_REQUEST_ABORT 			= 618 | QL_FTP_ERRCODE_BASE,	/*Requested action aborted: local error in processing*/
	QL_FTP_ERR_OVER_MEMORY 				= 619 | QL_FTP_ERRCODE_BASE,	/*Requested action not taken: insufficient system storage*/
	QL_FTP_ERR_COMMAND_ERROR 			= 620 | QL_FTP_ERRCODE_BASE,	/*Syntax error, command unrecognized*/
	QL_FTP_ERR_PARAM_ERROR 				= 621 | QL_FTP_ERRCODE_BASE,	/*Syntax error in parameters or arguments*/
	QL_FTP_ERR_COMMAND_FAILED 			= 622 | QL_FTP_ERRCODE_BASE,	/*Command not implemented*/
	QL_FTP_ERR_COMMAND_BAD_SEQUENCE 	= 623 | QL_FTP_ERRCODE_BASE,	/*Bad sequence of commands*/
	QL_FTP_ERR_COMMAND_NOT_IMPLENT 		= 624 | QL_FTP_ERRCODE_BASE,	/*Command parameter not implemented*/
	QL_FTP_ERR_UNLOGIN 					= 625 | QL_FTP_ERRCODE_BASE,	/*Not logged in*/
	QL_FTP_ERR_NO_ACCOUNT 				= 626 | QL_FTP_ERRCODE_BASE,	/*Need account for storing files*/
	QL_FTP_ERR_REQUEST_FAILED 			= 627 | QL_FTP_ERRCODE_BASE,	/*Requested action not taken*/
	QL_FTP_ERR_REQUEST_STOP 			= 628 | QL_FTP_ERRCODE_BASE,	/*Requested action aborted: page type unknown*/
	QL_FTP_ERR_FILEREQ_STOP 			= 629 | QL_FTP_ERRCODE_BASE,	/*Requested file action aborted*/
	QL_FTP_ERR_FILENAME_ERROR 			= 630 | QL_FTP_ERRCODE_BASE,	/*Requested file name invalid*/
	QL_FTP_ERR_SSL_AUTH_FAIL 			= 631 | QL_FTP_ERRCODE_BASE,	/*SSL authentication failed*/
	QL_FTP_ERR_INTERFACE_FAILED 		= 632 | QL_FTP_ERRCODE_BASE,	/*Source IP address for transmission cannot use*/
	QL_FTP_ERR_SEND_ERROR 				= 633 | QL_FTP_ERRCODE_BASE,	/*Send data failed*/
	QL_FTP_ERR_RECV_ERROR 				= 634 | QL_FTP_ERRCODE_BASE,	/*Receive data failed*/
} QL_FTP_CLIENT_ERR_E;

typedef enum {
    QL_FTP_CLIENT_SIM_CID,//设置SIM卡的CID
    QL_FTP_CLIENT_SSL_CTX,//设置FTP客户端使用的SSL Context
    QL_FTP_CLIENT_SSL_ENABLE,//设置FTP客户端是否使用SSL连接
	QL_FTP_CLIENT_OPT_PDP_CID, //设置ftp client使用的数据通道CID,执行数据拨号操作时使用的CID
	QL_FTP_CLIENT_OPT_SSL_CTX, //设置SSL
	QL_FTP_CLIENT_OPT_START_POS,//设置下载的起始偏移位置
	QL_FTP_CLIENT_SSL_VERIFY_LEVEL,//设置SSL的校验方式
    QL_FTP_CLIENT_SSL_CACERT_PATH,//设置SSL的证书
    QL_FTP_CLIENT_SSL_OWNCERT_PATH,//设置SSL的本地证书
    QL_FTP_CLIENT_SSL_CIPHERSUITE,//设置SSL的加密套件
    QL_FTP_CLIENT_SSL_VERSION,//设置SSL的版本信息
    QL_FTP_CLIENT_SSL_TRANSPORT,//设置SSL的协议类型
    QL_FTP_CLIENT_PORT_MODE,//设置FTP建立数据连接的主被动模式
    QL_FTP_CLIENT_IPV6_EXTEND,//设置IPV6扩展功能是否开启
    //QL_FTP_CLIENT_SSL_PSK,
}QL_FTP_CLIENT_OPT_E;

typedef enum {
    QL_FTP_CLIENT_SSL_TYPE_NONE,		// 连接FTP服务器
    QL_FTP_CLIENT_SSL_TYPE_IMP,			// 隐式加密连接FTPS服务器
    QL_FTP_CLIENT_SSL_TYPE_EXP,			// 显式加密连接FTPS服务器
    QL_FTP_CLIENT_SSL_TYPE_SSH,			// 连接SFTP服务器
}QL_FTP_CLIENT_SSL_TYPE_E;


typedef struct{
	char filename[MAX_FILE_NAME_SIZE];//文件或目录名
	int type;//类型，0：未知；1：目录；2：文件
	int permissions;//权限
	int links;//链接数
	char owner[MAX_OWNER_SIZE];//所属用户
	char group[MAX_OWNER_SIZE];//所属用户组
	struct tm timestamp;//创建时间
	unsigned long size;//文件大小，字节
}QL_FTP_CLIENT_FILE_INFO_T;


/*****************************************************************
* Function: QL_FTP_CLIENT_WRITE_CB
*
* Description:
* 	使用回调函数接收从FTP服务器获取的文件数据。
* 
* Parameters:
* 	ptr	  		    [in] 	获取数据指针。可通过该指针将获得的数据写入用户所指定的存储位置。
* 	size    		[in] 	要被写入的每个元素的大小，以字节为单位。
* 	nmemb   		[in] 	元素的个数，每个元素的大小为size字节。
*   stream          [in]    用户传入的callback function参数指针，可通过该指针指定参数ptr中数据存放的位置。
* Return:
* 	如果成功，该函数需要返回size*nmemb大小的字节，否则会导致数据读错误，导致ftp异常结束。
*
*****************************************************************/
typedef size_t (*QL_FTP_CLIENT_WRITE_CB_EX)(void *ptr, size_t size, size_t nmemb, void *stream);


/*****************************************************************
* Function: QL_FTP_CLIENT_READ_CB
*
* Description:
* 	使用回调函数发送数据到FTP服务器。
* 
* Parameters:
* 	ptr 	  		[out] 	读取数据的指针。用户传入的数据可被该指读取，完成用户数据的记录。
* 	size    		[in] 	要被读取的每个元素的大小，以字节为单位。
* 	nmemb   		[in] 	元素的个数，每个元素的大小为size字节。
*   stream          [in]    用户传入的callback function参数指针，可通过该指针向参数ptr传入数据。
* Return:
* 	如果成功，该函数需要返回size*nmemb大小的字节，否则会导致数据读错误，导致ftp异常结束。
*
*****************************************************************/
typedef size_t (*QL_FTP_CLIENT_READ_CB_EX)(void *ptr, size_t size, size_t nmemb, void *stream);



/*****************************************************************
* Function: ql_ftp_client_new
*
* Description:
* 	创建ftp client 句柄。
* 
* Parameters:
* 	无
*
* Return:
* 	不为 NULL, ftp client 句柄。
* 	NULL, 创建失败。
*
*****************************************************************/
void *ql_ftp_client_new(void);


/*****************************************************************
* Function: ql_ftp_client_release
*
* Description:
* 	释放ftp client资源。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
*
* Return:
* 	void。
*
*****************************************************************/
void ql_ftp_client_release(void *client);


/*****************************************************************
* Function: ql_ftp_client_setopt
*
* Description:
* 	配置ftp client相关属性。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
* 	tag	  			[in] 	属性标签，见QL_FTP_CLIENT_OPT_E。
* 	...	  			[in] 	属性参数。
*							tag为QL_FTP_CLIENT_OPT_PDP_CID是，此参数为int型，执行数据拨号操作时使用的CID值。
*							tag为QL_FTP_CLIENT_OPT_SSL_CTX是，此参数为指针，SSL 句柄。
*
* Return:
* 	0，成功。
*  	其他，错误码。
*
*****************************************************************/
int ql_ftp_client_setopt(void *client, QL_FTP_CLIENT_OPT_E tag, ...);


/*****************************************************************
* Function: ql_ftp_client_open
*
* Description:
* 	连接ftp服务器。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
* 	hostname	  	[in] 	ftp 服务器地址。
* 	username	  	[in] 	用户名。
* 	password	  	[in] 	密码。
*
* Return:
* 	0，成功。
*  	其他，错误码。
*
*****************************************************************/
int ql_ftp_client_open(void *client,char *hostname,char *username,char *password);


/*****************************************************************
* Function: ql_ftp_client_close
*
* Description:
* 	断开与ftp服务器的连接。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
*
* Return:
* 	0，成功。
*  	其他，错误码。
*
*****************************************************************/
int ql_ftp_client_close(void *client);


/*****************************************************************
* Function: ql_ftp_client_get_ex
*
* Description:
* 	从ftp服务器下载文件。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
* 	remotefile	  	[in] 	需要获取的ftp服务器上文件的文件名，可以包含相对或绝对路径。
* 	localfile	  	[in] 	存储到本地的文件名，可以包含相对或绝对路径，如果为NULL，则和ftp服务器上文件同名，本地默认使用的目录为U:/。
* 	write_cb	  	[in] 	使用回调函数接收从FTP服务器获取的文件数据。
* 	user_data	  	[in] 	用户数据。
*
* Return:
* 	0，成功。
*  	其他，错误码。
*
*****************************************************************/
int ql_ftp_client_get_ex(void *client,char *remotefile,char *localfile,QL_FTP_CLIENT_WRITE_CB_EX write_cb,void* user_data);
/*****************************************************************
* Function: ql_ftp_client_put_ex
*
* Description:
* 	上传本地文件到服务器。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
* 	localfile	  	[in] 	需要上传的本地文件名，可以包含相对或绝对路径，本地默认使用的目录为U:/。
* 	remotefile	  	[in] 	存储到ftp服务器上文件的文件名，可以包含相对或绝对路径，如果为NULL，则和本地文件同名，
* 	read_cb	  		[in] 	使用回调函数发送数据到FTP服务器，如果设置了此回调函数，localfile参数无效，remotefile参数必须设置。
* 	user_data	  	[in] 	用户数据。
*
* Return:
* 	0，成功。
*  	其他，错误码。
*
*****************************************************************/
int ql_ftp_client_put_ex(void *client,char *localfile,char *remotefile,QL_FTP_CLIENT_READ_CB_EX read_cb,void* user_data);


/*****************************************************************
* Function: ql_ftp_client_delete
*
* Description:
* 	删除ftp服务器上文件。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
* 	remotefile	  	[in] 	需要删除的ftp服务器上文件的文件名，可以包含相对或绝对路径，
*
* Return:
* 	0，成功。
*  	其他，错误码。
*
*****************************************************************/
int ql_ftp_client_delete(void *client,char *remotefile);


/*****************************************************************
* Function: ql_ftp_client_cwd
*
* Description:
* 	更改ftp服务器当前使用的目录。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
* 	path	  		[in] 	ftp服务器目录，可以是相对或绝对路径，
*
* Return:
* 	0，成功。
*  	其他，错误码。
*
*****************************************************************/
int ql_ftp_client_cwd(void *client, char *path);


/*****************************************************************
* Function: ql_ftp_client_lcwd
*
* Description:
* 	更改本地当前使用的目录。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
* 	path	  		[in] 	本地目录，可以是相对或绝对路径，
*
* Return:
* 	0，成功。
*  	其他，错误码。
*
*****************************************************************/
int ql_ftp_client_lcwd(void *client, char *path);


/*****************************************************************
* Function: ql_ftp_client_pwd
*
* Description:
* 	获取ftp服务器当前使用的目录。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
* 	path	  		[out] 	ftp服务器目录，绝对路径。
*	path_len		[in]	path的最大存储长度。
*
* Return:
* 	0，成功。
*  	其他，错误码。
*
*****************************************************************/
int ql_ftp_client_pwd(void *client, char *path, int path_len);


/*****************************************************************
* Function: ql_ftp_client_lpwd
*
* Description:
* 	获取本地当前使用的目录。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
* 	path	  		[out] 	本地目录，绝对路径。
*	path_len		[in]	path的最大存储长度。
*
* Return:
* 	0，成功。
*  	其他，错误码。
*
*****************************************************************/
int ql_ftp_client_lpwd(void *client, char *path, int path_len);


/*****************************************************************
* Function: ql_ftp_client_mkdir
*
* Description:
* 	在ftp服务器上新建目录。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
* 	path	  		[in] 	需要新建的ftp服务器目录，可以是相对或绝对路径。
*
* Return:
* 	0，成功。
*  	其他，错误码。
*
*****************************************************************/
int ql_ftp_client_mkdir(void *client, char *path);


/*****************************************************************
* Function: ql_ftp_client_rmdir
*
* Description:
* 	删除ftp服务器上的目录。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
* 	path	  		[in] 	需要删除的ftp服务器目录，可以是相对或绝对路径。
*
* Return:
* 	0，成功。
*  	其他，错误码。
*
*****************************************************************/
int ql_ftp_client_rmdir(void *client, char *path);


/*****************************************************************
* Function: ql_ftp_client_list
*
* Description:
* 	获取指定ftp服务器上目录下文件和目录列表。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
* 	path_or_file	[in] 	ftp服务器上的目录或文件，可以是相对或绝对路径。
* 	match			[in] 	只列出包含match字符的结果。
* 	file_info_list	[out] 	获取到的文件和目录列表。
* 	max_file_num	[in] 	file_info_list可以存储结果的最大个数。
*
* Return:
* 	大于0，实际获取到的结果个数。
*  	-1，失败。
*
*****************************************************************/
int ql_ftp_client_list(void *client, char *path_or_file,char *match,QL_FTP_CLIENT_FILE_INFO_T *file_info_list, int max_file_num);

/*****************************************************************
* Function: ql_ftp_client_get_server_file_size
*
* Description:
* 	获取FTP服务器上指定路径下指定文件的大小。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
*   path_or_file    [in]    FTP服务器上的目录或文件，可以是相对路径或绝对路径。
*   nSize           [out]   用于获取FTP服务器上所要查询指定文件的大小。
*
* Return:
* 	0，成功。
*   其他，错误码。
*
*****************************************************************/
int ql_ftp_client_size(void *client, const char *filename, double *nSize);

/*****************************************************************
* Function: ql_ftp_client_rename
*
* Description:
* 	对ftp服务器上的文件重命名。
* 
* Parameters:
* 	client	  		[in] 	ftp client 句柄。
*   oldname         [in]    FTP服务器上要重命名的文件名。
*   newname         [in]    重命名后的文件名。
*
* Return:
* 	0，成功。
*   其他，错误码。
*
*****************************************************************/
int ql_ftp_client_rename(void *client, const char *oldname, const char *newname);

#ifdef __cplusplus
}
#endif

#endif