# 画面設計書 26-DNS

## 概要

本ドキュメントは、libuvドキュメントサイトにおけるDNSユーティリティ（`uv_getaddrinfo_t` / `uv_getnameinfo_t`）APIリファレンスページの画面設計書である。非同期DNS解決機能のAPI定義を記載する。

### 本画面の処理概要

本ページは、libuvにおける非同期DNS解決機能のAPIリファレンスを提供する。標準のgetaddrinfo(3)とgetnameinfo(3)の非同期版を提供し、DNSの正引き（ホスト名からIPアドレス）と逆引き（IPアドレスからホスト名）を非同期に実行できる。

**業務上の目的・背景**：DNS解決はネットワークプログラミングにおいて必須の機能であるが、標準のgetaddrinfo(3)はブロッキング関数であり、イベントループをブロックする。libuvはスレッドプールを活用した非同期DNS解決を提供し、イベントドリブンプログラミングとの統合を可能にする。

**画面へのアクセス方法**：トップページからAPIドキュメント一覧（api.rst）を経由し、DNSリンクをクリックして本ページに遷移する。

**主要な操作・処理内容**：
1. 非同期アドレス解決（`uv_getaddrinfo`）のAPI仕様確認
2. アドレス情報解放（`uv_freeaddrinfo`）のAPI仕様確認
3. 非同期名前逆引き（`uv_getnameinfo`）のAPI仕様確認
4. コールバック仕様と同期モード（cb=NULL）の確認

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：リクエスト基底（request.rst）へのseealsoリンク

**権限による表示制御**：なし（公開ドキュメント）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 121 | アドレス解決 | 主機能 | uv_getaddrinfo()による非同期DNS正引きのAPI定義 |
| 122 | アドレス情報解放 | 主機能 | uv_freeaddrinfo()による解決結果メモリ解放のAPI定義 |
| 123 | 名前逆引き | 主機能 | uv_getnameinfo()による非同期DNS逆引きのAPI定義 |

## 画面種別

APIリファレンス（詳細表示）

## URL/ルーティング

`/docs/src/dns.rst` (Sphinx生成後: `/dns.html`)

## 入出力項目

| API関数 | パラメータ名 | 型 | 入出力 | 説明 |
|---------|-------------|-----|--------|------|
| uv_getaddrinfo | loop | uv_loop_t* | 入力 | イベントループ |
| uv_getaddrinfo | req | uv_getaddrinfo_t* | 入出力 | getaddrinfoリクエスト |
| uv_getaddrinfo | getaddrinfo_cb | uv_getaddrinfo_cb | 入力 | 完了コールバック（NULLで同期） |
| uv_getaddrinfo | node | const char* | 入力 | ホスト名（NULLも可だがserviceと同時にNULLは不可） |
| uv_getaddrinfo | service | const char* | 入力 | サービス名（NULLも可） |
| uv_getaddrinfo | hints | const struct addrinfo* | 入力 | アドレスヒント（NULLも可） |
| uv_getnameinfo | loop | uv_loop_t* | 入力 | イベントループ |
| uv_getnameinfo | req | uv_getnameinfo_t* | 入出力 | getnameinfo リクエスト |
| uv_getnameinfo | getnameinfo_cb | uv_getnameinfo_cb | 入力 | 完了コールバック（NULLで同期） |
| uv_getnameinfo | addr | const struct sockaddr* | 入力 | 逆引き対象アドレス |
| uv_getnameinfo | flags | int | 入力 | getnameinfo(3)のフラグ |

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | DNS utility functions | ページタイトル |
| 概要説明 | libuv provides asynchronous variants... | 非同期DNS解決の概要 |
| Data types | uv_getaddrinfo_t, uv_getnameinfo_t, コールバック型 | データ型の定義 |
| Public members | loop, addrinfo, host, service | 公開メンバー |
| API | uv_getaddrinfo, uv_freeaddrinfo, uv_getnameinfo | DNS解決の全API |

## イベント仕様

### 1-DNS解決完了コールバック

`uv_getaddrinfo`のコールバック（`uv_getaddrinfo_cb`）が、DNS解決完了時に呼び出される。statusが0の場合resにstruct addrinfoリストが設定される。status < 0の場合はresがNULL。結果は`uv_freeaddrinfo`で解放する必要がある。

