# 機能設計書 76-仮想端末状態制御

## 概要

uv_tty_set_vterm_state()/uv_tty_get_vterm_state()により仮想端末の状態を制御する機能の設計書である。主にWindows環境でのVirtual Terminal（VT）シーケンスサポート状態の取得・設定に使用される。

### 本機能の処理概要

uv_tty_set_vterm_state()は仮想端末の状態（VTシーケンス処理のサポート有無）を設定し、uv_tty_get_vterm_state()は現在の状態を取得する関数である。Unix環境ではset関数は何もせず（no-op）、get関数はUV_ENOTSUPを返す。Windows環境では、コンソールがVTシーケンスをネイティブに処理できるか（Windows 10新コンソール、ConEmu等）を制御する。

**業務上の目的・背景**：Windows環境ではレガシーコンソールとWindows 10以降の新コンソールでANSIエスケープシーケンスのサポートが異なる。libuvはこの違いを吸収するために、VT状態を明示的に制御するAPIを提供する。SUPPORTED状態ではOSにVT処理を委任し、UNSUPPORTED状態ではlibuv内部でVTシーケンスをパースする。

**機能の利用シーン**：
- Windows環境でのANSI色出力の制御
- コンソールのVTシーケンスサポート検出の上書き
- テスト環境でのVT状態の強制設定

**主要な処理内容**：
1. uv_tty_set_vterm_state(): VT状態をUV_TTY_SUPPORTEDまたはUV_TTY_UNSUPPORTEDに設定する
2. uv_tty_get_vterm_state(): 現在のVT状態を取得する

**関連システム・外部連携**：Windows Console API（ENABLE_VIRTUAL_TERMINAL_PROCESSING）。

**権限による制御**：特段の権限制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 20 | TTY | 主機能 | uv_tty_set_vterm_state()/uv_tty_get_vterm_state()のAPI定義 |

## 機能種別

設定取得処理 - 仮想端末状態の制御

## 入力仕様

### 入力パラメータ

#### uv_tty_set_vterm_state()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| state | uv_tty_vtermstate_t | Yes | 設定するVT状態 | UV_TTY_SUPPORTEDまたはUV_TTY_UNSUPPORTED |

#### uv_tty_get_vterm_state()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| state | uv_tty_vtermstate_t* | Yes | 状態の格納先 | NULLでないこと |

### 入力データソース

関数呼び出し時の引数。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| set: 戻り値 | void | 戻り値なし |
| get: 戻り値 | int | Unix: UV_ENOTSUP、Windows: 0 |
| get: *state | uv_tty_vtermstate_t | 現在のVT状態 |

### 出力先

get関数はstateポインタに格納。set関数はグローバルなVT状態変数を更新。

## 処理フロー

### 処理シーケンス

```
uv_tty_set_vterm_state() [Unix]:
1. 何もしない（空関数）

uv_tty_get_vterm_state() [Unix]:
1. return UV_ENOTSUP

uv_tty_set_vterm_state() [Windows]:
1. uv_tty_output_lockセマフォを取得
2. uv__need_check_vterm_stateをFALSEに設定
3. uv__vterm_stateを引数のstateに設定
4. セマフォを解放

uv_tty_get_vterm_state() [Windows]:
1. uv_tty_output_lockセマフォを取得
2. *stateにuv__vterm_stateをコピー
3. セマフォを解放
4. return 0
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{プラットフォーム}
    B -->|Unix| C{set or get?}
    C -->|set| D[何もしない]
    C -->|get| E[return UV_ENOTSUP]
    B -->|Windows| F{set or get?}
    F -->|set| G[セマフォ取得]
    G --> H[vterm_state設定]
    H --> I[セマフォ解放]
    F -->|get| J[セマフォ取得]
    J --> K[state読み取り]
    K --> L[セマフォ解放]
    L --> M[return 0]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-76-01 | Unix非サポート | Unix環境ではset_vterm_stateはno-op、get_vterm_stateはUV_ENOTSUP | Unix |
| BR-76-02 | Windows排他制御 | Windows環境ではセマフォで排他制御される | Windows |
| BR-76-03 | 自動検出無効化 | set_vterm_state()呼び出しにより自動VT検出が無効化される | Windows set呼び出し時 |

### 計算ロジック

特段の計算ロジックはない。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_ENOTSUP | 未サポート | Unix環境でuv_tty_get_vterm_state()を呼び出した | Unix環境では本機能は使用不可 |

### リトライ仕様

リトライは不要。

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

該当なし。

## パフォーマンス要件

軽量な操作であり、特段の性能要件はない。

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

- Windows版ではセマフォによるスレッドセーフなアクセスが保証される

## 備考

- uv_tty_vtermstate_tはUV_TTY_SUPPORTED(0)とUV_TTY_UNSUPPORTED(1)の2値列挙型
- Windows版ではuv_tty_set_vterm_state()はuv__need_check_vterm_stateをFALSEに設定し、以降の自動VTサポート検出を無効化する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **L826-836**: uv_tty_vtermstate_t列挙型。UV_TTY_SUPPORTED, UV_TTY_UNSUPPORTED |

#### Step 2: Unix実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | tty.c | `src/unix/tty.c` | **L505-506**: uv_tty_set_vterm_state() - 空関数 |
| 2-2 | tty.c | `src/unix/tty.c` | **L508-510**: uv_tty_get_vterm_state() - UV_ENOTSUP返却 |

#### Step 3: Windows実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | tty.c | `src/win/tty.c` | **L2448-2453**: uv_tty_set_vterm_state() - セマフォ保護でvterm_state設定 |
| 3-2 | tty.c | `src/win/tty.c` | **L2455-2460**: uv_tty_get_vterm_state() - セマフォ保護でvterm_state取得 |

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

```
uv_tty_set_vterm_state(state)   [Unix: src/unix/tty.c L505 - no-op]
                                [Win:  src/win/tty.c L2448]
    +-- uv_sem_wait(&uv_tty_output_lock)   [Windows]
    +-- uv__vterm_state = state
    +-- uv_sem_post(&uv_tty_output_lock)

uv_tty_get_vterm_state(state)   [Unix: src/unix/tty.c L508 - UV_ENOTSUP]
                                [Win:  src/win/tty.c L2455]
    +-- uv_sem_wait(&uv_tty_output_lock)   [Windows]
    +-- *state = uv__vterm_state
    +-- uv_sem_post(&uv_tty_output_lock)
```

### データフロー図

```
[入力]                   [処理]                    [出力]
state (列挙値) --------> グローバル変数更新 ------> uv__vterm_state(グローバル)
state* (ポインタ) -----> グローバル変数読取 ------> *state (VT状態)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | API宣言（L843-844）、uv_tty_vtermstate_t定義（L826-836） |
| tty.c | `src/unix/tty.c` | ソース | Unix版実装（L505-510） |
| tty.c | `src/win/tty.c` | ソース | Windows版実装（L2448-2460） |
