# 機能設計書 58-ブロードキャスト設定

## 概要

本ドキュメントは、libuvにおけるUDPブロードキャスト設定機能（`uv_udp_set_broadcast()`）の設計仕様を記述する。UDPソケットのSO_BROADCASTオプションを有効化・無効化する。

### 本機能の処理概要

**業務上の目的・背景**：UDPブロードキャストは、ローカルネットワーク上の全ホストに一斉にデータを送信するための機能である。デフォルトではUDPソケットでのブロードキャスト送信は無効化されており、明示的にSO_BROADCASTオプションを設定する必要がある。ネットワークディスカバリやLAN内一斉通知などで使用される。

**機能の利用シーン**：
- ネットワーク上のデバイスディスカバリ（SSDP、NetBIOS等）
- LAN内のブロードキャストメッセージ送信
- DHCPクライアント実装
- ローカルネットワーク上の全ホストへの通知

**主要な処理内容**：
1. setsockopt()でSOL_SOCKETレベルのSO_BROADCASTオプションを設定
2. onパラメータで有効（非0）/無効（0）を切り替え

**関連システム・外部連携**：OSのソケットAPI（setsockopt）。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | UDP | 主機能 | uv_udp_set_broadcast()によるブロードキャスト有効・無効のAPI定義 |

## 機能種別

ソケットオプション設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | uv_udp_t* | Yes | UDPハンドル | ソケットFDが有効であること |
| on | int | Yes | ブロードキャストの有効(非0)/無効(0) | 特になし |

### 入力データソース

アプリケーションから直接指定されるブロードキャスト有効/無効フラグ。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 成功時は0、失敗時は負のエラーコード |

### 出力先

OSカーネルのソケットオプションが変更される。

## 処理フロー

### 処理シーケンス

```
1. setsockopt(fd, SOL_SOCKET, SO_BROADCAST, &on, sizeof(on))を呼び出し
2. 成功時は0を返却
3. 失敗時はUV__ERR(errno)を返却
```

### フローチャート

```mermaid
flowchart TD
    A[uv_udp_set_broadcast呼び出し] --> B[setsockopt SOL_SOCKET SO_BROADCAST]
    B -->|成功| C[0返却]
    B -->|失敗| D[UV__ERR errno返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-58-01 | プロトコル非依存 | SOL_SOCKETレベルで設定するためIPv4/IPv6に関係なく動作 | 常時 |
| BR-58-02 | デフォルト無効 | OSレベルでSO_BROADCASTはデフォルトで無効 | ソケット作成時 |

### 計算ロジック

特になし。

## データベース操作仕様

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV__ERR(errno) | OS APIエラー | setsockopt失敗（FD無効等） | ハンドルを正しく初期化する |

### リトライ仕様

リトライは不要。

## トランザクション仕様

該当なし。

## パフォーマンス要件

同期処理。setsockopt()の実行時間のみ。

## セキュリティ考慮事項

- ブロードキャストはLAN上の全ホストにデータを送信するため、機密データの送信には不適切
- ブロードキャストストームを引き起こさないよう、送信頻度に注意が必要

## 備考

- ブロードキャストはIPv4のみの概念であり、IPv6ではマルチキャストが使用される
- マルチキャスト関連オプション（No.56, No.57）と異なり、SO_BROADCASTはuv__setsockoptヘルパーを使用せず直接setsockoptを呼ぶ

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **L774行目**: uv_udp_set_broadcast()のAPI宣言 |
| 1-2 | udp.c (unix) | `src/unix/udp.c` | **L1132-1142行目**: uv_udp_set_broadcast()の実装。setsockopt(SOL_SOCKET, SO_BROADCAST)を直接呼び出す |

**主要処理フロー**:
1. **L1133-1137行目**: setsockopt(fd, SOL_SOCKET, SO_BROADCAST, &on, sizeof(on))
2. **L1138行目**: 失敗時はUV__ERR(errno)を返す
3. **L1141行目**: 成功時は0を返す

**読解のコツ**: この関数は非常にシンプルで、uv__setsockoptヘルパーを使用せずに直接setsockoptを呼んでいる。これはSO_BROADCASTがSOL_SOCKETレベルであり、IPv4/IPv6の区別が不要なためである。

### プログラム呼び出し階層図

```
uv_udp_set_broadcast(handle, on)
    └─ setsockopt(handle->io_watcher.fd, SOL_SOCKET, SO_BROADCAST, &on, sizeof(on))
```

### データフロー図

```
[入力]                     [処理]                          [出力]

on (int) ──────────▶ setsockopt() ──────▶ カーネルソケットオプション更新
handle                                         SO_BROADCAST = on
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | API宣言（L774） |
| udp.c (unix) | `src/unix/udp.c` | ソース | Unix系実装（L1132-1142） |
| udp.c (win) | `src/win/udp.c` | ソース | Windows版実装 |
