JNI

https://github.com/androidgolab/jni
Admin
JNI is an idiomatic Go library providing bindings for the Java Native Interface and 53 Android Java...
Tokens:689,838
Snippets:5,323
Trust Score:7.5
License:CC0-1.0
Update:2 days ago
Show doc for...
Tokens:
Raw
### Install and run gomobile APK

Source: https://github.com/androidgolab/jni/blob/main/examples/gomobile/README.md

Install the generated gomobile.apk on a device and start the GoNativeActivity.

```sh
adb install gomobile.apk
adb shell am start -n org.golang.app.gomobile/.GoNativeActivity
```

--------------------------------

### Build all examples

Source: https://github.com/androidgolab/jni/blob/main/README.md

Builds and installs all 53 example APKs from the repository root.

```bash
make examples     # builds all 53 APKs
```

--------------------------------

### Install gomobile

Source: https://github.com/androidgolab/jni/blob/main/examples/gomobile/README.md

Install the gomobile tool and initialize it before building the example.

```sh
go install golang.org/x/mobile/cmd/gomobile@latest
gomobile init
```

--------------------------------

### Build and run an example app

Source: https://github.com/androidgolab/jni/blob/main/README.md

Builds an APK, installs it, grants permissions, and launches the app for a specific example. Run from the example directory.

```bash
cd examples/alarm
make run          # build APK → install → grant permissions → launch
```

--------------------------------

### Install gogio (Gio build tool)

Source: https://github.com/androidgolab/jni/blob/main/examples/gio/README.md

Install the Gio build tool `gogio` using `go install`. Required before building the APK.

```sh
go install gioui.org/cmd/gogio@latest
```

--------------------------------

### Complete example: Battery status

Source: https://github.com/androidgolab/jni/blob/main/docs/getting-started.md

A complete function that retrieves battery status using the app and battery packages. It obtains a context from the activity, creates a battery manager, and prints charging state and capacity percentage.

```go
import (
    "github.com/AndroidGoLab/jni"
    "github.com/AndroidGoLab/jni/app"
    "github.com/AndroidGoLab/jni/os/battery"
)

func getBatteryInfo(vm *jni.VM, activityRef *jni.GlobalRef) error {
    ctx, err := app.ContextFromObject(vm, activityRef)
    if err != nil {
        return err
    }
    defer ctx.Close()

    mgr, err := battery.NewManager(ctx)
    if err != nil {
        return err
    }
    defer mgr.Close()

    charging, _ := mgr.IsCharging()
    capacity, _ := mgr.GetIntProperty(int32(battery.BatteryPropertyCapacity))
    fmt.Printf("Battery: %d%%, charging: %v\n", capacity, charging)
    return nil
}
```

--------------------------------

### Install APK on device

Source: https://github.com/androidgolab/jni/blob/main/examples/gio/README.md

Install the built `gio.apk` on a connected Android device using adb.

```sh
adb install -r gio.apk
```

--------------------------------

### Get app context using ui.GetAppContext helper

Source: https://github.com/androidgolab/jni/blob/main/docs/getting-started.md

In NativeActivity examples, the shared ui package provides a helper to get the app context. Use it instead of manually creating a context from an object reference.

```go
import "github.com/AndroidGoLab/jni/examples/common/ui"

ctx, err := ui.GetAppContext(vm)
if err != nil {
    return err
}
defer ctx.Close()
```

--------------------------------

### Obtain VM from NativeActivity with ANativeActivity_onCreate

Source: https://github.com/androidgolab/jni/blob/main/docs/getting-started.md

In a NativeActivity, the VM pointer comes from the activity struct. Use jni.VMFromUintptr and jni.ObjectFromUintptr to convert the C fields to Go types.

```go
/*
#include <android/native_activity.h>
*/
import "C"

//export ANativeActivity_onCreate
func ANativeActivity_onCreate(activity *C.ANativeActivity, savedState unsafe.Pointer, savedStateSize C.size_t) {
    vm := jni.VMFromUintptr(uintptr(activity.vm))
    activityObj := jni.ObjectFromUintptr(uintptr(activity.clazz))
    // ... use vm and activityObj ...
}
```

--------------------------------

### View gomobile logcat output

Source: https://github.com/androidgolab/jni/blob/main/examples/gomobile/README.md

View the logcat output filtered by the GoLog tag to see the build information printed by the example.

```sh
adb logcat -s GoLog:*
```

--------------------------------

### Create battery manager and call typed methods

Source: https://github.com/androidgolab/jni/blob/main/docs/getting-started.md

Shows the manager pattern for Android API packages: create a manager from context, defer Close(), then call typed methods like IsCharging() and GetIntProperty(). Requires an *app.Context and the battery package.

```go
import "github.com/AndroidGoLab/jni/os/battery"

// 1. Create manager from context
mgr, err := battery.NewManager(ctx)
if err != nil {
    return err
}
defer mgr.Close()

// 2. Call typed methods
charging, err := mgr.IsCharging()
capacity, err := mgr.GetIntProperty(int32(battery.BatteryPropertyCapacity))
```

--------------------------------

### Build APK with gogio

Source: https://github.com/androidgolab/jni/blob/main/examples/gio/README.md

Build the Android APK targeting the `center.dx.jni.examples.gio` app ID. Run from the example directory.

```sh
gogio -target android -appid center.dx.jni.examples.gio .
```

--------------------------------

### Build gomobile APK

Source: https://github.com/androidgolab/jni/blob/main/examples/gomobile/README.md

Build the Android APK from the repository root using gomobile.

```sh
gomobile build -target=android ./examples/gomobile
```

--------------------------------

### Convert Go string to JNI String and back

Source: https://github.com/androidgolab/jni/blob/main/docs/getting-started.md

Shows converting a Go string to a JNI String with env.NewStringUTF() and back with env.GoString(). The JNI string must be deleted with env.DeleteLocalRef() when done.

