FTP4W API User Manual

• License
• Overview
• Known bugs
• Programming with the FTP4W API
• Interpreting FTP4W errors (from Joachim Durchholz)
• The FTP4W functions
  • Ftp4wVer
  • FtpAbort
  • FtpAppendToLocalFile / FtpAppendToRemoteFile
  • FtpBufferPtr
  • FtpBytesTransferred / FtpBytesToBeTransferred
  • FtpCDUP
  • FtpCloseConnection
  • FtpCloseDataConnection
  • FtpCWD
  • FtpDeleteFile
  • FtpDir
  • FtpErrorString
  • FtpFirewallLogin
  • FtpFlush
  • FtpGetFileSize
  • FtpHelp
  • FtpInit
  • FtpIsAsynchronousMode
  • FtpLocalClose
  • FtpLogin
  • FtpLogTo
  • FtpMGet
  • FtpMKD
  • FtpMtInit
  • FtpOpenConnection
  • FtpOpenDataConnection
  • FtpPWD
  • FtpQuote
  • FtpRecvFile / FtpAppendToLocaFile
  • FtpRecvThroughDataConnection
  • FtpRelease
  • FtpRenameFile
  • FtpRestart
  • FtpRestartRecvFile
  • FtpRestartSendFile
  • FtpRMD
  • FtpSendAccount
  • FtpSendFile / FtpAppendToRemoteFile
  • FtpSendPasswd
  • FtpSendThroughDataConnection
  • FtpSendUserName
  • FtpSetAsynchronousMode / FtpSetSynchronousMode
  • FtpSetDefaultPort / FtpSetDefaultTimeOut
  • FtpSetNewDelay / FtpSetNewSlices
  • FtpSetPassiveMode
  • FtpSetType
  • FtpSetVerboseMode
  • FtpSyst

License

FTP4W was written by Philippe Jounin and is Copyrighted 1994-1998 by him and the SNCF (French Railways). The author disclaims all liability for its use or for problems, data corruption, data loss, or other loss that may result from its use.

Permission is given without restriction to use and distribute the program provided that it is distributed without charge, that it is not modified in any way, and that this file accompanies the DLL file.

This program may be included on CD-ROMs or other distribution methods freely, provided any charge for such is for recovering the cost of distribution and reasonable profit and not for the purpose of "selling" the program. In this case the distribution must contain the complete program including this file.

Send any comments to ph.jounin@computer.org.

Thanks To Santanu Lahiri for providing the source of WinFTP, a FTP client for windows. I have learned a lot (about FTP and Windows) by reading it.

Thanks to all the Internet community which has reported some implementation problems and has contributed to this new release, especially:

• Gillian Duncan (Corrections of this manual)
  
• Burks Oakley <b-oakley@uiuc.edu> (Tests with ToolBook)
  
• Richard Terpstra <terpstr2@ksla.nl> and Kees de Rooij (VB Sample)
  
• Vince Vielhaber <vev@msen.com> (Tests with VMS and C++ )
  
• Bram Buitendijk <Bram.Buitendijk@library.KNAW.nl> (Tests with MS-Access)
  
• Teemu Mottonen <Teemu.Mottonen@ktl.fi> (Corrections of this manual)
  
• Robin Bowes <robin@plato.ucsalf.ac.uk> (Tests with Paradox)
  
• Terry Field <terry@mincom.oz.au> (Bug report)
  
• David Combs <dkcombs@netcom.com> (has fully rewritten this manual)
  
• Andreas Tikart <Andreas.Tikart@uni-konstanz.de> (tp7 sample)
  
• Ricky Freyre <rickyf@mail.halcyon.com>
  
• Michael Douglass <mikedoug@texas.net> (Ftp4w.hlp)
  
• Joachim Durchholz <durchjac@koa.ina.de> Tons of suggestions
  

Overview

• Local Functions
  
• Connection functions
  
• Data transfer functions
  
• FTP Commands functions
  

• wParam: FALSE (operation not completed)
  
• lParam : number of bytes received/sent
  

Known bugs

• SPRY winsockets
  
• LAN Workplace (Novell)
  
• Dec Pathworks
  

• Ftp4w's version
  
• Your operating system (Win 3.1, 95, NT)
  
• Your TCP/IP stack
  

Programming with the FTP4W API

• This reference
  
• The DLL FTP4W.DLL and its library file Ftp4w.Lib
  
• The 32 bits version FTP4W32.DLL and its library file Ftp4w32.Lib
  
• A C-header file Ftp4w.h
  

• The Help file written by Michael Douglass
  
• A Pascal header file UseFtp4w.Pas
  
