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.



TABLE OF CONTENTS


1 Introduction
1.1 Documentation Set
1.2 Example Program
1.3 Installation
1.4 Uninstalling
1.5 Ordering
1.6 Updates
2 Compiler Issues
2.1 Command Line Tool Setup
2.1.1 Microsoft
2.1.2 Borland
2.1.3 Watcom
2.1.4 Lcc-Win32
2.2 Command Line Batch Files
2.3 Command Line Makefiles
2.4 Compiling Using an IDE
3 Supported Compilers
3.1 Microsoft C/C++
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 Compiling Example Programs
4.1 Static Libraries
4.2 Your Key Code
5 Example Programs
5.1 FCEVER
5.2 WINFTP
5.3 GETPRO
5.4 CONFTP
5.5 BCB_
5.6 GETALL
5.7 MFC
5.8 MULTI
6 Revision History

1 Introduction

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:

  1. Connect to any FTP server.
  2. Get a list of files on the server.
  3. Navigate the server directories.
  4. Specify ASCII or BINARY transfer mode.
  5. Download files.
  6. Upload files.
  7. Delete files.
  8. Create and remove server directories.

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:

  1. FCE4C is a standard Windows DLL (NOT an OCX or ActiveX control) and is much smaller than a comparable OCX or ActiveX control.
  2. Both WIN16 and WIN32 DLLs are included.
  3. FCE4C does NOT depend on ActiveX or Microsoft Foundation Class (MFC) libraries or similar "support" libraries.
  4. The WIN32 version of FCE is fully threadable.
  5. The FCE functions can be called from applications not capable of using controls.

1.1 Documentation Set

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:

1.2 Example Program

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.

1.3 Installation

  1. Before installation of FCE4C, your Windows C/C++ compiler should already be installed on your system and tested. In particular, include command line tools when installing your compiler if you want to compile using command line makefiles. If you need help with makefiles, see MAKEFILE.TXT.

  2. Create your project directory, copy the zip-file, then unzip.

  3. Run the INSTALL program.

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.

1.4 Uninstalling

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!

1.5 Ordering

FCE4C can be registered for $95. See Section 1.4 of the FCE User’s Manual (FCE_USR) for details on ordering.

1.6 Updates

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.


2 Compiler Issues

2.1 Command Line Tool Setup

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%

2.1.1 Microsoft

Set LIB and INCLUDE environment variables. For example,

SET INCLUDE=C:\MSVC\INCLUDE
SET LIB=C:\MSVC\LIB

2.1.2 Borland

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=


2.1.3 Watcom

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

2.1.4 Lcc-Win32

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.


2.2 Command Line Batch Files

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.

2.3 Command Line Makefiles

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.

2.4 Compiling Using an IDE

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.

3.0 Supported Compilers

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.

3.1 Microsoft C/C++

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.

3.1.1 Microsoft Command Line Makefiles

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

3.2 Microsoft Visual C/C++

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.

3.2.1 Microsoft Command Line Makefiles

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


3.2.2 Microsoft Developer Studio

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.



3.3 Borland C/C++

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".

3.3.1 Borland Command Line Makefiles

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_

3.3.2 Borland IDE

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:"

NOTE1
If, after linking in the IDE, you get unresolved external references to the library functions in which each function name is all upper case, then you have NOT turned off case sensitivity as described above.
NOTE2
If you get errors compiling the windows header file "WINDOWS.H", turn on "Borland Extensions" in "Options", "Project", "Compiler", "Source".

3.4 Borland Turbo C/C++ for Windows

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.

3.5 Borland C++ Builder

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.

3.6 Watcom C/C++

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.

3.6.1 Watcom Command Line Makefiles

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

3.6.2 Watcom IDE

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]".

3.7 Lcc-Win32 C/C++

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.

4.0 Compiling Example Programs

4.1 Static Libraries

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:

  1. All application code that includes FCE.H must define STATIC_LIBRARY before including FCE.H
  2. Your application must link with WINSOCK.DLL (for WIN16) or with WSOCK32 (for WIN32) .

If using Microsoft Developer Studio, make these changes:

  1. To your project file: Do NOT add FCE32.LIB to your project file.
  2. To the settings: (See "Build Settings" or "Project/Settings")

    a. C/C++ Tab: Add STATIC_LIBRARY to "preprocessor definitions:".

    b. Link Tab: Add wsock32.lib and fce32.obj to "object/library modules:"

4.2 Key Codes

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.

5 Example Programs

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:

5.1 FCEVER

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

5.2 WINFTP

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) .

5.3 GETPRO

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.

5.4 CONFTP

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

5.5 BCB_PRJ

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.

5.6 GETALL

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.

5.7 MFC_PGM

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.

5.8 MULTI

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.

6 Revision History

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.