Using Callbacks with the IDLnetOGCWCS Object

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

The IDLnetOGCWCS object lets you define a single function (written in IDL) that will be called during a GetCapabilities, DescribeCoverage, or GetCoverage method call. If a callback function is specified via the CALLBACK_FUNCTION property, it is called in the following circumstances:

For the IDLnetOGCWCS::GetCapabilities method, the callback function is called each time a packet is received from the OGC WCS server. If the FROM_FILE keyword is set, the callback function is called before and after the XML file is parsed.

For the IDLnetOGCWCS::DescribeCoverage method, the callback function is called each time a packet is received from the OGC WCS server. If the FROM_FILE keyword is set, the callback function is called before and after the XML file is parsed.

For the IDLnetOGCWCS::GetCoverage method, the callback function is called each time a packet of data is received from the OGC WCS server.

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

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

StatusInfo is an array of strings that contain status information about the operation. The status strings are provided for information and human inspection rather than for programmatic processing; the exact strings included in the array will depend on numerous factors including the status of the operation and the type of OGC WCS server.

ProgressInfo is an array of five 64-bit long integers that contain progress information for the transfer:

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] – Contains the total number of bytes to be downloaded. This array element will contain 0 (zero) when the transfer encoding is "chunked."

ProgressInfo[2] – Contains the number of bytes that have been downloaded during the current transfer.

ProgressInfo[3] – Contains the total number of bytes to be uploaded.

ProgressInfo[4] – Contains the number of bytes that have been uploaded during the current transfer.

CallbackData is the data specified via the CALLBACK_DATA property. The value of this property is passed to the callback function unmodified. If the CALLBACK_DATA property is unspecified, an integer zero is passed to the callback function as the value of this parameter.

The CallbackData parameter is useful for passing static information, such as the widget ID of a widget where the status information is displayed, from the IDLnetOGCWCS object to the callback routine.

For a simple example of using a callback to return additional status information, see IDLnetOGCWCS::GetCapabilities. The StatusInfo details are printed to the Output window.