On this page

Fetching over the network

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

  1. net_opts_of() gives the defaults. Change what you need and pass it to net_get(url, &opts), or pass null for the defaults.
  2. 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.
  3. On success net_take(f, &n) hands you the bytes. They are yours to free.
  4. 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 frame
static void feed_wake(void* user)
{
    isolen_wake(static_cast<isolen_app*>(user));
}

static void 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 drop
static void 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;
}

static void feed_view(ui::ctx* u, feed* f)
{
    if (f->get) {
        feed_poll(f);
    }
    if (f->get) {
        ui::spinner(u, 20.0f);
    } else if (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 it
static void feed_close(feed* f)
{
    net_drop(f->get);
    free(f->bytes);
    *f = {};
}

Options

net_opts fieldMeaning
max_bytesThe 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_msThe whole get, from start to the last byte. Zero takes 30 seconds.
allow_httpOff by default, so plain http:// URLs and redirects from HTTPS to HTTP are refused. Set it to allow both.
wake, userCalled 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 fieldMeaning
errorA net_error, net_ok on success.
statusThe HTTP status, or 0 when no response came.
bytes, sizeThe body on success. After net_take the bytes are gone from the result and the size stays.
typeThe Content-Type the server sent, empty when it sent none.
whyA few words on what went wrong, empty on success, such as http 404 or only https is allowed.
secondsHow long the get took.

Errors

net_errornet_error_textWhen
net_okokThe body arrived with a 2xx status.
net_bad_urlbad urlNo URL, one longer than 2047 bytes, one with a space, or one that is not HTTPS or HTTP.
net_insecurenot httpsA plain HTTP URL or a redirect off HTTPS without allow_http.
net_offlinenetwork downNo connection, the host was not found or the connection dropped.
net_timeouttimed outThe get ran past its timeout.
net_too_bigtoo bigThe body is or grew over max_bytes.
net_httphttp errorThe server answered with a status outside 200 to 299.
net_tlstls failedThe secure connection or its certificate failed.
net_cancelledcancelledIt was dropped while in flight.
net_no_memoryout of memoryThe body could not be held.
net_failedfailedAnything 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

macOSWindows
TransportNSURLSession, an ephemeral session per get with no disk or memory cacheWinHTTP on a thread per get, with the system's automatic proxy
TimeoutsThe whole get is bounded by timeout_ms, and a stall between bytes by it or 15 seconds, whichever is lessEvery blocking call is bounded by timeout_ms or 15 seconds, whichever is less, and the whole get is checked between reads
RedirectsFollowed, except off HTTPS without allow_httpFollowed, except off HTTPS without allow_http, which comes back as the redirect status
User agentisolen/1.0

In the log

LineWhen
net get URL, cap N mb, timeout N msA get starts.
net got URL, N bytes of TYPE status N in N msIt landed with the body.
net failed URL, WHY, status N after N msA warning, it landed with an error.
net cancelled URL after N msIt 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.

Last updated 6 October 2026