EZFTP Professional ActiveX Control

Updated October 27, 1998

Note

Features available in the EZFTP Professional 2.0 control are shown in red.

Introduction

EZFTP.OCX is an ActiveX control that interfaces many programming languages like Visual Basic, Access and Visual C++ 4.0 to the TCP/IP File Transfer Protocol using the WININET code provided by Microsoft® Internet Explorer 3.0 and above.

Two versions of EZFTP are available:

Distribution Details

You must abide by the terms of the license at the end of this document (and also distributed with the Professional Edition in license.txt).

EZFTP.OCX is owned and copyrighted by COOL.STF. You may use EZFTP with any application without royalties or fees. WININET.DLL is supplied by Microsoft and is considered a component of your Windows 95 or Windows NT operating system and is subject to the same licensing terms as your Windows operating system.

Note that the Standard Edition of EZFTP only supports synchronous operation. This means that if you request a large file from a remote FTP server, control will be returned to your application only when the transfer has completed or has failed.

Installation

There is currently no flashy installation program, but all you need to do is:

  1. Transfer EZFTP.OCX and WININET.DLL to your \Windows\System or \Winnt\System32 folder
  2. Copy the EZFTP.LIC file to your \Windows\System or \Winnt\System32 folder (Professional Edition only)
  3. If you keep your old WININET.DLL, make sure its dated 10/15/96 or later
  4. Make sure you have the MFC/OLE DLLs on your system
  5. Make sure MFC40.DLL is dated 10/6/95 or later
  6. Register EZFTP.OCX with the command:

REGSVR32 EZFTP.OCX

If you don't have the MFC/OLE DLLs or don't have the latest versions, they can be download from the COOL.STF homepage, http://www.intr.net/coolstf.

Asynchronous Operation (Professional Edition only)

By default, EZFTP "blocks" when connecting to, sending or receiving data from the FTP server. This means that when a method such as GetFile is used, the code following the method will only be executed when the file transfer has either completed or aborted.

For example:

EZFTP1.RemoteAddress = "intr.net"
`Connect defaults to anonymous login
EZFTP1.Connect
EZFTP1.RemoteFile = "welcome.anon"
EZFTP1.LocalFile = "test.ftp"
EZFTP1.GetFile
`TransferProgress fires multiple times
MsgBox "Done"

Here, the MsgBox statement will only be executed when the file transfer has completed and the RemoteFile property will only be set after the connection to the remote server has been established.

By setting the property AsyncMode true, EZFTP returns immediately after a Connect, GetFile or PutFile method.

As the method executes (i.e. while the connection opens or the transfer occurs), the Status event will fire, indicating the progress of the method. When the method has completed, the EventCode variable supplied in the Status event will contain 100 and the variable Status will contain zero indicating the method completed without error or a non-zero value, indicating an error.

When using AsyncMode, the developer must be careful not to issue other methods against the EZFTP control as this may cause problems.

AsyncMode can be used to allow multiple instances of the EZFTP control to operate at the same time or to perform another task while the transfer occurs in the "background".

Properties

UserName - string

Set to the user name to log on with. For anonymous transfers, set to "anonymous".

Password - string

Set to the password to log on with. For anonymous transfers, set to an email address, for example "myname@domain.com".

LocalFile - string

Set to the name of the local file to be transferred to or from. For example, "c:\windows\desktop\myfile.txt".

RemoteFile - string

Set to the name of the remote file to be transferred to or from. For example, "/home/myacct/etc/stuff.txt".

Binary - boolean

Set as appropriate for the file transfer mode. If transferring ASCII files, should be false to allow <lf> to <cr><lf> translations when moving files between the PC and a Unix machine. If transferring binary files, set true.

RemoteAddress - string

Sets the address of the remote FTP server. Accepts either domain names, for example "ftp.domain.com" or IP addresses, for example "204.157.123.4".

RemoteDirectory - string

Sets or returns the directory in use on the remote FTP server. For example:

MsgBox EZFTP1.RemoteDirectory

might display "/usr/bin/rod". To change directory on the remote server, use:

EZFTP1.RemoteDirectory = "/usr/barney/hate/hate/hate"

