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:

- `read(int, int, byte[])`
- `write(int, int, byte[])`

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:

- `open(int)`
- `close()`

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:

- `getVersion()`
- `getFSVersion()`
- `getLibVersion()`

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

- `setupLogging(boolean, byte)`
- `setupLogging(boolean, java.lang.String, byte)`
- `setupLogging(boolean, java.lang.String, byte, int)`

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.