FTP works by making a control connection between the client computer and the FTP server. This control connection is used to send commands for everything from listing directories to authenticating users. When a user wants to download or upload a file a separate data connection is made. Part of the reason the protocol is considered outdated is because of this second connection. First, the data connection is traditionally made by the server to the client. Nowadays, allowing a remote computer to direct connect to a computer on your network is a big security risk. In addition to that, most client computers are not directly on the internet but instead are behind routers and firewalls. Generally, this means the server cannot make the data connection. Because of this and many other security issues with the protocol, please do NOT use it for any sensitive information.

Behind the scenes Legato uses Windows Internet (WinINet) to power the FTP functions. This means Legato’s FTP functions will use the current user’s Internet Options set in Windows Control Panel. This is also the case with Legato’s HTTP functions.

Now that we’ve had a brief discussion of FTP let’s dive into how to use it with Legato starting with making a connection:

handle = FTPOpenConnection ( string server, [string username], [string password], [int port], [boolean passive] );

The FTPOpenConnection creates a connection to an FTP server. Please note that the username and password are sent in plain text. This is a huge security consideration and another reason why FTP is outdated. However, many FTP servers can be used to anonymously download files. In this case the protocol is completely safe and very fast. The port parameter can be 0 to tell Legato to use the default FTP port of 21. Lastly, the passive parameter is important as it tells Legato to send the PASV command to the server. This means that instead of the server connecting to the client for the data channel the client will connect to the server. This helps deal with router issues as you no longer need to have computers on your network exposed in order to use FTP.

After connecting there are several functions to navigate the FTP server:

string = FTPGetFirstFile ( handle hFTP, string target );
string = FTPGetNextFile ( handle hFTP );
int = FTPGetFileSize ( handle hFTP, string target );

The FTPGetFirstFile and FTPGetNextFile work similarly to the GetFirstFile and GetNextFile functions. You can use a full path and/or a wildcard in the target name in order to match specific files. The big difference is that the FirstFile function returns a string which is the name of the first file. The normal function returns a handle to be used in subsequent calls. The FTP version does not since there can be only one FTP file enumeration running at a time. The FTPGetNextFile returns the next file that matches the search parameters or an empty string if there are no more files. Lastly, the FTPGetFileSize function returns the size of a file on the server. This is useful to estimate download times.

Let’s move to actually interacting with files:

int = FTPPutFile ( handle hFTP, string source, string destination );
int = FTPGetFile ( handle hFTP, string source, string destination );
int = FTPCreateFolder ( handle hFTP, string path );
int = FTPDeleteFolder ( handle hFTP, string target );
int = FTPRenameFile ( handle hFTP, string existing, string new );
int = FTPDeleteFile ( handle hFTP, string target );

The FTPPutFile and FTPGetFile functions upload and download files, respectively. These functions are the bread and butter of FTP as it is what FTP was designed to do. The FTPCreateFolder and FTPDeleteFolder functions can create and delete folders on the server. The FTPRenameFile function renames a file on the server. It is advisable to use this function instead of manually downloading a file and uploading it with a new name since the rename will be performed server-side. Lastly, the FTPDeleteFile function will remove a file from the remote server. Please note that outside of FTPGetFile most of these functions will likely not work unless you are logged in as a privileged user. Anonymous users do not usually have write access to servers and some servers don’t allow modifications even for authenticated users.

This concludes the quick overview of legato’s FTP functions. Even if it is a little outdated, FTP is one of the many features Legato offers. If you wish to use a newer protocol, such as SFTP, it is possible to use create batch files and execute a separate SFTP program using CreateProcess.

David Theis has been developing software for Windows operating systems for over fifteen years. He has a Bachelor of Sciences in Computer Science from the Rochester Institute of Technology and co-founded Novaworks in 2006. He is the Vice President of Development and is one of the primary developers of GoFiler, a financial reporting software package designed to create and file EDGAR XML, HTML, and XBRL documents to the U.S. Securities and Exchange Commission.

Additional Resources

Novaworks’ Legato Resources

Legato Script Developers LinkedIn Group

Primer: An Introduction to Legato