FTP Client Engine
Library for C/C++
Programmer's Manual
(FCE4C)
Version 2.0
April 24, 2000
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2000
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 256-881-4630
FAX : 256-880-0925
email : info@marshallsoft.com
web : www.marshallsoft.com
MarshallSoft is a member of the Association of Shareware Professionals
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1 Introduction
1.1 Documentation Set2 Compiler Issues
1.2 Example Program
1.3 Installation
1.4 Uninstalling
1.5 Ordering
1.6 Updates
2.1 Command Line Tool Setup3 Supported Compilers
2.1.1 Microsoft2.2 Command Line Batch Files
2.1.2 Borland
2.1.3 Watcom
2.1.4 Lcc-Win32
2.3 Command Line Makefiles
2.4 Compiling Using an IDE
3.1 Microsoft C/C++4 Compiling Example Programs
3.2 Microsoft Visual C/C++
3.3 Borland C/C++
3.4 Turbo C/C++ for Windows
3.5 Borland C++ Builder
3.6 Watcom C/C++
3.7 Lcc-Win32 C/C++
4.1 Static Libraries5 Example Programs
4.2 Your Key Code
5.1 FCEVER6 Revision History
5.2 WINFTP
5.3 GETPRO
5.4 CONFTP
5.5 BCB_
5.6 GETALL
5.7 MFC
5.8 MULTI
The FTP Client Engine (FCE) is a library of functions providing direct control of the FTP protocol. FCE can be used for both anonymous and private FTP sessions.
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. With FCE4C,
you can write GUI
or console mode programs that easily:
Multiple example programs are provided, including Microsoft Foundation Class (MFC) and Borland C++ Builder (BCB) examples.
FCE4C supports and has been tested with Microsoft Visual C/C++, Borland C/C++, Borland C++ Builder, Watcom C/C++, and Win-LCC compilers. It can also be used with most other Windows compilers.
Both Win16 and Win32 DLLs (Dynamic Link Libraries) are provided. FCE4C can be used with Windows 3.X, 95/98/2000, and NT 4. The FCE4C DLLs (FCE16.DLL and FCE32.DLL) can also be used from any language (Visual Basic, ACCESS, EXCEL, PowerBASIC Console Compiler, Delphi, Visual FoxPro, Visual dBase, Xbase++, Fujitsu COBOL, etc.) capable of calling the Windows API.
When comparing FCE against our competition, note that:
The complete set of documentation consists of three manuals in three formats. This is
the first manual
(FCE4C) in the set.
Each manual comes in three formats:
The following example demonstrates the use of some of the library functions:
#include <windows.h> #include <stdio.h> #include "fce.h" void main(int argc, char *argv[]) {int Code; /* attach FCE */ Code = fceAttach(1, 0); // KEY_CODE = 0 if(Code<0) ErrorExit(Code); /* connect to server */ Code = fceConnect(0,(LPSTR)"ftp.marshallsoft.com", (LPSTR)"anonymous", (LPSTR)"msc@traveller.com"); if(Code<0) ErrorExit(Code); /* change to proper directory */ Code = fceSetServerDir(0, (LPSTR)"marshallsoft/other"); if(Code<0) ErrorExit(Code); /* set to ASCII xfer mode */ fceSetMode(0,'A'); /* download the file */ Code = fceGetFile(0,(LPSTR)"products.txt"); if(Code<0) ErrorExit(Code); /* QUIT */ fceClose(0); fceRelease(); }In the example program above, fceConnect is called to connect to the FTP server as user "anonymous" and password "msc@traveller.com". The server directory is changed to "marshallsoft/other", the transfer mode is set to ASCII, and the file "products.txt" is downloaded. Lastly, the connection to the FTP server is closed and FCE is released. Refer to the FCE Reference Manual (FCE_REF) for individual function details.
The INSTALL batch file must be run to copy the DLL's to your Windows directory. All recent WIN32 C/C++ compilers support the "declspec" keyword. Microsoft VC (version 4.0 and up), Borland (version and up), Watcom (version 11.0 and up), and Lcc-Win32 compilers support the "declspec" keyword.
If you have an older Win32 compiler (Borland C/C++ 4.0/4.5 or Watcom 10.5/10.6), email us and we will send you the correct DLLs for your compiler.
Uninstalling FCE4C is very easy. FCE does NOT modify the registry. First, delete the FCE project directory created when installing FCE4C. Second, delete FCE16.DLL and FCE32.DLL from your Windows directory, typically C:\WINDOWS for Windows 3.1/95/98 or C:\WINNT for Windows NT. That's it!
FCE4C can be registered for $95. See Section 1.4 of the FCE User’s Manual (FCE_USR) for details on ordering.
When you register FCE4C 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, licenses can be updated (for another year) for $30 for email delivery.
Your command line compiler tools must be set up properly. Note that you have an option of installing the command line tools (or not) when your compiler is first installed. Refer to your compiler manufacturer's manual for details.
If necessary, you can increase the size of your environment table space (to 1024 for example) by adding
SHELL=C:\COMMAND.COM /e:1024 /p
to CONFIG.SYS in C:\ and then rebooting. Yes, this works for all versions of Windows, including Windows NT.
For all compilers, your path should point to the compiler BIN directory. For example, to add "C:\BC50\BIN" to your existing path, use
PATH C:\BC50\BIN;%PATH%
Set LIB and INCLUDE environment variables. For example,
SET INCLUDE=C:\MSVC\INCLUDE
SET LIB=C:\MSVC\LIB
Check that TURBOC.CFG, BCC32.CFG, TLINK.CFG, and TLINK32.CFG all have the correct information in them, as they should have when your compiler was installed. For example, assuming your BC compiler is installed at C:\BC5, the INCLUDE (-I) and LIB (-L) paths are specified by:
-IC:\BC5\INCLUDE
-LC:\BC5\LIB
BRCC (the Borland Resource Compiler) doesn't use the *.CFG files. Set the INCLUDE environment variable or BRCC will not be able to find the INCLUDE files (such as WINDOWS.H). For example,
SET INCLUDE=C:\BC5\INCLUDE
Clear the LIB environment variable (so it is not present when SET is typed at the command line) with
SET LIB=
Set the WATCOM environment variables to point to your compilers include (H) and BIN directories. For example,
SET INCLUDE=C:\WC11\H;C:\WC11\H\NT
SET WATCOM=C:\WC11
SET EDPATH=C:\WC11\EDDAT
SET WWINHELP=E:\BINW
The LCC environment variables are set like the others. For example,
SET INCLUDE=C:\LCC\INCLUDE
SET LIB=C:\LCC\LIB
After making the above changes for your compiler, type PATH at the command line prompt to verify the search path, and type SET at the command line prompt to verify the INCLUDE and LIB environment variables.
If your compiler installation includes command line tools, then all of the example programs can be compiled directly from the command line. These same compiler commands can also be placed in a batch file.
See CONFTP32.BAT for an example of a console mode command line batch file and WINFTP32.BAT for an example of a GUI mode command line batch file. Similarly, command line batch files can be created for all of the example programs.
Command line makefiles originated on UNIX systems. They are the standard way that C/C++ programs are constructed in command line environments. The advantage of makefiles (as compared to an integrated development environment) is that all compiler switches are coded within the makefile and the makefile can be run with a single keystroke.
Makefiles are provided for Microsoft, Borland, and WATCOM command line compilers.
All current windows compilers have an "Integrated Development Environment" (IDE) for building application programs in the Windows environment. Since there is no standard format for IDE project files, file names must be entered into the IDE from the keyboard.
Note that not only do IDE's vary between the different compiler manufacturers, but they also vary from version to version for the same compiler.
Creating a project makefile for the examples that have only command line makefiles is fairly straight forward. All of the IDE's use the concept of a file hierarchy. For example, the FCEVER example program file hierarchy in the IDE (for 32-bit) should look like:
FCEVER.EXE
+++ FCEVER.C
+++ FCE32.LIB
Replace FCE32.LIB above with FCE16.LIB for 16-bit applications, with FCE32BCB.LIB if using Borland C++ Builder, and with FCE32LCC.LIB if using Lcc-Win32.
The order of the files is not significant. Also refer to the sections on individual IDE's that follow this section.
FCE4C has been tested with Microsoft C/C++, Microsoft Visual C/C++, Borland C/C++ , Borland C++ Builder, Borland Turbo C/C++, Watcom C/C++, and Lcc-Win32. Other Windows C/C++ compilers may work as well.
Note: See the next section for Microsoft Visual C/C++.
Microsoft C/C++ programs can be compiled from either the command line or from within the Microsoft development environment.
The last Win16 Microsoft compiler is version 1.52.
All Microsoft Win16 makefiles end with "16._m_". Note that many of the example programs are console mode programs, and cannot be compiled as Win16 programs since Win16 does not support console mode. To compile, use the Microsoft NMAKE utility:
NMAKE -f WINFTP16._M_
FCE can be used with Microsoft Foundation Class (MFC) programs. Use the MFCPGM16.MAK makefile to compile the MFC_PGM example program.
NMAKE -f MFCPGM16.MAK
Microsoft Visual C/C++ programs can be compiled from either the command line or from within the Microsoft development environment. All MSVC programs are Win32 only.
Programs can be compiled using command line makefiles. All Microsoft Win16 command line makefiles end with "16._m_" while Win32 command line makefiles end with ’32._m_". To compile using a makefile, use the Microsoft NMAKE utility. For example,
NMAKE -f WINFTP16._M_
NMAKE -f WINFTP32._M_
FCE can be used with Microsoft Foundation Class (MFC) programs. Use the MFCPGM32.MAK makefile to compile the MFC_PGM example program.
NMAKE -f MFCPGM32.MAK
To open an existing project, choose "File", then "Open Workspace", and then select "Makefiles" from the list of file types. Several of the example programs have Microsoft Visual Studio C/C++ makefiles, ending with ".MAK" , such as
FCEVER32.mak
WINFTP32.mak
To create a new project in MSVC 4.0, choose "File", then "New", then "Project Workspace". Select "Application" or "Console Application" for "Type:" and your project name for "Name:". Choose Win32 for platform. Then select "Create". Select "Insert", then "Files into Project". Add all filenames including any resource file (.RC) and FCE32.LIB. Lastly, select "Build", then "Rebuild All".
To create a new project in MSVC 5.0, choose "File", then "New", then "Win32 Application" or "Win32 Console Application " and your project name. Check "Create new workspace Select "Project", then "Add to Project". Add all filenames including any resource file (.RC) and FCE32.LIB. Lastly, select "Rebuild All".
Creating a new project in MSVC 6.0 follows the same logic as for MSVC 5.0.
Borland C/C++ programs can be compiled from either the command line or from within the Borland development environment.
In order to use FCE with Borland C/C++ version 5.0 or later, install using "INSTALL U". To use with Borland version 4.0 or 4.5, install with "INSTALL B".
Programs can be compiled using command line makefiles. All Borland Win16 command line makefiles end with "16._b_" while Borland Win32 command line makefiles end with ’32._b_". To compile using a makefile, use the Borland MAKE utility. For example,
MAKE -f QUICK16._B_
MAKE -f QUICK32._B_
MAKE -f WINFTP16._B_
MAKE -f WINFTP32._B_
To create a new project, first turn off LINKER case sensitivities: Choose "Options", "Projects", "Linker", "General". Turn off the "case sensitive link" and "case sensitive exports and imports" boxes.
Next, choose "Project", then "New Project". Use the INS (Insert) key to pop up a dialog box into which the project file names are entered.
Select "GUI" or "Console" for the "Target Model:" Only "Runtime" and "Dynamic" should be checked for "Standard Libraries:"
Borland Turbo C/C++ for Windows does not have command line tools, so all programs must be compiled from the Turbo C/C++ integrated environment.
Follow the same directions as above (Borland IDE), except that the "Target Model:" can be any listed.
Borland C++ Builder does not have command line tools, so all programs must be compiled from the Borland C++ Builder integrated environment. Compile the BCB example program QM_PRJ with QM_PRJ.MAK if running BCB version 1 through 3, and compile with QM_PRJ.BPR if running BCB version 4 or above.
To load the QM_PRJ example project, Choose "File" / "Open Project" on the menu bar.
Load
QM_PRJ.MAK (or QM_PRJ.BPR). Then, choose "Build All" from "Project" to create the
executable.
Note that FCE32BCB.LIB is the LIB file used with Borland C++ Builder.
Watcom C/C++ programs can be compiled from either the command line or from within the Watcom development environment.
In order to use FCE with Watcom C/C++ version 11.0 and after, install using "INSTALL U". To use Watcom version 10.5 or 10.6, install with "INSTALL W".
Watcom cannot create Win16 Winsock programs.
Win32 programs can be compiled using command line makefiles. All Watcom command line makefiles end with "32._w_" for Win32 makefiles. To compile using a makefile, use the Watcom WMAKE utility. For example,
WMAKE -f WINFTP32._W_
Win32 programs can also be compiled using command line batch files. See WINFTP32.BAT for an example of a console mode command line batch file and WINFTP32.BAT for an example of a GUI mode command line batch file. To run these command line batch files from the command line, type
WINFTP32 W
To create a new project, choose "File", then "New Project". Enter the project name and then choose Win32 as the target. Use the INS (Insert) key to pop up a dialog box into which the project file names are entered.
Select "Options" from the main window, then "C Compiler Switches", then "10". Memory Models and Processor Switches". Check "80386 Stack based calling [-3s]", then check "32-bit Flat model [-mf]".
Lcc-Win32 C/C++ programs can be compiled from either the command line or from within the development environment.
In order to use FCE with Lcc-Win32 C/C++, install using "INSTALL U".
Lcc-Win32 is a freeware C compiler developed and distributed by Jacob Navia at
http://www.cs.virginia.edu/~lcc-win32/
To use our DLLs with Lcc-Win32, you must link with FCE32LCC.LIB. This file can also be re-created using the Lcc-Win32 utility BUILDLIB.
buildlib fce32.lcc fce32lcc.lib
Then, compile and link as normal. For example, to compile the CONFTP console mode example program,
lcc -DWIN32 conftp.c
lcclnk conftp.obj fce32.lib -subsystem:console
To compile the GUI mode example WINFTP,
lcc -DWIN32 connect.c
lcc -DWIN32 files.c
lcc -DWIN32 info.c
lcc -DWIN32 winftp.c
lrc winftp.rc
lcclnk winftp.obj info.obj connect.obj files.obj fce32lcc.lib
winftp.res -subsystem:windows
See CONFTP32.BAT for an example of a console mode command line batch file and WINFTP32.BAT for an example of a GUI mode command line batch file.
The registered user can also statically link FCE16.OBJ or FCE32.OBJ, rather than making
calls to the
DLL's. To create an application which links FCE16.OBJ or FCE32.OBJ statically:
If using Microsoft Developer Studio, make these changes:
a. C/C++ Tab: Add STATIC_LIBRARY to "preprocessor definitions:".
b. Link Tab: Add wsock32.lib and fce32.obj to "object/library modules:"
FCE16.DLL and FCE32.DLL have a keycode encoded within them. Your keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.H. The keycode for the shareware version is 0. You will receive a new key code when registering.
If you get an error message (value -74) when calling fceAttach, it means that the keycode in your application does not match the keycode in the DLL. After registering, it is best to remove the shareware version of the FCE DLL's from the Windows search.
Most of the example programs are written in Win32 console mode. This was done in order to provide the clearest possible code, without the complication and complexity of GUI code. All console mode programs can be converted to GUI mode by adding the necessary Windows interface code.
Makefiles are classified as follows:
Files ending with .MAK (and .BPR) include:
The first example program is the console mode program FCEVER (FCE Version) which displays the FCE library version number and registration string.
There are command line makefiles for Microsoft (FCEVER32._M_), Borland (FCEVER32._B_), and Watcom (FCEVER32._W_), as well as a Microsoft Developer Studio makefile (FCEVER32.MAK) .
After compiling, from the command line, type:
FCEVER
WINFTP is a Win16/Win32 GUI (Graphical User Interface) application which can be used to connect to a FTP server and upload, download, and delete files. See WINFTP.TXT for more details.
There are command line makefiles for Microsoft (WINFTP16._M_ and WINFTP32._M_), Borland (WINFTP16._B_ and WINFTP32._B_), and Watcom (WINFTP32._W_), Microsoft Developer Studio makefile (WINFTP32.MAK). There is also a Lcc-Win32 compiler batch file (WINFTP32.BAT) .
GETPRO is a console mode program that connects to the MarshallSoft FTP server at ftp://ftp.marshallsoft.com and downloads the file PRODUCTS.TXT from the server directory marshallsoft/other.
Before compiling, change the last argument in fceConnect to your email address.
CONFTP is a generic FTP client (console mode) application that exercises most of the FCE functions. After compiling, start CONFTP from the command line
CONFTP server user password
BCB_PRJ is a Borland C++ Builder (BCB) example program similar to WINFTP.
For Borland C++ Builder version 1 through 3, use project file BCB_PRJ.MAK. For Borland C++ Builder version 4 and above, use project file BCB_PRJ.BPR.
GETALL is a Win32 console mode program that logs onto a specified FTP server and downloads all files ending with the specified extension. Edit GETALL.C before compiling.
MFC_PGM is a Microsoft Foundation Class equivalent of the GETPRO example program. Its purpose is to demonstrate calling FCE functions from MFC. Compile from the command line with MFCPGM16.MAK and MFCPGM32.MAK.
MULTI is a Win32 console mode application that uses multiple threads in order to log on to several FTP servers concurrently.
Be sure to edit the FTP account information in MULTI.C before compiling.
Version 1.0 "Beta": February 12, 1999.
Version 1.0: March 22, 1999
Version 1.1: June 14, 1999
Version 1.2: August 10, 1999
Version 2.0: April 24, 2000.