ftpapi.txt

世纪民生公司的cs6209的开发ftp服务器的演示源程序。

FTP Client Function Document

1.include 
	<ftp.h>

2.Definations
	#define MAX_FTP_Q 10
	the command queue size of ftp
	
	#define FTP_DATA_SOCKET_PORT_START 2048
	the start port number for normal mode

3.Structure
3.1	
	typedef struct _st_ftp{
		void *Data_socket;	//socket for data
		void *Command_socket;	//socket for commanfd
		char *User_name;	//user name for login ftp server
		char *Password;		//password for login ftp server
		char (*Event_func)(void *ts,char end_of_data_flag);//internal used
		st_ftp_command_queue proc_queue[MAX_FTP_Q];//QUEUE for store command
		unsigned char current_proc;	//internal used
		unsigned char last_proc;	//internal used
		char client_type;		//internal used
		char passive_mode;		//Flag for using passive mode
		ENUM_FTP_status status;		//The status of FTP client
		char last_command[80];		//Last command sending to ftp server
		char last_return_code[4];	//Last return code from FTP server (refer to RFC959)
		char (*on_error)(void *ftp);	//On error callback function
		void *app;			//User data area
	}st_ftp;
	
		void *Data_socket:
			It point to TSOCK that is used for ftp data connection.
			In passive mode we must assign a free socket for it.
			In normal mode it is internal used.
		
		void *Command_socket:
			Point to TSOCK that is used for ftp command connection.
		
		char *User_name:
			Point to user name string.
		
		char *Password:
			Point to user password string.
		
		char (*Event_func)(void *ts,char end_of_data_flag):
			Internal use,it is point to current command callback function.
		
		st_ftp_command_queue proc_queue[MAX_FTP_Q]:
			Internal use,it is the command queue for ftp client.
			
		unsigned char current_proc;
			Internal use,it is the index of current command in proc_queue.

		unsigned char last_proc;
			Internal use,it is the index of last command in proc_queue.

		char client_type:
			Internel use,it is used to indicate which type of current command.
			The value is:
				FTP_GET_FILE,FTP_RECV:
					used for data receive (NLST,RETR,LIST....)
				FTP_SEND_FILE,FTP_SEND:
					used for data transmit (STOR....)
				FTP_NO_DATA:
					used for no data transmit or receiver(TYPE,CWD,CDUP....)
				FTP_QUIT:
					used for quit command (QUIT)
				
		char passive_mode:
			Internel use,to indicate if ftp client work on passive mode.
			
		char status;
			The status of ftp client,the value is:
		
			FTP_STOP:
			The FTP client is stop,it is the initial value of FTP client.
			
			FTP_CONN:
			The FTP is connected to FTP Srever.
			
			FTP_LOGIN_USER:
			The FTP have send username.
			
			FTP_LOGIN_PASS:
			The FTP have send password.
			
			FTP_SET_PORT:
			The FTP have set port.In passive mode the FTP receive and set port
			from PASV command.
			
			FTP_SEND_COMMAND:
			The FTP send command and wait for respond.
			
			FTP_IDLE:
			The FTP have finish login and wait for command.
			
			FTP_START:
			The FTP is start.This state is set in ftp_open function.
			
			FTP_CLOSE:
			The FTP is send "QUIT" command and wait for responding.
			
			FTP_ERROR:
			Some error have occurred.If the state set to FTP_ERROR,then
			the on_error callback function will be call.
			
			FTP_STOP_BY_QUIT:
			FTP have stop by "QUIT" command.It may indicate that the ftp is finished
			successful.
			
			FTP_STOP_BY_ERROR:
			FTP have stop by error.The error may cause by TCP connected error.
			
		char last_command[80]:
			The last command that send to FTP server.
			
		char last_return_code[4];
			The last return code respond by FTP server.Refer to RFC 959
			
		char (*on_error)(void *ftp);
			FTP error callback function.The ftp point to st_ftp.
	
3.2	
	typedef struct _st_ftp_command_queue{
		char *command;
		char command_type;
		char (*callback_func)(void *ts,char end_of_data_flag);
	}st_ftp_command_queue;

	NOTE:This structure is internal used.You doesn't have to care about it.
	

	char *command:
		point to command string.
		
	char command_type:

		FTP_GET_FILE,FTP_RECV:
			used for data receive (NLST,RETR,LIST....)
		FTP_SEND_FILE,FTP_SEND:
			used for data transmit (STOR....)
		FTP_NO_DATA:
			used for no data transmit or receiver(TYPE,CWD,CDUP....)
		FTP_QUIT:
			used for quit command (QUIT)
	
	char (*callback_func)(void *ts,char end_of_data_flag):
		The callback function for this command.The ts point to TSOCK,
		the end_of_data_flag indicate if this is the end of FTP data.
	
