|
The File Transfer Protocol (FTP) is the most common application
protocol used to upload and download files between a local system
and a remote 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 Secure 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 remote host, 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 remote host. 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 remote host 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 remote host 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 remote host 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 remote host 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 remote
host. 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 remote host. 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 remote host 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.
|