Package com.mouseviator.fsuipc

Class FSUIPCWrapper

java.lang.Object
com.mouseviator.fsuipc.FSUIPCWrapper
public class FSUIPCWrapper
extends java.lang.Object
Wrapper class for fsuipc_java64.dll and fsuipc_java32.dll libraries. This class is based upon SDK written by Mark Burton, later amended by Paul Henty for 64 bit environment.

Why the rewrite? Well, the main reason for me was performance considerations. After studying FSUIPC C SDK, the wrapper library and the Java SDK by Mark, I found out that the readData(int, int, byte[]) and writeData(int, int, byte[]) functions calls internally FSUIPC_Process() function (within that C++ fsuipc_java64.dll, fsuipc_java32.dll). I have read on the forums that this function is quite heavy on processing time - thus, calling it after each data request is at least not optimal. And I think it might cause trouble in bigger project where you need to update multiple data several times per second. Thus, I decided that I will try to write my own wrapper, that will allow to store multiple read/write requests for FSUIPC and then process them all via one call to the process function. Following the approach, we would use writing the code in C++.

I kept the above functions for those who are used to use them.... But there are new functions:

which will do the same as their counterparts within the C++ - store the read / write request, but will NOT immediately process them. To process them, you have to call:

process()

The other functions, that were present in the old SDK API, are the same with the same functionality:

Oh, OK. The naming convention changed... the method/function names started with a BIG letter and returned no value, most of the time, now they start with small letter and returns the value.... Just tried to make them the same as in FSUIPC C SDK. Also, some new functions were added:

The above functions returns the respective variables defined within FSUIPC C library... Last, for now least, are functions:

which enables logging to file - if you specify that by parameters. Then, a log file called fsuipc_java64.log is created by functions within the C++ library, so we have at least some idea, what happens inside there...

Please note that this class will NOT load either the fsuipc_java64.dll or fsuipc_java32.dll libraries. You have to do it before the first usage of this class! But, the direct usage of this class is sort of cumbersome. Rather, use the FSUIPC class. It uses more object oriented approach, uses this class internally and also provides functions, such as FSUIPC.load(), FSUIPC.load32() and FSUIPC.load64() to load the dll libraries.

