KCMS Application Developer's Guide


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.

Note -

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:

Example 3-2 KcsCallbackFunction()

 	KcsCallbackFunction myCallbackFunc;
 	status=KcsSetCallback(KcsOptimizeFunc, myCallbackFunc,
 	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);

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.