• A Visual Basic header file Ftp4w.Bas
  

• Call FtpOpenConnection, FtpSendUserName and FtpSendPasswd
  
• or just call FtpLogin (which combines the 3 functions).
  

Interpreting FTP4W errors (from Joachim Durchholz)

The FTP4W functions

Ftp4wVer

FtpAbort

FtpAppendToLocalFile / FtpAppendToRemoteFile

FtpBufferPtr

FtpBytesTransferred / FtpBytesToBeTransferred

FtpCDUP

FtpCloseConnection

FtpCloseDataConnection

FtpCWD

FtpDeleteFile

FtpDir

FtpErrorString

FtpFirewallLogin

int PASCAL FAR FtpFirewallLogin(LPSTR szFWHost, 
                                LPSTR szFWUser, LPSTR szFWPass,
                                LPSTR szRemHost,
                                LPSTR szRemUser,LPSTR szRemPass,
                                int nFirewallType,
                                HWND hParentWnd, UINT wMsg)

Arguments:

szFWHost	The name of the firewall
szFWUser	The name of the user on the firewall
szFWPasswd	The passwd on the firewall
szRemHost	The name to the FTP server
szRemUser	The name of the user for FTP server
szRemPasswd	The Password of the user for FTP server
nFirewallType	Identifies the firewall type
hWnd	the handler of the windows to which to pass the message
wMsg	the application-defined message to pass to the application

Return Codes:

FTPERR_OK	User is logged on
FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit
FTPERR_INVALIDPARAMETER	Required parameters are NULL or nTypeFirewall is incorrect
FTPERR_SENDREFUSED	Error happens during send
FTPERR_FWCANTCONNECT	Error during connection with firewall
FTPERR_FWCONNECTREJECTED	Firewall rejects log on command
FTPERR_FWLOGINREFUSED	Login on firewall refused
FTPERR_CANTCONNECT	FTP server unreachable/unknown...
FTPERR_LOGINREFUSED	Login on FTP server refused

FtpFlush

This function flushes the control connection (port 21). It can be used to resynchronize the server and the client.

Syntax: FtpFlush (void)

Return : FTPERR_OK Flush completed

FtpGetFileSize

Warning: This function has been obsoleted by FtpBytesToBeTransferred.

This function tries to get the size of the file which is to be received. It must be used immediatly after a FtpRecvFile, because it searches in the most recent reply, looking to see if the server has sent back the size of the file.

If the function succeeds, it returns the length of the file. (Note that in ASCII mode, it can be slightly different from the number of bytes FTP4W will receive). Otherwise, it returns 0.

This function is obsolete and should be replaced by FtpBytesToBeTransferred.

Syntax

FtpGetFileSize()

returns DWORD.

FtpHelp

FtpHelp retrieves the help file of the remote server.

Syntax: FtpHelp (LPCSTR szArg, LPSTR szBuf, UINT uBufSize)

Argument:

szArg	NULL for a global help
	a command for getting help on this command
szBuf	The buffer to copy the answer
uBufSize	Its size

Return codes:

FTPERR_OK	Initialisation has been done
FTPERR_INSMEMORY	not enough memory
FTPERR_CANTCREATEWINDOW	FtpInit can't create its window
FTPERR_SESSIONUSED	The task has already a FTP4W session
FTPERR_WINSOCKNOTUSABLE	Ftp4w needs a Winsock version 1.1 or higher

FtpInit

FtpInit must be called before any other function. It allocates buffers, reads information about the task which has called it and creates an invisible window for its internal use.

Before it exits, the application must call FtpRelease to release these internal resources.

The function requires the handler of an application window (or NULL).

Note: If the application should have multithreaded Ftp4w sessions, use FtpMtInit instead of Ftpinit.

Syntax: FtpInit (HWND hParentWnd)

Argument:

hParentWnd

is the handle of an existing application window.

Return codes:

FTPERR_OK	Initialization has been done
FTPERR_INSMEMORY	not enough memory
FTPERR_CANTCREATEWINDOW	FtpInit can't create its window
FTPERR_SESSIONUSED	The task has already a FTP4W session
FTPERR_WINSOCKNOTUSABLE	Ftp4w needs a Winsock version 1.1 or higher

FtpIsAsynchronousMode

This function checks if Ftp4w is in asynchronous mode.

Syntax: FtpIsAsynchronousMode()

Return:

TRUE	Ftp4w is in asynchronous mode,
FALSE	Ftp4w is in synchronous mode.

FtpLocalClose

This function closes the opened socket without warning the server. An application should use this function only if FtpCloseConnection has failed.