Author:
Mouseviator

  • Nested Class Summary

    Nested Classes
    Modifier and Type Class Description
    static class  FSUIPCWrapper.FSUIPCResult
    An enumeration of known result codes, that can be returned by calls to read(int, int, byte[]), write(int, int, byte[]), process().
    static class  FSUIPCWrapper.FSUIPCSimVersion
    An enumeration of known FSUIPC sim versions for passing as parameter to open(int) function.
    static class  FSUIPCWrapper.LogSeverity
    An enumeration of logging severity that can be used in setupLogging(boolean, byte) function.

  • Method Summary

    Modifier and Type Method Description
    static void close()
    Close the connection to FSUIPC.
    static int getFSVersion()
    Returns the FSUIPC_FS_Version variable.
    static int getLibVersion()
    Returns the FSUIPC_Lib_Version variable.
    static int getResult()
    Returns the last result code.
    static int getVersion()
    Returns the FSUIPC_Version variable.
    static int open​(int aFlightSim)
    Connect to FS.
    static int process()
    This function instructs FSUIPC to process all stored read/write requests.
    static int read​(int aOffset, int aSize, byte[] aData)
    Stores read request to read data from flight simulator.
    static int readData​(int aOffset, int aSize, byte[] aData)
    Reads data from flight simulator.
    static void setupLogging​(boolean bEnableFileLogging, byte severityLevel)
    This function will enable logging from the dll library...
    static void setupLogging​(boolean bEnableFileLogging, java.lang.String fileName, byte severityLevel)
    This function will enable logging from the dll library...Can be useful when something does not work and you want to see what happens inside the library.
    static void setupLogging​(boolean bEnableFileLogging, java.lang.String fileName, byte severityLevel, int rotationSize)
    This function will enable logging from the dll library...Can be useful when something does not work and you want to see what happens inside the library.The bEnableFileLogging, when set to true, will enable logging to file.
    static int write​(int aOffset, int aSize, byte[] aData)
    Stores write request to write data to flight simulator.
    static int writeData​(int aOffset, int aSize, byte[] aData)
    Writes data to flight simulator.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • open

      public static int open​(int aFlightSim)
      Connect to FS.
      Parameters:
      aFlightSim - Version of flight simulator to try to connect to.
      Returns:
      False (0) if connection failed. True (non-zero) if connection opened.

    • close

      public static void close()
      Close the connection to FSUIPC.

    • read

      public static int read​(int aOffset, int aSize, byte[] aData)
      Stores read request to read data from flight simulator.
      Parameters:
      aOffset - An FSUIPC offset to read data from.
      aSize - A size of the data to read (in bytes).
      aData - A buffer to store the read data into.
      Returns:
      Returns True (request successfully saved), or False (failed to save request). If request failed, we can get last error code by getResult()

    • readData

      public static int readData​(int aOffset, int aSize, byte[] aData)
      Reads data from flight simulator. This function will internally call FSUIPC_Read to store read request for given data, and immediately will call FSUPC_Process to force FSUIPC to process the request. The result will be available within aData right after function call. Note that this approach is suitable for small programs reading a couple of values in not so short intervals. The IPC communication , which happens every time FSUP_Process is called...is quite time consuming. Calling this with every read/write request is very UNEFFECTIVE. Use read(int, int, byte[]) function to store multiple data read requests and than get all values using process() function.
      Parameters:
      aOffset - An FSUIPC offset to read data from.
      aSize - A size of the data to read (in bytes).
      aData - A buffer to store the read data into.
      Returns:
      Returns True if data was read, or False in case of failure. If request failed, we can get last error code by getResult() - in this case, it will be result of the FSUIPC_Process function (called internally by implementation).

    • write

      public static int write​(int aOffset, int aSize, byte[] aData)
      Stores write request to write data to flight simulator.
      Parameters:
      aOffset - An FSUIPC offset to write data to.
      aSize - A size of the data to write (in bytes).
      aData - A data to write.
      Returns:
      Returns True (request successfully saved), or False (failed to save request). If request failed, we can get last error code by getResult()

    • writeData

      public static int writeData​(int aOffset, int aSize, byte[] aData)
      Writes data to flight simulator.
      Parameters:
      aOffset - An FSUIPC offset to write data to.
      aSize - A size of the data to write (in bytes).
      aData - A data to write.
      Returns:
      Returns True if data write succeeded, or False in case of failure. If request failed, we can get last error code by getResult() - in this case, it will be result of the FSUIPC_Process function (called internally by implementation).

    • process

      public static int process()
      This function instructs FSUIPC to process all stored read/write requests.
      Returns:
      True if processing succeeded, False otherwise. In case of failure, get the last result by getResult().

    • getResult

      public static int getResult()
      Returns the last result code. It is integer value. All the known values are defined within FSUIPCWrapper.FSUIPCResult This value is changed in the calls of either one of read(int, int, byte[]), write(int, int, byte[]), process().
      Returns:
      Integer value representing the last result.

    • getFSVersion

      public static int getFSVersion()
      Returns the FSUIPC_FS_Version variable.
      Returns:
      Integer value. Should match one of the FSUIPCWrapper.FSUIPCSimVersion ... so, if you use FSUIPCWrapper.FSUIPCSimVersion.get(int), where parameter will be the number returned by this function, it should not end up with exception and you should know what sim FSUIPC is connected to.

    • getVersion

      public static int getVersion()
      Returns the FSUIPC_Version variable.
      Returns:
      Integer value. HIWORD is 1000 x Version Number, minimum 1998. LOWORD is build letter, with a = 1 etc. For 1998 this must be at least 5 (1998e).

    • getLibVersion

      public static int getLibVersion()
      Returns the FSUIPC_Lib_Version variable.
      Returns:
      Integer value. HIWORD is 1000 x version, LOWORD is build letter, a = 1 etc.

    • setupLogging

      public static void setupLogging​(boolean bEnableFileLogging, byte severityLevel)
      This function will enable logging from the dll library... Can be useful when something does not work and you want to see what happens inside the library. The bEnableFileLogging, when set to true, will enable logging to file. The severityLevel sets severity level - ie. how much log messages you want to see. See FSUIPCWrapper.LogSeverity for possible values. With this function the log file name will be fsuipc_java64.log for 64bit library and fsuipc_java32.log for 32bit library. And the log rotation file size will be 10MB.
      Parameters:
      bEnableFileLogging - Whether to enable logging to file or not.
      severityLevel - Logging severity level.

    • setupLogging

      public static void setupLogging​(boolean bEnableFileLogging, java.lang.String fileName, byte severityLevel)
      This function will enable logging from the dll library...Can be useful when something does not work and you want to see what happens inside the library. The bEnableFileLogging, when set to true, will enable logging to file. The severityLevel sets severity level - ie. how much log messages you want to see. See FSUIPCWrapper.LogSeverity for possible values. The log rotation file size will be 10MB.
      Parameters:
      bEnableFileLogging - Whether to enable logging to file or not.
      fileName - The name of the log file.
      severityLevel - Logging severity level.

    • setupLogging

      public static void setupLogging​(boolean bEnableFileLogging, java.lang.String fileName, byte severityLevel, int rotationSize)
      This function will enable logging from the dll library...Can be useful when something does not work and you want to see what happens inside the library.The bEnableFileLogging, when set to true, will enable logging to file. The severityLevel sets severity level - ie. how much log messages you want to see. See FSUIPCWrapper.LogSeverity for possible values.
      Parameters:
      bEnableFileLogging - Whether to enable logging to file or not.
      fileName - The name of the log file.
      severityLevel - Logging severity level.
      rotationSize - The maximum size of the log file in bytes.