URL download helpers for ActiveX controls
=========================================

(c) 2000 Andrei Kashin (Andrei.Kashin@pobox.spbu.ru)

Version 1.00


Description
==========

This package contains helper classess and a component to simplify
the task of downloading data from URLs. It is intended to be used by
ActiveX controls embedded into Internet enabled containers
(mainly MS Internet Explorer). But it can be used in standalone applications
as well.


Status
======

  This software is provided 'as-is', without any express or 
  implied warranty. In no event will the author be held
  liable for any damages arising from the use of this
  software.
  Permission is granted to anyone to use this software for
  any purpose, including commercial applications, and to
  alter it and redistribute it freely, subject to the
  following restrictions:
  1. The origin of this software must not be misrepresented,
     you must not claim that you wrote the original software.
     If you use this software in a product, an acknowledgment
     in the product documentation would be appreciated but is
     not required.
  2. Altered source versions must be plainly marked as such,
     and must not be misrepresented as being the original
     software.
  3. This notice may not be removed or altered from any
     source distribution.


Support
=======

  I don't provide technical support. Nevertheless, bugs reports and
  suggestions are welcome.


Files
=====

  URLDownload.pas - implements classes TURLDownloader and TDownloaderToStream
                    to be used by ActiveX controls.

  URL_Loader.pas  - implements non-visual component TURL_Loader to be used by
                    TActiveForm descendants.

  URL_Loader.dcr  - TURL_Loader component bitmap.

  ReadMe.txt      - this file. 


Usage
=====

 Install component TURL_Loader from URL_Loader.pas (in usual way for Delphi).
 It will be put on 'Internet' page of the Delphi component palette.



Classes and components
=======================


TURLDownloader
--------------

TURLDownloader - the base URL download helper class
 
 Properties
  
   URL: string    (read only) 
              - specifies the URL from which data are downloaded.
   DownloadInProgress: boolean (read only)
              - indicates whether the downloading is in progress.
   AutoDestroy:boolean
              - specifies whether to destroy the TURLDownloader instance
                automatically after the download completion (OnDownloadStop event).
   BindFlags: DWord
              - specifies the download options. It can be combination of BINDF_xxx flags
              (UrlMon.pas). BINDF_ASYNCHRONOUS is always on, BINDF_ASYNCSTORAGE is
              always off. The setting of these flags is blocked.
   TotalRead: integer (read only)
               - indicates how much data was read (for current download operation).

 Methods

1) StartDownload - starts the downloading of data from the URL specified.

    procedure StartDownload(Caller:IUnknown; const DownloadURL:string;
                          HTTPRequestData:PHTTPRequestData = nil);
  
  The Caller should be a pointer to IUnknown interface of ActiveX control contained
  within Internet enabled framework (like MS Internet Explorer). This parameter
  can be "nil" if such framework is absent.

  The DownloadURL specifies the URL to download data from. It can be a relative URL
  (if Caller <> nil).

  Optional parameter HTTPRequestData specifies additional data for HTTP-request
  (Method, AdditionalHeaders, RequestBody). These data are used to form
  specific HTTP-requests. Method may be GET, POST, PUT or any custom. If Method
  is not specified then the GET method is assumed. HTTP-headers in AdditionalHeaders
  must be separated by #13#10 and the last HTTP-header must be ended by #13#10.
  RequestBody is ignored for the GET method.
    
2) AbortDownload - aborts the current download.
  
    procedure AbortDownload;


Events

1) OnStartDownload - occurs when downloading is started.
    
    OnStartDownload:TDownloadStartNotify;

    TDownloadStartNotify = procedure (Sender: TURLDownloader) of object;

   Write an OnStartDownload event handler to make necessary initializations.   


2) OnDownloadProgress - notifies about download progress.

    OnDownloadProgress: TDownloadProgressNotify;

    TDownloadProgressNotify = procedure (Sender: TURLDownloader;
                                         const Progress:TDownloadProgress) of object;   
   
   StatusCode field of TDownloadProgress structure tells about download stage.
   Values are taken from BINDSTATUS_xxx codes (UrlMon.pas).
   StatusText contains additional textual information specific for each download stage.
   ProgressMax indicates how much data is expected to receive.
   Progress field indicates how much data is received.

3) OnBytesAvailable - occurs when new data are available.

   OnBytesAvailable: TBytesAvailableNotify;

   TBytesAvailableNotify = procedure (Sender: TURLDownloader; BytesAvailable: integer;
                                      var BytesToRead: integer;
                                      var ReadBuffer: pointer) of object;

   On the arriving new portion of data two events occur. First OnBytesAvailable,
   second - OnDataRead. OnBytesAvailable event tells how much data is available
   to read and give you the following possibilities - first, to specify how much
   data you are ready to accept (parameter BytesToRead), and second (optinally),
   suply a pointer to a buffer where to write these data (parameter ReadBuffer).
   If you didn't specify the read buffer then it will be created automatically. 
   OnDataRead event notifies you how much and where data has been written to.
   If not all of available data has been read then the firing of these events
   is repeated.
   If you set BytesToRead to zero or greater than BytesAvaible then the subsequent
   OnDataRead is not fired and next OnBytesAvailable event occurs when more data is
   received. Do not use this option if you specified BINDF_PULLDATA flag for
   BindFlags property (otherwise the downloading will be suspended and the only way
   to exit this state will be to abort the downloading). You have to read all available
   data if you specified BINDF_PULLDATA flag.
   