Syntax: FtpLocalClose (void)

Return Codes:

FTPERR_OK
FTPERR_NOTINITIALIZED
FTPERR_CANTCLOSE

FtpLogin

This function combines the three functions FtpOpenConnection, FtpSendUserName, and FtpSendPassword.

If the current mode is "synchronous", FtpLogin will return when the job is over, and the two last arguments are unused. Otherwise ("asynchronous mode") it immediatly returns FTPERR_OK, and then later, when the request is completed, the application will receive a wMsg message in the hWnd window.

The message will be followed by:

wParam:	TRUE
lParam:	The return code of the function

Syntax:

FtpLogin(LPCSTR szHost,LPCSTR szUser,LPCSTR szPass, HWND hWnd,WMSG wMsg)

Arguments:

szHost	name of the remote host (the computer on which the server is running)
szUser	name of the user
szPass	Password (it can be NULL if the user has no password)
hWnd	the handler of the windows to which the message is to be posted
wMsg	the application-defined message to be posted to the application

Return Codes:

Return codes are in the Low Word of the lParam argument:

FTPERR_OK	User is logged on
FTPERR_ENTERACCOUNT	Successful function but server awaits an account name
FTPERR_LOGINREFUSED	The USER/PASSWD has been rejected
FTPERR_NOTINITIALIZED	session has not been initialized by FtpInit
FTPERR_NOTCONNECTED	User is not connected to a remote host
FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)
FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection.
FTPERR_CANTCREATESOCKET	The socket has not been created
FTPERR_CONNECTREJECTED	Connect has been rejected (server is not a FTP server, ...)
FTPERR_CANTCONNECT	The connect has failed
FTPERR_TIMEOUT	The connect has timed-out
FTPERR_INVALIDPARAMETER	Bad parameters

FtpLogTo

This function set or reset a log mode. In log mode, all data sent or received on the control port (21) are sent to the opened file passed as an argument.

The frame which contains the password is logged as "PASS +++" for obvious reasons.

To set silent mode (default), just call FtpLogTo (HFILE_ERROR).

Note that the file is not closed by Ftp4w.

Syntax: FtpLogTo (HFILE hLogFile)

Argument:

hLogFile	A opened file handler to be written to.
	Or HFILE_ERRORto set silent mode.

FtpMGet

This function gets specified files from the remote server.

This function needs an user-defined function which is to be called twice with 3 parameters :

- The name of the remote file which should be transferred or which has been transferred
- The name of the local file which should be created or which has been created
- an int value which is set first to FTPERR_ENDOFDATA (before a file transfer) then to
an FTP4W return code (after the file transfer).

When called with the third parameter to FTPERR_ENDOFDATA, this user-defined function can change the name of the local file or decide to skip this file by returning FALSE.
When called for the second time, the FtpMGet function can be aborted by returning FALSE.


Notes :
- This command should be used in synchronous mode only.
- if szFilter is not NULL, the behaviour of FtpMGet depends on the FTP server.


Syntax: FtpMGet (LPCSTR szFilter, char cType, BOOL bNotify, BOOL (CALLBACK *f))

Argument:

szFilter	The selection mask. It can include wilcards ("*", "*.*") or it can be a directory name. If this parameter is set to NULL all parameters from the current directory will be copied
cType	TYPE_A for ASCII, TYPE_B for binary
bNotify	A message should be sent by to the application each time a frame has been received.
f	NULL or a user-defined function which accepts three arguments :
	- szRemFile a 256 bytes zone which contains the name of the file which is to be received.
	- szLocalFile a 256 bytes zone which contains the name of the file which will be created (initialized to szRemFile)
	- The last return code if the transfer has been attempted or FTPERR_ENDOFDATA if the file is to be transferred

FtpMKD

FtpMtInit

DWORD MyGetCurrentThreadId ()
{ 
  return GetCurrentThreadId(); 
}

Argument:

hParentWnd	the handle of an existing application window.
f	a Callback function which returns a thread id.

Return codes:

FTPERR_OK	Initialisation has been done
FTPERR_INSMEMORY	not enough memory
FTPERR_CANTCREATEWINDOW	FtpInit can't create its window
FTPERR_SESSIONUSED	The task has already a FTP4W session
FTPERR_WINSOCKNOTUSABLE	Ftp4w needs a Winsock version 1.1 or higher

FtpOpenConnection

This function establishes the connection with the FTP server.

Once the connection is done, it waits for the reply of the server.

This reply must begin with "220" (RFC 959), if not a special error is generated.

FTP4W does not check to see if a connection already exists.

Syntax: FtpOpenConnection (LPCSTR szHost)

