FTP library

From openPicus Wiki
Jump to: navigation, search

The FTP library provides two kind of functions: the "high level" and the "low level" functions. With the first ones it's possible to directly connect Flyport to a server and easily send commands or read/write remote files. All the server answers are managed by framework's functions simply requiring the user to give the connection parameters of file names.
The "low level" functions include the basic set of FTP commands to open a command/data socket and read or write data and commands on it. With this kind of functions it's possible to have a greater control of FTP operations, but all the management of the timeouts and answers' parsing it's up to the users. For the most of applications, using high level functions is the fastest and easiest solution.

Contents

High level functions

This instruction set contains functions to automatically connect to an FTP, to manage file reading/writing and to send commands to the server without the user has to manage the timings or parse the server messages. A set of possible error codes are returned in case operation is not successfull. Details on returns can be found in single function's description. A complete list of error codes follows:

Error code define (value) Description
FTP_ERR_NOT_CREATED (-1) A problem occurred while creating a specified FTP socket. Not error in connection, maybe some internal problem in Flyport (maybe no more sockets available).
FTP_ERR_SERV_NOT_FOUND (-2) FTP server was not found. Maybe IP address was wrong, or maybe a firewall doesn't allow Flyport to reach the server.
FTP_ERR_WRONG_ANSWER (-3) Unexpected answer code from server. Operation is aborted.
FTP_ERR_WRONG_LOGIN (-4) Login went wrong, caused by wrong username/password.
FTP_ERR_SERV_TIMEOUT (-5) The server didn't answered within the expected timeout. Operation is aborted.
FTP_STREAM_INVALID_OP (-6) User has attempted an invalid stream operation, for example trying to write on a not-opened stream.
FTP_DATA_NO_CONNECTED (-7) An operation requiring a data socket (for example append to a file) failed going in passive mode.
FTP_SOCK_NOT_CONNECTED (-10) Returned in case the FTP command socket is not connected, in this case the operation is aborted.
FTP_ERR_SERV_DISCONNECTED (-11) FTP server disconnected client during the operation.
FTP_FILE_ERROR (-12) Some error occurred while accessing file, maybe user has not permission, or file is actually in use.
FTP_ERR_TX (-13) An error occurred while transmitting a command to the server, possible buffer issue on Flyport (increase FTP TX buffer in configuration wizard).
FTP_ERR_TX_NOT_OK (-14) Data transmission started correctly, but didn't ended with an acknowledge by the server (code 226).
FTP_FILE_NOT_FOUND (-15) Searched file was not found.


Connecting to an FTP server


The connection to a remote FTP server is achievede using the function FTPConnect():

int FTPConnect(TCP_SOCKET *cmdSocket, char[] ftpAddress, char[] ftpPort, char[] ftpUser, char[] ftpPwd);

Parameters

*cmdSock A variable TCP_Socket must be previously created and then passed as reference to the function. That variable contains the command socket that will be connected to the server. Once the socket is connected, it can be used to send commands, like append, store, change directory and others.
ftpAddress A string containing the IP address or the domain name of the FTP server.
ftpPort A string containing the port of the server (usually is "21").
ftpUser A string with the username required for the connection.
ftpPwd A string containing the password required for the user authentication. If no password is required, you can use the defined value FTP_NO_PASS.

Returns
An int with the report for the operation: FTP_CONNECTED if successfully connected, otherwise an error code as reported in the table at the beginning of the paragraph.

Example
An example of connection to a server follows:

TCP_SOCKET mySock = INVALID_SOCKET; // Socket declared and initialized
int report;
report = FTPConnect(&mySock, "ftp.myServerName.com", "21", char[] ftpUser, char[] ftpPwd);
if (report == FTP_CONNECTED)
	UARTWrite(1, "Connection successfull");
else
	UARTWRite(1, "Connection error");



Checking file existence on FTP server


To check if a specified file exists on server, the function FTPFileCheck() can be used.

int FTPFileCheck(TCP_SOCKET cmdSock, char fileToCheck[]);

Parameters

cmdSock The command socket previously connected to the server.
fileToCheck A string with the file name to check for existence.

Returns
An int containing the value FTP_FILE_EXIST if the file is found, or FTP_FILE_NOT_FOUND if the file is not found. If the operation has not succeeded, an error code will be reported.

Reading file size


The function FTPFileSize() returns the file of a specified file on the FTP server:

long FTPFileSize(TCP_SOCKET cmdSock, char fileName[]);

Parameters

cmdSock The command socket previously connected to the server.
fileName A string with the file name to read the size.

Returns
A long int (signed 32 bit var) containing the size of the desired file. If the operation has not succeded, an error code will be reported.

Append/store data on a file


To write data on file, there are two possible ways: APPEND or STORE methods. The append method, as the name says, append the data at the end file, while the store method creates a new file and then writes data on it, so the store method overwrites the existing file (if it exists). To append data is used the function FTPAppend(), while to store, is used FTPStore()
NOTE: both the functions take a command socket and open the data socket, write the data on file and close the socket. To keep the data socket opened and write data multiple times without reopening it, use the stream functions. To write multiple data on a file it's faster and easier, FTPAppend() and FTPStore() are "one shot" functions.
APPEND data:

int FTPAppend(TCP_SOCKET cmdSock, char fileName[], char appStr[]);

STORE data:

int FTPStore(TCP_SOCKET cmdSock, char fileName[], char stoStr[]);

Parameters

cmdSock The command socket previously connected to the server.
fileName A string with the file name to read the size.
appStr/stoStr the string to append/store on to the file.


Returns An int variable containing the number of bytes written, an error code if the operation failed.

File stream write mode


When a file writing must be repeated multiple times in a small time interval (ten of seconds or minutes), instead of using the FTPAppend() or FTPStore() function, it's more convenient to open a "stream" and keep it opened to write the data you need. For example, data can be read from a memory card in chunks and written directly on FTP server.
Attention must be kept on server timeouts! If you open the stream and don't write any data within the server timeout (changing from server to server), your connection is directly closed by the server, so you'll have to open it again. Server timeouts usually goes from 30 secs to some minutes, but it's a very variable value, so you first should check your server settings. Once the server disconnect the Flyport, the stream must be closed using the FTPStreamClose() function and reopened.

Opening the stream in write mode

To open the file stream in write mode, the function FTPStreamOpen() must be used. The stream can be opened in writing or reading mode, in particular, to open it in writing mode, it's possible to specify APPEND or STORE mode:

int FTPStreamOpen(TCP_SOCKET cmdSock, char fileName[], char mode[]);

Parameters

cmdSock The command socket previously connected to the server.
fileName A string with the file name to open in stream mode.
mode The mode of the stream: APPE or STOR to write the data on the file. APPE will open in append mode, STOR in store mode, so it will overwrite the file if it exist.

Returns
An int var containing the report for the operation: FTP_CONNECTED if succeded, otherwise an error code will be reported.

Writing data on stream

To write data on the stream, is used the function FTPStreamWrite():

long FTPStreamWrite(char strWrite[], long toWrite);

Parameters

strWrite The char array to write
toWrite The length of the char array to write

NOTE: since the length of the data to write is specified as parameter, there is no need to terminate it with a nul char. A string is not needed, a char array is sufficient. In this way it's possible to send "raw data" also containing nul chars.
Returns
A long int containing the data written on the stream. If the data written is different from the toWrite parameter, some error occured during writing.

File stream read mode


To read a file from an FTP server, can be used a stream of data in reading mode. Since Flyport's RAM is not sufficient to contain large files, in this way it's possible to read parts of the file, store it, for example in an sd card, and retrieve the data later.

Opening the stream in read mode

To open the file stream in read mode, the function FTPStreamOpen() must be used specifying the mode RETR.

int FTPStreamOpen(TCP_SOCKET cmdSock, char fileName[], char mode[]);

Parameters

cmdSock The command socket previously connected to the server.
fileName A string with the file name to open in stream mode.
mode The mode of the stream: RETR to read the data from the file.

Returns
An int var containing the report for the operation: FTP_CONNECTED if succeded, otherwise an error code will be reported.

Reading data from the stream

To read the data from the stream is used the function FTPStreamRead(), that allows the user the specify the destination and the length of the data to read:

long FTPStreamRead(char dest[], int len, BYTE timeout);

Parameters

dest The destination char array for the data.
len The length of the data to read.
timeout The max time (expressed in seconds) to wait for the data.

Returns The length of the data read from the file, otherwise an error code will be reported.

IMPORTANT: the reading operation should be performed as fast as possible, since the server could disconnect Flyport or data loss may be experienced, so don't use delays or perform any other operation if you want to download a file. In particular the last "chunk" of the file could be loss if the interval between reading is long. This may happen because when the server has sent the last byte, it disconnects the client. When the Flyport is disconnected from the server, the data is flushed in a max timeout of 50msecs. So if the data is not read within that interval, it is lost.
To know if the end of file is reached, it's possible to read the status of the stream using the function FTPStreamStat().

Closing the stream


The stream is closed using the function FTPStreamClose(). Anytime the stream must be reinitialized, or the server disconnected the Flyport, FTPStreamClose() must be called before FTPStreamOpen().

void FTPStreamClose();

Parameters
-
Returns
Nothing

The stream status


The function FTPStreamStat returns the status of the stream:

BYTE FTPStreamStat();

Parameters
-
Returns
A BYTE with the status of the stream.The possible values are the following:

  • FTP_STREAM_NOT_CONN - Stream still not connected.
  • FTP_STREAM_READING - Stream in reading mode.
  • FTP_STREAM_EOF - Stream in reading mode has reached the end of file.
  • FTP_STREAM_WRITING - Stream in writing mode.
Personal tools
Namespaces

Variants
Actions
START HERE
DEVELOPMENT
HARDWARE INFO
RESOURCES
PHASED OUT
Toolbox