```go
vm.Do(func(env *jni.Env) error {
    // Go string -> JNI String
    jStr, err := env.NewStringUTF("hello")
    if err != nil {
        return err
    }
    defer env.DeleteLocalRef(&jStr.Object)

    // JNI String -> Go string
    goStr := env.GoString(jStr)
    fmt.Println(goStr) // "hello"
    return nil
})
```

--------------------------------

### Create app Context from JNI object reference

Source: https://github.com/androidgolab/jni/blob/main/docs/getting-started.md

Most Android APIs need a Context. Create one from an existing global reference (e.g., a NativeActivity object) using app.ContextFromObject. Close the context when done.

```go
import "github.com/AndroidGoLab/jni/app"

// From an existing global reference (e.g., a NativeActivity object):
ctx, err := app.ContextFromObject(vm, globalRef)
if err != nil {
    return err
}
defer ctx.Close()
```

--------------------------------

### Complete Example: Query System Settings

Source: https://github.com/androidgolab/jni/blob/main/docs/content-resolver.md

Full function that queries system settings, prints row/column counts and all values. Combines context, resolver, URI parsing, and cursor iteration.

```go
import (
    "github.com/AndroidGoLab/jni"
    "github.com/AndroidGoLab/jni/app"
    "github.com/AndroidGoLab/jni/content/resolver"
)

func querySettings(vm *jni.VM, activityRef *jni.GlobalRef) error {
    ctx, _ := app.ContextFromObject(vm, activityRef)
    defer ctx.Close()

    resolverObj, _ := ctx.GetContentResolver()
    cr := resolver.ContentResolver{VM: vm, Obj: resolverObj}

    uriHelper := resolver.Uri{VM: vm}
    uri, _ := uriHelper.Parse("content://settings/system")

    cursorObj, err := cr.Query4(uri, nil, nil, nil)
    if err != nil {
        return err
    }
    if cursorObj == nil {
        return nil
    }

    cursor := resolver.Cursor{VM: vm, Obj: cursorObj}
    defer cursor.Close()

    count, _ := cursor.GetCount()
    colCount, _ := cursor.GetColumnCount()
    fmt.Printf("Settings: %d rows, %d columns\n", count, colCount)

    ok, _ := cursor.MoveToFirst()
    for ok {
        var vals []string
        for c := int32(0); c < colCount; c++ {
            s, _ := cursor.GetString(c)
            vals = append(vals, s)
        }
        fmt.Println(vals)

        ok, _ = cursor.MoveToNext()
    }
    return nil
}
```

--------------------------------

### Complete Example: getTelephonyInfo

Source: https://github.com/androidgolab/jni/blob/main/docs/telephony.md

Full function that retrieves and prints phone type, SIM state, operator info, and data state. Requires a JNI VM and activity reference to create a context. Uses app.ContextFromObject and telephony.NewManager.

```go
import (
    "fmt"
    "github.com/AndroidGoLab/jni"
    "github.com/AndroidGoLab/jni/app"
    "github.com/AndroidGoLab/jni/telephony"
)

func getTelephonyInfo(vm *jni.VM, activityRef *jni.GlobalRef) error {
    ctx, _ := app.ContextFromObject(vm, activityRef)
    defer ctx.Close()

    mgr, err := telephony.NewManager(ctx)
    if err != nil {
        return err
    }
    defer mgr.Close()

    phoneType, _ := mgr.GetPhoneType()
    switch int(phoneType) {
    case telephony.PhoneTypeGsm:
        fmt.Println("Phone: GSM")
    case telephony.PhoneTypeCdma:
        fmt.Println("Phone: CDMA")
    default:
        fmt.Println("Phone: none/other")
    }

    simState, _ := mgr.GetSimState0()
    if int(simState) == telephony.SimStateReady {
        operatorName, _ := mgr.GetNetworkOperatorName()
        operator, _ := mgr.GetNetworkOperator()
        roaming, _ := mgr.IsNetworkRoaming()
        fmt.Printf("Operator: %s (%s), roaming: %v\n", operatorName, operator, roaming)
    }

    dataState, _ := mgr.GetDataState()
    switch int(dataState) {
    case telephony.DataConnected:
        fmt.Println("Data: connected")
    case telephony.DataDisconnected:
        fmt.Println("Data: disconnected")
    default:
        fmt.Printf("Data: state %d\n", dataState)
    }

    return nil
}
```

--------------------------------

### Build, install, and run the alarm clock app with make

Source: https://github.com/androidgolab/jni/blob/main/examples/alarm_clock_app/README.md

Builds, installs, and runs the alarm_clock_app demo on an Android device or emulator. `make run` launches the app's NativeActivity via adb.

```shell
make
make install
make run
```

--------------------------------

### Run JNI operations with VM.Do()

Source: https://github.com/androidgolab/jni/blob/main/docs/getting-started.md

Every JNI operation must run on a thread attached to the JVM. VM.Do() locks the goroutine to an OS thread, attaches it to the JVM if needed, runs the closure, and detaches on return. Local references are valid only within the closure scope.

```go
import "github.com/AndroidGoLab/jni"

err := vm.Do(func(env *jni.Env) error {
    // All JNI calls happen inside this closure.
    // The current goroutine is locked to an OS thread and attached to the JVM.
    // Local references are valid only within this scope.
    cls, err := env.FindClass("android/os/Build")
    if err != nil {
        return fmt.Errorf("find class: %w", err)
    }
    // ... use cls ...
    return nil
})
```

--------------------------------

### Wrap JNI value types with typed constructors

Source: https://github.com/androidgolab/jni/blob/main/docs/getting-started.md

Use typed constructors like jni.IntValue, jni.LongValue, jni.FloatValue, jni.BooleanValue, and jni.ObjectValue to wrap arguments when calling methods. For strings, create a JNI string with NewStringUTF and wrap its Object.

```go
// Primitive types
jni.IntValue(42)
jni.LongValue(int64(1000))
jni.FloatValue(float32(3.14))
jni.BooleanValue(true)

// Object types (including strings)
jStr, _ := env.NewStringUTF("hello")
jni.ObjectValue(&jStr.Object)
```