Argument:

szHost

The name of the remote host to connect to

Return codes:

FTPERR_OK	Successful connection
FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit
FTPERR_CANTCREATESOCKET	The socket has not been created
FTPERR_UNKNOWNHOST	The hostname can not be resolved
FTPERR_CANCELBYUSER	User has called FtpAbort
FTPERR_SERVERCANTEXECUTE	The remote FTP server can not accept the connection : too many users logged on, server off-line, ...
FTPERR_CONNECTREJECTED	Connection has been rejected (server is not a FTP server, ...)
FTPERR_CANTCONNECT	The connection has failed
FTPERR_TIMEOUT	The connection has timed-out
FTPERR_NOREPLY	The connection is successful, but FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	The connection is successful and FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection.

FtpOpenDataConnection

This function is reserved for experimented programmers which needs to control the data sent on the data streams. It must be used in conjunction with FtpCloseDataConnection and FtpRecvThroughDataConnection or FtpSendThroughDataConnection.

It opens the data connection with the server on port 20. It does not send any data through this channel nor wait for them.

By default the active mode is used (ie. Ftp4w opened a listened socket and waits for a connection), although this mode may be changed by FtpSetPassiveMode.

FTP4W does not check to see if a connection already exists.

The action to be executed by the server is given in nAction. It should be either

FTP4W_STORE_ON_SERVER	The data sent by the client are written in the file szRemote
FTP4W_APPEND_ON_SERVER	The data sent by the client are written at the end of the file szRemote
FTP4W_GET_FROM_SERVER	The server sends the contents of the file szRemote

Syntax: FtpOpenDataConnection (LPCSTR szRemote, int nAction, char cType)

Argument:

szRemote	The remote file to be written or to be read.
nMode	The action to be executed by the server
cType	The data representation (ASCII, IMAGE, L 8)

Return codes:

FTPERR_OK	Successful connection
FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit
FTPERR_PASVCMDNOTIMPL	Server does not support Passive mode
FTPERR_SENDREFUSED	ftp4w can not send data
FTPERR_CANTCREATESOCKET	The socket has not been created
FTPERR_DATACONNECTION	Error during connection
FTPERR_CANCELBYUSER	Ftp4w has received an abort command
FTERR_TRANSFERREFUSED	Transfer is refused by the server
FTPERR_NOREMOTEFILE	File to be read has not been found
FTPERR_TIMEOUT	The connection has timed-out
FTPERR_NOREPLY	The connection is successful, but FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	The connection is successful and FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection.

FtpPWD

This function returns the name of the default directory on the remote server.

Syntax: FtpPWD (LPSTR szPath, UINT uBufSize)

Argument:

szPath:	buffer to be filled with the name of the remote default directory
uBufSize:	size of this buffer

Return Codes:

FTPERR_OK	Name of the remote directory available in the buffer
FTPERR_SERVERCANTEXECUTE	PWD has failed (directory does not exist,...)
FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit
FTPERR_NOTCONNECTED	User is not connected to a remote host
FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)
FTPERR_PWDBADFMT	FTP4W can not interpret server's answer
FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection
FTPERR_CMDNOTIMPLEMENTED	Command is not implemented

FtpQuote

It allows the user to send to the server any FTP command he wants. FTP4W will send it to the server and waits for its reply.

Note: The names of the commands given there are DIFFERENT from the commands you would type in by hand with a text-oriented FTP client. In fact, the ones you type in by hand are read by a higher-level "front end" to the REAL ftp, and that higher-level then translates them into shorter names.

To have the list of the codes accepted by the FTP servers, refers to the RFC 959.

Note: The application can not start a data-transfer with this command.

The return code is either a FTP code (ie 200) or a FTP4W error code (FTPERR_NOREPLY, FTPERR_SENDREFUSED, ...).

If szReplyBuf is not NULL, The reply (if any) is copied into a user's buffer.

Syntax FtpQuote (LPCSTR szCmd, LPSTR szReplyBuf, UINT uBufSize);

Arguments:

szCmd	The command to be sent
szReplyBuf	The buffer to copy the answer
uBufSize	The size of the user's buffer

Return Codes:

FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit
FTPERR_NOTCONNECTED
FTPERR_SENDREFUSED	Ftp4w can not send data
FTPERR_NOREPLY
A 3 digits number between 100 and 699.

FtpRecvFile / FtpAppendToLocaFile

Note : Since FtpAppendToLocalFile uses exactly the same syntax, only FtpRecvFile will be described. The only difference between them occurs when the local file already exists, in which case the Append function appends the remote file onto it, whereas the Recv function simply over-writes it.

