Using Callbacks with the IDLffDicomExQuery Object

Callbacks from the IDLffDicomExQuery object provide a way to transmit information back to the caller based on the status of a query or retrieve operation. The value returned by the callback function is then used by the IDLffDicomExQuery object to determine whether the query or retrieve operation should continue.

The IDLffDicomExQuery object allows you to define a single function (written in IDL) that will be called based on the intermediate status of a Query or Retrieve method call. If a callback function is specified via the CALLBACK_FUNCTION property, it is called in the following circumstances:

For the IDLffDicomExQuery::Query method, the callback function is called each time a match is returned by the source node.

For the IDLffDicomExQuery::Retrieve method:

If the source node (the remote Query/Retrieve SCP) implements the optional response mechanism, the callback function is called each time a DICOM file is moved from the source node to the destination node.

If the source node (the remote Query/Retrieve SCP) does not implement the optional response mechanism, the callback function is called every 3 seconds.

Both methods invoke the callback function with an array of strings indicating status as the first parameter, and with the value (if any) specified by the CALLBACK_DATA property as the second parameter.

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

Callback Routine Signature

A query/retrieve callback function is written in IDL and has the following 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 query or retrieve 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 query or retrieve and the type of node being queried or retrieved from.

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 IDLffDicomExQuery object to the callback routine.

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 query or retrieve operation will continue.