--------------------------------

### Create Java proxy with env.NewProxy

Source: https://github.com/androidgolab/jni/blob/main/docs/location.md

Use env.NewProxy to create a java.lang.reflect.Proxy that implements one or more Java interfaces and dispatches method calls to a Go callback. The callback receives the method name and arguments; handle each interface method in a switch. Call the returned cleanup function to release the Go callback and prevent leaks.

```go
proxy, cleanup, err := env.NewProxy(
    []*jni.Class{interfaceClass},
    func(env *jni.Env, methodName string, args []*jni.Object) (*jni.Object, error) {
        switch methodName {
        case "onLocationChanged":
            // Handle the callback
        case "onProviderEnabled":
            // Handle provider enabled
        }
        return nil, nil
    },
)
defer cleanup() // Release the Go callback prevent leaks
```

--------------------------------

### Convert local reference to global reference

Source: https://github.com/androidgolab/jni/blob/main/docs/getting-started.md

Shows how to keep an object alive across VM.Do() calls by converting a local reference to a global reference with env.NewGlobalRef(), then deleting the local ref. The global ref must be explicitly deleted later with env.DeleteGlobalRef().

```go
var globalObj *jni.Object
vm.Do(func(env *jni.Env) error {
    localObj, err := env.CallObjectMethod(someObj, someMethod)
    if err != nil {
        return err
    }
    // Convert local ref to global ref
    globalObj = env.NewGlobalRef(localObj)
    env.DeleteLocalRef(localObj)
    return nil
})
// globalObj is valid here, outside VM.Do()

// Later, when done:
vm.Do(func(env *jni.Env) error {
    env.DeleteGlobalRef(globalObj)
    return nil
})
```

--------------------------------

### Context.GetSystemService usage

Source: https://github.com/androidgolab/jni/blob/main/docs/method-calls.md

Shows how to obtain a context from a VM and activity reference, then call GetSystemService to get a service object. The method converts the returned local reference to a global reference.

```go
import "github.com/AndroidGoLab/jni/app"

ctx, _ := app.ContextFromObject(vm, activityRef)
defer ctx.Close()

// GetSystemService calls Context.getSystemService(String) via JNI,
// converts the returned local reference to a global reference,
// and returns it.
svcObj, err := ctx.GetSystemService("battery")
```

--------------------------------

### Convert Java exceptions to Go errors

Source: https://github.com/androidgolab/jni/blob/main/docs/getting-started.md

Wrap JNI calls in vm.Do to automatically convert Java exceptions to Go errors. The error contains the Java exception message, which can be wrapped with fmt.Errorf.

```go
vm.Do(func(env *jni.Env) error {
    result, err := env.CallObjectMethod(obj, method)
    if err != nil {
        // err contains the Java exception message
        return fmt.Errorf("call failed: %w", err)
    }
    return nil
})
```

--------------------------------

### Provider Constants

Source: https://github.com/androidgolab/jni/blob/main/docs/location.md

Constants for the standard Android location providers.

```APIDOC
## Provider Constants

### Description
Constants for the standard Android location providers.

### Constants
- `location.GpsProvider` (string) - "gps"
- `location.NetworkProvider` (string) - "network"
- `location.PassiveProvider` (string) - "passive"

### Example
```go
location.GpsProvider     // "gps"
location.NetworkProvider // "network"
location.PassiveProvider // "passive"
```
```

--------------------------------

### Data class accessor example with bluetooth.Device

Source: https://github.com/androidgolab/jni/blob/main/docs/general-patterns.md

Shows how to use typed data classes returned from manager methods. Access fields via methods like GetName, GetAddress, GetType. Compare with named constants (e.g., bluetooth.DeviceTypeLe) by casting int32 to int.

```go
import "github.com/AndroidGoLab/jni/bluetooth"

// device is returned from discovery or GATT operations
name, err := device.GetName()
addr, err := device.GetAddress()
devType, err := device.GetType()

// Compare with named constants (cast int32 to int to match constant type)
if int(devType) == bluetooth.DeviceTypeLe {
    fmt.Println("BLE device")
}
```

--------------------------------

### Use os/build package to read Build info

Source: https://github.com/androidgolab/jni/blob/main/docs/field-access.md

The os/build package provides GetBuildInfo and GetVersionInfo to read static fields from android.os.Build into Go structs. The example shows usage and the fields returned.

```go
import "github.com/AndroidGoLab/jni/os/build"

// GetBuildInfo reads static fields from android.os.Build.
info, err := build.GetBuildInfo(vm)
// info.Device, info.Model, info.Product, info.Manufacturer,
// info.Brand, info.Board, info.Hardware

// GetVersionInfo reads android.os.Build.VERSION fields.
ver, err := build.GetVersionInfo(vm)
// ver.SDKInt (int32), ver.Release, ver.Codename, ver.Incremental
```

--------------------------------

### BLE Advertising with le.BluetoothLeAdvertiser

Source: https://github.com/androidgolab/jni/blob/main/docs/bluetooth.md

Shows how to get a BluetoothLeAdvertiser and call StartAdvertising3 and StopAdvertising. Uses builder wrappers le.AdvertiseSettingsBuilder and le.AdvertiseDataBuilder for settings and data.

```go
import "github.com/AndroidGoLab/jni/bluetooth/le"

func bleAdvertise(vm *jni.VM, ctx *app.Context) error {
    adapter, err := bluetooth.NewAdapter(ctx)
    if err != nil {
        return err
    }
    defer adapter.Close()

    advertiserObj, err := adapter.GetBluetoothLeAdvertiser()
    if err != nil {
        return fmt.Errorf("GetBluetoothLeAdvertiser: %w", err)
    }
    advertiser := le.BluetoothLeAdvertiser{
        VM:  vm,
        Obj: (*jni.GlobalRef)(unsafe.Pointer(advertiserObj)),
    }

    // Build AdvertiseSettings and AdvertiseData using the builder wrappers,
    // or construct them via raw JNI.

    // StartAdvertising3(settingsObj, dataObj, callbackProxy)
    err = advertiser.StartAdvertising3(settingsObj, dataObj, callbackProxy)
    if err != nil {
        return err
    }

    // ... later ...

    // StopAdvertising(callbackProxy)
    return advertiser.StopAdvertising(callbackProxy)
}
```