This function copies a remote file to a local file. In the asynchronous mode, the function returns immediatly, then the application will receive a message when the transfer is completed with wParam=TRUE (transfer completed), lParam=return code. In the synchronous mode, the function returns when the transfer is completed.

In the notification mode, the application will receive a message each time some data has been received. The same message as above is used but wParam will be FALSE, lParam will be the current position in the file (it is also the number of bytes which have been received).

In synchronous mode, if bNotify has not been set, the final arguments hParentWnd and wMsg are not used.

If the local file already exists, The function FtpRecvFile over-writes it, whereas FtpAppendToLocalFile appends the remote file at the end of the file.

If the file does not exists, it is created in any case.

Syntax:

FtpRecvFile (LPCSTR szRemote, LPCSTR szLocal, 
             char cType, BOOL bNotify,
             HWND hParentWnd, UINT wMsg)
FtpAppendToLocalFile (LPCSTR szRemote, LPCSTR szLocal, 
                      char cType, BOOL bNotify,
                      HWND hParentWnd, UINT wMsg)

Arguments:

szRemote	Remote file specification
szLocal	The file where to write the data.
cType	TYPE_A for ASCII, TYPE_B for binary
bNotify	A message should be sent by to the application each time a frame has been received.
hWnd	the handler of the windows to which the message is to be passed
wMsg	the application-defined message to be passed to the application

Return Codes:

FTPERR_OK	File received
FTPERR_PASVCMDNOTIMPL	Server does not support passive mode
FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit
FTPERR_NOTCONNECTED	User is not connected to a remote host
FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)
FTPERR_NOREMOTEFILE	Remote file has ot been found
FTPERR_CANCELBYUSER	Operation aborted by FtpAbort
FTPERR_DATACONNECTION	Error in data connection
FTPERR_SERVERCANTEXECUTE	Server rejects the command
FTPERR_CANNOTCHANGETYPE	The server has rejected the command TYPE
FTPERR_CANTOPENLOCALFILE	Local file can not been open
FTPERR_CANTWRITE	FTP4W can not write in local file (disk full)
FTPERR_CANTCREATESOCKET	No more free sockets (Two sockets needed)
FTPERR_TRANSFERREFUSED	the server refused the Retrieve command
FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection

FtpRecvThroughDataConnection

This command allows the application to reads data from the file transfer stream. It should be used if the application needs to process in "real time" the incoming data.

The data connection should have been opened by FtpOpenDataConnection.

The application should call FtpCloseDataConnection after receiving an FTPERR_ENDOFDATA return code.

Syntax: int FtpRecvThroughDataConnection (LPSTR szBuf, unsigned int *lpBufSize)

Arguments:

szBuf	The buffer which will receive the data
lpBufSize	A pointer on an integer which gives the size of szBuf and which will be set to the amount of read data.

Return Codes:

FTPERR_OK	Data has been received
FTPERR_ENDOFDATA	The server has no more data to send
FTPERR_DATACONNECTION	Error during recv or time-out.
FTPERR_CANCELBYUSER	Transfer aborted by FtpAbort

FtpRelease

FtpRelease must be called before the application exits. It frees all resources taken by FtpInit.

The function requires no arguments.

Syntax: FtpRelease ()

return codes:

FTPERR_OK	Resources have been released
FTPERR_STILLCONNECTED	The connection is still active. Nothing has been done.
FTPERR_NOACTIVESESSION	FtpInit has not been called

FtpRenameFile

FtpRenameFile allows the application to change the name of a remote file. With some FTP servers, the remote file can be moved in a different directory.

Syntax: FtpRenameFile (LPCSTR szFrom, LPCSTR szTo)

Arguments:

szFrom	The name of the file to be renamed
szTo	The new name or the new location of the file

return codes:

FTPERR_OK	File has been renamed/moved
FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit
FTPERR_NOTCONNECTED	User is not connected to a remote host
FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)
FTPERR_FILELOCKED	File can not be renamed
FTPERR_NOREMOTEFILE	File szFrom does not exist
FTPERR_SERVERCANTEXECUTE	The server has refused the command (user can not write in directory, the file szTo already exists, ...)

FtpRestart

This command makes the server to begin the next file transfer at the specified position. This command should be issued just prior a file transfer request, which is not possible with the high-level transfer functions. Therefore this is mostly an internal command.

It has been exported since some servers does not support this command. Thus it is an easy way to check the server before starting any file transfer.

Syntax: FtpRestart (long lByteTransfer)

Argument :

lByteTransfer