provided the directory exists on the remote system (doesn't every machine have a /usr/barney/hate/hate/hate directory!!).

UseCache - boolean

Signals that EZFTP will attempt to use the cache to transfer the file if set to true. Setting to false (the default) will force EZFTP to go to the wire to transfer the file, regardless of whether the file is cached.

Professional Edition only:

AsyncMode boolean

Setting this property to true causes EZFTP to operate the GetFile and PutFile methods in asynchronous mode. See the section on Async Operation for details.

CancelTransfer - boolean

Setting this property to true during the TransferProgress event will abort the current transfer.

FTPPort integer

Sets the port address of the FTP server. Defaults to 21.

LastResponse string

Returns the last series of responses from the remote FTP server. There may be multiple lines of text returned, requiring that this string be parsed for CR/LF pairs.

OfflineMode boolean

Forces all FTP requests to be satisfied by the cache without attempting to obtain the file from the FTP server. If the file requested is not in the cache when this call is made, the transfer will fail.

OutData string

Supplies the data to be sent to the server during a PutFileDirect method.

OutSize integer

Specifies the size of the data in OutData to be sent to the server during a PutFileDirect method.

PASVMode boolean

If set true, causes all file transfers to operate in PASV mode. PASV is used to allow data transfer through a firewall.

ProxyMode boolean

If set true, EZFTP operates via a proxy server, rather than direct to the FTP server. Proxy servers are often used to connect a corporate intranet to the Internet.

ProxyServer string

Sets the hostname or address of the proxy server. If left blank, EZFTP will attempt to use the default registry setting for the proxy server address. Only applicable when ProxyMode is true.

Methods

Connect

Opens a connection to the remote FTP server specified in RemoteAddress.

Disconnect

Closes the connection with the remote FTP server previously opened with Connect. You must take care to issue a Disconnect after a successful Connect. Failure to do so will leave an open FTP connection on the server.

GetFile

Receives the remote file specified in RemoteFile and stores it locally in the file specified by LocalFile. Overwrites the local file if it already exists. For example:

EZFTP1.RemoteFile = "/etc/termcap"
EZFTP1.LocalFile = "c:\windows\desktop\termcap.txt"
On Error Resume Next
EZFTP1.GetFile
If Err <> 0 Then
MsgBox "Unable to get file. Error code : " & Format$(Err.Number)
End If

PutFile

Transfers the local file specified by LocalFile to the file specified by RemoteFile on the FTP server.

MkDir (Directory as string)

Creates a directory specified by the string Directory on the remote FTP server.

RmDir (Directory as string)

Removes the directory specified by the string Directory on the remote FTP server.

RenameFile (OldName as string, NewFile as string)

Renames the file specified in OldName to NewFile on the remote FTP server.

DeleteFile (FileName as string)

Deletes the file specified in FileName on the remote FTP server.

GetDirectory (FileName as string)

Gets a directory listing for the remote system. Wildcards may be specified in the FileName string. Fires the NextDirectoryEvent for each file that is reported by the remote FTP server. For example:

On Error Resume Next
'Get the directory. Work actually done in the NextDirectoryEntry event
EZFTP1.GetDirectory "*.*"
'Arrive here after all possible files have been returned
If Err <> 0 Then
MsgBox "Unable to get directory. Error: " & format$(Err.Number)
End If

Professional Edition only:

PutFileDirect

Transfers data to the remote file specified by RemoteFile. Rather than sending a local file, the DirectOut event fires whenever the EZFTP control is ready to send more data over the connection.

If the application creates data to send over an FTP connection, it may be more efficient to send the data directly, rather than writing it to a file and then sending it with the PutFile method.

GetFileDirect

Receives the remote file specified by RemoteFile using the DirectIn event, rather than writing data to a file.

If you transfer data from an FTP server and then process it, it may be more efficient to process it as it's received rather than writing it to a file first.

Events

NextDirectoryEntry (FileName As String, Attributes As Long, Length As Double)

Fires for each file that is returned by the remote FTP server after a GetDirectory method is used.

FileName Contains the name of the file on the remote system

Attributes Contains bit flags indicating the type of the file.

Length Contains the length of the file in bytes.

Professional Edition only:

TransferProgress(BytesTransferred As Long, TotalBytes As Long)

Fires for every 512 bytes transferred during a GetFile or PutFile method when AsyncMode is false. Can be used to update a progress indicator. You may also set the CancelTransfer property in this event to abort a file transfer.

DirectIn(InData As String, InSize As Integer)

Fires when data is received after a GetFileDirect call. Always ensure that the InSize variable is taken into account when accessing InData as InData may be longer than the data actually received.

DirectOut()

Fires when the control is ready to send more data during a PutFileDirect call. During this event, data to be sent to the remote server is placed into the OutData buffer and the length of the buffer into the OutSize property. Supplying a OutSize of zero will close the file on the remote system and terminate the PutFileDirect call.

Status(EventCode As Long, Status As Long)

Fires whenever data is transferred over the FTP connection. EventCode can be one of the following values:

10 Resolving hostname
11 Name Resolved
20 Connecting to server
21 Connected to server
30 Sending request
31 Request sent
40 Receiving response
41 Response received
50 Closing connection
51 Connection closed
60 Internal handle created
70 Internal handle closed
100 Request complete

During EventCode 41, the variable Status contains the length of data received for this response.

During EventCode 100, the variable Status contains zero if the transaction (logging on, getting a directory, transferring a file, etc.) completed or an error code according to this table:

12001 Out of handles
12002 Timeout
12003 Extended error
12004 Internal error
12005 Invalid URL
12006 Unrecognized scheme
12007 Name not resolved
12008 Protocol not found
12009 Invalid option
12010 Bad option length
12011 Option not settable
12012 Shutdown
12013 Incorrect user name
12014 Incorrect password
12015 Login failure
12016 Invalid operation
12017 Operation canceled

Error Handling

The RemoteDirectory property when written to and all methods can generate runtime errors. For example, attempting to receive a file that doesn't exist with the GetFile method will generate a runtime error. Therefore, it is important to ensure that error handling routines are provided for the methods and the RemoteDirectory property.

If an error occurs, Err.Number can be set to one of the following values. The errors without an explanation should never be seen. If you do encounter one of these errors, be sure to let us know what you did to generate the error. Send email to coolstf@intr.net.

Additionally, Err.Description contains an description of the error, plus any extra error information returned by the FTP interface, separated by a colon. For example:

Unable to connect to FTP server:
220-Welcome to the Internet Interstate FTP server!
220-
220 sheldon FTP server (Version wu-2.4(1) Thu Aug 17 09:56:25 EDT 1995) ready.
331 Password required for xx.
530 Login incorrect.
221 Goodbye.

Aborting Transfers

This section is only applicable to the Profession Edition of EZFTP and when AsyncMode is false.

If you abort a transfer by setting the CancelTransfer property, be aware that you will probably need to close and then re-establish the connection to the FTP server. Whether you have to do this or not depends on the FTP server being used, but to be safe, we recommend doing it each time after a cancelled transfer.

To close and then re-establish a connection, use code like:

temp$ = EZFTP1.RemoteDirectory
EZFTP1.GetFile
If AbortedFlag = True Then
EZFTP1.Disconnect
EZFTP1.Connect
EZFTP1.RemoteDirectory = temp$
AbortedFlag = False
Endif

License

Registered Version License

NOTE: If you do not agree to the terms of this license, promptly return the software for a full refund. Use of the EZFTP ActiveX Control assumes agreement with this license.

1. Products Licensed

Payment of registration fees for the EZFTP ActiveX Control includes rights to use:

2. Developer Usage

The licensed developer of the EZFTP ActiveX Control may develop applications using the EZFTP ActiveX Control on a single computer only. Any additional developers MUST purchase a separate license.

The licensed developer may freely distribute the EZFTP ActiveX control with their applications. UNDER NO CIRCUMSTANCES MAY THE EZFTP.LIC FILE BE DISTRIBUTED.

If the licensed developer also licenses the source codes to the EZFTP ActiveX control, the licensee agrees not to distribute the sources to any third party nor to use the sources to create a directly competitive product.

3. WININET.DLL Usage

WININET.DLL is provided for compatibility with the Windows® 95 and Windows NT operating systems. In order to use and distribute this file, the developer must agree to Microsoft's terms relating to this add-on component as described in the Microsoft license for Windows 95 or Windows NT.

4. Suitability

The EZFTP ActiveX Control is provided as-is. The licensee should ensure that the EZFTP ActiveX Control meets their needs before distributing the control. UNDER NO CIRCUMSTANCES WILL COOL.STF BE HELD LIABLE FOR USE OF THE EZFTP ACTIVEX CONTROL.

5. Support

Support of the EZFTP ActiveX Control is given only to licensed developers. Questions should be emailed to coolstf@intr.net.

Freeware Version License

NOTE: If you do not agree to the terms of this license, promptly remove EZFTP from your system. Use of the EZFTP ActiveX Control assumes agreement with this license.

1. Developer Usage

You may use the EZFTP ActiveX control for any purpose and freely distribute it both with your applications and to other developers. If distributing it to other developers, you must include the ZIP file and not just the OCX file.

2. WININET.DLL Usage

WININET.DLL is provided for compatibility with the Windows® 95 and Windows NT operating systems. In order to use and distribute this file, the developer must agree to Microsoft's terms relating to this add-on component as described in the Microsoft license for Windows 95 or Windows NT.

3. Suitability

The EZFTP ActiveX Control is provided as-is. The licensee should ensure that the EZFTP ActiveX Control meets their needs before distributing the control. UNDER NO CIRCUMSTANCES WILL COOL.STF BE HELD LIABLE FOR USE OF THE EZFTP ACTIVEX CONTROL.

4. Support

Support is not provided on this version of the control.