KcsCallbackFunction

typedef KCS_CALLBK (KcsStatusId) (KCS_PTR KcsCallbackFunction)
 (KcsProfileId                    profile,
      unsigned long               current,
      unsigned long               final,
      KcsFunction                 callingFunc,
      void      KCS_PTR           userDefinedData);

KcsCallbackFunction is the data type of one argument to KcsSetCallback(). It is a pointer to a function returning KcsStatusId.

The profile field is currently undefined.

A KcsCallbackFunction variable holds a pointer to a callback that your application supplies. The C API does not supply it. The callback tells your application how far certain lengthy operations (such as KcsEvaluate() and KcsOptimizeProfile()) have progressed. If these operations are too slow, your application can provide a way to terminate them. It can use K()csSetCallback() for each function for which a callback is needed.

Example 3-2 demonstrates a callback to the potentially time-consuming KcsOptimizeProfile() function. In the example, KcsSetCallback() sets myCallbackFunc, a variable of type KcsCallbackFunction, as the callback that KcsOptimizeProfile() calls. While executing, KcsOptimizeProfile() periodically calls myCallbackFunc, passing it the following arguments:

• profile--a reference to the profile.

• current--an integer value that tells your application how many times (minus one) KcsOptimizeProfile() has called myCallbackFunc(). The first time myCallbackFunc is called, KcsOptimizeProfile() sets the value of current to 0; the second time it sets current to 1, and so on.

• final--a positive integer that indicates the number of times (plus one) myCallbackFunc will ultimately be called (assuming your application does not cancel the operation before completion). Your application can set this argument if it knows how many times it wants myCallbackFunc to be called. It should use final to get a percent complete number or an indication of an endless loop. When current = final, the optimization is terminated.

• callingFunc--the identity of the function currently executing.

• userDefinedData--a pointer that can be any user-definable item.

Example 3-2 KcsCallbackFunction()

main()
 {
      KcsCallbackFunction myCallbackFunc;
      ...
      status=KcsSetCallback(KcsOptimizeFunc, myCallbackFunc,
                userDefinedData);
      status=KcsOptimizeProfile(profile, optimizationType, loadHint);
      ...
 }

 /* KcsOptimizeProfile will call myCallbackFunc periodically. This is a
  * simple progress monitoring function; your own progress monitoring
  * function will probably be far more sophisticated. */
 KcsStatusId myCallbackFunc (KcsProfileId profile,
           unsigned long current, unsigned long final,
           KcsCallbackFunction CallingFunc, void* userDefinedData);
 {
      printf("The call is %d percent complete.\n", (current*100)/final);
      return(KCS_SUCCESS);
 } 

If the application returns KCS_SUCCESS from the callback function, the API allows the operation in progress to continue. If the callback function returns any other KcsStatusId value, the operation terminates, returning the status value returned from the callback function as its own status. The API provides a status value, KCS_OPERATION_CANCELLED, that the callback function can use to indicate that the operation was terminated by the user.