DataStore¶

classDataStore

Persisted location record management — query, upload, and destroy stored locations.

Access via BGGeo.instance.store.

Members¶

all¶

suspend fun all(limit: Int = 0, offset: Int = 0, page: Int = 0, order: Int = 0): List<Map<String, Any>>

Retrieve LocationEvent records stored in the SDK's SQLite database.

Provide an optional LocationQuery to page through a large table, constraining results by limit, starting offset (or page), and sort order. Without a query, every record is returned in a single call — which can exhaust memory on a table of several thousand records, so prefer paging for large datasets. Size your paging with BGGeo.getCount.

// Within a coroutine scope
val bgGeo = BGGeo.instance

// All records
val locations = bgGeo.store.all()

// One page of 500, newest first
val page = bgGeo.store.all(limit = 500, page = 0, order = DataStore.ORDER_DESC)

count¶

val count: Int

Retrieve the count of all locations currently stored in the SDK's SQLite database.

val bgGeo = BGGeo.instance

val count = bgGeo.store.count

destroy¶

fun destroy(uuid: String)

Remove a single location by LocationEvent.uuid.

// Within a coroutine scope
val bgGeo = BGGeo.instance
val uuid = "some-location-uuid"
bgGeo.store.destroy(uuid)

destroyAll¶

fun destroyAll()

Remove all records from the SDK's SQLite database.

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.store.destroyAll()

insert¶

suspend fun insert(params: Map<String, Any>): String

Manually insert a location record into the SDK's SQLite database.

The record is stored as given — the SDK does not overwrite its timestamp, activity, is_moving, odometer, battery, or other fields with current device state. This is intended for importing history or externally-sourced fixes the SDK did not record itself. Only coords (latitude and longitude) is required; a missing or unparseable timestamp defaults to the current time. Resolves with the uuid of the inserted record — the SDK generates one when the caller does not supply a uuid.

Note

insertLocation deliberately bypasses PersistenceConfig.persistMode — an explicit insert always writes to the database, regardless of the configured persistence mode. For recording the device's own position on demand, prefer getCurrentPosition.

// Within a coroutine scope
val bgGeo = BGGeo.instance
val uuid = bgGeo.store.insert(mapOf(
  "timestamp" to "2024-01-15T10:30:00.000Z",
  "coords" to mapOf("latitude" to 45.5152, "longitude" to -73.6104),
  "extras" to mapOf("source" to "import")
))
Log.d(TAG, "[insertLocation] inserted record: $uuid")

sync¶

suspend fun sync(): List<Map<String, Any>>

Manually upload all queued locations to HttpConfig.url.

Initiates a POST of all records in the SQLite database to your configured HttpConfig.url. Records that receive a 200 OK response are deleted from the database. If HttpConfig.batchSync is true, all locations are sent in a single request; otherwise one request is made per location. If no HTTP service is configured, all records are deleted from the database.

See also - HTTP Guide

// Within a coroutine scope
val bgGeo = BGGeo.instance

try {
    val records = bgGeo.store.sync()
    Log.d(TAG, "[sync] success: $records")
} catch (e: Exception) {
    Log.d(TAG, "[sync] FAILURE: $e")
}