CFunc.java

Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved.

Sun grants you ("Licensee") a non-exclusive, royalty free, license to use,
modify and redistribute this software in source and binary code form,
provided that i) this copyright notice and license appear on all copies of
the software; and ii) Licensee does not utilize the software in a manner
which is disparaging to Sun.

This software is provided "AS IS," without a warranty of any kind. ALL
EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY
IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN AND ITS LICENSORS SHALL NOT BE
LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING
OR DISTRIBUTING THE SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS
LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT,
INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER
CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF
OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

This software is not designed or intended for use in on-line control of
aircraft, air traffic, aircraft navigation or aircraft communications; or in
the design, construction, operation or maintenance of any nuclear
facility. Licensee represents and warrants that it will not use or
redistribute the Software for such purposes.

/*
 * @(#)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
 * repesents 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 class CFunc extends CPtr {

    /* calling convention, not set now because we only support the "C"
     * convention.
     */
    private int callingConvention;

    /* 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() {}

}