4) OnDataRead - notifies how much and where new data has been written to.
   
    OnDataRead: TDataReadNotify;

    TDataReadNotify = procedure (Sender: TURLDownloader; 
                                 Data:pointer; DataSize: integer) of object;
    
    You can process these data as you want (on fly visualization, processing
    and so on).
   

5) OnDownloadStop - occurs when the downloading is finished (successfully or not).

   OnDownloadStop: TDownloadStopNotify;
            
   TDownloadStopNotify = procedure (Sender: TURLDownloader; ErrorCode: cardinal) of object;

   ErrorCode = S_OK if the downloading was successful. Otherwise ErrorCode specifies
   the error. Values usually are taken from INET_E_xxx codes (UrlMon.pas) but
   may be protocol specific.
   

6) OnHTTPResponse - occurs when HTTP response code and headers are recieved.
   
    OnHTTPResponse: THTTPResponseNotify;

    THTTPResponseNotify = procedure (Sender: TURLDownloader; ResponseCode: DWord;
                                     const ResponseHeaders: string) of object;

    Write OnHTTPResponse event handler if your want a special processing of HTTP response.
    Headers in ResponseHeaders are separated by #13#10.



TDownloaderToStream
-------------------

TDownloaderToStream - loads entire URL into specified TStream object 
                      (simple descendant of TURLDownloader)

 Methods

1) Create

   constructor Create(Stream:TStream);

   Creates TDownloaderToStream instance. Parameter Stream specifies TStream object where
   URL will be written to. If Stream parameter is nil then internal TMemoryStream will
   be created. In the process of URL downloading only 'write' operations on the TStream
   object are performed (no seek or read operations).

 Events

1) OnDownloadToStream - occurs at the end of URL downloading.

   OnDownloadToStream: TDownloadToStreamNotify;

   TDownloadToStreamNotify = procedure (Sender: TDownloaderToStream; ErrorCode: cardinal;
                                        Stream: TStream; StartPosition: integer) of object; 

   ErrorCode     - corresponds to ErrorCode of OnDownloadStop event for TURLDownloader.
   Stream        - specifies the TStream object where URL data are written to.
   StartPosition - specifies the value of Position property of Stream before downloading
                   data. Seek Stream to this value, if you want to read downloaded data.

   OnBytesAvailable, OnDataRead and OnDownloadStop events are never fired
   for TDownloaderToStream. Therefore their visibility is set to 'protected'.


TURL_Loader
-----------

TURL_Loader - component to be used on Active Forms. It is a simple component wrapper
              for TURLDownloader and TDownloaderToStream.

 Properties

1) URL:string - specifies the URL where to download data from.
2) DownloadOptions: TDownloadOptions - specifies download options. They are mapped
   to corresponding BindFlags of TURLDownloader.
3) AXControl: TComObject (run-time only) - specifies ActiveX control which is hosted
   by Internet enabled container. If the owner of TURL_Loader component is TActiveForm
   (or its descendant) then this property is set to ActiveFormControl of TActiveForm
   automatically.
   To disable interaction with ActiveX control container simply set this property to nil
   before the downloading start.
4) DownloadInProgress: boolean (run-time, read only) - 
     indicates whether the downloading is in progress.
5) TotalRead: integer (run-time, read only) - corresponds to TotalRead property of
   TURLDownloader.


 Methods

1) StartDownload - starts the URL downloading.

     procedure StartDownload;

   URL, DownloadOptions and AXControl properties must be specified before calling
   of this method.

2) StartDownloadToStream - starts the downloading to stream object specified.

     procedure StartDownloadToStream(Stream:TStream);

   Stream parameter can be nil. In this case the inner TMemoryStream object will
   be created. You will be notified about download completion in OnDownloadToStream
   event.

   OnBytesAvailable, OnDataRead and OnDownloadStop events are not fired for this
   type of downloading.

3) AbortDownload - aborts the current downloading.

     procedure AbortDowload;


 Events

 OnDownloadProgress, OnBytesAvailable, OnDataRead, OnDownloadStop and OnDownloadToStream
 events are similar to corresponding events of TURLDownloader and TDownloaderToStream. 

 OnHTTPRequestData - fired to suply additional data to form HTTP request. See explanations for
                     HTTPRequestData parameter of TURLDownloader.StartDownload method.
