ax-networking-ref

Network.framework API Reference

Quick Patterns

API Evolution

Year	iOS	Key Features
2018	12	NWConnection, NWListener, NWBrowser, NWPathMonitor
2019	13	User-space networking (30% CPU reduction), TLS 1.3 default
2025	26	NetworkConnection (async/await), TLV, Coder protocol, Wi-Fi Aware

When to Use vs URLSession

• URLSession: HTTP, HTTPS, WebSocket, simple TCP/TLS streams
• Network.framework: UDP, custom protocols, low-level control, peer-to-peer, gaming, streaming

NetworkConnection API (iOS 26+)

// Create -- TLS() infers TCP/IP, no explicit start() needed
let conn = NetworkConnection(to: .hostPort(host: "example.com", port: 1029)) { TLS() }

// Send/Receive
try await conn.send(data)
let received = try await conn.receive(exactly: 98).content

// Receive variants
try await conn.receive(atLeast: 1, atMost: 1024).content
try await conn.receive(as: UInt32.self).content // Fixed-size type

// States (async sequence)
for await state in conn.states { /* .preparing, .ready, .waiting, .failed, .cancelled */ }

// Cancel
conn.cancel()

NWConnection API (iOS 12-25)

let conn = NWConnection(host: "example.com", port: 443, using: .tls)
conn.stateUpdateHandler = { [weak self] state in /* handle states */ }
conn.start(queue: .main)

// Send with pacing
conn.send(content: data, completion: .contentProcessed { [weak self] error in
    self?.sendNext() // Pace: send next only after stack consumed current
})

// Receive
conn.receive(minimumIncompleteLength: 1, maximumLength: 65536) { [weak self] data, ctx, isComplete, error in
    self?.receiveMore()
}

// Mobility
conn.viabilityUpdateHandler = { isViable in /* route valid? */ }
conn.betterPathUpdateHandler = { hasBetter in /* migrate? */ }
conn.cancel()

Decision Tree

Choose API:
+-- iOS 26+ target?
|   +-- Custom protocols/UDP --> NetworkConnection { TLS()/UDP() }
|   +-- Codable messages --> NetworkConnection { Coder(T.self, using: .json) { TLS() } }
|   +-- Message framing --> NetworkConnection { TLV { TLS() } }
|   +-- Accept connections --> NetworkListener { ... }.run { conn in }
|   +-- Peer discovery --> NetworkBrowser(for: .wifiAware(...)).run { }
|
+-- iOS 12+ target?
    +-- TCP/TLS --> NWConnection(host:port:using: .tls)
    +-- UDP --> NWConnection(host:port:using: .udp)
    +-- Accept connections --> NWListener(using:on:)
    +-- Bonjour discovery --> NWBrowser(for: .bonjour(...), using:)
    +-- Network monitoring --> NWPathMonitor()