tCurl special notes on callbacks, events, filenames and streams.

The tCurl object provides several ways of communicating with
the I/O functions of libcurl, as shown in the following table:

Operation	Filename	Stream	Callback	Event
Receive data	OutputFile	OutputStream	WriteFunction	OnReceive
Transmit data	InputFile	InputStream	ReadFunction	OnTransmit
Receive headers	HeaderFile	HeaderStream	HeaderFunction	OnHeader

• The filename represents a disk file that will be used for input or output.
  
• The stream represents user data that will be passed to the callback.
  
• The callback represents a c-style function that is called by the library when it needs to read or write transferred data.
    ( Callbacks should always be declared using the cdecl directive. )
• The event represents a component-style procedure that is fired when the library needs to read or write transferred data.
    ( Event procedures must be declared as a method of another object. )
• The filename, stream, callback, and event each have an effect on the other, so they might not behave the way you expect!

Please consider the following principles:

If you assign a stream, the filename will be ignored.
If you assign a filename, the stream will be ignored.

If you assign a callback, the event will be ignored.
If you assign an event, the callback will be ignored.

If you don't specify any input or output handlers or filenames, tCurl will expect to use the standard input or output of the current console. This may cause problems with form-based Delphi applications, where a standard console is not available.

If you assign a callback, the filename will be ignored. In this case your callback is responsible for handling or providing the data.

If you assign an event, the filename will be honored, that is, the data will be written to the file AND passed to your event. However, you should NOT attempt to perform I/O operations on the filename from INSIDE your event! The event actually uses its own internal callback to interface with the library, and the object's self parameter is passed to the callback's stream parameter. This allows multiple instances to access the same internal callback without interfering with each other. In this case, the stream property is independent of the callback stream. The stream and other properties can be accessed from within an event through the Sender parameter, for instance:
   tCurl(Sender).HeaderStream;

A stream can be a pointer to any sort of data that you wish to pass to your callback or event. It does not need to be a file stream.
However...
If you assign a stream, and you do NOT use your own callback or event, libcurl will assume that the stream is a C-style file stream.
In this case it MUST be a valid file-pointer created using the ANSI-C fopen() function.

If all this seems confusing, the simple version is this:

• 1. Use a callback or event, not both.
• 2. Use a filename or stream, not both.
• 3. If you assign a stream with something other than fopen(), handle it with your own callback or event.