Position of the next file transfer. If this value is negative or 0, the function does nothing and returns FTPERR_RESTARTOK

return codes:

FTPERR_RESTARTOK	The command successful but it has no effect.
FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection
FTPERR_CMDNOTIMPLEMENTED	Command not implemented

FtpRestartRecvFile

This command starts a file transfer from a specified position. Please refer to the FtpRecvFile command to have more info concerning file transfers.

This command should be used only in binary mode, since the position in a text file has little meaning.

Syntax:

FtpRestartRecvFile (LPSTR szRemote, HFILE hLocal, char cType, 
                    BOOL bNotify, long lByteCount,
                    HWND hParentWnd, UINT wMsg);

Arguments :

szRemote	The remote file to be received
hLocal	A Windows handler to an opened file which is to be written
cType	TYPE_A for ASCII, TYPE_B for binary
bNotify	A message should be sent by to the application each time a frame has been received.
lByteCount	Starting position of the transfer
hWnd	the handler of the windows to which to pass the message
wMsg	the application-defined message to pass to the application

Return Codes:

FTPERR_OK	File received
FTPERR_PASVCMDNOTIMPL	Server does not support passive mode
FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit
FTPERR_NOTCONNECTED	User is not connected to a remote host
FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)
FTPERR_CANNOTCHANGETYPE	The server has rejected the command TYPE
FTPERR_CANTOPENLOCALFILE	Local file can not been open
FTPERR_CANTWRITE	FTP4W can not write in local file (disk full)
FTPERR_CANTCREATESOCKET	No more free sockets (Two sockets are needed)
FTPERR_TRANSFERREFUSED	the server refused the Retrieve command
FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection.
FTPERR_CMDNOTIMPLEMENTED	Command not implemented on the remote server
FTPERR_NOREMOTEFILE	File has not been found
FTPERR_CANCELBYUSER	Transfer aborted
FTPERR_DATACONNECTION	Error in data connection
FTPERR_SERVERCANTEXECUTE	Command rejected by the server

FtpRestartSendFile

This command starts a file transfer from a specified position. Please refer to the FtpSendFile command to have more info concerning file transfers.

This command should be used only in binary mode, since the position in a text file has little meaning.

Syntax:

FtpRestartSendFile (HFILE hLocal, LPCSTR szRemote, char cType, 
                    BOOL bNotify, long lByteCount,
                    HWND hParentWnd, UINT wMsg);

Arguments :

hLocal	A Windows handler to an opened file which is to be read. Ftp4w starts reading this file from the current position
szRemote	The remote file to be written from the position lByteCount.
cType	TYPE_A for ASCII, TYPE_B for binary
bNotify	A message should be sent by to the application each time a frame has been received.
lByteCount	Starting position of the transfer
hWnd	the handler of the windows to which to pass the message
wMsg	the application-defined message to pass to the application

Return Codes:

FTPERR_OK	File has been sent
FTPERR_PASVCMDNOTIMPL	Server does not support passive mode
FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit
FTPERR_NOTCONNECTED	User is not connected to a remote host
FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)
FTPERR_CANNOTCHANGETYPE	The server rejects the command TYPE ASCII
FTPERR_CANTOPENLOCALFILE	Local file can not been open
FTPERR_CANTWRITE	FTP4W can not write in local file (disk full)
FTPERR_CANTCREATESOCKET	No more free sockets (Two sockets are needed)
FTPERR_TRANSFERREFUSED	the server refused the STOR command
FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection
FTPERR_CMDNOTIMPLEMENTED	Command not implemented
FTPERR_CANCELBYUSER	Transfer aborted
FTPERR_DATACONNECTION	Error in data connection
FTPERR_SERVERCANTEXECUTE	Command rejected by the server

FtpRMD

This function removes a directory from the remote server.

Syntax: FtpRMD (LPCSTR szPath)

Argument:

szPath

name of the directory to be deleted

Return Codes:

FTPERR_OK	Directory has been removed
FTPERR_SERVERCANTEXECUTE	RMD has failed (directory is not empty)
FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit
FTPERR_NOTCONNECTED	User is not connected to a remote host
FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)
FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection
FTPERR_FILELOCKED
FTPERR_CMDNOTIMPLEMENTED

FtpSendAccount

This function sends the account to the server. This function should be used when FtpLogin or FtpSendPasswd return FTP_ENTERACCOUNT.

Syntax: FtpSendAccount (LPCSTR szAccount)

Argument:

szAccount

Account information

Return Codes:

FTPERR_OK	User is logged on
FTPERR_LOGINREFUSED	The USER/PASSWD/ACCOUNT has been rejected
FTPERR_NOTCONNECTED	User is not connected to a remote host
FTPERR_NOTINITIALIZED	session has not been initialized by FtpInit
FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)
FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection.
FTPERR_CMDNOTIMPLEMENTED

FtpSendFile / FtpAppendToRemoteFile

Note : Since FtpAppendToRemoteFile uses exactly the same syntax, only FtpSendFile will be described. The only difference between them occurs when the remote already exists, in which case the Append function appends the local file onto it, whereas the Send function simply over-writes it.

This function copies a local file to a remote file.

The application will receive a message when the transfer is completed with wParam=TRUE (transfer completed), lParam=return code. In the synchronous mode, the function returns only after the transfer has been completed.

In the notification mode, the application will receive a message each time some data has been sent. The same message as above is used but wParam will be FALSE, lParam will be the current position in the file (it is also the number of bytes which have been sent).

In synchronous mode, if bNotify has not been set, the final arguments (hParentWnd and wMsg) are not used.

Syntax:

FtpSendFile (LPCSTR szLocal, LPCSTR szRemote, 
             char cType, BOOL bNotify,
             HWND hParentWnd, UINT wMsg)
FtpAppendToRemoteFile (LPCSTR szLocal, LPCSTR szRemote, 
                       char cType, BOOL bNotify,
                       HWND hParentWnd, UINT wMsg)

Return Codes:

FTPERR_OK	File has been sent
FTPERR_PASVCMDNOTIMPL	Server does not support passive mode
FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit
FTPERR_NOTCONNECTED	User is not connected to a remote host
FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)
FTPERR_CANNOTCHANGETYPE	The server rejects the command TYPE ASCII
FTPERR_CANTOPENLOCALFILE	Local file can not been open
FTPERR_CANTWRITE	FTP4W can not write in local file (disk full)
FTPERR_CANTCREATESOCKET	No more free sockets (Two sockets are needed)
FTPERR_TRANSFERREFUSED	the server refused the STOR command
FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection
FTPERR_CANCELBYUSER	Transfer aborted
FTPERR_DATACONNECTION	Error in data connection
FTPERR_SERVERCANTEXECUTE	Command rejected by the server

FtpSendPasswd

This function sends the password to the server.

Note: As specified in the RFC 959, this password is sent "as it" on the network.

Syntax: FtpSendPasswd (LPCSTR szPasswd)

Argument:

szPasswd

Password of the user

Return Codes:

FTPERR_OK	User is logged on
FTPERR_ACCOUNTNEEDED	Successful function but server awaits an account name.
FTPERR_LOGINREFUSED	The USER/PASSWD has been rejected
FTPERR_NOTCONNECTED	User is not connected to a remote host
FTPERR_NOTINITIALIZED	session has not been initialized by FtpInit
FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)
FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection.
FTPERR_CMDNOTIMPLEMENTED

FtpSendThroughDataConnection

This command allows the application to sends data by the file transfer stream. It should be used if the data to be sent do not come from a file.

To end the data transfer, the application should call FtpCloseDataConnection.

Syntax: int FtpSendThroughDataConnection (LPCSTR szBuf, unsigned int uBufSize)

Arguments:

szBuf	The buffer which contains the data
uBufSize	The amount of data to be sent

Return Codes:

FTPERR_OK	Data has been received
FTPERR_DATACONNECTION	Error during recv or time-out.

FtpSendUserName

This function sends the user's name to the server. This authentification is necessary to begin a file transfer.

This function will usually return the "error-like" return value: FTPERR_ENTERPASSWORD (Successful function but server awaits a password). It means only that everything is just fine, it is simply reminding them that it still needs the password.>

Syntax: FtpSendUserName (LPCSTR szUserName)

Argument:

szUserName

Name of the user

Return Codes:

FTPERR_OK	User is logged on
FTPERR_ENTERPASSWORD	Successful function but server awaits a password.
FTPERR_NOTCONNECTED	User is not connected to a remote host
FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit
FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)
FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection.
FTPERR_SERVERCANTEXECUTE	Command rejected by the server

FtpSetAsynchronousMode / FtpSetSynchronousMode

Syntax:

void FtpSetAsynchronousMode (void)

void FtpSetSynchronousMode (void)

These functions changes the mode of Ftp4w's kernel.

In synchronous mode, Ftp4w does not return the control to the calling program until the transfer has ended. On the other hand, in asynchronous mode, Ftp4w returns quickly to the calling program then works in background, it uses user-defined messages to report the end of the operation.

Many languages does not handle user-defined message. They can only use Ftp4w in synchronous mode.

