Magenta Systems File Transfer Components v1.5
=============================================

Updated by Angus Robertson, Magenta Systems Ltd, England, 14th November 2005
delphi@magsys.co.uk, http://www.magsys.co.uk/delphi/
Copyright Magenta Systems Ltd

Magenta Systems File Transfer Components comprise three Delphi components,
TMagFtp, TMagHttp and TMagFileCopy, the first two of which are high level
descendants of the ICS TFtpClient and THttpCli components, all allowing
transfer of multiple files and subdirectories with a single function call.

The three components handle file listing from FTP, HTTP and disk volumes,
and multiple file copying.  They also include optional zipping or unzipping
(requires TVCLZip component).  There are numerous options available,
including copying only newer files, deleting old target files, deletion
after transfer, resumed failed FTP downloads and uploads, and a progress
events with various levels of information for logging or display, depending
upon application requirements that allows transfers to be cancelled. FTP
and file copying supports files larger than 2 gigs (64-bit).

A simple demonstration program that illustrates all major functionality.
End user help is available describing most of the functionality in Magenta
Systems DUN Manager application (from http://www.magsys.co.uk/dunman/),
look under Scheduled Task Properties, FTP General, FTP Common, FTP Upload,
FTP Download. HTTP Download and Sync Files.  DUN Manager also provides a
compiled test application for the components, using all functions (but DUN
Manager source code is not available).

Magenta Systems File Transfer Components are copyrighted software, but
the compiled component DCUs may be used without cost in applications for
use by the developer or within their company but which are not otherwise
distributed (including freeware and shareware).  The component source
code may be licensed for a cost of 65 (UKP) (76.38 with UK tax) which
is about $115, or is available without extra cost to anyone that has
financially contributed to the development of the ICS SSL version at
http://www.overbyte.be/ or that has licensed Magenta Systems TMagRas
component. Developers that license the source may distribute applications
using Magenta Systems File Transfer Components without further cost. The
compiled components are available for Delphi 6, 7, 2005 and 2006.


Usage Overview
--------------

TFileRec

The three file transfer components all rely on a common file listing
record type:

TFileRec = record
    FrFileName: string ;    // filename and extension
    FrSubDirs: string ;     // \ for base directory, else located sub dirs
    FrDirLevel: integer ;   // 0 for base directory, or level of sub dirs
    FrDirBaseLen: integer ; // length of basedir within FullName
    FrFullName: string ;    // basedir, subdirs, filename - complete path
    FrFileBytes: int64 ;    // size of file in bytes
    FrFileDT: TDateTime ;   // file time stamp - local time
    FrFileUDT: TDateTime ;  // file time stamp - UTC time
    FrFileAttr: integer ;   // bitmapped Windows file attributes
    FrExtra: string ;       // <DIR> or UNIX file attributes
    FrLinks: string ;       // not blank means this is not a real file
    FrFileCopy: TFileCopyState ;  // file copy state, selected, done, etc,
end ;

This record is used in TFileRecs dynamic arrays, and is filled by Windows
FindFile APIs for local files (in BuildDirList2) , from the FTP DIR or
MLSD commands (in FtpDir), or by parsing HTML for links (in Download).
Local and FTP file indexing optionally supports listing sub-directories.
Generally, two file record lists are built, for local and remote files,
and then compared (using SelectCopyFileList) to select the files that
need to be copied and optionally deleted (locally or remotely) to cause
synchronisation of directories.

The components also offer methods for handling single files, rather than
whole directories.


TFindList

This is a descendent of TList added a Find function using binary search
identical to sorting, that is much more efficient than the normal IndexOf
method when the file list contains potentially up to a million items.

function Find (const Item2: Pointer; Compare: TListSortCompare;
                                    var index: longint): Boolean;

This is used with the function CompareFNext to compare file name records
with case insensitivity.  A list of file name records in the dynamic array
is built into a TFindList and sorted, allowing the files to accessed in
sorted order, and also easing comparison between source and target lists.
Generally, this file list handling is all hidden, when doing straight
copying.


TBulkCopyEvent

The three component also share a common progress event, that returns
various levels of progress information for display to the user and
for logging, depending upon the application.  The progress events
also allows copying to be cancelled, including part way through a file.

TBulkCopyEvent = Procedure (LogLevel: TLogLevel ; Info: string ;
                                        var Cancel: boolean) of object ;

LogLevelInfo - general copying information, start, finish, etc
LogLevelFile - file level information, start, finish, etc
LogLevelProg - progress per file, chunks copied - avoid if possible
LogLevelDiag - diagnostic information - generally ignore
LogLevelDelimFile - seven | delimited fields after each file for logging
LogLevelDelimTot - seven | delimited fields after each job for logging

The delimited logging lines are seven fields:

SrcFile|TarFile|Size|Succ|Fail|Comm|Duration

Where succ and fail are digits, 0 or 1 for single files, larger for totals,
duration is milliseconds, comment might be OK or reason for failure.

For example, for LogLevelDelimFile after copying a single file:

d:\windows\system32\drivers\gmreadme.txt|d:\tempfiles\drivers\
  gmreadme.txt|646|1|0|OK|15

For example, for LogLevelDelimTot, totals after copying a directory:

d:\windows\system32|d:\tempfiles|419554|49|0|Totals|


TFileCopyType

Specifies the type of copying the component should perform, also used
for file deletion.

FCTypeSingle - just a single file will be copied
FCTypeMaskDir - multiple files will be copied that match the mask file
  Name (ie *.* for all *.zip for just zip files)
FCTypeArchDir - any files with the Archive file attribute set and matching
  the mask will be copied.  Note the attribute is not changed
FCTypeAllDir - all files found will be copied.
FCTypeDates - all files found will be copied within a date/time range


TFileCopyRepl

Specifies whether target files that exist should be replaced.

FCReplNever - copy will be skipped
FCReplAlways - always replace
FCReplDiff - replace if time stamp or size different
FCReplNewer - replace if time stamp newer or size different


TFileCopyState

This is primarily an internal copy state kept in TFileRec for each file,
which is updated as selection and copying proceeds.

FCStateNone - nothing done
FCStateIgnore - copy will be skipped
FCStateDir - file is directory entry
FCStateSelect - waiting to copy file
FCStateCopying - file being copied
FCStateOK - copied OK
FCStateFailed - copy failed


TTaskResult

Many of the methods return a typed task result:

TaskResNone - task did not start
TaskResOKNew - task finished OK and copied files
TaskResOKNone - task finished OK but found nothing to copy
TaskResFail - task failed, reason will be in ReqResponse property
TaskResAbort - task was aborted, usually by user or lost connection


The full interface sections of the various components are listed in
interfaces.txt.


TMagFileCopy
------------

TMagFileCopy is a high level HTTP Delphi component that allows indexing
and copying of multiple file directories, using a single function call.
The component handles listing source and destination files, and comparing
them to avoid unnecessary transfers, selection using a file mask, deletion
of old files, delete after copy, safe copy (to avoid partial files), and
zip before copying or unzip after copy.  The component is equally useful
for copying single files or entire volumes with hundreds of thousands of
files, and provides 'sync files' functionality making it ideal for
backups, only copying changed files and deleting old target files.

Note there are two distinct copying modes in TMagFileCopy, copying a
single directory (and subdirectories) and copying a list of multiple
specific directories (and subdirectories).

Properties to set before copying multiple files:

CopyEvent: TBulkCopyEvent - with a logging and progress function

MultiDir: boolean - true copy multiple specific directories, false single

MultiDirList: string - multi directories are passed as srcdir+tab+tardir+
    recsep (repeat) for as many pairs as needed.  The srcdir may
    optionally include a masked file name (including *)

SrcDirList: TStringLists - alternate to MultiDirList, source dirs only
TarDirListTStringLists - alternate to MultiDirList, target dirs only


SrcDir: string - not multidirs, the source directory
TarDir: string - not multidirs, the target directory
SrcFName: string - optional mask name (including *) for partial copy
SubDirs: boolean - true copy all sub directories

CopyType: TFileCopyType - see above
LocalHost: string - set to WSocket.LocalHostName if using masked name
Mask: boolean - true, allow date/time mask characters in SrcFName,
  also $H will be replaced by the LocalHost (see above)
Prev: boolean - true, use yesterday's date for Mask

DelDone: boolean - true delete source file after copy
DelOldTar: boolean -true, delete target files not in source directory
Repl: TFileCopyRepl - see above
ReplRO: boolean - true, replace read only files
Safe: boolean - true, copy file with TMP extension, rename when done
IgnoreFileExt: string - a delimited list of file extensions to ignore

UseUTC: Boolean - whether to compare file timestamps in UTC or local time
CopyLoDT: TDateTime - for CopyType FCTypeDates, lower date/time
CopyHiDT: TDateTime - for CopyType FCTypeDates, higher date/time

Main Methods

function SelCopyFiles (const CheckFiles: boolean): TTaskResult ;

This is the main method that selects and copies files.

If CheckFiles is true it skips the actual copying just returning a list
of the files selected for copying, with file records in SrcFiles and the
sorted pointers in SrcFileList, if CopyState is FCStateSelect the file
has been selected for copying.

If CheckFiles is false, the selected files will be copied, with the result
showing success or otherwise.  Several properties are completed with
various totals processed: TotProcFiles, ProcOKFiles, DelOKFiles,
ProcFailFiles, SkippedFiles, TotProcBytes, ProcOKBytes and DelOKBytes.
The file records in SrcFiles and the sorted pointers in SrcFileList are
updated with the success or failure of each file copied, although logging
will normally have been done on a file by file basis through the
CopyEvent.

Use of the SelCopyFiles function is illustrated in the demo application.


function DeleteFiles (const CheckFiles: boolean): TTaskResult ;

This method is for deleting multiple files, it uses the same source file
properties as SelCopyFiles, including CopyType, except no MultiDir.

Use of the DeleteFiles function is illustrated in the demo application.


procedure Cancel ;

This method will cancel copying.


function GetTaskResName (TaskResult: TTaskResult): string ;

This function returns an ASCII version of the task result.


Support Functions

A number of the functions used internally by SelCopyFiles are available
for separate use in applications that need to index and process files.

function MagDeleteFile (const Fname: string;
                                const ReadOnly: boolean): Integer ;

This function deletes a single file, optionally removing the read only
attribute. Returns 0 for delete OK, -1 file not found, 1 could not remove
read only, larger number failed and is GetLastError code.


function MagRenameFile (const OldName, NewName: string;
                            const Replace, ReadOnly: boolean): Integer ;

This function renames a single file, optionally replacing it, optionally
removing read only attribute.  Returns 0 for replace OK, 1 could not
remove read only, 2 new file exists (and Replace false), larger number
failed and is GetLastError code.


function DeleteEmptyDirs (RootDir: string; DirList: TStringList): integer ;

This function deletes empty directories, typically after all the files in
them have been deleted.  It also deletes higher level directories, down to
the specified root directory.


function CopyOneFile (const Fnamesrc, Fnametar: string ; Replopt:
  TFileCopyRepl; const Safe: boolean; var Fsize: Int64) : TTaskResult ;

This function copies a single file, using source and target file names,
and standard Replopt options.  Fsize will be filled with the size copied,
if successful.  CopyEvent is called with progress messages.


function BuildDirList2 (LocDir, LocPartName: string; const SubDirs:
    boolean; Level, InitDLen: integer ; const LoDT, HiDT: TDateTime ;
              var TotFiles: integer; var LocFiles: TFileRecs): boolean ;

This is the main local file indexing function, that calls itself
recursively if SubDirs is specified to build-up lists of files in the root
and sub-directories.  LocDir is the local directory to index, it may be a
root.  LocPartName is an optional file name mask for sub-selection.  Level
and InitDLen should be 0 (they are used for recursive calls).  LoDT and
HiDT are an optional date selection range (if non-zero). Files are listed
in non-sorted order into a dynamic array LocFiles, with the initial number
of listed files in the array specified by TotFiles (this need not be
zero). The  CopyEvent is called with progress messages. It returns false
for error or if cancelled from CopyEvent.  This function will index
hundreds of thousands of files on a large volume, but will take a few
minutes to do so.


function BuildDirList (LocDir, LocPartName: string; const SubDirs:
    boolean; Level, InitDLen: integer ; var TotFiles: integer;
                                  var LocFiles: TFileRecs): boolean ;

This function calls BuildDirList2, but ignores file date ranges.


function GetDirList (LocDir, LocPartName: string; const SelOpt:
    TFileCopyType; const SubDirs: boolean; LoDT, HiDT: TDateTime ;
        var LocFiles: TFileRecs; var LocFileList: TFindList): integer ;

This function calls BuildDirList2, but has differing parameters, in
particular SelOpt and a LocFileList which is filled with a sorted
pointer list to LocFiles. It returns the total number of files found
or -1 if cancelled or an error.


function SelectCopyFileList (const SrcFileList, TarFileList: TFindList;
     const fname: string; const selopt: TFileCopyType;
       const replopt: TFileCopyRepl; const DiffStamp: integer;
         const IgnoreOldTime: boolean; IgnoreExt: string ;
               var skipped: integer; const UTCFlag: boolean): integer ;

This is the main function that is used to compare source and target file
lists against each other and the specified Copy Type and Replace options
and to select files that should be copied.  It may also be used to locate
which files are in the target directory but not the source, to allow
deletion is synchronising directories.  When comparing hundreds of
thousands of files, this function will take a few minutes.  DiffStamp
is the number of minutes difference in time stamp before a file is
considered different, use 61 or 62 minutes to avoid summer times issues.


function MagCheckReplace (const replopt: TFileCopyRepl;
       const IgnoreOldTime: boolean; const AllowDiffDT: TDateTime;
         const SrcSize, TarSize: Int64; SrcDT, TarDT: TDateTime): boolean ;

This function is used to determine if a single file should be replaced, by
comparing file sizes and time stamps, and the specified Replopt option.


function FmtFileDir (const FileRecs: TFileRecs;
                                        const UTCFlag: boolean): string ;

Format an unsorted file directory from FileRecs array, into a multi-line
ASCII string which may be very large.


function FmtFileDirList (const LocFileList: TFindList;
                                        const UTCFlag: boolean): string ;

Format an sorted file directory from File List pointer to an array, into
a multi-line ASCII string which may be very large.


function DispLocFiles (const SrcDir, SrcFile: string ; const CopyType:
        TFileCopyType ; const SubDirs: boolean; const UTCFlag: boolean): string ;

This function builds a displayable file directory a multi-line ASCII string,
it calls BuildDirList2 and FmtFileDirList.

Use of the DispLocFiles function is illustrated in the demo application.


function CheckDirAny (LocDir: string): boolean ;

Check if a directory contains at least one file or sub-directory, used
before deleting the directory.


Network File Share Methods

File copying will often work across a LAN using UNC share names, provided
the remote computer accepts the same logon as the local computer.  If not,
it's necessary to first connect to the remote computer with a logon,
which can either map a drive letter to the remote share or just create a
connection so UNC file names may be used for copying.  Note it's more
efficient to use mapped drives.  Properties that should be set are:

LocalName: string - blank if using UNC names, otherwise drive, ie N:
RemoteName: string - UNC name of remote share, ie \\sysname\share
UserName: string - a logon user name for remote share
Password: string - a logon password for remote share

Methods

function Connect: boolean ;

Connect with LocalName, RemoteName, UserName and Password to the remote
computer, true if successful, error in ReqResponse, CopyEvent is called.

function Disconnect (AForce: boolean): boolean ;

Disconnect the remote share specified in LocalName or RemoteName.


function GetConnection (ALocalName: string): string ;

Checks if a local drive, ie N:, is connected to a remote share, returning
the remote name if found, or blank if not.  Result also in ReqResponse.



TMagFTP
-------

TMagFtp is a high level FTP Delphi component that allows uploading or
downloading of multiple files from or to an FTP server, from a single
function call.  The component handles listing local and remote files,
including subdirectories, and comparing them to avoid unnecessary
transfers, selection using a file mask, deletion of old files, resuming
failed FTP downloads, unzipping of downloaded files, or zipping before
upload, deletion after uploading or downloading, archive copy after
upload.  A progress event provides various levels of information for
logging or display, depending upon application requirements, and allows
transfers to be cancelled.

TMagFtp descends from ICS TFtpClient, and publishes all it's logon and
proxy properties and events.

Note the component transfer files using temporary file names, only
renaming them to the correct name once the file is confirmed as being
the correct size. So the file test.zip will be uploaded as test_zip.tmp.
This avoids partial real files being left if a connection drops, and is
also used for file resuming, which uses the name test_zip.ftp on the
local computer to store details for possible resumed upload or download
in case of interruption.  The component may be set to immediately repeat
a failed transfer, a specified number of times.

The component attempts to make of the most efficient FTP commands
supported by the server, as reported by the FEAT command.  Specifically,
historically FTP had very poor file indexing with different servers
returning widely differing responses to the LIST file directory command.
The component will use the MLSD, MSLST and MDTM commands if possible for
better listing (using UTC time in particular), and will also use MFMT or
MDTM YYYYMMDDHHMMSS to set the time stamp of uploaded files, if possible.
It uses the MD5 command to perform an MD5SUM check on transferred files to
confirm file integrity.

Properties to set before transferring any files, these relate to the FTP
server and optional proxies, retries, etc.  Also see the ICS documentation
for details of specific FTP properties.

HostName1: string - main FTP server host name or IP address
HostName2: string - alternate FTP server host name or IP address, if
  main server can not be contacted
UserName: string - FTP server logon name
PassWord: string - FTP server logon password
Port: string -  FTP server port, usually 21
MaxAttempts: integer - number of attempts to connect to the FTP server,
  if HostName2 is specified this will alternate with HostName1
AttemptDelay: integer - delay in seconds between connection attempts
FailRepeat: integer - how many times to retry a failed file transfer
ConnectionType: TFTPConnectionType - ftpDirect, ftpProxy, ftpSocks4,
    ftpSocks4A, ftpSocks5
ProxyPort: string - if ConnectionType = ftpProxy
ProxyServer: string - if ConnectionType = ftpProxy
SocksPort: string - if ConnectionType = ftpSocksX
SocksServer: string - if ConnectionType = ftpSocksX
SocksUsercode: string - if ConnectionType = ftpSocksX
SocksPassword: string - if ConnectionType = ftpSocksX

PassiveX: boolean - must only be changed after connection type, true
  if FTP passive mode is to used for the data connection
HostType: THostType - set to FTPTYPE_NONE for automatic detection
XferMode: TXferMode - set to XferModeBinary
CaseFile: TCaseFile  - FileLowerCase for Windows, sometimes FileMixedCase
    for Unix/Linux which has case sensitive file names
DiffStampMins: integer - number of minutes difference in time stamp
  before a file is considered different, use 61 or 62 minutes to avoid
  summer times issues
Timeout: integer - seconds to wait for response to command, typically 60
DispFiles: boolean - true to log file stamp information
DispRDir: boolean - true to log remote file directory
DispLDir: boolean - true to log local file directory
DispRemList: boolean - true to log FTP LIST responses for remote dir
UpArchive: boolean - true to move file to archive directory after
  successful upload, to avoid it being uploaded again
UpArchDir: string - if UpArchive true, directory to move file

ResFailed: boolean - if true, if possible resume failed uploads or
    downloads.  This requires a small file to be saved on the local
    PC, see above
BulkMode: TBulkMode - VERY important, either BulkModeDownload or
    BulkModeUpload, this determines how SrcDir/TarDir are used
SrcDir: string - the source directory, a local directory should include
    a drive or share, a remote directory should not since it will be
    the FTP server root for the user (also use forward slashes)
TarDir: string - the target directory
SrcFName: string - optional mask name (including *) for partial copy
SubDirs: boolean - true copy all sub directories

CopyType: TFileCopyType - see above, but not by Date Range
LocalHost: string - set to WSocket.LocalHostName if using masked name
Mask: boolean - true, allow date/time mask characters in SrcFName,
  also $H will be replaced by the LocalHost (see above)
Prev: boolean - true, use yesterday's date for Mask

DelDone: boolean - true delete source file after copy
DelOldTar: boolean -true, delete target files not in source directory
Repl: TFileCopyRepl - see above
ReplRO: boolean - true, replace read only files
IgnoreFileExt: string - a delimited list of file extensions to ignore


Main single functions:

These functions handle the entire FTP process, including connecting and
logging onto the FTP server, checking remote and local files, then
transferring any files, and finally logging off the FTP server.


function DispFtpDir (var dirlisting: string): TTaskResult ;

This function return a formatted file directory from the FTP server of
the target directory and optionally sub-directories, BulkMode should be
set to BulkModeDownload. The result will show success or otherwise.

Use of the DispFtpDir function is illustrated in the demo application.


function FtpDownload (const CheckFiles: boolean): TTaskResult ;

This is the main method that selects and download files.

If CheckFiles is true it skips the actual download just returning a list
of the files selected for downloading, with file records in SrcFiles and
the sorted pointers in SrcFileList, if CopyState is FCStateSelect the
file has been selected for downloading.

If CheckFiles is false, the selected files will be downloaded, with the
result showing success or otherwise.  Several properties are completed
with various totals processed: TotProcFiles, ProcOKFiles, DelOKFiles,
ProcFailFiles, SkippedFiles, TotProcBytes, ProcOKBytes and DelOKBytes.
The file records in SrcFiles and the sorted pointers in SrcFileList are
updated with the success or failure of each file downloaded, although
logging will normally have been done on a file by file basis through the
CopyEvent.

Use of the FtpDownload function is illustrated in the demo application.


function FtpUpload (const CheckFiles: boolean): TTaskResult ;

This is the main method that selects and uploads files.

If CheckFiles is true it skips the actual uploading just returning a list
of the files selected for uploading, with file records in SrcFiles and the
sorted pointers in SrcFileList, if CopyState is FCStateSelect the file
has been selected for uploading.

If CheckFiles is false, the selected files will be uploaded, with the
result showing success or otherwise.  Several properties are completed
with various totals processed: TotProcFiles, ProcOKFiles, DelOKFiles,
ProcFailFiles, SkippedFiles, TotProcBytes, ProcOKBytes and DelOKBytes.
The file records in SrcFiles and the sorted pointers in SrcFileList are
updated with the success or failure of each file uploaded, although
logging will normally have been done on a file by file basis through the
CopyEvent.

Use of the FtpUpload function is illustrated in the demo application.


procedure Cancel ;

This method will cancel downloads or uploads.


function GetTaskResName (TaskResult: TTaskResult): string ;

This function returns an ASCII version of the task result.


function LookupFTPReq (const RqType: TFtpRequest): String;

This functions returns an ASCII version of TFtpRequest, for diagnostic
purposes.


function LookupFtpState (const FtpState: TFtpState): String;

This functions returns an ASCII version of TTFtpState, for diagnostic
purposes.


Main multiple functions

These functions are used where more control is needed over the FTP
process, for instance where several single files are to be transferred
rather than an entire directory, or where a list of directories need
to be transferred.  FtpLogon must be called first, and FtpLogoff last.

function FtpLogon: TTaskResult ;

This function connects and logs onto to FTP server, the result will show
TaskResOKNew for successful logon, with any error in ReqResponse.  The
Connected property will also be true, and FtpLogoff must then be called
at some point.

Use of the FtpLogon function is illustrated in the demo application.


function FtpDir (var FtpFiles: TFileRecs;
                            var FtpFileList: TFindList): TTaskResult ;

This function builds file directory lists from the FTP server of the
target directory and optionally sub-directories, BulkMode should be
set to BulkModeDownload. The result will show success or otherwise.
It will fail unless the Connected property is true.


function FtpCheckFile (const RemDir, RemFile: string ;
                   var FSize: Int64; var FileUDT: TDateTime): boolean;

This function checks the time stamp and size of a single file on the FTP
server.  It is used by the MagFtp component before every download and
before and after every upload, to check the remote file details.
It will fail unless the Connected property is true.


function FtpDownFiles (const CheckFiles: boolean): TTaskResult ;

This function is identical to FtpDownload, except it assumes an already
connected FTP server. It will fail unless the Connected property is true.


function FtpDownOneFile (const FdirSrc, Fnamesrc, Fnametar: string ;
                                  Replopt: TFileCopyRepl) : TTaskResult ;

This function will download a single file from an already connected FTP
server. It will fail unless the Connected property is true.

Use of the FtpDownOneFile function is illustrated in the demo application.


function FtpUpOneFile (const LocFileFull, RemTarDir, RemTarFile: string;
                                    Replopt: TFileCopyRepl) : TTaskResult ;

This function will upload a single file to an already connected FTP server.
It will fail unless the Connected property is true.


procedure FtpLogoff ;

This function will disconnect from FTP server, if there is already a
connection to the server.  It will wait up to five seconds to confirm
the connection has been closed

Use of the FtpLogoff function is illustrated in the demo application.


TMagHttp
--------

TMagHttp is a high level HTTP Delphi component that allows downloading of
multiple files from an HTTP server using full URLs, or listed by parsing
links from a web page, using a single function call.  The component
handles listing local and remote files, and comparing them to avoid
unnecessary transfers, selection using a file mask, unzipping of
downloaded files.  A progress event provides various levels of information
for logging or display, depending upon application requirements, and
allows downloads to be cancelled. If authentication is needed for the
download, it may be specified in the URL in the format
http://logon:password@host/file.zip.

TMagHttp descends from ICS THttpCli, and publishes all it's properties
and events.

Properties to set before downloading any files, these relate to the HTTP
server and optional proxies, retries, etc.  Also see the ICS documentation
for details of specific HTTP properties such as authorisation or SOCKS.

URLList: string - one or more source URLs separated by CRLF
SrcMask: string - optional mask name (including *) for partial downloads
DownDir: string - the target directory for downloaded files
KeepPath: boolean - if true, use HTTP path for subdirs in DownDir
KeepHost: boolean - if true, use HTTP host for subdir in DownDir
ParseHTML: boolean - if true, parse HTML page for links to files
Proxy: string - if non-blank, an HTTP proxy server
ProxyPort: string - port for proxy server

Repl: TFileCopyRepl - see above
ReplRO: boolean - true, replace read only files
LogFiles: boolean - true to log each file downloaded
LogProt: boolean - true to log HTTP protocol
LogLDir: boolean - true to log local file directory
LogRDir: boolean - true to log remote file directory

Main functions:

function Download (CheckFiles: boolean): TTaskResult ;

If CheckFiles is true it skips the actual download just returning a list
of the URLs and parsed files selected for downloading, with file records
in SrcFiles and the sorted pointers in SrcFileList, if CopyState is
FCStateSelect the file has been selected for downloading.

If CheckFiles is false, the selected URLs and parsed files will be
downloaded, with the result showing success or otherwise.  Several
properties are completed with various totals processed: TotProcFiles,
ProcOKFiles, ProcFailFiles and SkippedFiles.  The file records in
SrcFiles and the sorted pointers in SrcFileList are updated with the
success or failure of each file downloaded, although logging will normally
have been done on a file by file basis through the CopyEvent.


procedure Cancel ;

This method will cancel downloads.


Files Enclosed
--------------

=Xfer Demo Application
demomain.dfm
demomain.pas
xferdemo1.dpr
xferdemo1.exe

=File Transfer Components
MagCopy.pas
MagFtp.pas
MagHttp.pas
magzip.inc
magxfer6.dpk
magxfer7.dpk
magxfer9.dpk
magxfer10.dpk

=Support files
HtmlPars.pas
latin1.pas
magclasses.pas
magsubs1.pas
magsubs4.pas


Requirements
------------

Requires Internet Component Suite (ICS) from http://www.overbyte.be/ dated
1st November 2005 or later.

Requires Kevin Boylan's TVCLZip component for zipping from
http://www.vclzip.net/, if you don't purchase this component you will need
to suppress DEFINE Zipping from MAGZIP.INC so the zip code is not linked.

Compatible with Delphi 6/7/2005/2006, tested with Windows 98, NT4,
Windows 2000, XP and 2003.  Files larger than 2 gigs needs Delphi 6 or
later.


Installation
------------

ICS must be installed first.  If the full ICS package is not available,
the minimum needed files are located in the ICS sub-directory, and should
be copied into the MagXfer root directory.

If the source code has not been purchased, copy the DCUs and package files
for the appropriate version of Delphi into the root directory.

Open the magxferX.dpr package file, where X is your version of Delphi,
build and install the package.  In Tools, Options, add the MagXfer root
directory to the library path.



Copyright Information
---------------------

Magenta Systems File Transfer Components are copyrighted software, but
the compiled component DCUs may be used without cost in applications for
use by the developer or within their company but which are not otherwise
distributed (including freeware and shareware).  The component source
code may be licensed for a cost of 65 (UKP) (76.38 with UK tax) which
is about $115, or is available without extra cost to anyone that has
financially contributed to the development of the ICS SSL version at
http://www.overbyte.be/ or that has licensed Magenta Systems TMagRas
component. Developers that license the source may distribute applications
using Magenta Systems File Transfer Components without further cost. The
compiled components are available for Delphi 6, 7, 2005 and 2006.
The source code must never be distributed, it is only available from
password protected areas of http://www.magsys.co.uk/delphi/ and
http://www.overbyte.be/.

Magenta Systems Ltd
9 Vincent Road
Croydon
CR0 6ED
United Kingdom

Phone 020 8656 3636, International Phone +44 20 8656 3636
Fax 020 8656 8127, International Fax +44 20 8656 8127

Email: delphi@magsys.co.uk
Web: http://www.magsys.co.uk/delphi/



