001/*
002 * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.
008 *
009 * This code is distributed in the hope that it will be useful, but WITHOUT
010 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
011 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
012 * version 2 for more details (a copy is included in the LICENSE file that
013 * accompanied this code).
014 *
015 * You should have received a copy of the GNU General Public License version
016 * 2 along with this work; if not, write to the Free Software Foundation,
017 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
018 *
019 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
020 * or visit www.oracle.com if you need additional information or have any
021 * questions.
022 */
023package com.oracle.nfi.api;
024
025/**
026 * Interface to get a {@linkplain NativeFunctionHandle handle} or {@linkplain NativeFunctionPointer
027 * pointer} to a native function or a {@linkplain NativeLibraryHandle handle} to an open native
028 * library.
029 */
030public interface NativeFunctionInterface {
031
032    /**
033     * Resolves and returns a handle to an open native library. This method will open the library
034     * only if it is not already open.
035     *
036     * @param libPath the absolute path to the library
037     * @return the resolved library handle
038     * @throws UnsatisfiedLinkError if the library could not be found or opened
039     */
040    NativeLibraryHandle getLibraryHandle(String libPath);
041
042    /**
043     * Determines if the underlying platform/runtime supports the notion of a default library search
044     * path. For example, on *nix systems, this is typically defined by the {@code LD_LIBRARY_PATH}
045     * environment variable.
046     */
047    boolean isDefaultLibrarySearchSupported();
048
049    /**
050     * Resolves the function pointer {@code NativeFunctionPointer} of a native function.
051     *
052     * @param libraries the ordered list of libraries to search for the function
053     * @param name the name of the function to be resolved
054     * @return a pointer to the native function, or <code>null</code> if the function pointer could
055     *         not be resolved
056     */
057    NativeFunctionPointer getFunctionPointer(NativeLibraryHandle[] libraries, String name);
058
059    /**
060     * Resolves a function name to a {@linkplain NativeFunctionHandle handle} that can be called
061     * with a given signature. The signature contains the types of the arguments that will be passed
062     * to the handle when it is {@linkplain NativeFunctionHandle#call(Object...) called}.
063     *
064     * @param library the handle to a resolved library
065     * @param name the name of the function to be resolved
066     * @param returnType the type of the return value
067     * @param argumentTypes the types of the arguments
068     * @return the function handle of the native function, or <code>null</code> if the function
069     *         handle could not be resolved
070     */
071    NativeFunctionHandle getFunctionHandle(NativeLibraryHandle library, String name, Class<?> returnType, Class<?>... argumentTypes);
072
073    /**
074     * Resolves a function pointer to a {@linkplain NativeFunctionHandle handle} that can be called
075     * with a given signature. The signature contains the types of the arguments that will be passed
076     * to the handle when it is {@linkplain NativeFunctionHandle#call(Object...) called}.
077     *
078     * @param functionPointer a function pointer
079     * @param returnType the type of the return value
080     * @param argumentTypes the types of the arguments
081     * @return the function handle of the native function, or <code>null</code> if the function
082     *         handle could not be resolved
083     */
084    NativeFunctionHandle getFunctionHandle(NativeFunctionPointer functionPointer, Class<?> returnType, Class<?>... argumentTypes);
085
086    /**
087     * Resolves a function name to a {@linkplain NativeFunctionHandle handle} that can be called
088     * with a given signature. The signature contains the types of the arguments that will be passed
089     * to the handle when it is {@linkplain NativeFunctionHandle#call(Object...) called}.
090     *
091     * @param libraries the ordered list of libraries to search for the function
092     * @param name the name of the function to be resolved
093     * @param returnType the type of the return value
094     * @param argumentTypes the types of the arguments
095     * @return the function handle of the native function, or <code>null</code> if the function
096     *         handle could not be resolved
097     */
098    NativeFunctionHandle getFunctionHandle(NativeLibraryHandle[] libraries, String name, Class<?> returnType, Class<?>... argumentTypes);
099
100    /**
101     * Resolves a function name to a {@linkplain NativeFunctionHandle handle} that can be called
102     * with a given signature. The signature contains the types of the arguments that will be passed
103     * to the handle when it is {@linkplain NativeFunctionHandle#call(Object...) called}.
104     *
105     * @param name the name of the function to be resolved
106     * @param returnType the type of the return value
107     * @param argumentTypes the types of the arguments
108     * @return the function handle of the native function, or <code>null</code> if default library
109     *         searching is not {@linkplain #isDefaultLibrarySearchSupported() supported} or if the
110     *         function could not be resolved
111     */
112    NativeFunctionHandle getFunctionHandle(String name, Class<?> returnType, Class<?>... argumentTypes);
113
114    /**
115     * Creates a {@link NativeFunctionPointer} from a raw value.
116     *
117     * @param rawValue raw function pointer
118     * @return {@code NativeFunctionPointer} for {@code rawValue}
119     */
120    NativeFunctionPointer getNativeFunctionPointerFromRawValue(long rawValue);
121}