1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
/* ballistics-engine JSON command bridge — C ABI.
*
* One request/response exchange per call. The request is a UTF-8 JSON envelope:
*
* { "api_version": 1, "command": "meta.capabilities" }
* { "api_version": 1, "command": "solve", "request": { ...solve-json v1... } }
*
* The response is always a UTF-8 JSON envelope. On success:
*
* { "ok": true, "api_version": 1, "engine_version": "...",
* "command": "...", "result": { ... } }
*
* On ANY failure (invalid UTF-8, malformed JSON, unknown command, command
* failure, internal error) the failure is reported IN-BAND:
*
* { "ok": false, "api_version": 1, "engine_version": "...",
* "error": { "code": "...", "message": "...", "details": { ... } } }
*
* Branch on "ok" and "error"."code" rather than on which fields are present:
* a request refused before it reaches the bridge — one whose bytes are not
* UTF-8, or a NULL pointer — is answered by this ABI layer with the minimal
* shape, "ok"/"api_version"/"error", and carries no "engine_version".
*
* "details" appears only when "code" is "command_failed", and not always then.
* Its shape depends on the command:
*
* - "solve" and "atmosphere.density_altitude": the command's whole solve-json
* error envelope, so the code to branch on is error.details.error.code:
*
* "details": { "schema_version": 1, "status": "error",
* "error": { "code": "invalid_value", "message": "...",
* "path": "$.atmosphere.latitude_rad",
* "line": null, "column": null } }
*
* "path" is a string, or JSON null when no one field is at fault (as with
* "solve_failed"). "line" and "column" are null: malformed JSON fails the
* envelope itself first, as "invalid_json". The outer "message" is
* "solve request rejected" when the solve-json decoder refused the
* document, "solve failed" when the solve service refused or could not
* finish it, and "atmosphere.density_altitude request rejected" for every
* refusal of that command.
* - "reticle.describe", "reticle.hold", "reticle.holds", "reticle.import",
* "true.dsf", "true.plan", "true.dial_plan" and "profile.export_a7p": a
* flat object with a machine-readable "reason", plus the offending values
* when the error has any.
* - Every other command: no "details"; the reason is in "message" alone.
*
* Messages are text for a person; branch on codes. Per command, with a Kotlin
* unwrap: docs/ANDROID_JNI_BRIDGE.md, "Reading a failure".
*
* Contract:
* - The calls NEVER return NULL and NEVER throw/abort; check "ok" in the JSON.
* - The caller owns the input buffer; the engine does not retain it.
* - Every returned pointer must be released exactly once with
* ballistics_bridge_free(). Freeing NULL is a no-op.
* - Calls are thread-safe and independent; there is no shared mutable state.
* - Requests larger than 1 MiB are rejected with code "resource_limit".
* - Feature-detect with the "meta.capabilities" command instead of assuming a
* command list; builds differ (e.g. "pdf", "profile-import").
*
* ANDROID / JNI: call ballistics_bridge_call_n with the bytes of a Kotlin
* String.toByteArray(Charsets.UTF_8), and return the response as a jbyteArray.
* JNI's own string conversions — GetStringUTFChars AND GetStringUTFRegion —
* produce MODIFIED UTF-8, which this ABI refuses as invalid UTF-8 the first
* time a user types a character above U+FFFF, and NewStringUTF expects modified
* UTF-8 on the way back. Worked Kotlin + C example, and why:
* docs/ANDROID_JNI_BRIDGE.md.
*/
extern "C" __cplusplus
}
/* BALLISTICS_BRIDGE_H */