package com.jstatcom.engine;

/*
 * @(#)CFunc.java	1.6 98/03/22
 *
 * Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved.
 *
 * See also the LICENSE file in this distribution.
 */

/**
 * An abstraction for a C function pointer.  An instance of CFunc
 * represents a pointer to some C function.  callXXX methods
 * provide means to call the function; select a xxx variant based
 * on the return type of the C function.
 *

 * Beware that the copyIn, copyOut,
 * setXXX, and getXXX methods inherited from the
 * parent will indirect machine code.
 *
 * @author Sheng Liang
 * @see CPtr
 */
public final class CFunc extends CPtr {


	/* Find names function in the named dll. */
	private native long find(String lib, String fname);

	/**
	 * Create a new CFunc that is linked with a C function that
	 * follows a given calling convention.
	 * 

	 * The allocated instance represents a pointer to the named C function
	 * from the named library, called with the named calling convention.
	 * 

	 * @param lib   library in which to find the C function
	 * @param fname name of the C function to be linked with
	 * @param conv  calling convention used by the C function
	 */
	public CFunc(String lib, String fname, String conv) {
		if (!conv.equals("C")) {
			throw new IllegalArgumentException(
				"unrecognized calling convention: " + conv);
		}
		peer = find(lib, fname);
	}

	/**
	 * Create a new CFunc that is linked with a C function that
	 * follows the standard "C" calling convention.
	 * 

	 * The allocated instance represents a pointer to the named C function
	 * from the named library, called with the standard "C" calling
	 * convention.
	 * 

	 * @param lib   library in which to find the C function
	 * @param fname name of the C function to be linked with
	 */
	public CFunc(String lib, String fname) {
		peer = find(lib, fname);
	}

	/**
	 * Call the C function being represented by this object.
	 *
	 * @param  args arguments to pass to the C function
	 * @return      int value returned by the underlying
	 *		    C function
	 */
	public native int callInt(Object[] args);

	/**
	 * Call the C function being represented by this object.
	 *
	 * @param  args arguments to pass to the C function
	 */
	public native void callVoid(Object[] args);

	/**
	 * Call the C function being represented by this object.
	 *
	 * @param  args arguments to pass to the C function
	 * @return      float value returned by the underlying
	 *		    C function
	 */
	public native float callFloat(Object[] args);

	/**
	 * Call the C function being represented by this object.
	 *
	 * @param  args arguments to pass to the C function
	 * @return      double value returned by the underlying
	 *		    C function
	 */
	public native double callDouble(Object[] args);

	/**
	 * Call the C function being represented by this object.
	 *
	 * @param  args arguments to pass to the C function
	 * @return      C pointer returned by the underlying C function
	 */
	public native CPtr callCPtr(Object[] args);

	/* Don't allow creation of unitializaed CFunc objects. */
	private CFunc() {
	}

}