|
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 following properties, methods and events are available for
use by your application:
Initialize
Initialize the control and load the Windows Sockets library for the
current process. This method is normally not used if the control is
placed on a form in languages such as Visual Basic. However, if the
control is being created dynamically using a function similar to
CreateObject, then the application must call this method to
initialize the component before setting any properties or calling
any other methods in the control.
Connect
Connect to the remote host, using either a host name or IP address.
The method has several options related to security as well as the
general operation of the control. One important option is
ftpOptionPassive, which instructs the control 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. It is also possible to enable passive mode
transfers by simply setting the Passive property prior to calling
this method.
Login
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. If the UserName and Password
properties are set prior to connecting, the user will automatically
be logged in. This method is only necessary if the application
needs to access the server using different user accounts during the
same session.
Disconnect
Disconnect from the server and release the memory allocated for
that client session. After this method is called, the client
session is no longer valid.
Uninitialize
Unload the Windows Sockets library and release any resources that
have been allocated for the current process. This is the last
method call that the application should make prior to terminating.
This is only necessary if the application has previously called the
Initialize method.
File Transfers
The control provides several methods which can be used to
transfer files between the local and remote host. This group of
methods are high level, meaning that it is not necessary to
actually write the code to read and/or write the file data. The
control automatically handles the lower level file I/O and notifies
your application of the status of the transfer by periodically
generating progress events.
GetData
This method 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. The file
data can returned in a string or byte array.
GetFile
This method transfers a file from the remote host and stores it in
a file on the local system. This method is similar to how the GET
command works for the command-line FTP client in Windows.
GetMultipleFiles
This method 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 method is
similar to how the MGET command works for the command-line FTP
client in Windows.
PutData
This method 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. The data may be specified
either as a string, or as the contents of a byte array.
PutFile
This method uploads a file from the local system to the remote
host. This method is similar to how the PUT command works for the
command-line FTP client in Windows.
PutMultipleFiles
This method 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 method 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 control can also perform many of the same kinds of file
management methods on the remote host as you would on the local
system.
DeleteFile
Delete a file from the server. This operation requires that the
current user have the appropriate permissions to delete the
file.
GetFileSize
Return the size of a file on the server without actually
downloading the contents of the file.
GetFileStatus
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.
GetFileTime
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.
RenameFile
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.
SetFileTime
Update the modification time for a file on the server. This method
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.
GetFilePermissions
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 control.
SetFilePermissions
Change the access permissions for a file. This method is supported
on most UNIX based servers, as well as any other server that
supports the site-specific CHMOD command.
Directory Management
The control also provides a set of methods 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.
ChangeDirectory
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.
MakeDirectory
Create a new directory on the server. This requires that the
current user have the appropriate access permissions in order to
create the directory.
OpenDirectory
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.
ReadDirectory
Return information about the next file in the directory that has
been opened. This method is called repeatedly until it indicates
that all of the files have been returned.
RemoveDirectory
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.
|