IEDownload

Events



The must important events are called in the following order:

OnBeginningTransaction
OnAuthenticate (if authentication is needed)
OnResponse
repeating until complete:
     
  OnProgress
      OnData
OnComplete

 

OnBeginningTransaction:

You can use this event to add additional headers to the HTTP request. It is most likely when you use method POST or PUT.

If you assign a string to IEDownload.AdditionalHeader it will be added automatically, and you don't need to use this event.

The following sample shows how to use additionalheader and Postdata i a POST call:

procedure TForm1.Button1Click(Sender: TObject);
begin
  with IEDownload1 do begin
 
Method := POST;
  AdditionalHeader := 'Content-Type:application/x-www-form-urlencoded\r\n';
  PostData := 'Firstname=Per&Lastname=Larsen';
  Go('http://localhost/posttest.asp');
  end;
end;

For more info: IHttpNegotiate--BeginningTransaction Method


OnResponse:

Allows you to examine the response headers, optionally terminate the bind operation, and add HTTP headers to a request before resending the request.

By default download is canceled if responsecode is between 400-499 (e.g. 404 : Not Found). You can trap this in OnComplete (see later).

Sender.QueryInfo is useful to get more information about the resource you are about to download and the server you are communicating with. See demo "IEDownloadDemo".

Return E_ABORT (or IEDownload1.cancel(sender)) to cancel the download or S_OK to continue.

The demo "LinkCheck" is a link-validator. It grabs the responsecode in OnResponse and always return E_ABORT, since only the headers are needed to determine if the page is available.

For more info: IHttpNegotiate--OnResponse Method

OnAuthenticate:

This event is called before OnResponse if Password/username or other authentication is needed to access the URL. You can provide Username/Password here and continue the process. If you don't provide authentication  OnResponse will return Responsecode 401 (Unauthorized).

You can use either:

IEDownload1.Username:='iedelphi';
IEDownload1.PassWord:='seamonkey';

before you call IEDownload1.Go('TheURL')

or in OnAutheticate add:

function TForm1.IEDownload1Authenticate(Sender: TBSCB; var hwnd: HWND;
var szUserName, szPassWord: PWideChar): HRESULT;
begin
  if Sender.Url = 'TheUrl' then
  begin
    szUsername := 'iedelphi';
    szPassword := 'seamonkey';
  end;
Result := S_OK;
end;

For more info: 
IAuthenticate--Authenticate Method
 
Q156905 - SAMPLE- Progress Uses IAuthenticate to Bind to Secured Web Page


OnProgress:

Keeps you informed about the download progress. The following values are available:

Sender (The binding the information is valid for)

ulProgress (Bytes downloaded so far)

ulProgressMax (total filesize)

ulStatusCode (Bindstatus). You can use the function BindstatusText(ulStatusCode) to get textinformation about the bindstatus.

szStatusText (additional information).

The following list shows the possible values of ulStatuscode and information in szStatustext:

BINDSTATUS_FINDINGRESOURCE
Notifies the client application that the bind operation is finding the resource that holds the object or storage being bound to. The szStatusText parameter provides the display name of the resource being searched for (for example, "www.microsoft.com").
BINDSTATUS_CONNECTING
Notifies the client application that the bind operation is connecting to the resource that holds the object or storage being bound to. The szStatusText parameter provides the display name of the resource being connected to (for example, an IP address).
BINDSTATUS_REDIRECTING
Notifies the client application that the bind operation has been redirected to a different data location. The szStatusText parameter provides the display name of the new data location.
BINDSTATUS_BEGINDOWNLOADDATA
Notifies the client application that the bind operation has begun receiving the object or storage being bound to. The szStatusText parameter provides the display name of the data location.
BINDSTATUS_DOWNLOADINGDATA
Notifies the client application that the bind operation continues to receive the object or storage being bound to. The szStatusText parameter provides the display name of the data location.
BINDSTATUS_ENDDOWNLOADDATA
Notifies the client application that the bind operation has finished receiving the object or storage being bound to. The szStatusText parameter provides the display name of the data location.
BINDSTATUS_BEGINDOWNLOADCOMPONENTS
Notifies the client application that the bind operation is beginning to download the component.
BINDSTATUS_INSTALLINGCOMPONENTS
Notifies the client application that the bind operation is installing the component.
BINDSTATUS_ENDDOWNLOADCOMPONENTS
Notifies the client application that the bind operation has finished downloading the component.
BINDSTATUS_USINGCACHEDCOPY
Notifies the client application that the bind operation is retrieving the requested object or storage from a cached copy. The szStatusText parameter is nil.
BINDSTATUS_SENDINGREQUEST
Notifies the client application that the bind operation is requesting the object or storage being bound to. The szStatusText parameter provides the display name of the object (for example, a file name).
BINDSTATUS_CLASSIDAVAILABLE
Notifies the client application that the CLSID of the resource is available.
BINDSTATUS_MIMETYPEAVAILABLE
Notifies the client application that the MIME type of the resource is available.
BINDSTATUS_CACHEFILENAMEAVAILABLE
Notifies the client application that the temporary or cache file name of the resource is available. The temporary file name might be returned if NOWRITECACHE is set in Options. The temporary file will be deleted once the storage is released.
BINDSTATUS_BEGINSYNCOPERATION
Notifies the client application that a synchronous operation has started.
BINDSTATUS_ENDSYNCOPERATION
Notifies the client application that the synchronous operation has completed.
BINDSTATUS_BEGINUPLOADDATA
Notifies the client application that the file upload has started.
BINDSTATUS_UPLOADINGDATA
Notifies the client application that the file upload is in progress.
BINDSTATUS_ENDUPLOADINGDATA
Notifies the client application that the file upload has completed.
BINDSTATUS_PROTOCOLCLASSID
Notifies the client application that the CLSID of the protocol handler being used is available.
BINDSTATUS_ENCODING
Notifies the client application that the Urlmon.dll is encoding data.
BINDSTATUS_VERFIEDMIMETYPEAVAILABLE
Notifies the client application that the verified MIME type is available.
BINDSTATUS_CLASSINSTALLLOCATION
Notifies the client application that the class install location is available.
BINDSTATUS_DECODING
Notifies the client application that the bind operation is decoding data.
BINDSTATUS_LOADINGMIMEHANDLER
Notifies the client application that a pluggable MIME handler is being loaded. This value was added for Microsoft® Internet Explorer 5.
BINDSTATUS_CONTENTDISPOSITIONATTACH
Notifies the client application that this resource contained a Content-Disposition header that indicates that this resource is an attachment. The content of this resource should not be automatically displayed. Client applications should request permission from the user. This value was added for Internet Explorer 5.
BINDSTATUS_FILTERREPORTMIMETYPE
Notifies the client application of the new MIME type of the resource. This is used by a pluggable MIME filter to report a change in the MIME type after it has processed the resource. This value was added for Internet Explorer 5.
BINDSTATUS_CLSIDCANINSTANTIATE
Notifies the Urlmon.dll that this CLSID is for the class the Urlmon.dll should return to the client on a call to IMoniker.BindToObject. This value was added for Internet Explorer 5.
BINDSTATUS_IUNKNOWNAVAILABLE
Reports that the IUnknown interface has been released. This value was added for Internet Explorer 5.
BINDSTATUS_DIRECTBIND
Reports whether or not the client application is connected directly to the pluggable protocol handler. This value was added for Internet Explorer 5.
BINDSTATUS_RAWMIMETYPE
Reports the MIME type of the resource, before any code sniffing is done. This value was added for Internet Explorer 5.
BINDSTATUS_PROXYDETECTING
Reports that a proxy server has been detected. This value was added for Internet Explorer 5.
BINDSTATUS_ACCEPTRANGES
Reports the valid types of range requests for a resource. This value was added for Internet Explorer 5.

ElapsedTime, Speed and EstimatedTime shows the time since download began, transfer speed (kb/sec) and estimated time remaining.



The following code shows how to get user-friedly information from the OnProgress event:

procedure TForm1.IEDownload1Progress(Sender: TBSCB; ulProgress,
ulProgressMax, ulStatusCode: Cardinal; szStatusText: PWideChar;
ElapsedTime, Speed, EstimatedTime: string);
begin
Label1.Caption := 'Elapsed time: ' + ElapsedTime;
Label2.Caption := 'Speed: ' + Speed;
Label3.Caption := 'Estimated time: ' + EstimatedTime;
if ulStatusCode = BINDSTATUS_DOWNLOADINGDATA then
Memo1.lines.add(BindStatusText(ulStatusCode) +
'(' + InttoStr(ulProgress) + '/' + InttoStr(ulprogressmax) + ')')
else
Memo1.lines.add(BindStatusText(ulStatusCode));
end;

The progress in memo1 looks like this:

Finding resource...
Connecting...
Sending request...
MIME type available...
Beginning to download data...
Downloading data... (7015/14934)
Downloading data... (11395/14934)
Downloading data... (14934/14934)
Ending data download...

and Labels:

Elapsed time: 00:03:42
Speed: 7.28 kb/sec
Estimated time: 00:12:36


For more info: IBindStatusCallback--OnProgress Method


OnData:

Use this function, if you need the data as they come in. You receive a pointer to a buffer and the bufferlength.

You can parse/edit the data 'on the fly', but you are responsible for returning the proper bufferlength, if it has changed.

 

OnComplete:

Download operation is completed for the URL in Sender.Url. use the result parameter to determine the result of the operation. 

If result=S_OK (0) you can get the data from Stream

If you have cancelled the process, the result value is E_ABORT. 

If result is E_ABORT you might want to check the value of property Sender.ResponseCode, since the reason for termination could be that the requested url was not found (Responsecode 404)  and not cancelled by user.

To get a text representation of other results, you can use ErrorText(result).

The following code shows all data in a memobox after a successful download has been completed:

procedure TForm1.IEDownload1Complete(Sender: TBSCB; Stream: TStream;Result: HRESULT);
begin
  if
result=0 then memo2.lines.loadfromstream(stream);
end;

 


Created and maintained by
Per Lindsø Larsen

Last Update: October 1, 2000