--------------------------------

### System service manager example with telephony.NewManager

Source: https://github.com/androidgolab/jni/blob/main/docs/general-patterns.md

Shows the default pattern for accessing Android system services via a generated wrapper. Obtain a manager from an app.Context, close it with defer, and call typed methods. Use named constants like telephony.PhoneTypeGsm instead of magic numbers; cast int32 returns to int for switch comparisons.

```go
import (
    "github.com/AndroidGoLab/jni/app"
    "github.com/AndroidGoLab/jni/telephony"
)

func example(ctx *app.Context) error {
    mgr, err := telephony.NewManager(ctx)
    if err != nil {
        return err
    }
    defer mgr.Close()

    phoneType, err := mgr.GetPhoneType()
    if err != nil {
        return err
    }

    // Use named constants -- never magic numbers.
    // Constants are typed int; cast the int32 return to match.
    switch int(phoneType) {
    case telephony.PhoneTypeGsm:
        fmt.Println("GSM")
    case telephony.PhoneTypeCdma:
        fmt.Println("CDMA")
    }

    operatorName, err := mgr.GetNetworkOperatorName()
    if err != nil {
        return err
    }
    fmt.Println("Operator:", operatorName)

    return nil
}
```

--------------------------------

### Get BluetoothLeScanner in Go

Source: https://github.com/androidgolab/jni/blob/main/docs/bluetooth.md

Initializes a Bluetooth adapter and retrieves the BluetoothLeScanner object. The scanner is wrapped in a le.BluetoothLeScanner struct using a global reference from the adapter. Requires an app context and returns an error if adapter creation or scanner retrieval fails.

```go
import (
    "github.com/AndroidGoLab/jni"
    "github.com/AndroidGoLab/jni/bluetooth"
    "github.com/AndroidGoLab/jni/bluetooth/le"
)

func bleScan(vm *jni.VM, ctx *app.Context) error {
    adapter, err := bluetooth.NewAdapter(ctx)
    if err != nil {
        return err
    }
    defer adapter.Close()

    // GetBluetoothLeScanner returns a *jni.Object (global ref).
    scannerObj, err := adapter.GetBluetoothLeScanner()
    if err != nil {
        return fmt.Errorf("GetBluetoothLeScanner: %w", err)
    }
    scanner := le.BluetoothLeScanner{
        VM:  vm,
        Obj: (*jni.GlobalRef)(unsafe.Pointer(scannerObj)),
    }

```

--------------------------------

### Getting a ContentResolver

Source: https://github.com/androidgolab/jni/blob/main/docs/content-resolver.md

Obtains a ContentResolver from an Android activity context. Requires a valid VM and activity reference; errors are wrapped for context.

```go
import "github.com/AndroidGoLab/jni/content/resolver"

ctx, _ := app.ContextFromObject(vm, activityRef)
defer ctx.Close()

resolverObj, err := ctx.GetContentResolver()
if err != nil {
    return fmt.Errorf("GetContentResolver: %w", err)
}
cr := resolver.ContentResolver{VM: vm, Obj: resolverObj}
```

--------------------------------

### Full Bluetooth Discovery with BroadcastReceiver in Go

Source: https://github.com/androidgolab/jni/blob/main/docs/bluetooth.md

Registers a BroadcastReceiver for ACTION_FOUND, starts discovery, and cleans up. Requires a user-defined Java adapter GoBroadcastReceiver with a (J)V constructor. Checks that Bluetooth is enabled and that StartDiscovery returns true, otherwise returns an error.

