Skip to content

Automation API (Android) ​

Other apps, such as sleep managers or automation tools, can start, stop and query the proxy through RAOfflineProxy's content provider:

content://com.raofflineproxy.config

Setup ​

Declare the control permission and make the provider visible to your app:

xml
<uses-permission android:name="com.raofflineproxy.permission.CONTROL_PROXY" />

<queries>
    <provider android:authorities="com.raofflineproxy.config" />
</queries>

status needs no permission. start and stop throw a SecurityException without it.

The user grants the permission, like camera or location access. Request it at runtime, which works whichever app was installed first:

kotlin
const val CONTROL_PROXY = "com.raofflineproxy.permission.CONTROL_PROXY"

if (checkSelfPermission(CONTROL_PROXY) != PackageManager.PERMISSION_GRANTED) {
    requestPermissions(arrayOf(CONTROL_PROXY), REQUEST_CODE)
}

Android asks "Allow ‹your app› to start and stop the RAOfflineProxy proxy?". If RAOfflineProxy isn't installed yet, the request is denied without a dialog, so ask again once it is. Check the permission before each call: the user can revoke it, and Android may revoke it from apps that go unused for months.

Apps that already hold the permission keep it when RAOfflineProxy updates.

Methods ​

All methods go through ContentResolver.call() and return a Bundle. start and stop block until the work is done, so call them off the main thread.

kotlin
val uri = Uri.parse("content://com.raofflineproxy.config")
val result = contentResolver.call(uri, "stop", null, null)
val code = result?.getString("result")
val status = result?.getString("status")
MethodDoesReturns
startPatches the enabled emulators and starts the proxyresult, status
stopStops the proxy and reverts the emulator patchesresult, status
statusNothingstatus

start and stop go through the same logic as the app: emulator patching, restart handling and cleanup work exactly as they do in the UI. They are idempotent, so calling start while the proxy is running or stop while it's stopped does nothing. Neither changes the Autostart RAOfflineProxy at startup setting.

Result codes ​

resultMeaning
okDone, or nothing to do
no_emulator_enabledNo emulator is enabled in RAOfflineProxy
port_unavailableAnother app uses the proxy port
patch_failedAn emulator config couldn't be patched, open RAOfflineProxy to fix it
foreground_service_not_allowedAndroid blocked starting the proxy from the background, see below

Starting from the background ​

Since Android 12, an app in the background may not start a foreground service. While RAOfflineProxy is in the background, start fails with foreground_service_not_allowed. Any emulator patches are rolled back and shouldBeRunning stays false. Setting RAOfflineProxy's battery usage to Unrestricted lifts this limit.

start returns ok once the service has been asked to start. running turns true once the proxy accepts connections. If Android refuses the service afterwards, which happens when RAOfflineProxy's battery usage is Restricted, the proxy stops again and shouldBeRunning turns false.

stop returns ok as soon as the proxy has been asked to stop. running turns false shortly after, once the service is gone.

Status ​

json
{
  "version": 2,
  "running": true,
  "shouldBeRunning": true,
  "online": true,
  "queue": { "count": 342, "state": "waiting", "nextWindowAt": 1759230000000 },
  "pendingAwards": { "count": 3, "state": "syncing", "error": null }
}
FieldMeaning
version2 since pendingAwards was added
runningThe proxy accepts connections
shouldBeRunningRAOfflineProxy intends the proxy to run. true while running is false means it's starting or about to restart
onlineRetroAchievements is reachable
queue.countGames waiting in the caching queue
queue.stateSee below
queue.nextWindowAtEpoch milliseconds of the next caching batch while waiting, otherwise null
pendingAwards.countAchievements unlocked offline that haven't been uploaded yet
pendingAwards.stateSee below
pendingAwards.errorWhy the upload failed while blocked, otherwise null
queue.stateMeaning
idleThe queue is empty
cachingGames are being cached right now
waitingWaiting for the next caching window. RAOfflineProxy wakes the device for it
blockedWon't progress without the user, e.g. the proxy is stopped or the login is invalid. Treat it like idle

Pending awards are uploaded automatically when the proxy starts and whenever RetroAchievements becomes reachable again. A failed upload isn't retried until the next time that happens.

pendingAwards.stateMeaning
idleNothing to upload
waitingAwards will upload once RetroAchievements is reachable
syncingAwards are being uploaded right now
blockedThe proxy is stopped, or the last upload failed and won't be retried until connectivity drops and returns. Treat it like idle
pendingAwards.errorMeaning
authThe login was rejected, log in again in RAOfflineProxy
chain_brokenThe pending awards failed their integrity check, open RAOfflineProxy
refresh_failedThe achievement data couldn't be refreshed from RetroAchievements
upload_failedSome awards couldn't be uploaded, e.g. a network or server error

Observing changes ​

RAOfflineProxy notifies the provider URI whenever the status changes, so you can register a ContentObserver instead of polling. Android delivers them about 10 seconds late while your app is in the background, and right away while it's active, for example while it runs a foreground service.

kotlin
contentResolver.registerContentObserver(uri, false, object : ContentObserver(handler) {
    override fun onChange(selfChange: Boolean) {
        val status = contentResolver.call(uri, "status", null, null)?.getString("status")
    }
})

Example: sleep manager ​

Before sleep:

  • queue.state is idle or blocked: call stop, start again on wake
  • queue.state is caching or waiting: leave the proxy running until the queue is done, or let the user decide

To sync achievements in a maintenance window, turn Wi-Fi on and keep it on until online is true and pendingAwards.state is idle or blocked.