Using Callbacks with the IDLnetURL Object

Callbacks from the IDLnetURL object provide a way to transmit information back to the caller based on the status of a request made to a HTTP or FTP server. The value returned by the callback function is then used by the IDLnetURL object to determine whether to continue or abort the request.

The caller must set the callback function property to receive callbacks from a method. The callback is made to an IDL function, which takes IDL variables as input parameters.

Note
The callback method is intended to provide status and progress information. The callback should not be used to process the incoming or outgoing data. Any data processing must occur after the Get, Put, GetFtpDirList, or FtpCommand methods have returned.

The IDLnetURL object lets you define functions that are called during a Get or Put method call. If a callback function is specified with the CALLBACK_FUNCTION property, it is called in the following circumstances:

For the IDLnetURL::Get method, the callback function is called each time a packet is received from the HTTP or FTP server.

For the IDLnetURL::Put method, the callback function is called each time a packet of data is sent to the HTTP or FTP server.

For the IDLnetURL::GetFtpDirList method, the callback function is called each time a list of files is retrieved.

For the IDLnetURL::FtpCommand method, the callback function is called each time an FTP command is executed.

All methods invoke the callback function with an array of strings indicating status as the first parameter, an array of integers containing progress information as the second parameter, and with the value (if any) specified by the CALLBACK_DATA property as the third parameter. A callback function returns a value of type Int.

Cancelling a Request

The return value of the callback function should be an integer zero or one. If the return value is zero, a cancel message will be sent to the remote node. If the return value is one, the operation will continue.

Callback Routine Signature

A callback function is written in IDL and has the following format:

Function Callback_Function_Name, StatusInfo, ProgressInfo, 
   CallbackData 
... 
return vCancelFlag

where

Callback_Function_Name is the name of the callback function. This value is specified by the CALLBACK_FUNCTION property.

StatusInfo is the first input parameter. It is an array of IDL strings that contains status information about the Get or Put. When the caller is a user interface (UI), the UI typically displays the string array in a text widget.

ProgressInfo is the second input parameter, and is an array of signed 64-bit values (type Long64) that contains progress information:

ProgressInfo[0] – Contains 1 (one) when the ProgressInfo array contains valid data, or 0 (zero) when the array does not contain valid data.

ProgressInfo[1] – The download total used when doing a HTTP Get or FTP Get. This value is 0 when doing a HTTP Get and the transfer encoding is chunked.

ProgressInfo[2] – Contains the number of bytes that have been downloaded during the current HTTP or FTP get.

ProgressInfo[3] – Contains the total number of bytes to be uploaded during a HTTP Put, HTTP Post, or FTP Put.

ProgressInfo[4] – Contains the number of bytes currently uploaded during the HTTP Put, HTTP Post, or FTP Put.

CallbackData is the CALLBACK_DATA property that can be set prior to calling the Get, Put, GetFtpDirList, or FtpCommand method. This property is passed into the callback function unmodified, and the contents of the property are determined by the user. When the caller is a UI, the callback data typically contains the ID of a text widget that displays the status information strings. If the CALLBACK_DATA property is not set, its value is undefined.

The return value is of type Int, and can be used to cancel the Get, Put, GetFtpDirList, or FtpCommand operation. See Cancelling a Request for more information.