FtpSetDefaultPort / FtpSetDefaultTimeOut

Syntax:

int FtpSetDefaultPort (int nDefPort)

int FtpSetDefaultTimeOut (int nTimeOutInSeconds)

These functions are used to change either the FTP-control port (21 by default) or the timeout (30 seconds by default).

Note that the FTP-data potr can not be changed.

The new timeout is given in seconds.

FtpSetNewDelay / FtpSetNewSlices

Syntax:

int FtpSetNewDelay (int nNewDelayInMilliseconds)

int FtpSetNewSlices (int nSliceAlone, int nSliceMultiUser)

When a given number of frames has been received during a data transfer, FTP4W will wait for a while in order to let other tasks run.

FtpSetNewDelay allows the application to change the length of the pause. The argument is the length of the pause to be applied in milliseconds.

FtpSetNewSlices is used to change the number of frames which will cause a pause. The first argument is the number of frames when one FTP session are active, the second argument is used when two or more sessions are active.

Both arguments should not be set to zero.

FtpSetPassiveMode

Syntax:

void FtpSetPassiveMode (BOOL bPassif)

These command requests the FTP-server to "listen" on a data port and to wait for a connection rather than initiate one upon receipt of a transfer command.

These command is not implemented on all FTP-server, and thus the application must check the return code of the next data-transfer (FtpRecvFile, FtpSendFile, FtpDir).

Note: If FtpInit has not been called, these calls will cause a GPF.

Arguments:

bPassif

TRUE if the application wants to switch to passive mode, FALSE if it wants to reset the default mode.

FtpSetType

This function changes the default transfer type.

Syntax: FtpSetType (char cType)

Argument:

cType

new default transfer mode (either TYPE_A or TYPE_I)

Return Codes:

FTPERR_OK	Type has been changed
FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit
FTPERR_NOTCONNECTED	User is not connected to a remote host
FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)
FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection
FTPERR_CMDNOTIMPLEMENTED
FTPERR_CANNOTCHANGETYPE

FtpSetVerboseMode

If a programmer needs to have a look on each frame sent by the server, he uses this function. He will get a message (by the SendMessage function) each time a frame has been received. The argument wParam is TRUE, lParam points to the frame. It is NULL-terminated but can contain p more than one line (a line is ended with <CR><LF>).

Note that the frame will be overwritten by the next reply from the server.

Syntax: FtpSetVerboseMode (BOOL bVerboseMode, WND hWnd, WMSG wMsg)

Arguments:

bVerboseMode	TRUE if the application wants to watch incoming messages,
	FALSE to end a previous FtpSetVerboseMode
hWnd	the handler of the window to which the message is to be passed
wMsg	the application-defined message to be passed to the application each time a frame has been received.

Return codes

FTPERR_OK	Mode has been changed
FTPERR_NOTINITIALIZED	session has not been initialized by FtpInit

FtpSyst

This command asks to the server the system on which it is running.

The return code is either a FTP4W error code (FTPERR_NOREPLY, FTPERR_SENDREFUSED, ...). or the index into the array of strings passed as an argument.

The argument given is an array of pointers to string. Each string should contain a possible system name. The final pointer must be NULL The function returns the index of the string whose contents matches the answer returned by the server. If no system name has been found, FTPERR_SYSTUNKNOWN is returned.

In the given strings, upper and lower case characters are to be treated identically.

Since the position of the system's name in the host's answer is unknown, it can not be returned in a buffer. If the application wants to have the full host's answer, it must either use the verbose mode (FtpsetVerboseMode) or use the FtpQuote command.

Syntax FtpSyst (LPCSTR FAR *szSystStr)

Arguments:

szSystStr

An array of strings that contains the system names to be checked.

Return Codes:

The index of the array of strings
FTPERR_NOTINITIALIZED	Session has not been initialized by FtpInit
FTPERR_SYSTUNKNOWN	The server has returned a string, but its answer does not match with the array of strings given as argument.
FTPERR_NOTCONNECTED	User is not connected to a remote host
FTPERR_SENDREFUSED	FTP4W can not send the data (network is down)
FTPERR_NOREPLY	FTP4W has received no reply. FTP4W does not close the connection socket (use FtpLocalClose).
FTPERR_UNEXPECTEDANSWER	FTP4W has received a reply. But this reply is not a valid FTP answer. FTP4W does not close the connection

Example:

static char *szSystem[] = { "Unix", "VMS", "Dos", NULL };
   Rc=FtpSyst (szSystem);
   printf ("System %s", Rc==FTPERR_SYSTUNKNOWN ? "Unknown": szSystem[Rc]);