# Network System

Source: `src/dusk/network/`, platform layers in
`src/dusk<platform>/network/`

## Overview

The network system provides a platform-agnostic API for detecting and
managing a network connection. Higher-level functionality (HTTP, sockets)
is not yet implemented in any platform. The system handles the
connection lifecycle -- connect, detect disconnect, disconnect -- and
reports the current IP address.

## Implementation status by platform

| Platform | Connection | IP info | HTTP/Requests | Notes |
|----------|-----------|---------|--------------|-------|
| **Linux** | Auto (OS) | IPv4 + IPv6 | Not implemented | `getifaddrs()` |
| **Knulli** | Auto (OS) | IPv4 + IPv6 | Not implemented | same as Linux |
| **PSP** | Manual dialog | IPv4 only | Not implemented | `sceUtilityNetconf`; SSL/HTTP modules commented out |
| **GameCube** | Manual DHCP | IPv4 only | Not implemented | `if_config()` stubbed; `net_init()` commented out |
| **Wii** | Manual DHCP | IPv4 only | Not implemented | blocking `if_config()` via System Menu Wi-Fi settings |

## Connection states

```c
typedef enum {
  NETWORK_STATE_DISCONNECTED,
  NETWORK_STATE_CONNECTING,
  NETWORK_STATE_CONNECTED,
  NETWORK_STATE_DISCONNECTING,
} networkstate_t;
```

## Global state

```c
extern network_t NETWORK;
// NETWORK.state         -- current connection state
// NETWORK.platform      -- platform-specific data
// NETWORK.onDisconnect  -- callback fired on unexpected disconnect
```

## Core API (`network.h`)

```c
errorret_t networkInit();
errorret_t networkUpdate();   // call each frame; detects dropped connections
errorret_t networkDispose();

bool_t networkIsConnected();

void networkRequestConnection(
  void (*onConnected)(void *user),
  void (*onFailed)(errorret_t error, void *user),
  void (*onDisconnect)(errorret_t error, void *user),
  void *user
);

void networkRequestDisconnection(
  void (*onComplete)(void *user),
  void *user
);
```

On platforms that manage their own connection (Linux, macOS, Windows),
`networkRequestConnection` immediately calls `onConnected` if a network
interface is up, or `onFailed` if not. No `networkPlatformRequestConnection`
macro is needed.

On platforms that require explicit connection (PSP, Wii), the platform
implements `networkPlatformRequestConnection` and
`networkPlatformRequestDisconnection`.

## Network info

```c
networkinfo_t networkGetInfo();
// Only valid when NETWORK.state == NETWORK_STATE_CONNECTED.
```

```c
typedef struct {
  networktype_t type;   // NETWORK_TYPE_IPV4 or (ifdef) NETWORK_TYPE_IPV6
  union {
    networkinfoipv4_t ipv4;  // uint8_t ip[4]
    networkinfoipv6_t ipv6;  // uint8_t ip[16] (requires DUSK_NETWORK_IPV6)
  };
} networkinfo_t;
```

IPv6 support requires the `DUSK_NETWORK_IPV6` compile-time define.

## Platform-specific notes

### Linux / Knulli

Fully functional for connection detection and IP querying. No explicit
connect/disconnect step needed -- the OS manages the interface. Uses
`getifaddrs()` to find the first non-loopback running interface.

### PSP

Connection is asynchronous and driven by a state machine in
`networkPSPUpdate()`. The PSP shows the built-in network configuration
dialog (`sceUtilityNetconfInitStart`) to let the user pick a Wi-Fi
access point.

HTTP/SSL modules (`psphttp`, `pspssl`) are loaded in commented-out code
-- the infrastructure for HTTP exists but is disabled.

### GameCube

`net_init()` is commented out. Networking on GameCube is non-functional
in the current build.

### Wii

Uses `if_config()` (DHCP via libogc) to connect using the Wi-Fi settings
stored in Wii System Menu. This call **blocks** the main thread. The
connection only works when `DUSK_WII` is defined; the GameCube path
always fails.

## Adding a new platform implementation

1. Create `src/dusk<platform>/network/network<platform>.h/.c`.
2. Implement the five required functions:
   `Init`, `Update`, `Dispose`, `IsConnected`, `GetInfo`.
3. Optionally implement `RequestConnection` and `RequestDisconnection`
   if the platform requires an explicit connection step.
4. Create `networkplatform.h` mapping each `networkPlatform*` macro to
   your functions, and defining `networkplatform_t`.