public class LibraryManager
extends java.lang.Object
Modifier and Type | Field and Description |
---|---|
private static java.util.Map<java.lang.Long,java.util.Map<java.lang.String,java.lang.Long>> |
addrcache
Caches the memory addresses of functions in currently loaded libraries.
|
private static int |
CONVENTION_CDECL
Use the CDECL calling convention (only valid on 32-bit Windows).
|
private static int |
CONVENTION_DEFAULT
Use the default calling convention for the platform.
|
private static int |
CONVENTION_PASCAL
Use the PASCAL calling convention (only valid on 32-bit Windows).
|
private static int |
CONVENTION_STDCALL
Use the STDCALL calling convention (only valid on 32-bit Windows).
|
static int |
ERROR_INVALID_CALL_CONV
Invalid calling convention.
|
static int |
ERROR_INVALID_TYPE
Invalid data type specified.
|
static int |
ERROR_LIBRARY_LOAD
An error occurred when trying to load the library.
|
static int |
ERROR_MISSING_ENTRYPOINT
An error occurred when trying to find the function address.
|
static int |
ERROR_NONE
No error occurred.
|
static int |
ERROR_OUT_OF_MEMORY
Out of memory error occurred.
|
static int |
ERROR_UNKNOWN_FAILURE
Invalid data type specified.
|
private static java.util.Map<java.lang.String,java.lang.Long> |
libcache
Caches the module handles of currently loaded libraries.
|
private static int |
platform
The platform on which the client is running.
|
static int |
PLATFORM_UNIX
Client is running the UNIX/Linux platform.
|
static int |
PLATFORM_WINDOWS
Client is running the Windows platform.
|
private static int |
ptrSize
Size of a native memory pointer in bytes.
|
static int |
TYPE_DOUBLE
The type of the argument or return value is a 64-bit floating point value.
|
static int |
TYPE_FLOAT
The type of the argument or return value is a 32-bit floating point value.
|
static int |
TYPE_POINTER
The type of the argument or return value is a memory address (a pointer).
|
static int |
TYPE_SIGNED_INT16
The type of the argument or return value is a signed 16-bit value.
|
static int |
TYPE_SIGNED_INT32
The type of the argument or return value is a signed 32-bit value.
|
static int |
TYPE_SIGNED_INT64
The type of the argument or return value is a signed 64-bit value.
|
static int |
TYPE_SIGNED_INT8
The type of the argument or return value is a signed 8-bit value.
|
static int |
TYPE_UNSIGNED_INT16
The type of the argument or return value is an unsigned 16-bit value.
|
static int |
TYPE_UNSIGNED_INT32
The type of the argument or return value is an unsigned 32-bit value.
|
static int |
TYPE_UNSIGNED_INT8
The type of the argument or return value is an unsigned 8-bit value.
|
static int |
TYPE_VOID
The type of the argument or return value is void.
|
Modifier | Constructor and Description |
---|---|
private |
LibraryManager()
Private constructor so instances are not created.
|
Modifier and Type | Method and Description |
---|---|
private static int |
calcCallingConv(CallingConvention conv)
Convert the calling convention enum into an integer constant version that can be
passed to the native layer.
|
private static int |
dispatch(long funcAddr,
int callConv,
int retType,
long retAddr,
int numArgs,
int[] argTypes,
long argAddr)
Call the function with the specified arguments and return value processing.
|
private static long |
findByName(long modhandle,
java.lang.String funcname)
Uses the operating-system runtime library lookup facility to obtain the address of the
given symbol in the library.
|
private static long |
findByOrdinal(long modhandle,
int ordinal)
Uses the operating-system runtime library lookup facility to obtain the address of the
given ordinal in the library.
|
private static java.lang.String |
generateAddressCacheKey(java.lang.String funcname,
int ordinal)
Calculate the key that will be used to access the given function in the address
cache.
|
static void |
init()
Load the native library containing functions for library management.
|
(package private) static Signature |
invoke(java.lang.String libname,
java.lang.String funcname,
int ordinal,
boolean persistent,
CallingConvention conv,
Signature signature)
Invoke the defined native API call, loading (and optionally unloading) the library as
needed.
|
private static long |
load(java.lang.String libname,
boolean persist)
Attempts to load the named library.
|
private static long |
obtainFunctionAddress(long module,
boolean stdcall,
java.lang.String funcname,
int ordinal,
int argsize,
boolean persistent)
Obtain the function address for the given function name or ordinal.
|
private static long |
obtainLibrary(java.lang.String libname,
boolean persistent)
Obtain the library handle for the given library name, loading the library if needed.
|
private static int |
platform()
Reports the platform type on which the client is running.
|
(package private) static int |
ptrSize()
Reports on the number of bytes needed to store a native memory pointer.
|
(package private) static void |
release(java.lang.String libname)
Attempts to unload the library identified by the given name.
|
private static void |
unload(long modhandle)
Attempts to unload the library identified by the "handle" which was returned from a
previous call to
load(java.lang.String, boolean) . |
private static int |
wordSize()
Reports on the number of bytes that the native stack uses for push/pop operations (the
width or size of the word used).
|
public static final int TYPE_SIGNED_INT8
public static final int TYPE_UNSIGNED_INT8
public static final int TYPE_SIGNED_INT16
public static final int TYPE_UNSIGNED_INT16
public static final int TYPE_SIGNED_INT32
public static final int TYPE_UNSIGNED_INT32
public static final int TYPE_SIGNED_INT64
public static final int TYPE_FLOAT
public static final int TYPE_DOUBLE
public static final int TYPE_POINTER
public static final int TYPE_VOID
public static final int PLATFORM_UNIX
public static final int PLATFORM_WINDOWS
public static final int ERROR_NONE
public static final int ERROR_INVALID_CALL_CONV
public static final int ERROR_INVALID_TYPE
public static final int ERROR_UNKNOWN_FAILURE
public static final int ERROR_OUT_OF_MEMORY
public static final int ERROR_LIBRARY_LOAD
public static final int ERROR_MISSING_ENTRYPOINT
private static final int CONVENTION_DEFAULT
private static final int CONVENTION_STDCALL
private static final int CONVENTION_CDECL
private static final int CONVENTION_PASCAL
private static final java.util.Map<java.lang.String,java.lang.Long> libcache
private static final java.util.Map<java.lang.Long,java.util.Map<java.lang.String,java.lang.Long>> addrcache
private static int ptrSize
private static int platform
private LibraryManager()
public static void init()
static Signature invoke(java.lang.String libname, java.lang.String funcname, int ordinal, boolean persistent, CallingConvention conv, Signature signature)
All exceptions will be raised on the server-side (not here). Instead of throwing an exception, this code will set an error code and return.
libname
- The library name where this native procedure should be found.funcname
- The function name being called in the library (except where an ordinal is being
used).ordinal
- The entry point's ordinal or -1 if the entry point should be found by name.persistent
- true
to leave the library loaded when the native call is complete.conv
- The calling convention to be used in this native call.signature
- Contains the return value and argument descriptors. In the case of the arguments
there will be 1 descriptor for each argument to the call (where the 0 index is
the leftmost argument and the numargs - 1 index is the rightmost). Each
descriptor defines the type and will contain any input value in the case of an
argument. If the return value descriptor is null
, the call should
be treated as a void return.static void release(java.lang.String libname)
null
) can be provided and the lack
of a corresponding cached library will be silently ignored. The call to the OS will only
occur when there is a cached module handle.libname
- The name of the library to attempt to unload.static int ptrSize()
private static int wordSize()
private static int platform()
private static long load(java.lang.String libname, boolean persist)
libname
- This may be any valid library filename for the current system, including names
that contain path separators (both relative and absolute). This should not be
null
or the empty string.persist
- true
if the library is being loaded persistently. This allows the
native code a chance to differentially process if that platform requires it.NULL
(0) is returned, then the call failed.private static void unload(long modhandle)
load(java.lang.String, boolean)
. This will use the operating-system runtime library
unloading mechanism. Although this call may fail, Progress seems to always silently ignore
any failures, so this method has no return value.modhandle
- This must be a valid handle to the library.private static long findByName(long modhandle, java.lang.String funcname)
modhandle
- This must be a valid handle to a library that is already loaded.funcname
- This is the exact symbol to lookup in the library.NULL
(0) if the function
cannot be found by that name in the given library.private static long findByOrdinal(long modhandle, int ordinal)
modhandle
- This must be a valid handle to a library that is already loaded.ordinal
- The ordinal to lookup in the library.NULL
(0) if the function cannot
be found by that ordinal in the given library. Operating systems that do not
support ordinal exports will always return 0.private static int dispatch(long funcAddr, int callConv, int retType, long retAddr, int numArgs, int[] argTypes, long argAddr)
funcAddr
- The memory address of the function to call. Must not be NULL
.callConv
- A constant representing the calling convention to be used. This is only honored on
32-bit Windows, where there are multiple calling conventions to choose from.retType
- Specifies the data type of the return value. Ignored if the retAddr
is
NULL
.retAddr
- The memory address in which to place the return value. The call is assumed to have
no return value (or a return value that can be ignored) if this pointer is
NULL
.numArgs
- The number of arguments in the called function's signature. Must be non-negative
(0 is valid).argTypes
- If numArgs
is greater than 0, this is an array that specifies the data
type of each argment from left to right (the 0 index of the array corresponds to the
leftmost argument).argAddr
- If numArgs
is greater than 0, this must be the memory address of the
array of void*
. Each one points to an argment value from left to right
(the 0 index of the array corresponds to the leftmost argument).private static long obtainLibrary(java.lang.String libname, boolean persistent)
libname
- The library name to be loaded. In general, no modifications to this string will
be done (the exception is in the native layer for Windows loading, where forward
slashes are converted to backslashes).persistent
- If true
, the library should not be unloaded at the end of the
function invocation, which means that this method should cache the module
handle if it is successfully loaded.NULL
(0) is returned, then the loading failed.private static long obtainFunctionAddress(long module, boolean stdcall, java.lang.String funcname, int ordinal, int argsize, boolean persistent)
module
- An operating-system specific "handle" to the library. Under Windows this is
the "module handle" of type HMODULE and under Linux it is just referred to as
a "handle" that is returned as a void pointer.stdcall
- true
if the STDCALL calling convention is being used for this
function.funcname
- The function name to be loaded. In general, no modifications to this string will
be done (the exception is in the native layer for Windows loading, where STDCALL
names are checked with an underscore prefix and an at-sign + decimal argument
length IF the non-decorated version fails).ordinal
- The ordinal that the API is exported as (on Windows this is used in preference
to the name) or -1 if no ordinal was specified.argsize
- The number of bytes used to pass the arguments. This is only used on Windows for
decorating STDCALL name lookups.persistent
- If true
, the library will not be unloaded at the end of the
function invocation, which means that this method should cache the function
address if it is successfully found.NULL
(0) is returned, then the lookup failed.private static java.lang.String generateAddressCacheKey(java.lang.String funcname, int ordinal)
funcname
- The function name.ordinal
- The ordinal that the API is exported as (on Windows this is used in preference
to the name) or -1 if no ordinal was specified.private static int calcCallingConv(CallingConvention conv)
conv
- The calling convention enum.