```go
import (
    "fmt"
    "unsafe"

    "github.com/AndroidGoLab/jni"
    "github.com/AndroidGoLab/jni/app"
    "github.com/AndroidGoLab/jni/bluetooth"
    "github.com/AndroidGoLab/jni/content"
)

func runDiscovery(vm *jni.VM, ctx *app.Context) error {
    adapter, err := bluetooth.NewAdapter(ctx)
    if err != nil {
        return fmt.Errorf("NewAdapter: %w", err)
    }
    defer adapter.Close()

    enabled, err := adapter.IsEnabled()
    if err != nil {
        return err
    }
    if !enabled {
        return fmt.Errorf("bluetooth is not enabled")
    }

    // --- Register a BroadcastReceiver for ACTION_FOUND ---

    // 1. Register a Go handler that receives dispatched method calls.
    //    jni.RegisterProxyHandler returns a unique int64 ID.
    handlerID := jni.RegisterProxyHandler(
        func(env *jni.Env, methodName string, args []*jni.Object) (*jni.Object, error) {
            if methodName != "onReceive" || len(args) < 2 {
                return nil, nil
            }
            // args[0] = Context, args[1] = Intent (local ref)

            // Wrap the intent in a typed wrapper. Promote to global ref first
            // because Intent methods call vm.Do() internally.
            intentGlobal := env.NewGlobalRef(args[1])
            intent := app.Intent{VM: vm, Obj: intentGlobal}
            defer env.DeleteGlobalRef(intentGlobal)

            // Use typed wrapper to read the action.
            action, err := intent.GetAction()
            if err != nil {
                return nil, err
            }
            if action != bluetooth.ActionFound {
                return nil, nil
            }

            // Extract the BluetoothDevice from the intent extras.
            deviceObj, err := intent.GetParcelableExtra(bluetooth.ExtraDevice)
            if err != nil || deviceObj == nil {
                return nil, err
            }

            // Wrap in the generated Device type to use typed accessors.
            deviceGlobal := env.NewGlobalRef(deviceObj)
            device := bluetooth.Device{VM: vm, Obj: deviceGlobal}
            defer env.DeleteGlobalRef(deviceGlobal)

            name, _ := device.GetName()
            addr, _ := device.GetAddress()
            devType, _ := device.GetType()
            fmt.Printf("Found device: %s (%s) type=%d\n", name, addr, devType)

            return nil, nil
        },
    )
    defer jni.UnregisterProxyHandler(handlerID)

    // 2. Create an IntentFilter for ACTION_FOUND.
    filter, err := content.NewIntentFilter(vm, bluetooth.ActionFound)
    if err != nil {
        return fmt.Errorf("new IntentFilter: %w", err)
    }
    defer filter.Close()

    // 3. Instantiate GoBroadcastReceiver (user-defined Java adapter -- raw JNI required).
    var receiverGlobal *jni.GlobalRef
    err = vm.Do(func(env *jni.Env) error {
        recvClass, err := env.FindClass("center/dx/jni/generated/GoBroadcastReceiver")
        if err != nil {
            return fmt.Errorf("find GoBroadcastReceiver: %w", err)
        }
        defer env.DeleteLocalRef(&recvClass.Object)

        recvInit, err := env.GetMethodID(recvClass, "<init>", "(J)V")
        if err != nil {
            return fmt.Errorf("get <init>: %w", err)
        }
        recvLocal, err := env.NewObject(recvClass, recvInit, jni.LongValue(handlerID))
        if err != nil {
            return fmt.Errorf("new GoBroadcastReceiver: %w", err)
        }
        receiverGlobal = env.NewGlobalRef(recvLocal)
        env.DeleteLocalRef(recvLocal)
        return nil
    })
    if err != nil {
        return fmt.Errorf("create receiver: %w", err)
    }

    // 4. Register the receiver with the Context.
    _, err = ctx.RegisterReceiver2(
        (*jni.Object)(unsafe.Pointer(receiverGlobal)),
        filter.Obj,
    )
    if err != nil {
        return fmt.Errorf("register receiver: %w", err)
    }

    // 5. Start discovery.
    //    Returns (bool, error): true if discovery started successfully.
    started, err := adapter.StartDiscovery()
    if err != nil {
        return fmt.Errorf("StartDiscovery: %w", err)
    }
    if !started {
        return fmt.Errorf("StartDiscovery returned false (check permissions)")
    }
    fmt.Println("Discovery started -- devices will arrive in the handler above")

    // ... wait for results, e.g. time.Sleep or channel ...

    // 6. Cleanup: cancel discovery + unregister receiver.
    _, _ = adapter.CancelDiscovery()
    _ = ctx.UnregisterReceiver((*jni.Object)(unsafe.Pointer(receiverGlobal)))
    _ = vm.Do(func(env *jni.Env) error {
        env.DeleteGlobalRef(receiverGlobal)
        return nil
    })

    return nil
}
```

--------------------------------

### Call Java Instance Method via JNI

Source: https://github.com/androidgolab/jni/blob/main/docs/method-calls.md

Look up a Java instance method by name and JNI signature, then call it on an instance. The example retrieves the BluetoothAdapter's getName method, calls it, and converts the returned String to a Go string using unsafe.Pointer and jni.GoString.

```go
vm.Do(func(env *jni.Env) error {
    cls, err := env.FindClass("android/bluetooth/BluetoothAdapter")
    if err != nil {
        return err
    }

    // Look up the method ID
    mid, err := env.GetMethodID(cls, "getName", "()Ljava/lang/String;")
    if err != nil {
        return err
    }

    // Call it on an instance
    resultObj, err := env.CallObjectMethod(adapterObj, mid)
    if err != nil {
        return err
    }

    // Convert the returned String to Go
    name := env.GoString((*jni.String)(unsafe.Pointer(resultObj)))
    fmt.Println("Name:", name)
    return nil
})
```

--------------------------------

### Parsing Content URIs

Source: https://github.com/androidgolab/jni/blob/main/docs/content-resolver.md

Parses a content URI string into a Uri object using the resolver.Uri helper. The example parses the system settings URI.

```go
uriHelper := resolver.Uri{VM: vm}
uri, err := uriHelper.Parse("content://settings/system")
```

--------------------------------

### Launch alarm_clock_app NativeActivity via adb

Source: https://github.com/androidgolab/jni/blob/main/examples/alarm_clock_app/README.md

Resolves to the command used by `make run` to start the app's NativeActivity. Use `adb -s emulator-5554 ...` or `adb -s <serial> ...` when both an emulator and a real device are attached.

```shell
adb shell am start -n center.dx.jni.examples.alarm_clock_app/android.app.NativeActivity
```

--------------------------------

### Provider Constants

Source: https://github.com/androidgolab/jni/blob/main/docs/location.md

Lists the provider constants used with the location manager: GpsProvider, NetworkProvider, and PassiveProvider, with their string values.

```go
location.GpsProvider     // "gps"
location.NetworkProvider // "network"
location.PassiveProvider // "passive"
```

--------------------------------

### Call constructors with NewObject

Source: https://github.com/androidgolab/jni/blob/main/docs/method-calls.md

Use NewObject to create Java objects by calling their constructor. The example creates an android.os.HandlerThread with a name argument, passing a jni.String via jni.ObjectValue.

```go
vm.Do(func(env *jni.Env) error {
    // Create a HandlerThread with a name argument
    cls, err := env.FindClass("android/os/HandlerThread")
    if err != nil {
        return err
    }
    initMid, err := env.GetMethodID(cls, "<init>", "(Ljava/lang/String;)V")
    if err != nil {
        return err
    }
    name, err := env.NewStringUTF("MyThread")
    if err != nil {
        return err
    }
    obj, err := env.NewObject(cls, initMid, jni.ObjectValue(&name.Object))
    if err != nil {
        return err
    }
    // obj is a local reference to the new HandlerThread
    return nil
})
```

