com.upek.android.ptapi
Class PtGlobal

java.lang.Object
  extended by com.upek.android.ptapi.PtGlobal
All Implemented Interfaces:
PtGlobalI

public class PtGlobal
extends java.lang.Object
implements PtGlobalI

Main class with basic static Ptapi library methods.


Field Summary
static int apiVersion
          Version of API in form A.B.C = 0xAAAABBCC.
static int dllVersion
          Version of DLL.
 
Constructor Summary
PtGlobal()
          Use and load the default native library name before first use of the class.
 
Method Summary
 PtDeviceListItem[] enumerateDevices(java.lang.String enumDsn)
          Enumerate TFM/ESS devices
 PtGlobalInfo globalInfo()
          Get information about the API version and other global information, independent on any connection.
 void initialize()
          Initialize the API library.
 void initializeEx(int flags)
          Initialize the PTAPI library with possibility to set some additional flags.
static void libraryIsAlreadyLoaded()
          Signals to class, that the native library has been loaded by different way and shouldn't be loaded during first construct.
static void loadLibrary()
          Load native library with default name.
 PtConnectionI open(java.lang.String dsn)
          Open new "local" connection to TFM.
 PtConnectionI openDevice(java.lang.String dsn)
          Opens and prepares connection interface with TFM/ESS.
 PtConnectionI openRemote(PtCommCallback commCallback)
          Open a new connection to a remote instance of PTAPI library, set the address of a communication callback for this connection and return a connection handle.
static void removeWatchConnection(int handle)
          Removes all connections with specified handle from watchedQueu.
 void terminate()
          Uninitialize the API library.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

apiVersion

public static final int apiVersion
Version of API in form A.B.C = 0xAAAABBCC. Increase of minor version number means a change of interface, so old DLL library can be used with newer JAR. This contains: adding and removing functions into interface, adding members in structures or adding whole structures. If a newer JAR is used with old DLL, new structures and data members will be ignored and calling of new functions will throw UnsatisfiedLinkError, but the rest of functionality will work fine. If a newer DLL is used with old JAR, everything will work as DLL was the same version as JAR.

Increase of major version number means big change in API, which is not compatible with rules of minor version changes. These are: deleting of data Structure members and deleting whole structures and interfaces. After this change old DLL library can not be compatible with the newer JAR and while first use of PtGlobal (whose static constructor loads DLL) it will raise Error("Incompatible JniPtapi native library."). If a newer DLL is used with old JAR, everything will work correctly, as a DLL should be the same version.

Increase of subversion number means change only inside library without change of outer interface.

Before use of any method, the native library must be loaded by the same classloader which has loaded this class. By default, it will be done automatically during first construct of this class. It is possible to use methods loadLibray(), loadLibrary(libName), load(libFile). These methods are wrapping System.load() and System.loadLibrary calls(), the default one use the default library name (System.loadLibrary("jniidt");) Or it is possible load the native library by different way and signal this fact to class by libraryIsAlreadyLoaded(), constructor will not do the loading then.

See Also:
Constant Field Values

dllVersion

public static int dllVersion
Version of DLL. After first use of PtGlobal is loaded DLL library and at this moment DLL library set up this member to value of DLL version.

Constructor Detail

PtGlobal

public PtGlobal()
Use and load the default native library name before first use of the class.

Method Detail

enumerateDevices

public PtDeviceListItem[] enumerateDevices(java.lang.String enumDsn)
                                    throws PtException
Description copied from interface: PtGlobalI
Enumerate TFM/ESS devices

Specified by:
enumerateDevices in interface PtGlobalI
Parameters:
enumDsn - ASCII string describing the TFM/ESS connection interface, where enumeration is required, e.g. USB. Example: "usb".
Returns:
The list of found TFM/ESS devices. (Corresponds with parameter ppDeviceList in original function)
Throws:
PtException - Error code of fail, if any was accoured.

globalInfo

public PtGlobalInfo globalInfo()
                        throws PtException
Description copied from interface: PtGlobalI
Get information about the API version and other global information, independent on any connection.

Specified by:
globalInfo in interface PtGlobalI
Returns:
Global info class. (Corresponds with parameter ppGlobalInfo in original function)
Throws:
PtException - Error code of fail, if any was accoured.

initialize

public void initialize()
                throws PtException
Description copied from interface: PtGlobalI
Initialize the API library. Must be called before any other function.

Specified by:
initialize in interface PtGlobalI
Throws:
PtException - Error code of fail, if any was accoured.

initializeEx

public void initializeEx(int flags)
                  throws PtException
Description copied from interface: PtGlobalI
Initialize the PTAPI library with possibility to set some additional flags.

Specified by:
initializeEx in interface PtGlobalI
Throws:
PtException - Error code of fail, if any was accoured.

libraryIsAlreadyLoaded

public static void libraryIsAlreadyLoaded()
Signals to class, that the native library has been loaded by different way and shouldn't be loaded during first construct.


loadLibrary

public static void loadLibrary()
Load native library with default name.


open

public PtConnectionI open(java.lang.String dsn)
                   throws PtException
Description copied from interface: PtGlobalI
Open new "local" connection to TFM.

Specified by:
open in interface PtGlobalI
Parameters:
dsn - ASCII string descriobing the TFM connection parameters, e.g. port number etc. Example: "Port=COM1".
Returns:
Resulting connection class. At the end of the connection it should be closed using close(). To close local connection you should call close(). (Corresponds with parameter phConnection in original function)
Throws:
PtException - Error code of fail, if any was accoured.

openDevice

public PtConnectionI openDevice(java.lang.String dsn)
                         throws PtException
Description copied from interface: PtGlobalI
Opens and prepares connection interface with TFM/ESS. In order to open communication session function openSession() must be called afterwards. Call closeDevice() to close opened interface.

Specified by:
openDevice in interface PtGlobalI
Parameters:
dsn - ASCII string descriobing the TFM/ESS connection interface parameters, e.g. port number etc. Example: "Port=COM1".
Returns:
Resulting connection class. (Corresponds with parameter phConnection in original function)
Throws:
PtException - Error code of fail, if any was accoured.

openRemote

public PtConnectionI openRemote(PtCommCallback commCallback)
                         throws PtException
Description copied from interface: PtGlobalI
Open a new connection to a remote instance of PTAPI library, set the address of a communication callback for this connection and return a connection handle. The callback function is described at the description of PtCommCallback.

Specified by:
openRemote in interface PtGlobalI
Parameters:
commCallback - Application-provided callback to pass data packet to/from the remote library instance.
Returns:
Resulting connection class. At the end of the connection it should be closed using close(). (Corresponds with parameter phConnection in original function)
Throws:
PtException - Error code of fail, if any was accoured.

removeWatchConnection

public static void removeWatchConnection(int handle)
Removes all connections with specified handle from watchedQueu. It is called by native "close" and "closedevice" methods.

Parameters:
handle - is native connection handle for remove

terminate

public void terminate()
               throws PtException
Description copied from interface: PtGlobalI
Uninitialize the API library. Must not be called while any connection is still open. There is usually no need to call this function.

Specified by:
terminate in interface PtGlobalI
Throws:
PtException - Error code of fail, if any was accoured.