# lite/abi/tflite.h

Native functions for initializing and shutting down the TensorFlow Lite (TFLite) in Google Play Services Native API.

## Summary

One of the following functions must be called (and must return successfully) before any of the TFLite C API functions are called:

- the `GmsTfLiteInitialize()` or `GmsTfLiteInitializeOrThrow()` native functions defined in this header file.
- the `com.google.android.gms.tflite.java.TfLiteNative.initialize(Context context)` or `com.google.android.gms.tflite.java.TfLiteNative.initialize(Context context, TfLiteInitializationOptions options)` methods defined in the Java API.

### Functions
`GmsTfLiteCheckInitializedOrThrow(JNIEnv *env)` | `bool` Checks whether the TFLite API has been initialized, throwing a Java exception otherwise.
`GmsTfLiteErrorCodeVersionTooNew(int error_code)` | `bool` Returns true if the error code indicates the TFLite ABI version is too new.
`GmsTfLiteErrorCodeVersionTooOld(int error_code)` | `bool` Returns true if the error code indicates that the TFLite ABI version is too old.
`GmsTfLiteInitialize(JNIEnv *env, jobjecthandle)` | `int` Initialize TFLite with a handle acquired from Google Play Services API.
`GmsTfLiteInitializeOrThrow(JNIEnv *env, jobjecthandle)` | `bool` Initialize TFLite with a handle acquired from Google Play Services API, throwing a Java exception on failure.
`GmsTfLiteShutdown(void)` | `void` Resets the TFLite API.

## Functions

### GmsTfLiteCheckInitializedOrThrow

    bool GmsTfLiteCheckInitializedOrThrow(
      JNIEnv *env
    )

Checks whether the TFLite API has been initialized, throwing a Java exception otherwise.

Details
Parameters |
`env` | The JNIEnv for the current thread (which has to be attached to the JVM).
Returns | Whether or not the TFLite API has been initialized. If this method returns false, no other JNI method should be called until the pending exception has been handled (typically by returning to Java).

### GmsTfLiteErrorCodeVersionTooNew

    bool GmsTfLiteErrorCodeVersionTooNew(
      int error_code
    )

Returns true if the error code indicates the TFLite ABI version is too new.

In this case, the client should be updated to a newer version.

To avoid this error, make sure that your app is built against the latest version of the TFLite in Google Play Services client library code.

If TFLite is important for the functionality of the app, then we recommend that the calling code notify the user in this case. Suggested actions for the user could include:

- Try updating the app to the latest version

If the in-app update API (https://developer.android.com/guide/playcore/in-app-updates) is available, we also recommend using the in-app update API to allow the user to automatically update the app if a new version is available.

Details
Parameters |
`error_code` | An error code returned by GmsTfLiteInitialize.

### GmsTfLiteErrorCodeVersionTooOld

    bool GmsTfLiteErrorCodeVersionTooOld(
      int error_code
    )

Returns true if the error code indicates that the TFLite ABI version is too old.

In this case, the TFLite in Google Play Services module should be updated to a newer version.

If TFLite is important for the functionality of the app, then we recommend that the calling code notify the user in this case. Suggested actions for the user could include:

- Make sure your device is connected to the internet, and
- Try updating Google Play services https://support.google.com/googleplay/answer/9037938.

Details
Parameters |
`error_code` | An error code returned by GmsTfLiteInitialize.

### GmsTfLiteInitialize

    int GmsTfLiteInitialize(
      JNIEnv *env,
      jobjecthandle
    )

Initialize TFLite with a handle acquired from Google Play Services API.

This method (along with `GmsTfLiteInitializeOrThrow()`) can be called multiple times with the same handle; attempting to initialize with a different handle (without a call to `GmsTfLiteShutdown()` in between) will fail.

Details
Parameters |
`env` | The JNIEnv for the current thread (which has to be attached to the JVM).
`handle` | An InternalNativeInitializationHandle object acquired through the Google Play Services API.
Returns | 0 on success, or a non-zero error code on failure. The error codes are implementation-specific, but error conditions that clients may need to deal with can be tested using the `GmsTfLiteErrorCodeVersionTooOld()` and `GmsTfLiteErrorCodeVersionTooNew()` functions. Clients may also wish to log the specific error code for ease of debugging.

### GmsTfLiteInitializeOrThrow

    bool GmsTfLiteInitializeOrThrow(
      JNIEnv *env,
      jobjecthandle
    )

Initialize TFLite with a handle acquired from Google Play Services API, throwing a Java exception on failure.

This method (along with `GmsTfLiteInitialize()`) can be called multiple times with the same handle; attempting to initialize with a different handle (without a call to `GmsTfLiteShutdown()` in between) will fail.

Details
Parameters |
`env` | The JNIEnv for the current thread (which has to be attached to the JVM).
`handle` | An InternalNativeInitializationHandle object acquired through the Google Play Services API.
Returns | Whether or not initialization was successful. If this method returns false, no other JNI method should be called until the pending exception has been handled (typically by returning to Java).

### GmsTfLiteShutdown

    void GmsTfLiteShutdown(
      void
    )

Resets the TFLite API.

After this method is called, the TFLite API will be unusable until a subsequent call to `GmsTfLiteInitialize()` or `GmsTfLiteInitializeOrThrow()`. This can be used to switch to a different version of the TFLite library.