# stun

<a id="stun"></a>

# stun

STUN messages, attributes, and transaction helpers defined by RFC 5389.

## Classes

| Name | Description |
|------|-------------|
| [`AddressAttribute`](https://auscaster.com/icey/docs/api-reference/icy-stun-AddressAttribute.md#addressattribute) | Implements a STUN/TURN attribute that contains a socket address. Handles XOR encoding/decoding for address and port as required by RFC 5389 section 15.2. |
| [`Attribute`](https://auscaster.com/icey/docs/api-reference/icy-stun-Attribute.md#attribute) | The virtual base class for all STUN/TURN attributes. |
| [`ErrorCode`](https://auscaster.com/icey/docs/api-reference/icy-stun-ErrorCode.md#errorcode-1) | Implements the STUN ERROR-CODE attribute (RFC 5389 section 15.6). Encodes a 3-digit error code as a class (hundreds digit) and number (tens + units digits), plus an optional UTF-8 reason phrase. |
| [`FlagAttribute`](https://auscaster.com/icey/docs/api-reference/icy-stun-FlagAttribute.md#flagattribute) | Implements a zero-length STUN/TURN flag attribute (presence implies the flag is set). |
| [`Message`](https://auscaster.com/icey/docs/api-reference/icy-stun-Message.md#message-6) | STUN/TURN protocol message with method, class, transaction ID, and attributes. |
| [`MessageIntegrity`](https://auscaster.com/icey/docs/api-reference/icy-stun-MessageIntegrity.md#messageintegrity) | Implements the STUN MESSAGE-INTEGRITY attribute (RFC 5389 section 15.4). On write, computes an HMAC-SHA1 over the message bytes preceding this attribute when a key is set. On read, captures the raw HMAC bytes and the input bytes needed to verify them later via [verifyHmac()](https://auscaster.com/icey/docs/api-reference/icy-stun-MessageIntegrity.md#verifyhmac). |
| [`StringAttribute`](https://auscaster.com/icey/docs/api-reference/icy-stun-StringAttribute.md#stringattribute) | Implements a STUN/TURN attribute that holds an arbitrary byte string. Used for Username, Password, Realm, Nonce, Software, Data, and similar attributes. |
| [`Transaction`](https://auscaster.com/icey/docs/api-reference/icy-stun-Transaction.md#transaction-3) | STUN request/response transaction with timeout and retry logic. Extends the generic [net::Transaction](https://auscaster.com/icey/docs/api-reference/icy-net-Transaction.md#transaction) with STUN-specific transaction ID matching and response class inference (Success, [Error](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error), or Indication). |
| [`UInt16ListAttribute`](https://auscaster.com/icey/docs/api-reference/icy-stun-UInt16ListAttribute.md#uint16listattribute) | Implements a STUN/TURN attribute that holds a list of attribute type codes. Used by the UNKNOWN-ATTRIBUTES attribute (RFC 5389 section 15.9). |
| [`UInt32Attribute`](https://auscaster.com/icey/docs/api-reference/icy-stun-UInt32Attribute.md#uint32attribute) | Implements a STUN/TURN attribute that holds a 32-bit integer. |
| [`UInt64Attribute`](https://auscaster.com/icey/docs/api-reference/icy-stun-UInt64Attribute.md#uint64attribute) | Implements a STUN/TURN attribute that holds a 64-bit integer. |
| [`UInt8Attribute`](https://auscaster.com/icey/docs/api-reference/icy-stun-UInt8Attribute.md#uint8attribute) | Implements a STUN/TURN attribute that holds an 8-bit integer. |

## Enumerations

| Name | Description |
|------|-------------|
| [`AddressFamily`](#addressfamily)  | STUN address types as defined in RFC 5389. NB: Undefined is not part of the STUN spec. |

---

<a id="addressfamily"></a>

### AddressFamily

```cpp
enum AddressFamily
```

[Defined in src/stun/include/icy/stun/stun.h:47](https://github.com/auscaster/icey/blob/main/src/stun/include/icy/stun/stun.h#L47)

STUN address types as defined in RFC 5389. NB: Undefined is not part of the STUN spec.

| Value | Description |
|-------|-------------|
| `Undefined` | Not a valid STUN address family; used as a sentinel. |
| `IPv4` | IPv4 transport address. |
| `IPv6` | IPv6 transport address. |
## Typedefs

| Return | Name | Description |
|--------|------|-------------|
| `std::string` | [`TransactionID`](#transactionid-1)  | Fixed-width 12-byte STUN transaction identifier stored as raw bytes. |

---

<a id="transactionid-1"></a>

### TransactionID

```cpp
using TransactionID = std::string
```

[Defined in src/stun/include/icy/stun/message.h:27](https://github.com/auscaster/icey/blob/main/src/stun/include/icy/stun/message.h#L27)

Fixed-width 12-byte STUN transaction identifier stored as raw bytes.

## Functions

| Return | Name | Description |
|--------|------|-------------|
| `constexpr bool` | [`isValidMethod`](#isvalidmethod) `constexpr` | Returns true if `methodType` corresponds to a recognised STUN/TURN method. Used during parsing to reject malformed packets. |

---

<a id="isvalidmethod"></a>

### isValidMethod

`constexpr`

```cpp
constexpr constexpr bool isValidMethod(uint16_t methodType)
```

[Defined in src/stun/include/icy/stun/message.h:224](https://github.com/auscaster/icey/blob/main/src/stun/include/icy/stun/message.h#L224)

Returns true if `methodType` corresponds to a recognised STUN/TURN method. Used during parsing to reject malformed packets. 
#### Returns
true if the method is one of the defined MethodType values.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `methodType` | `uint16_t` | Raw method bits extracted from the message type field. |

## Variables

| Return | Name | Description |
|--------|------|-------------|
| `constexpr int` | [`kAttributeHeaderSize`](#kattributeheadersize) `constexpr` | Bytes in a STUN attribute header. |
| `constexpr int` | [`kMessageHeaderSize`](#kmessageheadersize) `constexpr` | Bytes in the fixed STUN message header. |
| `constexpr int` | [`kTransactionIdOffset`](#ktransactionidoffset) `constexpr` | Byte offset of the transaction ID inside the message header. |
| `constexpr int` | [`kTransactionIdLength`](#ktransactionidlength) `constexpr` | Length in bytes of a STUN transaction ID. |
| `constexpr uint32_t` | [`kMagicCookie`](#kmagiccookie) `constexpr` | RFC 5389 magic cookie used by modern STUN/TURN messages. |
| `constexpr int` | [`kMagicCookieLength`](#kmagiccookielength) `constexpr` | Length in bytes of the magic cookie field. |

---

<a id="kattributeheadersize"></a>

### kAttributeHeaderSize

`constexpr`

```cpp
constexpr int kAttributeHeaderSize = 4
```

[Defined in src/stun/include/icy/stun/stun.h:37](https://github.com/auscaster/icey/blob/main/src/stun/include/icy/stun/stun.h#L37)

Bytes in a STUN attribute header.

---

<a id="kmessageheadersize"></a>

### kMessageHeaderSize

`constexpr`

```cpp
constexpr int kMessageHeaderSize = 20
```

[Defined in src/stun/include/icy/stun/stun.h:38](https://github.com/auscaster/icey/blob/main/src/stun/include/icy/stun/stun.h#L38)

Bytes in the fixed STUN message header.

---

<a id="ktransactionidoffset"></a>

### kTransactionIdOffset

`constexpr`

```cpp
constexpr int kTransactionIdOffset = 8
```

[Defined in src/stun/include/icy/stun/stun.h:39](https://github.com/auscaster/icey/blob/main/src/stun/include/icy/stun/stun.h#L39)

Byte offset of the transaction ID inside the message header.

---

<a id="ktransactionidlength"></a>

### kTransactionIdLength

`constexpr`

```cpp
constexpr int kTransactionIdLength = 12
```

[Defined in src/stun/include/icy/stun/stun.h:40](https://github.com/auscaster/icey/blob/main/src/stun/include/icy/stun/stun.h#L40)

Length in bytes of a STUN transaction ID.

---

<a id="kmagiccookie"></a>

### kMagicCookie

`constexpr`

```cpp
constexpr uint32_t kMagicCookie = 0x2112A442
```

[Defined in src/stun/include/icy/stun/stun.h:41](https://github.com/auscaster/icey/blob/main/src/stun/include/icy/stun/stun.h#L41)

RFC 5389 magic cookie used by modern STUN/TURN messages.

---

<a id="kmagiccookielength"></a>

### kMagicCookieLength

`constexpr`

```cpp
constexpr int kMagicCookieLength = sizeof(kMagicCookie)
```

[Defined in src/stun/include/icy/stun/stun.h:42](https://github.com/auscaster/icey/blob/main/src/stun/include/icy/stun/stun.h#L42)

Length in bytes of the magic cookie field.