--------------------------------

### Create and start a HandlerThread with os.NewHandlerThread

Source: https://github.com/androidgolab/jni/blob/main/docs/broadcast-receiver.md

Creates a HandlerThread to provide a Looper for Android callbacks. Returns an error if creation fails. The Looper can be passed to APIs that need it for callback delivery.

```go
// NewHandlerThread creates and starts the thread in one call.
ht, err := os.NewHandlerThread(vm, "GoCallbackThread")
if err != nil {
    return err
}

// Get its Looper for registering callbacks.
looperObj, err := ht.GetLooper()
if err != nil {
    ht.Close()
    return err
}
// looperObj can be passed to APIs that need a Looper for callback delivery.
_ = looperObj
```

--------------------------------

### Method Naming Conventions

Source: https://github.com/androidgolab/jni/blob/main/docs/general-patterns.md

Java method names map to Go method names with specific conventions for getters, setters, and boolean checks. Overloaded methods get numeric suffixes for disambiguation.

```APIDOC
## Method Naming Conventions

### Description
Java method names map to Go method names. When Java has overloaded methods (same name, different parameter counts), Go appends a numeric suffix for arity.

### Naming Rules

| Java method | Go method |
|---|---|
| `getFoo()` | `GetFoo()` |
| `setFoo(x)` | `SetFoo(x)` |
| `isFoo()` | `IsFoo()` |

### Overload Disambiguation

| Java signature | Go method |
|---|---|
| `registerReceiver(BroadcastReceiver, IntentFilter)` | `RegisterReceiver2(...)` |
| `registerReceiver(BroadcastReceiver, IntentFilter, int)` | `RegisterReceiver3_1(...)` |

The `_N` suffix disambiguates when multiple overloads share the same arity.

### Return Types

Generated methods convert Java types to Go types automatically:

| Java return | Go return | Notes |
|---|---|---|
| `boolean` | `bool` | Converted from JNI `uint8` internally |
| `int` | `int32` | |
| `long` | `int64` | |
| `float` | `float32` | |
| `double` | `float64` | |
| `String` | `string` | Converted via `GoString` internally |
| Any object | `*jni.Object` | When no typed wrapper exists for the return type |

All methods return `error` as the last value.
```

--------------------------------

### Internal JNI Sequence for NewAdapter (Pseudocode)

Source: https://github.com/androidgolab/jni/blob/main/docs/bluetooth.md

This pseudocode shows the internal JNI steps performed by bluetooth.NewAdapter: getting the BluetoothManager system service, finding the BluetoothManager class, obtaining the getAdapter method ID, calling it, promoting the local reference to a global reference, and deleting the local reference. It is for debugging reference only; you do not need to write this yourself.

```go
// Pseudocode of what NewAdapter does internally:
svc, _ := ctx.GetSystemService("bluetooth")       // returns BluetoothManager global ref
bmClass, _ := env.FindClass("android/bluetooth/BluetoothManager")
getAdapterMid, _ := env.GetMethodID(bmClass, "getAdapter",
    "()Landroid/bluetooth/BluetoothAdapter;")       // JNI signature: no args, returns object
adapterLocal, _ := env.CallObjectMethod(svc, getAdapterMid)
adapter.Obj = env.NewGlobalRef(adapterLocal)        // promote to global ref
env.DeleteLocalRef(adapterLocal)                    // free local ref
```

--------------------------------

### Call static methods with GetStaticMethodID and CallStatic*Method

Source: https://github.com/androidgolab/jni/blob/main/docs/method-calls.md

Use GetStaticMethodID and CallStatic*Method to invoke static Java methods. The example calls android.os.Build.getRadioVersion() returning a String and getMajorSdkVersion(int) returning an int, passing an int argument via jni.IntValue.

```go
vm.Do(func(env *jni.Env) error {
    cls, err := env.FindClass("android/os/Build")
    if err != nil {
        return err
    }

    // Static method returning String
    mid, err := env.GetStaticMethodID(cls, "getRadioVersion", "()Ljava/lang/String;")
    if err != nil {
        return err
    }
    resultObj, err := env.CallStaticObjectMethod(cls, mid)
    if err != nil {
        return err
    }
    version := env.GoString((*jni.String)(unsafe.Pointer(resultObj)))

    // Static method returning int
    mid2, err := env.GetStaticMethodID(cls, "getMajorSdkVersion", "(I)I")
    if err != nil {
        return err
    }
    major, err := env.CallStaticIntMethod(cls, mid2, jni.IntValue(36))

    return nil
})
```

--------------------------------

### Using Android SDK constants from parent package

Source: https://github.com/androidgolab/jni/blob/main/docs/general-patterns.md

Shows how to reference Android SDK constants as named Go values from the parent package (e.g., bluetooth). Use these instead of magic numbers in comparisons, switch statements, and arguments.

```go
import "github.com/AndroidGoLab/jni/bluetooth"

// Use directly from the parent package:
bluetooth.DeviceTypeClassic          // = 1
bluetooth.BondBonded                 // = 12
bluetooth.GattSuccess                // = 0
bluetooth.StateConnected             // = 2
bluetooth.ConnectionPriorityHigh     // = 1
bluetooth.ScanModeConnectableDiscoverable // = 23
```

--------------------------------

### WiFi manager usage

Source: https://github.com/androidgolab/jni/blob/main/README.md

Creates a WiFi manager and checks if WiFi is enabled. Requires a valid context and ignores errors.

```go
import "github.com/AndroidGoLab/jni/net/wifi"

    mgr, _ := wifi.NewManager(ctx)
    defer mgr.Close()

    enabled, _ := mgr.IsWifiEnabled()
    fmt.Println("WiFi enabled:", enabled)
```

--------------------------------

### Create HandlerThread for callbacks

Source: https://github.com/androidgolab/jni/blob/main/docs/general-patterns.md

