FTP Client Engine
Users Manual
(FCE_USR)
Version 3.0
Sept 14, 2009
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2009
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815 USA
Voice : 1.256.881.4630
email : info@marshallsoft.com
web : www.marshallsoft.com
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1 Introduction
1.1 Documentation2 FTP Client Library Overview
1.2 Technical Support
1.3 How to Purchase
1.4 Updates
1.5 Customer ID
1.6 License File
2.1 Keycode3 Using FTP
2.2 Dynamic Link Library
2.3 GUI and Console Mode
2.4 Getting Started Using the Library
3.1 FTP Basics4 Theory of Operation
3.2 Private and Anonymous Access
3.3 ASCII and Binary Modes
3.4 Passive Mode
3.5 Socket Address In Use Error
3.6 Renaming Files on the Server
3.7 Proxy Servers
3.8 Proxy Protocols
3.9 Firewalls
3.10 Renaming Files "On The Fly"
3.11 Using Append Mode for Uploads
3.12 Using Append Mode for Downloads
3.13 Getting File Lengths
3.14 Adjusting Performance
3.15 Auto Dial
3.16 Secure FTP
3.17 FTP Passwords
3.18 S/Key Password Encryption
3.19 Progress Bars
3.20 Network Connectivity
4.1 Indirect Method5 Development Languages Supported
4.2 Direct Method
5.1 Using FCE with Supported Languages6 Resolving Problems
5.2 Using FCE with Unsupported Languages
7 Versions of FCE
7.1 Evaluation Version8 Legal Issues
7.2 Academic Version
7.3 Professional Version
8.1 License9 FCE Function Summary
8.2 Warranty
10 FCE Error Return Code List
The FTP Client Engine (FCE) is a component DLL library providing direct control of the FTP protocol. The FCE component library can be used for both anonymous and private FTP sessions and can be used with any application capable of calling the Windows API.
A simple interface provides the capability to quickly develop FTP software applications to connect to any FTP server, navigate its directory structure, list files, upload files, delete files, append files, and download files using the FTP protocol.
FTP functions can easily be called from any program written in any programming language (such as C/C++, Visual Studio .NET, Visual C#, Delphi, Visual Basic, VB.NET, PowerBASIC, Visual FoxPro, dBase, Xbase++, COBOL, etc.) that is capable of calling Windows API functions.
The User's Manual applies to the FTP Client Engine (FCE) for all supported programming languages. It discusses FTP processing as well as language independent programming issues and provides purchasing and licensing information.
We have versions of the FTP Client Engine SDK for C/C++ (FCE4C), Delphi (FCE4D), Visual Basic (FCE4VB), PowerBASIC (FCE4PB), Visual FoxPro (FCE4FP), dBase (FCE4DB) and Alaska Xbase++ (FCE4XB). Purchase a developer license for one software development language and use it with all others. All versions of FCE use the same DLLs (FCE32.DLL and FCE64.DLL), however, the examples provided for each version are written and tested for the specified computer development language.
The FTP Client Engine DLLs (FCE32.DLL and FCE64.DLL) run under all versions of Windows (Windows 95, Windows 98, Windows ME, Windows 2000, Windows NT, Windows Server 2003, Windows XP and Windows Vista. The 64-bit version (FCE64.DLL) runs with 64-bit applications running under Vista/x64.
Fully functional versions of our FTP Client software components are provided so that the developer can test the FCE library in their environment. The evaluation version as well as a list of the many FTP Client library features provided can be found on our website at:
http://www.marshallsoft.com/ftp-client-library.htm
The complete set of documentation consists of three manuals in two formats. This is the second manual (FCE_USR) in the set.
Each manual comes in three formats:
The FCE4x Programmer's Manual is the computer language specific manual. All language dependent programming issues including installation, compiling and example programs are discussed in this manual. Language specific manuals are as follows:
The FCE User's Manual (FCE_USR) discusses FTP processing as well as language independent programming issues. License and purchase information is also provided. Read this manual after reading the FCE_4x Programmer's Manual.
The FCE Reference Manual (FCE_REF) contains details on each individual FCE function.
All documentation can also be accessed online at http://www.marshallsoft.com/ftp-client-library.htm
We want you to be successful in developing your applications using our FTP Client Library! We are committed to providing the best, robust component library that we can. If you have any suggestions or comments, please let us know.
If you are having a problem using FCE, refer to Section 6.0 "Resolving Problems". If you still cannot resolve your problem, email us at
support@marshallsoft.com
To avoid having your email deleted by our Spam scanners, begin the subject with "MSC HELP" or with the product name (FCE4C, FCE4VB, etc.). Zip up any attachments and send plain ASCII text email only.
Contact us by phone at 1.256.881.4630 between 7:00 AM - 7:00 PM CST Monday-Thursday and 7:00 AM -5:00 PM Friday.
The latest versions of our products are available on our web site at
http://www.marshallsoft.com
and on our anonymous FTP site at
ftp://ftp.marshallsoft.com/pub
Registered users can update (for a period of one year) to the latest DLL's at
http://www.marshallsoft.com/update.htm
A developer license for the FTP Client Engine Library may be purchased for $115 (USD) for electronic (email) delivery, or $295 (USD) with ANSII C source code for the DLLs. This price is good for one year from the release date.
The fastest and easiest way to order is on our web site at
http://www.marshallsoft.com/order.htm
Multiple copy discounts (3 or more) and site licenses are available. Please call for details.
We accept American Express, VISA, MasterCard, Discover, checks in US dollars drawn on a US bank, International Postal Money Orders (such as Western Union), and purchase orders (POs) within the USA from recognized US schools and companies listed in Dun & Bradstreet.
You can also order by completing INVOICE.TXT (pro forma invoice) and emailing (info@marshallsoft.com), mailing (see our address at top), or faxing it to us. Our fax number will be provided upon request.
For credit card orders, be sure to include the account number, the expiration date, the exact name on the card, and the complete card billing address (the address to which the credit card bill is mailed- not the banks). Please include the Card Verification Code (last 3 numbers printed on the back of Visa, MasterCard and Discover cards, or the 4 numbers of the front of American Express cards.) The cardholder's signature is required on faxed orders.
The purchased package includes:
We offer an "academic price" with a 40% discount for prepaid email orders to faculty and full time students currently enrolled in any accredited high school, college, or university. The software must be used for educational purposes. The academic discount does not apply to source code.
To qualify for the discount, your school must have a web site and you must have an email address at your school. When ordering, ask for the "academic discount", or enter "student at" (or "faculty at") and your schools web site address (URL) in the comments field of the order form on our web site order page. Your order will be sent to your email address at your school.
This offer is not retroactive and cannot be used with any other discount. Products bought with academic pricing cannot be used for any commercial purpose.
Source code is available for the purpose of re-compiling FCE32.DLL. Source code for the DLL library is standard ANSI C. The source code for FCE32.DLL is copyrighted by MarshallSoft Computing and may not be released in whole or in part.
There are two ways to order Source Code for the FTP Client Engine Library SDK.
When a developer license is purchased for the FTP Client Engine Library SDK, the developer will be sent a new set of DLLs plus a license file (FCExxxxx.LIC) that can be used to update the registered DLL (does not include source code) for a period of one year from purchase. Updates can be downloaded from
http://www.marshallsoft.com/update.htm
After one year, the developer license must be updated to be able to download updates. The developer license can be updated for $30 if ordered within one year from the original purchase (or previous update). After one year, licenses can be updated for $55 ($75 after 3 years).
Source code previously purchased may be updated for $100 in addition to the cost of the update ($30, $55 or $75).
Note that the registered DLL's never expire.
The Customer ID is the 4 or 5 digits following the product name (FCE) in the license file. For example, customer 1234 would receive license file FCE1234.LIC. Provide the Customer ID in the SUBJECT of an email when contacting us for technical support (FCE4C 1234).
A license file, FCExxxx.LIC, where "xxxx" is the 4 or 5- digit customer ID is provided with each developer license. The license file is an encrypted binary file used for updating FCE as explained in section 1.4 "Updates". The license file is required in order to create (or update) the registered DLLs. The license file can be found in the /DLLS directory created after SETUP is run.
The FTP Client Engine Library has been tested on multiple computers running Windows 95/98/Me/2003/XP/Vista/Vista x64 and Windows NT/2000.
When a developer license is purchased, the developer will receive a new set of DLLs and a keycode for the FCE DLL's. Pass this keycode as the argument to fceAttach. The keycode will be found in the file named "KEYCODE". The keycode for the evaluation version is 0. The keycode for the registered version will be a unique 9 or 10 digit number. Note: Your keycode is NOT your Customer ID/Registration number.
The FTP Client Engine Library SDK includes a Win32 [FCE32.DLL] and Win64 [FCE64.DLL] dynamic link libraries (DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to a static library that is bound at link time to each and every application that uses it.
FCE functions can be called from WIN32 console mode programs as well as GUI programs. A "console mode" program is a Windows 95/98/Me/NT/2000/2003/XP/Vista WIN32 command line program running in a command window. Although console mode programs look like DOS programs, they are WIN32 programs that have access to the entire Windows address space.
The first FTP Client Engine (FCE) function that should be called is fceAttach, which initializes the FCE library and allocates necessary resources. fceAttach is typically called in the initialization section of your application.
After fceAttach is called, you are ready to connect to a FTP server with fceConnect. Once connected, you are ready to call the other FCE functions.
After completing your FTP session, the connection to the server can be closed with fceClose. The fceClose function should not be called if the previous fceConnect failed.
Before exiting your application, fceRelease should be called. fceRelease should not be called if fceAttach failed.
The best way to get familiar with FCE is to try out one of the example programs. The example programs are described in the FCE4x Programmer's Manual. . The "x" in FCE_4x specifies the host programming language such as C for C/C++, VB for Visual Basic, etc. the example source is written in.
The FTP (File Transfer Protocol) protocol is defined by Internet document RFC 959. It is used to copy files between a FTP client and a FTP server over a TCP/IP connection using well-known port 21.
There are two types of FTP connections: private and anonymous. However, some FTP servers do not accept anonymous connections.
Three parameters are necessary in order to connect to a FTP server, as follows:
These FTP parameters are hard coded in most of the examples. However, these parameters could be read from the keyboard, from a file, from a dialog box at runtime, etc., as well as being hard coded.
For private connections, the users account name and password must be specified.
Some FTP servers allow "anonymous" access, which is usually download only. For anonymous connections, the user name is "anonymous" and the password is the user's email address.
The default FTP access mode is ASCII text. In order to upload or download any file that is not ASCII text, the transfer mode must be set to binary with the fceSetMode function first. A binary file uploaded or downloaded in ASCII mode may be corrupted.
FCE supports "Passive" mode. Passive mode means that the server specifies the data port rather than the client when listing or transferring files. Using passive mode is often necessary to get past a firewall.
Passive mode is an optional FTP command, so that although most FTP servers support passive mode, there are some that do not. Passive mode can be enabled by calling:
fceSetInteger(Chan, FCE_SET_PASSIVE, 1)
The use of passive mode is recommended when possible.
The FTP protocol specifies that data sockets are reserved after use for some fixed period of time. This means that a data socket cannot be immediately re-used. When making multiple calls to list or transfer files, FCE will increment the data socket number. However, if you terminate and then restart your application while the FTP server still has your last data socket reserved, and attempt to list or transfer files, you will get the error "socket address already in use". There are three solutions to this problem:
Files can be renamed on the FTP server by using the fceCommand function. For example, to rename the file "oldname.txt" to "newname.txt" on the server, use (C/C++ example):
// rename "oldname.txt" to "newname.txt" on the server Code = fceCommand(Chan, "RNFR oldname.txt") Code = fceCommand(Chan, "RNTO newname.txt")
Also refer to Section 3.10, 'Renaming Files "On The Fly"'.
In order to use a FTP proxy server, the FTP client connects to the proxy server, and then the proxy server connects to the remote FTP server. The sequence of connection events is as follows:
The proxy server requires that a particular port (not well known port 21) be used when connecting to it. The proxy server port number is specific to the particular proxy server. Refer to the documentation for the specific FTP proxy server to find out the port number and the method for specifying connection parameters such as the user name and password.
The most common method for providing remote server parameters to a proxy server is sometimes known as "PROXY USER". For example, to connect to ftp.marshallsoft.com as user "anonymous" with password "test@marshallsoft.com" through the proxy server running at 10.0.0.1 on proxy port 4421;
fceSetInteger(0, FCE_SET_FTP_PORT, 4421)
fceConnect(0, "10.0.0.1", NullString, NullString)
fceCommand(0, "USER anonymous@ftp.marshallsoft.com")
fceCommand(0, "PASS test@marshallsoft.com")
Note that the user name and password in the above example are for the remote FTP server, not for the proxy FTP server. The "NullString" refers to a string (or buffer) in which the first byte is a hex zero. Refer to the PROXY example for a complete program.
Check the documentation provided with a particular proxy server for a description of the proxy protocol that it requires. Also refer to Section 3.8, "Proxy Protocols".
There are no formally defined proxy connection protocols. However, the following lists the most common proxy connection protocols. Refer to the PROXY example program for an example using the "PROXY USER" connection protocol. Note that ProxyUser and ProxyPass are not always used. The following parameters are used for connection to a remote FTP site through a proxy server.
ProxyServer = Proxy server name or IP address.
ProxyUser = Proxy user name (optional).
ProxyPass = Proxy password (optional).
ProxyPort = Proxy port number. Consult your proxy documentation.
RemoteServer = Remote FTP server name or IP address.
RemoteUser = Remote FTP server user name.
RemotePass = Remote FTP server password.
USER RemoteUser@RemoteServer
PASS RemotePass
USER ProxyUser
PASS ProxyPass
USER RemoteUser@RemoteServer
PASS RemotePass
USER ProxyUser@RemoteServer ProxyUser
PASS RemotePass
USER ProxyUser@RemoteUser@RemoteServer
PASS RemotePass
OPEN RemoteServer
USER RemoteUser
PASS RemotePass
Check the documentation provided with a particular proxy server for a description of the proxy protocol that it requires.
Firewalls operate transparently with respect to all TCP/IP programs, monitoring inbound and outbound traffic. Firewalls can filter packets based on their contents, source addresses, destination addresses, and port numbers. If the traffic meets criterion of the firewall, it is allowed, otherwise it is not.
Firewalls are often combined with proxy servers. Firewalls usually require the use of passive mode. Refer to Section 3.4 "Passive Mode".
When a client program attempts to connect to a FTP server, the first thing that the server does is accept the connection, then send its greeting message - all before the actual logon. If a server's greeting message is not received, then one of the following may have occurred: an incorrect server name or IP address was specified, the wrong port (a few servers don't use standard port 21) was specified, there is a connectivity problem (problem with cable, DSL, Windows itself, etc.), or a firewall is blocking the connection.
If a connection to the server is successful, and all commands work up to the point prior to attempting to get a listing or upload/download a file, then the problem is almost always that the data port chosen is being blocked on one side or the other. Often using passive mode (which allows the server to choose the data port) will resolve this problem, although passive mode is not supported by all servers.
If the connection is being blocked by a local firewall (as opposed to the server's firewall) then the local firewall will need to be reconfigured to unblock a range of data ports. Note that a range of data ports can be specified by using:
fceSetInteger(FCE_SET_FIRST_DATA_PORT, first-data-port-to-use)
fceSetInteger(FCE_SET_LAST_DATA_PORT, last-data-port-to-use)
Once a data port is used, the port is freed, but it cannot be reused for a period of time determined by the server. To be on the safe side, use one data port for each file listing/upload/download that will occur within any 60-second time period.
Files can renamed as they are being uploaded or downloaded by specifying the filename in "oldname:newname" format. For example, to download the file "serverfile.txt" from an FTP server renamed as "myfile.txt" on the client computer, call
fceGetFile(Chan, "serverfile.txt:myfile.txt")
Note that there are no extra spaces in the filename string.
The default filename delimiter is the ':' character, but can be changed to any character necessary. For example, to change the filename delimiter from ':' to '$', call
fceSetInteger(Chan, FCE_SET_RENAME_DELIMITER, '$')
Provided that a FTP server supports it, uploads can be appended to the existing file of the same name (on the server). This can be done by setting append mode and (optionally) a file offset before calling fcePutFile.
For example, to append file "myfile.txt" to the server,
fceSetInteger(Chan, FCE_SET_APPEND_MODE, 1)
fcePutFile(Chan, "myfile.txt")
To append "myfile.txt", but begin reading the file at file offset 1024 on the client computer,
fceSetInteger(Chan, FCE_SET_APPEND_MODE, 1)
fceSetInteger(Chan, FCE_SET_CLIENT_OFFSET, 1024)
fcePutFile(Chan, "myfile.txt")
In order to continue an interrupted upload, the offset used should be the existing size of the file on the server. The client offset (if specified) applies only to the client computer not to the server. The server file offset cannot be specified for uploads. Append mode and the file offset must be set for every file before calling fcePutFile.
Provided that an FTP server supports it, downloads can be appended to the existing file of the same name on the client computer. This is done by setting append mode, a server file offset, and a client file offset before calling fceGetFile.
For example, to download file "myfile.txt"' beginning at file offset 1024 on the server to the client computer, also at file offset 1024,
fceSetInteger(Chan, FCE_SET_APPEND_MODE, 1)
fceSetInteger(Chan, FCE_SET_SERVER_OFFSET, 1024)
fceSetInteger(Chan, FCE_SET_CLIENT_OFFSET, 1024)
fceGetFile(Chan, "myfile.txt")
In order to continue an interrupted download, both the client file offset and the server file offset should be set to the existing size of the file on the client computer. Append mode and the file offsets must be set for every file before calling fceGetFile.
According to the FTP protocol standard, there is no standard for the format of full FTP listings returned by the server. The format will vary by host operating system, and sometimes between various makes of FTP servers. However, most servers return the full listing exactly as reported by the host operating system. For UNIX, it is typically "ls -l". For Windows, it is typically "dir".
To get the file length of a particular file, request a full listing entry by calling
fceGetList(Chan, FCE_FULL_LIST, DataBuffer, DataBufferSize)
then call fceExtract to extract each field in turn. One of the fields, depending on the host's operating systems, will be the field length.
A few FTP servers have trouble receiving large buffers sent by the client. However, for most servers, the write performance can be increased by enlarging the write buffer size from 1024 (default value) to 8192 and reducing the sleep time set to 0:
fceSetInteger(0, FCE_SET_WRITE_BUFSIZE, 8192)
fceSetInteger(0, FCE_SET_SLEEP_TIME, 0)
If uploading is much slower than you believe that it should be, try calling
fceSetInteger(0, FCE_STATUS_BEFORE_WRITE, 0)
This will direct FCE to not check the WRITE status of a socket before writing to it.
There are some FTP servers that, for various reasons, cannot keep up with the load of FTP requests from FTP clients. In order to make it easier for those servers, FCE can be programmed to run slower. For example,
fceSetInteger(0, FCE_SET_SLEEP_TIME, 150)
fceSetInteger(0, FCE_SET_MIN_LINE_WAIT, 250)
fceSetInteger(0, FCE_SET_MIN_RESPONSE_WAIT, 3000)
To allow Dial-Up Networking (DUN) to dial up an ISP when the accessing the Winsock (WIN32 only):
HKEY_CURRENT_USER/Software/Microsoft/Windows/CurrentVersion/InternetSettings/EnableAutod ial`
HKEY_CURRENT_USER/Software/Microsoft/Windows/CurrentVersion/InternetSettings/EnableAutod isconnect.
HKEY_CURRENT_USER/Software/Microsoft/Windows/CurrentVersion/InternetSettings/DisconnectI dleTime
This changes the idle time (until disconnect) from 20 minutes (hex 14) to one minute.
Windows NT and XP users can control auto dialing by editing the setting in the "Dial-Up Networking" (DUN) window. Choose "More", "User Preferences", then "Appearance".
The Dial-Up Networking window can also be displayed by executing the Microsoft Windows program RASPHONE.EXE.
Start Windows help, then type "autodial", then click "configuring". Follow all directions, including "notes". Note that the "Remote Access Auto Connection Manager" must be enabled.
The MarshallSoft DUN Dialer (MDD) can dial up (and hang up) under program control. MDD works under all Windows 32-bit operating systems (Win 95, 98, Me, XP, Vista, NT, 2000,2003).
For more information, see the MDD product page at www.marshallsoft.com/mdd4c.htm (for C/C++), www.marshallsoft.com/mdd4vb.htm (for Visual Basic), etc. The cost for MDD is discounted when ordered at the same time as FCE.
The FTP protocol itself is not secure. If sensitive or private data is to be exchanged, some form of FTP security should be considered.
Unfortunately, there are quite a few differing solutions to FTP security, and none of them are part of the standard FTP protocol. There are, however, several solutions to the problem of FTP security. The FTP Client Engine supports 3.16.1 through 3.16.4 below.
Changing the FTP server's port provides a minimal degree of security. The idea is that hackers will not know which port to attack. The port chosen should be changed on a regular basis. Most FTP servers and clients can use non-standard ports.
Encrypt all files using strong encryption such as "Pretty Good Privacy". Although hackers may be able to intercept FTP passwords and download copies of your encrypted files, they will not be able to decode them unless they know the encryption key. Standard FTP clients and servers can be used.
Set up a "Virtual Private Network", which will encrypt all traffic between VPN nodes. VNP products may be either software or hardware, and are widely available. They also allow the use of standard FTP servers and clients.
Similar to VPN, secure FTP proxy servers can be used to automatically encrypt all traffic between two end points. Using secure FTP proxy servers allows the use of standard FTP servers and clients.
Use one of several "secure" FTP servers that typically implement SSL, TSL, or SFTP security protocols. This approach also requires the use of an FTP client using the same security protocol and requires X.509 certificates. Currently the FTP Client Engine does not support these protocols, however, they are included in the documentation for completeness.
When a connection is made to a FTP server, a user name and password are normally supplied. However, occasionally the FTP server will be configured to require "no password". This can mean two different things:
The S/KEY "One-Time Password System", defined by RFC 2289, encrypts passwords before sending them. The actual password is never transmitted in the clear as is the case for standard FTP.
A FTP server that supports the one time password system will respond to the client's USER command with the challenge string "otp-md5 <sequence> <seed>" to which the client responds with the 6 word password phrase as calculated from the users password according to RFC 2289. For example,
R: 220 Serv-U FTP Server v6.3 for WinSock ready...
S: USER mike
R: 331 Response to otp-md5 999 hello required for skey.
S: PASS NEIL JULY NONE EMIT FLEW MUDD
R: 230 User logged in, proceed.
If "otp-md5" is not seen, FCE sends the user's password normally (in the clear) as required by the FTP protocol. Thus, S/KEY password encryption is performed automatically when FCE connects to an S/KEY enabled FTP server.
The function fceGetInteger(0, FCE_SKEY_WAS_SEEN) will return TRUE (none zero) if the challenge string "otp-md5" was seen in the server's response to the client's USER command.
There are several FTP servers that support S/KEY password encryption. For Windows,
Direct mode (calling fceDriver) must be used in order to periodically (for example, each second) get the transfer byte count as the upload/download progresses.
In order to implement an upload progress bar, it is necessary to know the size of the file to be uploaded, which can be found by calling fceGetLocalFSize. For implementing a download progress bar, the size of the file on the server must be known. This is complicated by the fact that there is NO standard (long) listing format. However, the file size is almost always the first numeric field (beginning with the third), and can be found by calling fceFileLength.
The percentage uploaded is computed as
BytesWritten = fceGetInteger(0, FCE_GET_FILE_BYTES_SENT)
FileSize = fceGetLocalFSize(0, FilenamePointer)
PerCentage = (100 * BytesWritten) / FileSize
and the percentage downloaded is computed as
BytesRead = fceGetInteger(0, FCE_GET_FILE_BYTES_RCVD)
FileSize = fceFileLength(LongListingPointer, 3, 7)
PerCentage = (100 * BytesRead) / FileSize
Also see the WINFTP example program that displays the percentage uploaded/downloaded at runtime.
It is possible to detect loss of network connectivity in some situations by calling
fceGetInteger(0, FCE_GET_CONNECT_STATUS)
However, depending on many factors, loss of network connectivity cannot always be detected. The only 100% method of detecting loss of connectivity to the server is to send a "NOOP" command to the server and then reading its response. Calling the function fceHello can perform this.
fceHello(0)
The FTP Client Engine (FCE) is state driven. This means that each call to FCE functions (that access the server) is broken down into sequential steps, each of which can be performed within a second or so. There are two ways in which FCE is used: (1) indirect use of the state engine, and (2) direct use of the state engine.
The first (or "indirect") way to use the FCE library is to allow all FCE function calls to automatically call the FCE driver (fceDriver) before returning. This is the default way that FCE operates.
The major advantage of this approach is that each FCE function returns only after it has completely finished. The disadvantage of this approach is that some functions may run for a considerable amount of time during which time the calling application must wait.
Refer to the GET example program for an illustration of this approach.
The second (or "direct") way that the FCE state driver is used is to call it (fceDriver) directly. In order to operate this way, the function fceSetInteger must be called to set the AUTO_CALL flag to off:
fceSetInteger(Chan, FCE_SET_AUTO_CALL_DRIVER, 0)
After the above statement is executed, the state driver (fceDriver) must be called after all of the other FCE functions that access the server. For example (code example),
... enable direct mode (disable indirect mode).
fceSetInteger(Chan, FCE_SET_AUTO_CALL_DRIVER, 0)
... connect to server.
Code = fceConnect(...)
If Code < 0 Then
... handle error here.
End If
... run the driver.
Loop
... call the driver
Code = fceDriver(Chan)
If Code < 0 Then
... handle error here.
Exit Loop
End If
If Code = 0 Then
... fceDriver has finished.
Exit Loop
End If
... display progress or do other processing here.
End Loop
... enable indirect mode (disable direct mode).
fceSetInteger(Chan, FCE_SET_AUTO_CALL_DRIVER, 1)
The major advantage of the direct approach is that the calling application can perform other work such as reporting the progress of large downloads. The disadvantage is the extra code that must be written to call fceDriver.
Refer to the WINFTP example program for an illustration of this approach.
We have versions of the FTP Client Engine (FCE) component library for C/C++ and .NET (FCE4C), Borland Delphi (FCE4D), Visual Basic and VB.NET (FCE4VB), PowerBASIC (FCE4PB), Visual FoxPro (FCE4FP), dBase (FCE4DB), and Alaska Xbase++ (FCE4XB). All versions of FCE use the same DLLs (FCE32.DLL and FCE64.DLL). Evaluation versions for these may be downloaded from our website at
http://www.marshallsoft.com/ftp-client-library.htm
The FTP Client Engine DLL's can also be used with any application written in any language capable of calling the Windows (95/98/Me, NT/2000/XP/2003/Vista) API.
Once a developer license is purchased for a particular programming language version of the FTP Client Engine SDK (FCE), the same license can be used with all other supported programming languages. Supported languages are C/C++, Visual Basic, PowerBASIC, Delphi, Visual FoxPro, Visual dBase, Xbase++, and (Fujitsu) COBOL.
For example, assume that you have previously downloaded and installed the registered version of FCE4C and now you want to also call FCE functions from Visual Basic.
A quicker and easier way would be to request multiple programming versions of FCE when a developer license is purchased. There is no additional charge.
The FTP Client Engine DLL can be used with any application written in any language capable of calling the Windows (95/98/ME, NT/2000/XP/2003/Vista) API.
Declaration files have been defined for the following languages:
C/C++ and .NET FCE.H
Visual Basic and VB NET FCE32.BAS
VBA (Excel, Access,...) FCE32.BAS
PowerBASIC FCE32.PBI
Borland Delphi FCE32.PAS
Fujitsu COBOL FCE32.CBI
Fortran FCE32ABS.INC and FCE32DEC.INC
Visual FoxPro FCE32.FOX
Visual dBase FCE32.CC
Alaska Xbase++ FCE32.CH
Additional declaration files will be added. Email us if you need a declaration not listed above. If you have interfaced FCE to an unusual language, email us the declaration file!
First, be sure you are passing the proper keycode. Refer to section 2.1 "Keycode". Before attempting to run any of the example programs, you should already be able to connect to the Internet (or your TCP/IP LAN) and run your normal FTP client, such as the Microsoft command line FTP client FTP.EXE (in the Windows directory).
If you have trouble connecting to an FTP server, try using the IP address instead of the server name. If using the IP address works but the server name does not, the problem lies with the Domain Name System (DNS) lookup. If this does not solve your connection problem, try connecting using TELNET, located in the Windows or Windows/System32 .
If you cannot get your application to run properly, first compile and run the example programs. If you call us to report a possible bug in the library, the first thing we will ask is if the example programs run correctly. All example programs have been compiled and tested.
Be sure to test the code returned from all FCE functions. Then, call fceErrorText to get the text associated with the error code. All functions return an integer code. Negative values are always errors.
For example (C Example):
Code = fceConnect(0,"ftp.marshallsoft.com","mike", "mike");
if(Code<0)
{static char Buffer[64];
fceErrorText(0,Code,Buffer,64);
printf("Error %d: %s\n", Code, Buffer);
}
Another good idea is to turn on logging by calling
fceSetString(Chan, FCE_LOG_FILE, logfilename)
If you encounter a problem that you cannot resolve, email us at info@marshallsoft.com. To avoid having your email deleted by our Spam scanners, begin the subject with FCE or MSC HELP. Zip up any attachments and send plain ASCII text email only.
If you still get the evaluation screen (popup window) after purchasing a developer license, the problem is that Windows is finding the evaluation DLL before the registered DLL. The solution is to delete (or zip up) all evaluation versions of FCE32.DLL (or FCE64.DLL) and run the SETUP program again.
If you get "error -74" when calling fceAttach, the problem is that the keycode passed to fceAttach does not match the keycode in the DLL's. This is caused by (1) using the evaluation keycode (value = 0) with the registered DLL, or (2) using the registered keycode with the evaluation DLL.
We recommend the following steps if you believe that you have discovered a bug in the library:
If the problem is an error in the library and can be solved with an easy work-around, we will publish the work-around. If the problem requires a modification to the library, we will make the change and make the modified library available to our customers without charge.
Review the FCE Programmer's and Reference Manuals. We also suggest reading Section 3 "Using FTP".
The FTP Client Engine (FCE) component library is available in three versions. All three versions have identical functionality.
The evaluation version can be differentiated from the other two versions by:
The academic version can be differentiated from the other two versions by:
The professional version can be differentiated from the other two versions by:
The professional version compiled DLL may be distributed royalty free with your compiled applications as specified by the software license. However, the Keycode to the DLL can NOT be distributed. The Professional version may be used for commercial purposes. Licensing information is provided in Section 10.1
This license agreement (LICENSE) is a legal agreement between you (either an individual or a single entity) and MarshallSoft Computing, Inc. for this software product (SOFTWARE). This agreement also governs any later releases or updates of the SOFTWARE. By installing and using the SOFTWARE, you agree to be bound by the terms of this LICENSE. If you do not agree to the terms of this LICENSE, do not install or use the SOFTWARE.
MarshallSoft Computing, Inc. grants a nonexclusive license to use the SOFTWARE to the original purchaser for the purposes of designing, testing or developing software applications. Copies may be made for back-up or archival purposes only. This product is licensed for use by only one developer at a time. All developers working on a project that includes a MarshallSoft Software SDK, even though not working directly with the MarshallSoft SDK, are required to purchase a license for that MarshallSoft product.
The academic registered DLL's may not be distributed under any circumstances, nor may they be used for any commercial purpose.
The professional registered DLL's may be redistributed (without royalty) as part of the user's compiled application. The registered DLL's may NOT be distributed as part of any software development system (compiler or interpreter) without our express written permission. When the software is registered, a key-code will be provided, which enables access to the registered DLL's. This key-code may NOT be distributed or made known.
The SOFTWARE is owned by MarshallSoft Computing, Inc. and is protected by United States copyright laws and international treating provisions. This SOFTWARE is being licensed and not sold.
MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE.
Some states do not allow the exclusion of the limit of liability for consequential or incidental damages, so the above limitation may not apply to you.
This agreement shall be governed by the laws of the State of Alabama and shall inure to the benefit of MarshallSoft Computing, Inc. and any successors, administrators, heirs and assigns. Any action or proceeding brought by either party against the other arising out of or related to this agreement shall be brought only in a STATE or FEDERAL COURT of competent jurisdiction located in Madison County, Alabama. The parties hereby consent to in personam jurisdiction of said courts.
Refer to the FCE Reference Manual (FCE_REF) for detailed information on the FCE functions. A one-line summary of each function follows.
There are 34 functions in the FTP Client Component (FCE) library.
fceAbort Abort FTP session.
fceAttach Attach (initialize) FCE for use.
fceByteToShort Converts from 8-bit ASCII characters to 16-bit.
fceClose Close connection opened with fceConnect.
fceCommand Sends arbitrary command to server [Rename,get status, etc]
fceConnect Connect to FTP server.
fceDelFile Delete file on server.
fceDelServerDir Delete server directory.
fceDriver FCE direct mode driver.
fceErrorText Get text associated with error code.
fceExtract Extract line from LIST buffer.
fceFileLength Gets file length for file on server.
fceGetFile Download (receive) file.
fceGetInteger Get FCE integer parameter for FTP processing.
[GET RESPONSE, CONNECT STATUS, BYTES SENT/RECEIVED, DATA PORT, etc.]
fceGetList Get list of files on server.
fceGetLocalDir Get local directory.
fceGetLocalFList Gets list of files in up/download directory.
fceGetLocalFSize Gets size of file in up/download directory.
fceGetServerDir Get server directory.
fceGetString Get FCE string parameter.
[GET LINE COUNT, SERVER IP, LOCAL IP, FULL RESPONSE etc.]
fceGetTicks Get system ticks.
fceHello Send "NOP" command.
fceIsConnected Get current connection status.
fceMakeServerDir Create directory on server.
fceMatchFile Match next filename in list.
fcePutFile Upload (transmit) file to server.
fceRelease Release FCE.
fceSetInteger Set FCE integer parameter for FTP processing.
[SET DATA PORT.FTP PORT, WRITE BUFSIZE, APPEND MODE, SLEEP
TIME, HIDE PASSWORD, PASSIVE, MASTER INDEX, RESPONSE WAIT, etc.]
fceSetLocalDir Set local directory.
fceSetMode Set XFER mode (ASCII or Binary).
fceSetServerDir Set server directory.
fceSetString Set FCE parameter string.
[SET LOG FILE, BIND TO LOCAL IP, WRITE TO LOG]
fceShortToByte Converts from 16-bit ASCCII characters to 8-bit.
fceToInteger Converts ASCII text to integer.
The complete list of FTP Client Engine Component (FCE) error codes follows.
FCE_ABORTED Internal checksum fails!
FCE_ACCEPT_SILENT Timed out waiting for accept.
FCE_ALREADY_ATTACHED Already attached.
FCE_BAD_STATUS_FLAG Bad status flag passed to fceStatus.
FCE_BUFFER_OVERFLOW List buffer overflow.
FCE_CANNOT_ALLOC Cannot allocate memory.
FCE_CANNOT_COMPLY Cannot comply.
FCE_CANNOT_CREATE_SOCK Cannot create socket.
FCE_CANNOT_OPEN Cannot open file.
FCE_CHAN_OUT_OF_RANGE Channel out of range.
FCE_CONNECT_ERROR Error attempting to connect.
FCE_EOF Socket has been closed.
FCE_EXPIRED Evaluation version expired.
FCE_FILE_IO_ERROR File I/O error.
FCE_INVALID_SOCKET Invalid socket.
FCE_IS_BLOCKING WINSOCK is currently blocking.
FCE_LISTEN_ERROR Listen error.
FCE_LISTENER_SILENT No response on listener socket.
FCE_MODE_NOT_AB Must specify 'A' or 'B' for mode.
FCE_NO_GREETING Missing server greeting message.
FCE_NO_HOST No host name.
FCE_NO_SERVER Cannot find FTP server.
FCE_NO_SOCK_ADDR No available sockaddr structures.
FCE_NOT_ATTACHED Must call fceAttach first.
FCE_NOT_COMPLETED LIST/GET/PUT not completed.
FCE_NOT_SERVER Illegal chars in server name.
FCE_PASS_NULL_ARG PASSWORD not specified.
FCE_PASV_ERROR Cannot find PASV port.
FCE_PORT_RANGE Port number out of range.
FCE_SERVER_ERROR FTP server returned error.
FCE_SERVER_NULL_ARG SERVER not specified.
FCE_SOCK_READ_ERROR Socket read error.
FCE_SOCK_WRITE_ERROR Socket write error.
FCE_TIMED_OUT Socket timed out.
FCE_USER_NULL_ARG USER name not specified.
The numerical value for each error codes is listed in the file fceErrors.txt.