|
The File Transfer Protocol (FTP) is the most common application
protocol used to upload and download files between a local system and a
server. In addition to basic file transfer capabilities, FTP
also enables a client application to perform common file and directory
management functions on the server, such as renaming and deleting files
or creating new directories. The SocketTools Library Edition also
supports secure file transfers using SSH (SFTP) and SSL/TLS (FTPS) by
simply specifying an option when establishing the connection.
The first step that your application must take is to initialize the
library and then establish a connection. The following functions are
available for use by your application:
FtpInitialize
Initialize the library and load the Windows Sockets library for the
current process. This must be the first function call that the
application makes before calling the other FTP API functions.
FtpConnect
Connect to the server, using either a host name or IP address.
The function has several options related to security as well as the
general operation of the library. One important option is
FTP_OPTION_PASSIVE, which instructs the library to use passive mode
file transfers. If the local system is behind a firewall or a route
which uses Network Address Translation (NAT), it is often necessary
to use this option. This function returns a client handle which is
used in subsequent calls to the library.
FtpProxyConnect
A variation on the standard connection, this function can be used to
connect to an FTP server through a proxy server. The library provides
support for a number of standard proxy types, such as those used by
the Gauntlet and InterLock proxy servers. A custom proxy server type
is also supported where your application can send any custom commands
required to establish the connection.
FtpLogin
Authenticate the client session, providing the server with a user
name, password and optionally an account name. It is also possible to
use an anonymous (unauthenticated) session by providing empty strings
as the username and password.
FtpDisconnect
Disconnect from the server and release the memory allocated for that
client session. After this function is called, the client handle is
no longer valid.
FtpUninitialize
Unload the Windows Sockets library and release any resources that
have been allocated for the current process. This is the last
function call that the application should make prior to
terminating.
File Transfers
The library provides several functions which can be used to transfer
files between the local and server. This group of functions is
high level, meaning that it is not necessary to actually write the code
to read and/or write the file data. The library automatically handles
the lower level file I/O and notifies your application of the status of
the transfer by periodically generating progress events.
FtpGetData
This function transfers a file from the server to the local
system, storing the file data in memory. This can be useful if your
application needs to perform some operation based on the contents of
the file, but does not need to store the file locally.
FtpGetFile
This function transfers a file from the server and stores it in
a file on the local system. This function is similar to how the GET
command works for the command-line FTP client in Windows.
FtpGetMultipleFiles
This function transfers multiple files from the server and
stores them in a directory on the local system. A wildcard may be
specified so that only files which a certain name or those that match
a particular file extension are downloaded. This function is similar
to how the MGET command works for the command-line FTP client in
Windows.
FtpPutData
This function creates a file on the server containing the data
that you provide. This can be useful if your application wants to
upload dynamically created content without having to create a
temporary file on the local system.
FtpPutFile
This function uploads a file from the local system to the server.
This function is similar to how the PUT command works for the
command-line FTP client in Windows.
FtpPutMultipleFiles
This function transfers multiple files from the local system to a
directory on the server. A wildcard may be specified so that
only files with a certain name or those that match a particular file
extension are uploaded. This function is similar to how the MPUT
command works for the command-line FTP client in Windows.
File Management
In addition to performing file transfers, the File Transfer Protocol
library can also perform many of the same kinds of file management
functions on the server as you would on the local system.
FtpDeleteFile
Delete a file from the server. This operation requires that the
current user have the appropriate permissions to delete the file.
FtpRenameFile
Change the name of a file or move a file to a different directory.
This operation requires that the current user have the appropriate
permissions to rename the file. If the file is being moved to another
directory, the user must have permission to access that
directory.
FtpGetFileStatus
Return status information about the file in the form of a structure.
This typically specifies the ownership, access permissions, size and
modification time for the file. It is similar to opening a directory
on the server and reading information about the file, but with less
overhead.
FtpGetFileSize
Return the size of a file on the server without actually downloading
the contents of the file.
FtpGetFileTime
Return the modification time for the specified file on the server.
This can be used by you application to determine if the file has been
changed since the time that you last uploaded or downloaded the
contents.
FtpSetFileTime
Update the modification time for a file on the server. This function
requires that the current user have the appropriate permissions to
change the last modification timestamp for the file. Note that this
is not supported on all servers and in some cases may be restricted
to specific accounts.
FtpGetFilePermissions
Return the access permissions for a file on the server. This can be
used to determine if a file can be read, modified and/or deleted by
the current user. For users who are familiar with UNIX file
permissions, it is the same type which is used by the library.
FtpSetFilePermissions
Change the access permissions for a file. This function is supported
on most UNIX based servers, as well as any other server that supports
the site-specific CHMOD command.
Directory Management
The library also provides a set of functions which can be used to
access and manage directories or folders, including the ability to list
and search for files, create new directories and remove empty
directories from the server.
FtpOpenDirectory
Open the specified directory on the server. This is the first step in
returning a list of files in the directory. After the directory has
been opened, information about the files it contains can be returned
to the application. The directory path may also include wildcards to
only return information about a certain subset of files based on the
file name or extension.
FtpGetFirstFile
Return information about the first file in the directory that has
been opened. This is similar to how the Windows API function
FindFirstFile works.
FtpGetNextFile
Return information about the next file in the directory that has been
opened. This function is called repeatedly until it indicates that
all of the files have been returned. This is similar to how the
Windows API function FindNextFile works.
FtpChangeDirectory
Change the current working directory on the server. This is similar
to how the CD command is used from the command-line to change the
current directory in Windows. If a path is not specified in the file
name, the current working directory is where files will be uploaded
to and downloaded from.
FtpCreateDirectory
Create a new directory on the server. This requires that the current
user have the appropriate access permissions in order to create the
directory.
FtpRemoveDirectory
Remove an empty directory from the server. This operation requires
that the current user have the appropriate permissions to delete the
directory. For safety, it is required that the directory does not
contain any files or subdirectories or the operation will fail.
|