Use os.NewHandlerThread to create and start a Looper thread for callback-based Android APIs. The returned handler thread must be closed with ht.Close() to release resources. Get the Looper object via ht.GetLooper() to pass when registering callbacks.

```go
import "github.com/AndroidGoLab/jni/os"

ht, err := os.NewHandlerThread(vm, "GoCallbackThread")
if err != nil {
    return err
}
defer ht.Close()

looperObj, err := ht.GetLooper()
if err != nil {
    return err
}
// Pass looperObj when registering callbacks...
```

--------------------------------

### Graceful degradation across API levels

Source: https://github.com/androidgolab/jni/blob/main/docs/general-patterns.md

Try a newer API first and fall back to a legacy method when the newer one is unavailable on older devices.

```go
// Try the newer API first, fall back gracefully
result, err := mgr.GetFoo()
if err != nil {
    // Might not exist on older devices -- use fallback
    result, err = mgr.GetLegacyFoo()
}
```

--------------------------------

### Host GATT Server with OpenGattServer

Source: https://github.com/androidgolab/jni/blob/main/docs/bluetooth.md

Sets up a GATT server on the device using bluetooth.Manager.OpenGattServer. The callback must implement BluetoothGattServerCallback. Add services, notify clients, and send responses via the returned GattServer object.

```go
func gattServer(vm *jni.VM, ctx *app.Context) error {
    mgr, err := bluetooth.NewManager(ctx)
    if err != nil {
        return err
    }
    defer mgr.Close()

    // OpenGattServer(context, callback) -> raw BluetoothGattServer object
    // callback must implement BluetoothGattServerCallback (abstract class)
    serverObj, err := mgr.OpenGattServer(
        (*jni.Object)(unsafe.Pointer(ctx.Obj)),
        serverCallbackProxy,
    )
    if err != nil {
        return fmt.Errorf("OpenGattServer: %w", err)
    }
    server := bluetooth.GattServer{
        VM:  vm,
        Obj: (*jni.GlobalRef)(unsafe.Pointer(serverObj)),
    }
    defer server.Close()

    // Add a service (constructed via raw JNI using BluetoothGattService constructor)
    ok, err := server.AddService(serviceObj)

    // Notify connected clients of characteristic changes
    err = server.NotifyCharacteristicChanged3(deviceObj, characteristicObj, true)

    // Send response to a read/write request (in the callback)
    err = server.SendResponse(deviceObj, requestID, bluetooth.GattSuccess, offset, valueObj)

    return nil
}
```

--------------------------------

### Bluetooth adapter usage

Source: https://github.com/androidgolab/jni/blob/main/README.md

Creates a Bluetooth adapter, checks if it is enabled, and retrieves the device name and address. Requires a valid context and handles errors by ignoring them.

```go
import "github.com/AndroidGoLab/jni/bluetooth"

    adapter, _ := bluetooth.NewAdapter(ctx)
    defer adapter.Close()

    enabled, _ := adapter.IsEnabled()
    name, _ := adapter.GetName()
    addr, _ := adapter.GetAddress()
    fmt.Printf("Bluetooth: %s (%s), enabled=%v\n", name, addr, enabled)
```

--------------------------------

### Location.GetLongitude

Source: https://github.com/androidgolab/jni/blob/main/docs/location.md

Returns the longitude of the location.

```APIDOC
## Location.GetLongitude

### Description
Returns the longitude of the location.

### Method
GetLongitude

### Signature
`func (loc *Location) GetLongitude() (float64, error)`

### Returns
- `float64` - The longitude in degrees.
- `error` - An error if the operation fails.

### Example
```go
lon, _ := loc.GetLongitude()
```
```

--------------------------------

### Location.GetLatitude

Source: https://github.com/androidgolab/jni/blob/main/docs/location.md

Returns the latitude of the location.

```APIDOC
## Location.GetLatitude

### Description
Returns the latitude of the location.

### Method
GetLatitude

### Signature
`func (loc *Location) GetLatitude() (float64, error)`

### Returns
- `float64` - The latitude in degrees.
- `error` - An error if the operation fails.

### Example
```go
lat, _ := loc.GetLatitude()
```
```

--------------------------------

### Post a Notification

Source: https://github.com/androidgolab/jni/blob/main/docs/notifications.md

Demonstrates how to create a notification manager, channel, builder, and post a notification from Go using the jni package.

```APIDOC
## Post a Notification

### Description
This example shows the complete flow of posting a notification: creating a manager, creating a channel, building a notification, and posting it.

### Code Example
```go
import "github.com/AndroidGoLab/jni/app/notification"

// 1. Create NotificationManager from app context
mgr, err := notification.NewManager(ctx)
if err != nil {
    return err
}
defer mgr.Close()

// 2. Create a notification channel (required on API 26+)
ch, err := notification.NewChannel(
    vm,
    "alerts",                              // channel ID
    "Alerts",                              // display name
    int32(notification.ImportanceHigh),     // importance level
)
if err != nil {
    return err
}
if err := mgr.CreateNotificationChannel(ch.Obj); err != nil {
    return err
}

// 3. Get the application context for the builder
appCtxObj, err := ctx.GetApplicationContext()
if err != nil {
    return err
}

// 4. Build the notification
b, err := notification.NewBuilder(vm, appCtxObj, "alerts")
if err != nil {
    return err
}
b.SetSmallIcon1_1(17301620) // android.R.drawable.ic_dialog_info
b.SetContentTitle("Hello from Go!")
b.SetContentText("Posted via JNI — no Java code")
notif, err := b.Build()
if err != nil {
    return err
}

// 5. Post it
if err := mgr.Notify2(1, notif); err != nil {
    return err
}
```
```

--------------------------------

### RemoveUpdates1

Source: https://github.com/androidgolab/jni/blob/main/docs/location.md

Removes location updates for a given listener. Should be called to stop receiving updates.

