FTP Client Engine
Users Manual
(FCE_USR)
Version 2.6
January 17, 2007
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2007
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815 USA
Voice : 1.256.881.4630
FAX : 1.256.880.0925
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 Updating
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 Using the FTP Client 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 library of functions 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 allows connecting to any FTP server, navigating its directory structure, listing files, sending files, deleting files, and receiving files using the FTP protocol.
The User's Manual applies to the FTP Client Engine (FCE) for all supported languages. It discusses FTP processing, language independent programming issues, as well as 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), Visual 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 (FCE16.DLL or FCE32.DLL), however, the examples provided for each version are written and tested for the specified computer development language.
We also have declaration files and example programs for a few other languages. Check http://www.marshallsoft.com/ftp-client-library.htm for the latest version of our FTP software.
The complete set of documentation consists of three manuals in three 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. Read this manual after reading the FCE_4x Programmer's Manual.
The FCE Reference Manual (FCE_REF) contains details on each individual FCE function.
Use Microsoft Word or Microsoft WordPad to print the document files. 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 FCE. Zip up any attachments and send plain ASCII text email only.
You can also reach us at +1.256.881.4630 between 7:00 AM and 7:00 PM CST Monday through Friday. You can also often reach us on Saturday.
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/oem.htm
The professional version of the FTP Client Engine Library (FCE) may be registered for $115 (US dollars).
All prices are for email delivery. The professional version DLL is also branded internally with your company name.
The fastest and easiest way to order is on our web site at
http://www.marshallsoft.com/order.htm
You can also order by completing INVOICE.TXT (pro forma invoice) and emailing (info@marshallsoft.com), mailing (see our address at top), or faxing (1.256.880.0925) it to us.
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, and purchase orders (POs) within the USA from recognized US schools and companies listed in Dun & Bradstreet.
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 bank's). 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.
Print the file INVOICE.TXT if a "Pro Forma" invoice is needed. The registered package includes:
We offer an "academic price" with a 30% 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.
When ordering FCE, a 3.5" HD disk can be purchased for $5 for delivery to the, US, Canada, and Mexico. For all other destinations, the disk is $8. A CD can be purchased instead for an additional $3.
See INVOICE.TXT or http://www.marshallsoft.com/order.htm
Printed manuals (see Section 1.1 "Documentation Set") are the same as in the FCE zip file. Printed manuals can be purchased for $20 for delivery to the US, Canada, and Mexico. For all other destinations, printed manuals are $25. Printed manuals also come with a 3.5" HD disk.
See INVOICE.TXT or http://www.marshallsoft.com/order.htm
Source code is available for the purpose of re-compiling FCE16.DLL and FCE32.DLL. Source code for the DLL library is standard ANSI C. The source code for FCE16.DLL and FCE32.DLL is copyrighted by MarshallSoft Computing and may not be released in whole or in part.
The FTP Client Engine Library (FCE) may be purchased with source code for $295.
If you have already purchased FCE, source code can be purchased for $200 provided that your registration is current (purchase or last update within the last year).
When you register the FTP Client Engine Library SDK, you will receive a set of registered DLLs plus a license file (FCExxxx.LIC) that can be used to update your registered DLL's for a period of one year from purchase. Updates can be downloaded from
http://www.marshallsoft.com/oem.htm
After one year, the developer license must be updated if you want 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. These update prices do not include source code.
Source code may be updated for $100 in addition to the cost of the update ($30 or $55).
Note that the registered DLL's never expire.
Your customer ID is the 4 digits following the product name (FCE) in your license file. For example, customer 1234 would receive license file FCE1234.LIC. Provide the Customer ID when contacting us for technical support (FCE4C 1234).
A license file named FCExxxx.LIC, where "xxxx" is the 4-digit Customer ID, is provided with each developer license. The license file is an encrypted binary file used for downloading FCE updates as explained in Section 1.4 "Updates".
When you register the FTP Client Engine SDK, you will receive a new set of DLL's and a keycode for your DLL's. Pass this keycode as the second 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 both Win16 [FCE16.DLL] and Win32 [FCE32.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/XP 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 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.9, '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 are 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.
Your proxy server documentation will describe the proxy protocol that it requires. Also see Section 3.7, "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
Your proxy server documentation will describe 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.3 "Passive Mode".
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 your 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 your computer (the client), 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 your 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".
Once you know the name of the file for which you want a file length, request a full listing entry by calling
fceGetList(Chan, FCE_FULL_LIST, DataBuffer, DataBufferSize)
then calling 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, write performance can be increased by increasing 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 always 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 your ISP when you access 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, NT, 2000).
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 a 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. This is done by calling the function fceHello.
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), Visual dBase (FCE4DB), and Alaska Xbase++ (FCE4XB). All versions of FCE use the same DLLs (FCE16.DLL or FCE32.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) API. FCE16.DLL is required for all Win16 (Windows 3.1) applications, and FCE32.DLL is required for all Win32 (Windows 95/98/Me/2000/NT) applications.
Once you have purchased one language version of the FTP Client Engine SDK (FCE), you can use it with all other supported 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.
The FTP Client Engine DLLs can be used with any application written in any language capable of calling the Windows (95/98/ME, NT/2000/XP) API. FCE16.DLL is required for all Win16 applications, and FCE32.DLL is required for all Win32 applications.
Declaration files have been defined for the following languages:
C/C++ FCE.H
Visual Basic FCE16.BAS and FCE32.BAS
VBA (Excel, Access,...) FCE32.BAS
PowerBASIC FCE32.PBI
Borland Delphi FCE16.PAS and FCE32.PAS
Fujitsu COBOL FCE32.CBI
Fortran FCE32ABS.INC and FCE32DEC.INC
Visual FoxPro FCE32.FOX
Visual dBase FCE16.CC and 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.4 "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 a 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 directory.
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. 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 the FCE16.DLL and FCE32.DLL and run the SETUP program.
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.
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 may be distributed royalty free with your application as specified by the software license.
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.
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 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 33 functions in the 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.
fceConnect Connect to FTP server.
fceDebug Gets debug information.
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.
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.
fceGetTicks Get system ticks.
fceHello Send "NOP" command.
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.
fceSetLocalDir Set local directory.
fceSetMode Set XFER mode (ASCII or Binary).
fceSetServerDir Set server directory.
fceSetString Set FCE parameter string.
fceShortToByte Converts from 16-bit ASCCII characters to 8-bit.
The complete list of 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.