.\" pragma ident "@(#)KcsSetCallback.3	1.3  04/21/95"
.TH KcsSetCallback 3 "21 April 1995" "" "KCMS Library"
.SH NAME
KcsSetCallback \- Associate a callback with a KCMS function
.SH SYNOPSIS
.ft B
.nf
#include <kcms/kcs.h>
#include <kcms/kcstypes.h>
.sp
KcsStatusId KcsSetCallback (
		KcsFunction		function, 
		KcsCallbackFunction	callback, 
		void			*userDefinedData)
.fi
.ft R
.SH MT-LEVEL
MT-Unsafe
.SH DESCRIPTION
Use 
.B KcsSetCallback()
to associate a callback function with 
any set of API functions that support callbacks. 
If 
.B KcsSetCallback()
is not called for particular values of KcsFunction, no callback 
is issued.
.PP
This function allocates resources. To deallocate those resources, 
set all callback functions to NULL:
.br
.in +3
.nf
KcsSetCallback(KcsAllFunc, NULL, NULL);
.fi
.in -3
.SH ARGUMENTS
.TP
.SP function
A set of API functions. 
.TP
.SP callback
The application-supplied function to be called when the variable 
function needs to report progress.
.TP
.SP userDefinedData
Any user-defined data.
.SH RETURN VALUES
Upon successful completion KCS_SUCCESS is returned. Otherwise
one of the following errors will be returned.
.SH SEE ALSO
.BR KcsOptimizeProfile (3)
.BR KcsEvaluate (3)
.br
.BR "KCMS Application Developers Guide"
.SH ERRORS
KCS_MEM_ALLOC_ERROR
.SH EXAMPLE
.nf
/* template function declaration */
int 		myProgressCallback(KcsProfileId profileid, unsigned long
			current, unsigned long total, KcsFunction
			operation, void *userDefinedData);
KcsProfileId	completeProfile;
KcsPixelLayout 	pixelLayoutIn;

/* the profiles have been loaded and connected, now set up the
 * callback to be active for both the optimize and evaluate
 * functions */

status = KcsSetCallback(KcsOptFunc + KcsEvalFunc,
			(KcsCallbackFunction)myProgressCallback, NULL );
if (status != KCS_SUCCESS) {
	fprintf(stderr, "Callback function call failed\\n");
	exit (1);
}

status = KcsOptimizeProfile(completeProfile, KcsOptSpeed, KcsLoadAllNow);
/* check status here*/

/* set up the pixel layout */
status = KcsEvaluate(completeProfile, op, &pixelLayoutIn, &pixelLayoutIn);
/* check status here*/

/* This is my callback function */
int 
myProgressCallback(KcsProfileId profileid, 
	unsigned long current, unsigned long total, 
	KcsFunction operation, void *userDefinedData)
{
	int	pcent;

	pcent = (int) (((float)current/ (float)total) *100.0);
	fprintf(stderr,"Optimize+Evaluate is %3d percent complete\\n", pcent); 
	fflush(stderr);
	return(KCS_SUCCESS);
}
.fi