FTP Client Engine
Reference Library
(FCE_REF)
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 USA
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 General Remarks2 FCE Functions
1.2 Documentation Set
1.3 Declaration Files
2.1 fceAbort
2.2 fceAttach
2.3 fceClose
2.4 fceConnect
2.5 fceDelFile
2.6 fceDelServerDir
2.7 fceDriver
2.8 fceErrorText
2.9 fceExtract
2.10 fceGetFile
2.11 fceGetInteger
2.12 fceGetList
2.13 fceGetLocalDir
2.14 fceGetServerDir
2.15 fceGetString
2.16 fceHello
2.17 fceMakeServerDir
2.18 fcePutFile
2.19 fceRelease
2.20 fceSetInteger
2.21 fceSetLocalDir
2.22 fceSetMode
2.23 fceSetServerDir
2.24 fceSetString
All functions return an integer code. Negative values are always errors. See Section 9.2 "FCE Error Return Code List" in the FCE Users Manual (FCE_USR). Non-negative return codes are never errors.
Note that the fceErrorText function is used to get the text message associated with any error code.
Each function argument is marked as:
(I) : 2-byte integer (Win16), 4-byte integer (Win32).
(L) : 4-byte integer (Win16 and Win32).
(P) : 4-byte pointer (Win16 and Win32).
Refer to the declaration files (see section 1.3 below) for the exact syntax of each FCE function. Also note that the example programs show exactly how FCE functions are called.
The complete set of documentation consists of three manuals in three formats. This is
the third manual
(FCE_REF) in the set.
Each manual comes in three formats:
The exact syntax for calling FCE functions are specific to the host language (C/C++, Delphi, VB, etc.) and are defined for each language in the "FCE declaration files". Each FCE product comes with the appropriate declaration file for the supported language. For example,
FCE4C C/C++ FCE.H FCE4VB Visual Basic FCE16.BAS and FCE32.BAS VBA (EXCEL,ACCESS,etc.) FCE16.BAS and FCE32.BAS FCE4PB PowerBASIC FCE32.BAS [not the same as above] FCE4D Borland Delphi FCE16.PAS and FCE32.PAS FCE4CB Fujitsu COBOL FCE32.CBI FCE4FP Visual FoxPro FCE32.FOX FCE4DB Visual dBase FCE16.CC and FCE32.CC FCE4XB Xbase++ FCE32.CHAll FCE functions are used in one or more example programs.
NOTE: Constants defined for PowerBASIC (FCE32.PBI) begin with the character '%' symbol.
fceAbort(Channel)
Channel : (I) Channel number
The fceAbort function is used to abort the FCE state driver. This is used when calling the FCE state driver (fceDriver) directly and it is necessary to abort.
After calling fceAbort, subsequent calls to fceDriver will return 0 (IDLE). Thus, FCE is ready for the next command.
This function is not required unless the state driver fceDriver is being called directly.
Return < 0 : An error has occurred. Call fceErrorText.
See the WINFTP example program.
// abort FCE fceAbort(0);
' abort FCE Code = fceAbort(0)
fceDriver
fceAttach(NbrChans, KeyCode)
NbrChans : (I) Number of channels or threads.
KeyCode : (L) Registration key code.
The fceAttach function must be the first FCE call made. Pass the maximum number of channels or threads that will be in use. Use NbrChans = 1 for non threaded applications.
The 'Chan' parameter for subsequent calls to FCE functions must be in the range of 0 to NbrChans 1.
In WIN32, up to 32 threads (numbered from 0 to 31) can be started, each of which can be connected to a different FTP server and run independently.
When FCE is registered, you will receive a 'KeyCode' which matches the 'KeyCode' within the registered DLL. For the shareware version, the keycode is 0. See file KEYCODE.
Return < 0 : An error has occurred. Call fceErrorText.
All example programs call fceAttach.
// Initialize FCE (look in KEYCODE.H for FCE_KEY_CODE) fceAttach(1, FCE_KEY_CODE);
' Initialize FCE (look in KEYCODE.BAS for FCE_KEY_CODE) Code = fceAttach(1, FCE_KEY_CODE)
fceRelease.
fceClose(Channel)
Channel : (I) Channel number
The fceClose function closes the connection to the FTP server opened with fceConnect. After closing, another connection on channel 'Chan' may be opened with fceConnect.
If fceConnect fails, do NOT call fceClose.
Return < 0 : An error has occurred. Call fceErrorText.
All example programs that call fceConnect will also call fceClose.
// close connection. fceClose(0);
' close connection. Code = fceClose(0)
fceConnect.
fceConnect(Channel, Server, User, Pass)
Channel : (I) Channel number.
Server : (P) Server name or dotted IP address.
User : (P) Users account name or "anonymous".
Pass : (P) Password for above.
The fceConnect function connects to the FTP server 'Server' and logs on as 'User' with password 'Pass'.
FTP servers that allow anonymous access will accept "ftp" or "anonymous" for the user name and your email address for the password.
Return < 0 : An error has occurred. Call fceErrorText.
Most example programs call fceConnect.
// Connect to FTP server Code = fceConnect(0,"ftp.hiwaay.net","ftp","you@yourisp.com");
' Connect to FTP server Code = fceConnect(0,"ftp.hiwaay.net","ftp","you@yourisp.com")
fceClose.
fceDelFile(Channel, FileName)
Channel : (I) Channel number.
FileName : (P) Name of file to delete.
The fceDelFile function is used to delete the file 'FileName' from the FTP server.
The delete may fail if either you don't have the necessary permission (as is typical when you connect as an anonymous user) or the file itself is marked as read only.
Return < 0 : An error has occurred. Call fceErrorText.
See the WINFTP example program.
// delete file fceDelFile(0,"PRODUCTS.TXT");
' delete file Code = fceDelFile(0, "PRODUCTS.TXT")
fcePutFile and fceDelServerDir
fceDelServerDir(Channel, DirName)
Channel : (I) Channel number.
DirName : (P) Name of directory to delete.
The fceDelServerDir function is used to delete the server directory 'DirName' from the FTP server.
The delete may fail if you don't have the necessary permission, as is typical when you connect as an anonymous user.
Return < 0 : An error has occurred. Call fceErrorText.
See the WINFTP example program.
// delete server directory MYSTUFF.DIR Code = fceDelServerDir(0,"MYSTUFF.DIR");
' delete server directory MYSTUFF.DIR Code = fceDelServerDir(0,"MYSTUFF.DIR")
fceDelFile
fceDriver(Channel)
Channel : (I) Channel number.
The fceDriver function executes the next state in the FCE state engine.
This function is only used when FCE_AUTO_CALL_DRIVER is set to 0.
Refer to Section 4, "Theory of Operation" in the FCE Users Manual (FCE_USR) for more details.
Return > 0 : The driver is not yet finished.
See the CONFTP example program.
// call driver until it returns 0 while (fceDriver(0)!=0);
' call driver until it returns 0 While fceDriver(0) > 0 ' Wend
See Section 4, "Theory of Operation" in the User’s Manual (FCE_USR).
fceErrorText(Channel, ErrCode, Buffer, BufLen)
Channel : (I) Channel number.
ErrCode : (I) Error code.
Buffer : (P) Pointer to put error message.
BufLen : (I) Size of 'Buffer'.
The fceErrorText function formats the error message for error 'Code' in 'Buffer'.
Call this function when an error (a negative value) is returned from a FCE function so that the error message can be displayed or logged.
The number of characters copied to 'Buffer'.
See the WINFTP example program.
n = fceErrorText(0,ErrCode,(LPSTR)Buffer,100); if(n>0) printf("ERROR %s\n", Buffer);
Buffer = SPACE$(100) N = fceErrorText(0, ErrCode, Buffer, 100) If N > 0 Then Print Buffer End If
None.
fceExtract(Buffer, LineNbr, FieldNbr, BufPtr, BufLen)
Buffer : (P) Buffer returned by fceGetList.
LineNbr : (I) Line number [1,2,...] wanted.
FieldNbr : (I) Field number [1,2,...] wanted.
BufPtr : (P) Resultant buffer.
BufLen : (I) Size of 'BufPtr'.
The fceExtract function extracts fields from FTP formatted file lists for line 'LineNbr' and field 'FieldNbr'. The extracted substring is copied into 'BufPtr'. Use 'FieldNbr' 0 in order to copy the entire line rather than a field.
A typical line in a full FTP directory listing may look like the following. Note that there are 9 fields.
rw rr 1 345 15 100424 Feb 8 16:26 fce4c10b.zip
Note that in the line above, field 5 is the file length.
The fceExtract function is typically called after calling fceGetList. See CONFTP for an example of use.
The number of characters copied to 'BufPtr'.
See the GETPRO example program.
/* get each field for line 8 (returned from call to fceGetList) */ for(i=1;i<=9;i) {Code = fceExtract((LPSTR)DataBuffer, 8, i, (LPSTR)LineBuf, 100); printf("FIELD %d: %s \n", i, LineBuf); }
' get each field for line 8 (returned from call to fceGetList) For I = 1 To 9 LineBuf = SPACE$(100) Code = fceExtract(DataBuffer, 8, I, LineBuf, 100) Print 'FIELD ', I, ' :', LineBuf Next I
fceGetList
fceGetFile(Channel, FileName)
Channel : (I) Channel number.
FileName : (P) Name of file to download.
The fceGetFile function is used to download the file 'FileName' from the FTP server. The file can be also be renamed when it is saved by specifying "oldname:newname" for filename. See example below.
Note that ASCII transfer mode is normally the default. Call fceSetMode(Chan,'B') to set the transfer mode to binary for non ASCII files.
Return < 0 : An error has occurred. Call fceErrorText.
See the WINFTP example program.
// download file "PRODUCTS.TXT" Code = fceGetFile(0,"PRODUCTS.TXT"); // download "YOURFILE.BIN" and save as "MYFILE.BIN" Code = fceGetFile(0, "YOURFILE.BIN:MYFILE.BIN");
' download file "PRODUCTS.TXT" Code = fceGetFile(0,"PRODUCTS.TXT") ' download "YOURFILE.BIN" and save as "MYFILE.BIN" Code = fceGetFile(0, "YOURFILE.BIN:MYFILE.BIN")
fcePutFile
fceGetInteger(Channel, ParamName)
Channel : (I) Channel number.
ParamName : (I) Parameter name.
The fceGetInteger function returns the value of the specified parameter 'ParamName'.
Note that the return type is unsigned long.
FCE_GET_BUILD Returns FCE build number. FCE_GET_CONNECT_STATUS Returns 1 if connected. FCE_GET_COUNTER Returns # times FCE driver was called. FCE_GET_FILE_BYTES_RCVD Returns # file bytes received. FCE_GET_FILE_BYTES_SENT Returns # file bytes sent. FCE_GET_RESPONSE Returns last FTP response. FCE_GET_SOCKET Returns control socket number. FCE_GET_SOCK_ERROR Returns last socket error code. FCE_GET_TOTAL_BYTES_RCVD Returns total bytes received. FCE_GET_TOTAL_BYTES_SENT Returns total file bytes sent. FCE_GET_VERSION Returns FCE version.
// display FCE version and build number. Version = fceGetInteger(0, FCE_GET_VERSION); printf("FCE32 Version: %1d.%1d.%1d \n", 0x0f&(Version>>8),0x0f&(Version>>4),0x0f&Version);
Version = fceGetInteger(0, FCE_GET_VERSION) S = Hex$(Version) Print Mid$(S, 1, 1) + "." + Mid$(S, 2, 1) + "." + Mid$(S, 3, 1)
fceGetString
fceGetList(Channel, Flag, Buffer, BufLen)
Channel : (I) Channel number.
Flag : (I) Listing type flag (see below).
Buffer : (P) List buffer.
BufLen : (I) Size of 'Buffer'
The fceGetList function downloads the directory list from the FTP server.
If 'FCE_FULL_LIST' is passed for 'Flag', a full directory listing is returned in 'Buffer'. Note that the exact format of the list depends on the particular FTP server.
If 'FCE_NAME_LIST' is passed for 'Flag', a listing is returned consisting of file names only. Note that some FTP servers do not support the name list function.
If 'FCE_FULL_LIST_FILE' is passed for 'Flag', the filename to list is taken from 'Buffer'. If the file exists, a listing of this file is returned.
If 'FCE_NAME_FULL_LIST_FILE' is passed for 'Flag', the filename to list is taken from 'Buffer'. If the file exists, the name of this file is returned. Be sure to check the return code length.
File lists consist of a zero terminated list of file entries, each of which is terminated by a carriage return, line feed pair. Also check the return code, which contains the length of the characters placed in 'Buffer'.
Return < 0 : An error has occurred. Call fceErrorText.
Return > 0 : Number of characters copied to 'Buffer'.
See the WINFTP example program.
// get file name list Code = fceGetList(0, FCE_LIST_NAME, (LPSTR)Buffer,2000); if(Code>0) printf("%s", Buffer);
' get file name list Buffer = SPACE$(2000) Code = fceGetList(0, FCE_LIST_NAME, Buffer,2000) If Code > 0 Then Print Buffer End If
fceGetLocalDir(Channel, Buffer, BufLen)
Channel : (I) Channel number.
Buffer : (P) String buffer.
BufLen : (I) Size of 'Buffer'.
The fceGetLocalDir function returns the local upload/download directory.
The local upload/download directory is the directory used for all uploads and downloads. The default is the current directory (".").
Both relative and absolute directories may be specified.
Return < 0 : An error has occurred. Call fceErrorText.
Return > 0 : The number of characters copied.
See the WINFTP example program.
// Set local upload/download directory. fceSetLocalDir(0, "DOWNLOADS\\TEXT");
' Set local upload/download directory. fceSetLocalDir(0, "DOWNLOADS\TEXT")
fceSetLocalDir
fceGetServerDir(Channel, Buffer, Buflen)
Channel : (I) Channel number
Buffer : (P) String buffer.
BufLen : (I) Size of 'Buffer'.
The fceGetServerDir function returns the FTP server directory.
Note that most all FTP servers will restrict clients as to which directories on the server that can be accessed.
The default is the current logged directory on the FTP server.
Return < 0 : An error has occurred. Call fceErrorText.
Return > 0 : The number of characters copied.
See the WINFTP example program.
// copy directory string to 'Buffer' Code = fceGetServerDir(0, (LPSTR)Buffer, 65); printf("Server directory is %s\n", Buffer);
' copy directory string to 'Buffer' Buffer = SPSACE$(65) Code = fceGetServerDir(0, Buffer, 65) Print "Server directory is ", Buffer
fceSetServerDir
fceGetString(Channel, ParamName, Buffer, BufLen)
Channel : (I) Channel number
ParamName : (P) Parameter name
Buffer : (P) String buffer.
BufLen : (I) Size of 'Buffer'.
The fceGetString function returns the string parameter 'ParamName'.
FCE_GET_LINE_COUNT Returns the # lines in 'Buffer'. FCE_GET_LAST_RESPONSE Returns last FTP response. FCE_GET_REGISTRATION Returns registration string. FCE_GET_SERVER_IP Returns IP address of FTP server.
Return < 0 : An error has occurred. Call fceErrorText.
See the WINFTP example program.
// display registration string within the DLL Code = fceGetString(0, FCE_GET_REGISTRATION, (LPSTR)Buffer, 50); printf("Registration = '%s'\n", Buffer);
' display registration string within the DLL Buffer = SPACE$(50) Code = fceGetString(0, FCE_GET_REGISTRATION, Buffer, 50) Print "Registration ", Buffer
fceGetInteger
fceHello(Channel)
Channel : (I) Channel number.
The fceHello function issues a "NOOP" command to the server. The primary purpose for this command is to determine if the server is still responding to commands.
This function can sometimes be used as a "keep alive" command, although most servers will drop your connection after a fixed period of time unless data is transferred.
Return < 0 : An error has occurred. Call fceErrorText.
Return > 0 : The number of characters copied.
See the CONFTP example program.
// is the server responding ? Code = fceHello(0); if(Code>=0) printf("Server is responding\n");
' is the server responding ? Code = fceHello(0) If Code >=0 Then Print "Server is responding" End If
None.
fceMakeServerDir(Channel, DirName)
Channel : (I) Channel number.
DirName : (P) Name of directory to make.
The fceMakeServerDir function is used to make (create) server directory 'DirName' on the FTP server.
The make may fail if you don't have the necessary permission, as is typical when you connect as an anonymous user.
Return < 0 : An error has occurred. Call fceErrorText.
See the WINFTP example program.
// create new directory Code = fceMakeServerDir(0, "MYSTUFF.DIR");
' create new directory Code = fceMakeServerDir(0, "MYSTUFF.DIR")
fceDelServerDir
fcePutFile(Channel, FileName)
Channel : (I) Channel number.
FileName : (P) Name of file to upload.
The fcePutFile function uploads the file 'FileName' to the FTP server.
The file 'FileName' to be uploaded must be in the local upload/download directory.
Return < 0 : An error has occurred. Call fceErrorText.
See the WINFTP example program.
// upload file Code = fcePutFile(0, "COMMENTS.TXT");
' upload file Code = fcePutFile(0, "COMMENTS.TXT")
fceGetFile.
fceRelease
The fceRelease function releases the FCE system. This should be the very last function called.
fceClose should be called for all channels before calling fceRelease.
Return < 0 : An error has occurred. Call fceErrorText.
All example programs call fceRelease.
// Terminate FCE fceRelease();
' Terminate FCE Code = fceRelease()
fceAttach.
fceSetInteger(Channel, ParamName, ParamValue)
Channel : (I) Channel number.
ParamName : (I) Parameter name.
ParamValue : (L) Parameter value.
The fceSetInteger function sets the numeric parameter 'ParamName' to the value 'ParamValue'.
Parameter Name Default FCE_SET_AUTO_CALL_DRIVER 1 FCE_SET_CLOSE_LINGER 50 (WIN32) or 500 (WIN16) FCE_SET_CONNECT_WAIT 60000 FCE_SET_DATA_PORT (none) FCE_SET_FTP_PORT 21 FCE_SET_MAX_LINE_WAIT 20000 FCE_SET_MAX_LISTEN_WAIT 25000 FCE_SET_MAX_RESPONSE_WAIT 10000 FCE_SET_MIN_LINE_WAIT 0 FCE_SET_MIN_RESPONSE_WAIT 0 FCE_SET_PASSIVE 1 FCE_SET_SLEEP_TIME 20 (WIN32 only) FCE_SET_WRITE_BUFSIZE 128
FCE_SET_AUTO_CALL_DRIVER enables and disables automatic calling of fceDriver.
FCE_SET_CLOSE_LINGER is the "linger" time after an upload is completed before closing the data socket. Setting this value too small (at least in WIN16) causes the data socket to be closed before the last block of data is transmitted.
FCE_SET_CONNECT_WAIT is the maximum time allowed to complete a connection to the FTP server.
FCE_SET_DATA_PORT specifies the port number to use (in non-passive mode) for the next list of file transfer command.
FCE_SET_FTP_PORT is the port number to use when connecting to the FTP server. The default is the well known port number 21.
FCE_SET_MAX_LINE_WAIT is the time after which a "time out" error is declared if the server has not responded.
FCE_SET_MAX_LISTEN_WAIT is the time after which a "time out" error is declared while waiting for a data port "Listen" to complete.
FCE_SET_MAX_RESPONSE_WAIT is the time after which a "time out" error occurs if the server has not
responded.
FCE_SET_MIN_LINE_WAIT is the delay before checking if the server is ready to accept the next line of input.
FCE_SET_MIN_RESPONSE_WAIT is the delay before looking for the server's response.
FCE_SET_PASSIVE sets passive mode on (1) and off (0).
FCE_SET_SLEEP_TIME is the sleep time (in milliseconds) when waiting for socket I/O to complete. Useful in multi threaded environments.
FCE_SET_WRITE_BUFSIZE is the transmit block size. The maximum value is 4096.
Return < 0 : An error has occurred. Call fceErrorText.
Most example programs call fceSetInteger.
// disable the automatic calling of the state driver. fceSetInteger(0, FCE_SET_AUTO_CALL_DRIVER, 0);
' disable the automatic calling of the state driver. Code = fceSetInteger(0, FCE_SET_AUTO_CALL_DRIVER, 0)
fceSetString
fceSetLocalDir(Channel, DirName)
Channel : (I) Channel number.
DirName : (P) Local directory path.
The fceSetLocalDir function sets the local computer upload/download directory. The upload/download directory is the directory used by FCE for all uploads and downloads.
Return < 0 : An error has occurred. Call fceErrorText.
See the WINFTP example program.
// specify the local upload/download directory. fceSetLocalDir(0, "C:\\TEMP");
' specify the local upload/download directory. Code = fceSetLocalDir(0, "C:\TEMP");
fceGetLocalDir
fceSetMode(Channel, Mode)
Channel : (I) Channel number.
Mode : (I) transfer mode ('A' or 'B').
The fceSetMode function sets the FTP transfer mode. Pass 'A' to specify ASCII mode and 'B' to specify binary mode.
Since the FTP default is usually ASCII, it is good practice to always specify the transfer mode before the first call to fceGetFile or fcePutFile.
If unsure of the transfer mode, choose binary.
Return < 0 : An error has occurred. Call fceErrorText.
See the WINFTP example program.
// set binary mode fceSetMode(0, 'B');
' set binary mode Code = fceSetMode(0, ASC("B"))
fceGetFile and fcePutFile.
fceSetServerDir(Channel, DirName)
Channel : (I) Channel number.
DirName : (P) Directory name.
The fceSetServerDir sets the FTP directory to 'DirName' which is used for subsequent FCE calls.
Note that UNIX FTP servers use forward slashes for directories while Windows FTP servers use backward slashes.
Return < 0 : An error has occurred. Call fceErrorText.
See the WINFTP example program.
// note forward slashes Code = fceSetServerDir (0, "marshallsoft/other")
' note forward slashes Code = fceSetServerDir (0, "marshallsoft/other")
None.
fceSetString(Channel, ParamName, ParamPtr)
Channel : (I) Channel number.
ParamName : (I) Parameter name.
ParamPtr : (P) Parameter string.
The fceSetString function sets the string parameter 'ParamName' to 'ParamPtr'.
FCE_SET_LOG_FILE is used to specify the log file name. Log files can be quite large, so use only when necessary.
FCE_WRITE_TO_LOG is used to write a string (message) to log file.
Return < 0 : An error has occurred. Call fceErrorText.
See the WINFTP example program.
// open LOG file fceSetString(0, FCE_SET_LOG_FILE, "program.log");
' open LOG file Code = fceSetString(0, FCE_SET_LOG_FILE, "program.log")
fceSetInteger