4.API Functions

4.1 
Function:
	char ftp_open(st_ftp *ftp,char passive_mode)
Description:
	Open a FTP client
Parameter:
	st_ftp *ftp:
		Point to st_ftp structure.
		
	char passive_mode:
		Set to 1 to let FTP work in passive mode.
Return:
	Return FTP_SUCCESS if success, or
	FTP_SOCKET_ERROR if FTP command socket error,or
	FTP_USER_PASS_ERROR if FTP username or password error.


4.2		
Function:
	char en_queue_command(st_ftp *ftp,char *command,char command_type,char *callback_func)
Description:	
	Add a command to FTP process QUEUE

Parameter:
	st_ftp *ftp:
		point to st_ftp structure.
		
	char *command:
		point to command string.
		
	char command_type:
		FTP_GET_FILE,FTP_RECV:
			used for data receive (NLST,RETR,LIST....)
		FTP_SEND_FILE,FTP_SEND:
			used for data transmit (STOR....)
		FTP_NO_DATA:
			used for no data transmit or receiver(TYPE,CWD,CDUP....)
		FTP_QUIT:
			used for quit command (QUIT)
	
	char *callback_func:
		The callback function for this command.Refer to [5.Callback Functions]
Return:
	Return FTP_SUCCESS if success, or
	FTP_PROC_QUERE_FULL if fail.

5.Callback Functions

5.0
	The Keil C compiler have some problem in useing function point,and we must 
	correct it by OVERLAP in OPTION->ML51MISC OVERLAP memo.
	
	If we don,t use OVERLAP to correct the call table,the program may work well.
	But when we use Optimization or memory bank switch,some error may occur.

5.1
Function:
	char (*on_error)(void *ftp);
Parameter:
	void *ftp:
		Point to st_ftp.

Return:
	True:Continue FTP client
	
	False:Close FTP Client

Description:
	The on_error function will be call when some error occurring.The function
	may declear as "char error(st_ftp *ftp)".You can get last command by
	ftp->last_command,and last return code bt ftp->last_return_code.You can also 
	add some command by en_queue_command function.If the error can't be recover(like 
	login error),you can return False to close FTP client.

Note:
	The on_error function must be add to FTP_CLIENT_FUNCTION call table.For example,
	if our on_error is point to FTP_ERROR function in FTPTEST.c , we must add 
	?PR?_FTP_CLIENT_FUNCTION?FTPAPI ! ?PR?_FTP_ERROR?FTPTEST in OVERLAP memo(Option->ML51misc).
	
5.2
Function:
	char (*callback_func)(void *ts,char flag)
Parameter:
	void *ts:
		Point to st_ftp.

	char flag:

	1.command_type is FTP_GET_FILE or FTP_RECV:
		Indicate if this is the end of FTP data.
		
	2.command_type is FTP_SEND_FILE or FTP_SEND:
		Indicate if this is the first time of FTP data transmitting.

NOTE:It may declear like char callback(TSOCK *ts,char flag)
Return:

	1.command_type is FTP_GET_FILE or FTP_RECV:
		None
		
	2.command_type is FTP_SEND_FILE or FTP_SEND:
	
		If FTP data have transmit completely:Return 0.
		
		If there are more data to transmit:Return 1.

Description:
	The callback function will be call FTP according to command_type.
	In FTP_GET_FILE or FTP_RECV it will be call when data have received and in
	FTP_SEND_FILE or FTP_SEND it will be call when FTP is ready to transmit data.
	In FTP_NO_DATA or FTP_QUIT,this function is unused.

	1.command_type is FTP_GET_FILE or FTP_RECV:
	
		You can use "buff_out" function (declear in netutil.h) to get receiving data
 		from ts and check end_of_data_flag to judge if the "data receive" 
 		have completed.
		
	2.command_type is FTP_SEND_FILE or FTP_SEND:
	
		You can use "buff_in" function (declear in netutil.h) to fill data
 		into ts and when there are no more data to transmit you can return 0
 		to tell FTP the transmission have complete.

Note:
	The callback_func function must be add to ftp_send_function call table(command type 
	FTP_SEND_FILE or FTP_SEND) or ftp_receive_function call table(command type 
	FTP_GET_FILE or FTP_RECV). For example,if our callback_func 
	is point to FTP_SEND function in FTPTEST.c,we must add 

	?PR?_FTP_SEND_FUNCTION?FTPAPI ! ?PR?_FTP_SEND?FTPTEST

	in OVERLAP memo(Option->ML51misc).

6.Sample code
	Please refer to FTP demo code .The ftp_callback contain callback functions .