```APIDOC
## RemoveUpdates1

### Description
Removes location updates for a given listener. Should be called to stop receiving updates.

### Method
RemoveUpdates1

### Signature
`func (mgr *Manager) RemoveUpdates1(listener *jni.Object) error`

### Parameters
- `listener` (*jni.Object) - Required - The listener to remove.

### Returns
- `error` - An error if the operation fails.

### Example
```go
mgr.RemoveUpdates1(listenerGlobal)
```
```

--------------------------------

### IsProviderEnabled

Source: https://github.com/androidgolab/jni/blob/main/docs/location.md

Checks whether a given location provider is enabled. Returns a boolean indicating availability.

```APIDOC
## IsProviderEnabled

### Description
Checks whether a given location provider is enabled. Returns a boolean indicating availability.

### Method
IsProviderEnabled

### Signature
`func (mgr *Manager) IsProviderEnabled(provider string) (bool, error)`

### Parameters
- `provider` (string) - Required - The provider name (e.g., "gps", "network").

### Returns
- `bool` - True if the provider is enabled.
- `error` - An error if the check fails.

### Example
```go
gpsEnabled, _ := mgr.IsProviderEnabled(location.GpsProvider)
netEnabled, _ := mgr.IsProviderEnabled(location.NetworkProvider)
```
```

--------------------------------

### NewManager

Source: https://github.com/androidgolab/jni/blob/main/docs/location.md

Creates a new LocationManager wrapper for accessing Android location services. Returns an error if the manager cannot be created.

```APIDOC
## NewManager

### Description
Creates a new LocationManager wrapper for accessing Android location services. Returns an error if the manager cannot be created.

### Method
NewManager

### Signature
`func NewManager(ctx context.Context) (*Manager, error)`

### Parameters
- `ctx` (context.Context) - Required - The context for the operation.

### Returns
- `*Manager` - The manager instance.
- `error` - An error if creation fails.

### Example
```go
mgr, err := location.NewManager(ctx)
if err != nil {
    return fmt.Errorf("location.NewManager: %w", err)
}
defer mgr.Close()
```
```

--------------------------------

### Call Object Method and Promote to GlobalRef (CallObjectMethod + GlobalRef)

Source: https://github.com/androidgolab/jni/blob/main/docs/bluetooth.md

Calls a Java method that returns an object, then promotes the local reference to a global reference to keep it across vm.Do calls. The local reference is deleted after promotion.

```go
// JNI signature "()Landroid/bluetooth/le/BluetoothLeScanner;"
mid, _ := env.GetMethodID(cls, "getBluetoothLeScanner",
    "()Landroid/bluetooth/le/BluetoothLeScanner;")
localRef, err := env.CallObjectMethod(obj, mid)
globalRef := env.NewGlobalRef(localRef)  // must promote if keeping across vm.Do calls
env.DeleteLocalRef(localRef)
```

--------------------------------

### Using Android SDK constants from consts sub-package

Source: https://github.com/androidgolab/jni/blob/main/docs/general-patterns.md

Shows how to reference the same constants from the consts sub-package to avoid name collisions. Import the consts package with an alias and use the constant names directly.

```go
import btconsts "github.com/AndroidGoLab/jni/bluetooth/consts"

btconsts.DeviceTypeClassic
btconsts.GattSuccess
```

--------------------------------

### RequestLocationUpdates5_4

Source: https://github.com/androidgolab/jni/blob/main/docs/location.md

Requests location updates using the Android 5.4 API. Requires a LocationListener proxy and a Looper for callback delivery.

```APIDOC
## RequestLocationUpdates5_4

### Description
Requests location updates using the Android 5.4 API. Requires a LocationListener proxy and a Looper for callback delivery.

### Method
RequestLocationUpdates5_4

### Signature
`func (mgr *Manager) RequestLocationUpdates5_4(provider string, minTimeMs int64, minDistanceMeters float32, listener *jni.Object, looper *jni.Object) error`

### Parameters
- `provider` (string) - Required - The provider name (e.g., "gps").
- `minTimeMs` (int64) - Required - Minimum time interval between updates in milliseconds.
- `minDistanceMeters` (float32) - Required - Minimum distance between updates in meters.
- `listener` (*jni.Object) - Required - A global reference to the LocationListener proxy.
- `looper` (*jni.Object) - Required - A Looper for callback delivery.

### Returns
- `error` - An error if the request fails.

### Example
```go
mgr.RequestLocationUpdates5_4(
    location.GpsProvider,
    0,
    0,
    listenerGlobal,
    looper,
)
```
```

--------------------------------

### bluetooth.NewAdapter

Source: https://github.com/androidgolab/jni/blob/main/docs/bluetooth.md

Obtains the BluetoothAdapter via the BluetoothManager system service. It internally calls ctx.GetSystemService("bluetooth") to get a BluetoothManager, then calls BluetoothManager.getAdapter() on it.

```APIDOC
## bluetooth.NewAdapter

### Description
Obtains the BluetoothAdapter via the BluetoothManager system service. It internally calls ctx.GetSystemService("bluetooth") to get a BluetoothManager, then calls BluetoothManager.getAdapter() on it.

### Method
NewAdapter

### Endpoint
bluetooth.NewAdapter(ctx *app.Context) (*Adapter, error)

### Parameters
#### Arguments
- **ctx** (*app.Context) - Required - The application context used to access system services.

### Response
#### Success Response
- **adapter** (*Adapter) - The BluetoothAdapter instance wrapped in a Go object.
- **err** (error) - nil on success.

#### Error Response
- **err** (error) - Non-nil if the adapter could not be obtained.

### Request Example
```go
adapter, err := bluetooth.NewAdapter(ctx)
if err != nil {
    return fmt.Errorf("bluetooth.NewAdapter: %w", err)
}
defer adapter.Close() // releases the JNI global reference
```
```

--------------------------------

### Declare location permissions in AndroidManifest.xml

Source: https://github.com/androidgolab/jni/blob/main/docs/location.md

Add these uses-permission elements to your Android manifest to request fine and coarse location access. Required for location-based features.

```xml
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
```
Tokens:
Raw