isolenui/platform/net_fetch.h is the engine's one way to get bytes from a URL. A get runs on a thread of its own and never blocks a frame. It is HTTPS only unless you ask otherwise, capped at 32 MB and 30 seconds by default, and it can wake an idle app when the bytes land. It uses NSURLSession on macOS and WinHTTP on Windows.
A get, start to finish
net_opts_of() gives the defaults. Change what you need and pass it to net_get(url, &opts), or pass null for the defaults.
net_poll(f) is null while the get is in flight. Once it lands it returns the net_result, which stays the same until the drop. Poll it from your view, typically once a frame while it is open.
On success net_take(f, &n) hands you the bytes. They are yours to free.
net_drop(f) always ends it, landed or not. A get still in flight is cancelled, and no wake runs after the drop.
feed.cpp
#include"isolenui/app/app.h"#include"isolenui/platform/net_fetch.h"#include"isolenui/ui/ui.h"#include"isolenui/kit/kit.h"#include<stdio.h>#include<stdlib.h>struct feed {
net_fetch* get;
uint8_t* bytes;
size_t size;
char why[96];
};
// runs on the fetch thread, so it only asks the app for a framestaticvoid feed_wake(void* user)
{
isolen_wake(static_cast<isolen_app*>(user));
}
staticvoid feed_start(isolen_app* a, feed* f)
{
net_opts o = net_opts_of();
o.max_bytes = 4ull << 20;
o.timeout_ms = 10000u;
o.wake = feed_wake;
o.user = a;
f->get = net_get("https://example.com/schedule.json", &o);
}
// polled from the view, the result is stable until the dropstaticvoid feed_poll(feed* f)
{
const net_result* r = net_poll(f->get);
if (!r) {
return;
}
if (r->error == net_ok) {
f->bytes = net_take(f->get, &f->size);
} else {
snprintf(f->why, sizeof(f->why), "%s", r->why);
}
net_drop(f->get);
f->get = nullptr;
}
staticvoid feed_view(ui::ctx* u, feed* f)
{
if (f->get) {
feed_poll(f);
}
if (f->get) {
ui::spinner(u, 20.0f);
} elseif (f->bytes) {
ui::textf(u, ui::caption(u), "%zu bytes", f->size);
} else {
ui::text(u, f->why, ui::caption(u));
}
}
// a drop cancels a get still in flight and no wake runs after itstaticvoid feed_close(feed* f)
{
net_drop(f->get);
free(f->bytes);
*f = {};
}
Options
net_opts field
Meaning
max_bytes
The most the body may be. Zero takes 32 MB. A Content-Length over it fails before anything downloads, and a body that grows past it stops there.
timeout_ms
The whole get, from start to the last byte. Zero takes 30 seconds.
allow_http
Off by default, so plain http:// URLs and redirects from HTTPS to HTTP are refused. Set it to allow both.
wake, user
Called once with user when the get lands. It runs on the fetch thread, so keep it to isolen_wake or an atomic flag and read the result on your own thread.
The result
net_result field
Meaning
error
A net_error, net_ok on success.
status
The HTTP status, or 0 when no response came.
bytes, size
The body on success. After net_take the bytes are gone from the result and the size stays.
type
The Content-Type the server sent, empty when it sent none.
why
A few words on what went wrong, empty on success, such as http 404 or only https is allowed.
seconds
How long the get took.
Errors
net_error
net_error_text
When
net_ok
ok
The body arrived with a 2xx status.
net_bad_url
bad url
No URL, one longer than 2047 bytes, one with a space, or one that is not HTTPS or HTTP.
net_insecure
not https
A plain HTTP URL or a redirect off HTTPS without allow_http.
net_offline
network down
No connection, the host was not found or the connection dropped.
net_timeout
timed out
The get ran past its timeout.
net_too_big
too big
The body is or grew over max_bytes.
net_http
http error
The server answered with a status outside 200 to 299.
net_tls
tls failed
The secure connection or its certificate failed.
net_cancelled
cancelled
It was dropped while in flight.
net_no_memory
out of memory
The body could not be held.
net_failed
failed
Anything else. why carries the system's own words.
A URL refused before any request, bad or not HTTPS, lands at once: net_get returns a fetch that has already landed with its error, and its wake runs inside that call on your thread. net_get returns null only when it has no memory.
On each platform
macOS
Windows
Transport
NSURLSession, an ephemeral session per get with no disk or memory cache
WinHTTP on a thread per get, with the system's automatic proxy
Timeouts
The whole get is bounded by timeout_ms, and a stall between bytes by it or 15 seconds, whichever is less
Every blocking call is bounded by timeout_ms or 15 seconds, whichever is less, and the whole get is checked between reads
Redirects
Followed, except off HTTPS without allow_http
Followed, except off HTTPS without allow_http, which comes back as the redirect status
User agent
isolen/1.0
In the log
Line
When
net get URL, cap N mb, timeout N ms
A get starts.
net got URL, N bytes of TYPE status N in N ms
It landed with the body.
net failed URL, WHY, status N after N ms
A warning, it landed with an error.
net cancelled URL after N ms
It was dropped in flight.
The kit plays a GIF straight from a URL on top of this, with its own cache and a spinner while it loads. See GIF from a URL.