> For the complete documentation index, see [llms.txt](https://xrho.gitbook.io/rho/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xrho.gitbook.io/rho/gateways/api.md).

# API Reference

## Class: `Gateway`

**Header:** `#include <Lines/Gateway.hpp>`

### Construction

```cpp
Gateway gw;
// keypair is auto-generated
// router is empty
// server is unhooked
```

### Configuration

| Property          | Type                | Default        | Description                         |
| ----------------- | ------------------- | -------------- | ----------------------------------- |
| `address`         | `NumericalAddress`  | `{}`           | This gateway's address in the tree  |
| `keypair`         | `Security::KeyPair` | Auto-generated | X25519 keypair for encryption       |
| `unauthed`        | `bool`              | `false`        | Enable unauthed forwarding for IoT  |
| `unauthedMarker`  | `String`            | `""`           | Marker for unauthed identification  |
| `unauthedAddress` | `NumericalAddress`  | `{}`           | Address prefix for unauthed devices |
| `unauthedTimeout` | `u32`               | `30000`        | Unauthed session timeout (ms)       |

### Subcomponents

| Property        | Type                   | Description                          |
| --------------- | ---------------------- | ------------------------------------ |
| `router`        | `Router`               | The routing trie                     |
| `server`        | `Server`               | The connection acceptor              |
| `clients`       | `Array<Client*>`       | Outbound connections to peers/parent |
| `sessions`      | `Array<TunnelSession>` | Active client sessions               |
| `activeReaches` | `Array<ActiveReach>`   | In-progress name resolutions         |

### Station Management

```cpp
// Hook a station (listen for incoming connections)
void hookStation(Station& station);

// Bind a port (create a child address)
void bindPort(u32 port);
```

### Reach (Name Resolution)

```cpp
// Resolve a name (returns cached result or starts async resolution)
NumericalAddress reach(const String& address);

// Add a default Reach server
void addDefaultReachServer(const NumericalAddress& addr, const String& publicKey);
```

### Callbacks

```cpp
// New client connected
gw.onUpgrade([](Packet& pkt, Tunnel& client, Cart& c) -> RoutingEntry* {
    // Return a routing entry to track the session
    // Return nullptr to reject the connection
});

// Data from a client
gw.onReady([](Packet& pkt, Tunnel& client, Cart& c) {
    // Handle application data
});

// Client probed us
gw.onAnnounce([](Cart& c) {
    // Inspect or modify the announce response
});

// Name resolution completed
gw.onReachCompleted([](const String& name, const NumericalAddress& addr) {
    // Use the resolved address
});
```

### Lifecycle

```cpp
// Tick all components (Server, Clients, Reaches, session cleanup)
void update();

// Clean up all resources
void destroy();
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://xrho.gitbook.io/rho/gateways/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.