@spec battery_level() :: integer()

Current battery level (0..100), or -1 if unknown.

@spec battery_state() :: :unplugged | :charging | :full | :unknown

Current battery state — :unplugged | :charging | :full | :unknown.

@spec categories() :: [category()]

Returns the configured list of valid categories.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec foreground?() :: boolean()

True if the app is currently in the foreground.

@spec keep_awake(boolean()) :: :ok

Keep the screen awake — disable the auto-dim / auto-lock idle timer while on? is true, release it with false. Useful for video, reading, navigation, or any screen the user watches without touching. No permission required on either platform.

The keep-awake flag is app-scoped and the OS clears it when the app is backgrounded, so re-assert it on resume (e.g. from the :app did_become_active event) if you need it to persist across a background/ foreground cycle. On a device with no active window (e.g. before first render) it's a no-op.

iOS: UIApplication.isIdleTimerDisabled. Android: the window's FLAG_KEEP_SCREEN_ON.

@spec lock_orientation(lock()) :: :ok | {:error, :invalid}

Lock the app to orientation, overriding the OS auto-rotate setting.

Accepts :portrait, :portrait_upside_down, :landscape (either side), :landscape_left, or :landscape_right. Returns {:error, :invalid} for anything else. Global to the app; pair with unlock_orientation/0.

@spec low_power_mode?() :: boolean()

True if Low Power Mode (iOS) / Power Save Mode (Android) is on.

@spec model() :: String.t()

Device model (e.g. "iPhone", "Pixel 8").

@spec network_state() :: network_state()

Current network connectivity snapshot.

online is true when the OS reports a usable default network path is up. It does not guarantee the internet is reachable — a captive-portal or not-yet-validated network reports online: true on both platforms (iOS NWPath satisfied / Android default NetworkCallback). transport names the active interface — :wifi | :cellular | :wired | :other | :none; it is :none exactly when online is false. expensive is true on metered links (cellular, personal hotspot), so defer large transfers when it is set.

validated and constrained are single-platform signals — each platform reports :unavailable (not a misleading false) for the one it can't answer:

• validated — Android only (NET_CAPABILITY_VALIDATED): the OS actively probed and confirmed real internet reachability; false on a captive portal or before validation completes. :unavailable on iOS (NWPath has no probe).

• constrained — iOS only (nw_path_is_constrained): Low Data Mode is on. :unavailable on Android (no per-network equivalent).

  # iOS #=> %{online: true, transport: :wifi, expensive: false, # validated: :unavailable, constrained: false} # Android #=> %{online: true, transport: :wifi, expensive: false, # validated: true, constrained: :unavailable}

Subscribe to the :network category to receive {:mob_device, :connectivity_changed, state} when this changes — state is the same full map shape returned here (all five keys, validated/constrained included).

@spec online?() :: boolean()

True if the device currently has a usable network path.

@spec open_settings(:app | :notifications | :exact_alarm) :: :ok | {:error, :invalid}

Opens an OS settings screen for this app.

target is one of:

• :app — the app's details / permissions page (both platforms). The go-to when a runtime permission was permanently denied and the user must re-enable it by hand.
• :notifications — the app's notification settings (Android). iOS has no granular deep-link, so it opens the app page.
• :exact_alarm — the "Alarms & reminders" special-access screen (Android 12+). iOS opens the app page.

iOS exposes only the single app settings page, so target is honored on Android and falls back to the app page on iOS. Fire-and-forget: a valid target returns :ok immediately (an unavailable screen is a no-op, not a raise); an unknown target returns {:error, :invalid} without touching the NIF.

@spec open_url(String.t()) :: :ok

Hands a URL to the OS to open in the default browser/handler.

Fire-and-forget. Returns :ok immediately; failures (malformed URL, no registered handler) are logged but not raised.

@spec orientation() :: orientation()

Current interface orientation — :portrait | :portrait_upside_down | :landscape_left | :landscape_right, or :unknown if it can't be determined.

@spec os_version() :: String.t()

OS version string (e.g. "17.4").

@spec start_link(keyword()) :: GenServer.on_start()

Start the dispatcher. Called from Mob.Application (or the app supervision tree). After start, the registered NIF dispatcher pid is this GenServer.

@spec subscribe(category() | [category()] | :all) :: :ok

Subscribe the calling process to device events.

Accepts a single category atom, a list of categories, or :all. Default is [:app, :display, :audio, :appearance, :memory].

Mob.Device.subscribe()
Mob.Device.subscribe(:thermal)
Mob.Device.subscribe([:app, :power, :thermal])
Mob.Device.subscribe(:all)

@spec thermal_state() :: :nominal | :fair | :serious | :critical

Current thermal state — :nominal | :fair | :serious | :critical.

@spec unlock_orientation() :: :ok

Release an orientation lock; the app follows the sensor again.

@spec unsubscribe() :: :ok

Unsubscribe the calling process from all categories.