### 2-名前逆引き完了コールバック

`uv_getnameinfo`のコールバック（`uv_getnameinfo_cb`）が、逆引き完了時に呼び出される。hostnameとserviceが結果文字列として渡される。

### 3-seealsoリンク遷移

ページ末尾の「See also」セクションから `uv_req_t` の基底APIリファレンスページへ遷移する。

## データベース更新仕様

### 操作別データベース影響一覧

該当なし（本プロジェクトはCライブラリであり、データベースは使用しない）

## メッセージ仕様

| メッセージ種別 | 条件 | 内容 |
|--------------|------|------|
| versionchanged | v1.3.0 | コールバックにNULLを渡すと同期実行が可能になった |
| versionchanged | v1.3.0 | addrinfo, host, serviceフィールドがpublicに変更 |

## 例外処理

| エラーコード | 発生条件 | 説明 |
|-------------|---------|------|
| UV_ECANCELED | uv_cancel()でキャンセル時 | コールバックのstatusに設定される |
| UV_EAI_* | DNS解決失敗時 | getaddrinfo(3)由来のエラーコード |

## 備考

- nodeとserviceの両方をNULLにすることはできない
- コールバックにNULLを渡すと同期的に実行される（v1.3.0以降）
- uv_getaddrinfo_t.addrinfoフィールドはuv_freeaddrinfo()で解放が必要
- uv_getnameinfo_t.hostとserviceはリクエスト構造体内のchar配列に格納される
- 内部的にスレッドプールを使用して非同期処理を実現

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_getaddrinfo_t, uv_getnameinfo_t, コールバック型の定義 |

**読解のコツ**: uv_getaddrinfo_t.addrinfoはstruct addrinfo*で、標準ライブラリのstruct addrinfoと同じ構造体を使用する。

#### Step 2: プラットフォーム実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | getaddrinfo.c (Unix) | `src/unix/getaddrinfo.c` | Unix系でのgetaddrinfo/getnameinfo非同期実装 |
| 2-2 | getaddrinfo.c (Win) | `src/win/getaddrinfo.c` | Windows系でのgetaddrinfo非同期実装 |

**主要処理フロー**:
- `uv_getaddrinfo()`: スレッドプールにDNS解決ワークを投入
- ワーカースレッド上でgetaddrinfo(3)を呼び出し
- 完了時にイベントループスレッドでコールバックを実行

#### Step 3: スレッドプール連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | threadpool.c | `src/threadpool.c` | スレッドプールでのワーク実行 |

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

```
uv_getaddrinfo() [src/unix/getaddrinfo.c or src/win/getaddrinfo.c]
    |
    +-- [cb != NULL] uv__work_submit() [src/threadpool.c]
    |       |
    |       +-- uv__getaddrinfo_work() [スレッドプール上]
    |       |       +-- getaddrinfo(3)
    |       |
    |       +-- uv__getaddrinfo_done() [イベントループスレッド]
    |               +-- uv_getaddrinfo_cb() [ユーザーコールバック]
    |
    +-- [cb == NULL] 同期実行
            +-- getaddrinfo(3)

uv_freeaddrinfo()
    +-- freeaddrinfo(3)
```

### データフロー図

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

ホスト名/サービス名 --> uv_getaddrinfo() -------> struct addrinfo*
                              |                    (IPアドレスリスト)
                              v
                    スレッドプール
                    getaddrinfo(3)

IPアドレス ---------> uv_getnameinfo() -------> hostname, service
                              |                    (文字列)
                              v
                    スレッドプール
                    getnameinfo(3)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| dns.rst | `docs/src/dns.rst` | テンプレート | DNSページのSphinxソース |
| uv.h | `include/uv.h` | ソース | uv_getaddrinfo_t等の公開API定義 |
| getaddrinfo.c (Unix) | `src/unix/getaddrinfo.c` | ソース | Unix系DNS解決実装 |
| getaddrinfo.c (Win) | `src/win/getaddrinfo.c` | ソース | Windows系DNS解決実装 |
| threadpool.c | `src/threadpool.c` | ソース | スレッドプール実行基盤 |
| api.rst | `docs/src/api.rst` | テンプレート | API一覧ページ（遷移元） |
| request.rst | `docs/src/request.rst` | テンプレート | リクエスト基底ページ（参照先） |
