Skip to main content

spectranext.h

spectranext.h (included in the SDK) exposes the Z80 interface to Spectranext services: controller status, Wi-Fi scan/connect/disconnect, DNS, and engine calls (e.g. JSONPath). Everything routes through the single SPECTRANEXT ($3EF0) jump-table entry, selected by register A on entry.

spectranext.h is linked by libspectranet

Functions declared here are not linked separately as are provided as part of libspectranet library.

Error convention (assembly): carry set = error; carry clear = success.

Functions​

C calling convention: __z88dk_callee (callee cleans stack). spectranext_detect is __FASTCALL__.

spectranext_detect​

Returns whether the cartridge is Spectranext (see Detection):

ReturnMeaning
1Spectranext
0Classic Spectranet
-1No compatible interface
int result = spectranext_detect();
if (result == 1) {
    // Spectranext present
}

spectranext_get_controller_status​

int8_t spectranext_get_controller_status(int8_t *wifi_connection_out, uint32_t *ipv4_out)

Fills Wi-Fi connection state and IPv4 (host byte order).

ReturnMeaning
< 0ROM/port failure.
≥ 0Controller status (compare with WIFI_CONTROLLER_STATUS_*).

On success, *wifi_connection_out uses WIFI_CONNECT_*; *ipv4_out is the IPv4 address in host order.

uint32_t ipv4;
int8_t wifi_state;
int8_t status = spectranext_get_controller_status(&wifi_state, &ipv4);
if (status >= 0) {
    // wifi_state: WIFI_CONNECT_*
    // ipv4: address in host order
}

spectranext_wifi_scan_access_points​

int8_t spectranext_wifi_scan_access_points(void)
ReturnMeaning
< 0Failure.
≥ 0Number of networks found.
int8_t count = spectranext_wifi_scan_access_points();
if (count < 0) {
    // error
} else {
    // count networks available via spectranext_wifi_get_access_point()
}

spectranext_wifi_get_access_point​

int8_t spectranext_wifi_get_access_point(uint8_t ap, char *result_name)

Copies the NUL-terminated SSID for index ap (0-based) into result_name (buffer must hold up to 64 bytes).

ReturnMeaning
0Success.
-1Failure.
char ssid[64];
int8_t r = spectranext_wifi_get_access_point(0, ssid);
if (r == 0) {
    // ssid[] contains NUL-terminated network name
}

spectranext_wifi_connect_access_point​

int8_t spectranext_wifi_connect_access_point(const char *ssid, const char *password)
ReturnMeaning
0Success.
-1Failure.
int8_t r = spectranext_wifi_connect_access_point("MyNetwork", "s3cr3t");
if (r < 0) {
    // connection failed
}

spectranext_wifi_disconnect​

int8_t spectranext_wifi_disconnect(void)
ReturnMeaning
0Success.
-1Failure.
int8_t r = spectranext_wifi_disconnect();

spectranext_gethostbyname​

int8_t spectranext_gethostbyname(const char *hostname, uint32_t *result_ipv4)

Resolves hostname to an IPv4 address; *result_ipv4 is host byte order.

ReturnMeaning
0Success.
-1Failure (ROM/port or lookup error).
uint32_t ipv4;
int8_t r = spectranext_gethostbyname("example.com", &ipv4);
if (r == 0) {
    // ipv4 contains resolved address in host byte order
}

spectranext_enginecall​

int8_t spectranext_enginecall(const char *input, const char *output, const char *operation)

Runs a named engine call with argv-style arguments in operation (space-separated; see below). Used for heavier work such as JSONPath queries over a file.

Input file (input) — must include the mount index as a prefix: N:path where N is a single digit 0…3 selecting mount slot 0…3, and path is the path on that mount (e.g. 1:data/app.json).

Output file (output) — path on the RAM XFS volume only (no N: prefix); the result is written there.

Operation (operation) — first token is the engine name (e.g. jsonpath; the legacy name json is also accepted); further tokens are engine-specific. Example:

spectranext_enginecall("1:example.json", "example.bin", "jsonpath $[*].id $[*].name");
ReturnMeaning
0Success.
< 0Failure: negative int8_t error code from the engine (e.g. -1 unknown engine, -2 I/O, -3 JSON parse, -4 JSONPath, -5 non-scalar match, -6 bad argv).
int8_t r = spectranext_enginecall("0:config.json", "out.bin", "jsonpath $.name");

Linking (libspectranet vs libspectranet_np)​

  • libspectranet.lib — Paged build: use when your program already follows the usual Spectranet paging model (see memory).
  • libspectranet_np.lib — No-page stubs: often paired with an explicit pagein() at startup when your code expects Spectranet ROM to be mapped before calling these helpers.

Exact link lines and pragma redirects match your other Spectranet projects (e.g. libterm, ndos). The SDK copies spectranext.h into sdk/include/.

See also​