# 通知設計書 4-DLL依存関係エラー通知

## 概要

本ドキュメントは、K-Shoot MANIAのアプリケーション起動時に必要なDLLファイルが見つからない場合に表示されるエラーダイアログ通知の設計を記述する。bass.dll等の必須DLLの存在チェックとバージョン検証について、チェック対象、エラーメッセージ、処理フローを網羅的に定義する。

### 本通知の処理概要

本通知は、アプリケーション起動シーケンスにおいて、実行に必要な外部DLLファイルの存在確認とバージョン検証を行い、不足または不適合の場合にエラーダイアログを表示してアプリケーションを終了する機能を提供する。

**業務上の目的・背景**：K-Shoot MANIAは複数の外部DLL（音声処理ライブラリBASS、ネットワーク通信ライブラリ、VST処理ライブラリ等）に依存している。これらのDLLが不足している場合、実行時にクラッシュするのではなく、起動時に明確なエラーメッセージを表示してユーザーに対処方法を案内することで、トラブルシューティングを容易にしている。

**通知の送信タイミング**：アプリケーション起動直後の初期化シーケンスで、各DLLの`exist`チェックを順次実行する。最初に見つからないDLLが検出された時点でダイアログ表示後にアプリケーションを終了する。

**通知の受信者**：アプリケーションを起動しようとしているユーザー（プレイヤー）。

**通知内容の概要**：不足しているDLLのファイル名を含むエラーメッセージ、またはDLLバージョン不適合のメッセージ。一部は多言語対応（lang変数経由）。

**期待されるアクション**：ユーザーが不足しているDLLファイルを入手してアプリケーションのインストールディレクトリに配置する。バージョン不適合の場合は最新版のDLLをコピーする。

## 通知種別

モーダルダイアログ通知（OS標準のdialog命令、アイコン種別1=警告）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（dialog命令はモーダルで、OKボタン押下後にend命令でアプリ終了） |
| 優先度 | 最高（DLL不足はアプリケーション起動不可のため致命的） |
| リトライ | なし（DLLファイル配置後にアプリケーション再起動が必要） |

### 送信先決定ロジック

ダイアログはアクティブウィンドウに対してモーダル表示される。送信先はプレイヤーのPC画面上のダイアログウィンドウ固定。

## 通知テンプレート

### メール通知の場合

本通知はOS標準ダイアログのため、メール関連項目は該当しない。

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | N/A |
| 送信元名称 | N/A |
| 件名 | N/A |
| 形式 | OS標準ダイアログ（dialog命令、アイコン=1/警告） |

### 本文テンプレート

DLL未発見エラー:
```
Cannot find the file MSVCR100.dll.
Cannot find the file kshlib.dll.
Cannot find the file kson.dll.
Cannot find the file hspinet.dll.
Cannot find the file bass_vst.dll.
{lang.0.3} (bassconv.dll未発見時)
{lang.0.4} (bass.dll未発見時)
```

DLLバージョン不適合:
```
最新版のkshlib.dllをコピーする必要があります。
Make sure to copy the latest version of kshlib.dll.
```
```
最新版のkson.dllをコピーする必要があります。
Make sure to copy the latest version of kson.dll.
```

BASS初期化失敗:
```
{lang.0.5} (BASS_Init失敗時)
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| N/A | N/A | N/A | ダイアログ通知のため添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| lang.0.2 | ダイアログタイトル文字列 | 言語リソース | Yes |
| lang.0.3 | bassconv.dll未発見エラーメッセージ | 言語リソース | Yes |
| lang.0.4 | bass.dll未発見エラーメッセージ | 言語リソース | Yes |
| lang.0.5 | BASS初期化失敗エラーメッセージ | 言語リソース | Yes |
| strsize | exist命令の結果（-1=ファイル未発見） | HSP3ランタイム | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 起動チェック | msvcr100.dll存在確認 | strsize=-1 | kshootmania.hsp:750-751 |
| 起動チェック | kshlib.dll存在確認 | strsize=-1 | kshootmania.hsp:752-753 |
| 起動チェック | kshlib.dllバージョン確認 | KSHLib_GetVersion()<1663 | kshootmania.hsp:754-756 |
| 起動チェック | kson.dll存在確認 | strsize=-1 | kshootmania.hsp:758-759 |
| 起動チェック | kson.dllバージョン確認 | KSON_GetVersion()<1752 | kshootmania.hsp:760-762 |
| 起動チェック | hspinet.dll存在確認 | strsize=-1 | kshootmania.hsp:763-764 |
| 起動チェック | bass_vst.dll存在確認 | strsize=-1 | kshootmania.hsp:765-766 |
| 起動チェック | bassconv.dll存在確認 | strsize=-1 | kshootmania.hsp:767-768 |
| 起動チェック | bass.dll存在確認 | strsize=-1 | kshootmania.hsp:769-770 |
| 起動チェック | BASS_Init初期化確認 | stat!=1 | kshootmania.hsp:771-772 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| すべてのDLLが存在しバージョンが適合 | エラーダイアログを表示しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[アプリケーション起動] --> B[言語リソース読み込み]
    B --> C{msvcr100.dll存在?}
    C -->|No| D1[dialog: Cannot find MSVCR100.dll → end]
    C -->|Yes| E{kshlib.dll存在?}
    E -->|No| D2[dialog: Cannot find kshlib.dll → end]
    E -->|Yes| F{kshlib.dllバージョン>=1663?}
    F -->|No| D3[dialog: 最新版kshlib.dll必要 → end]
    F -->|Yes| G[KSHLib_Init]
    G --> H{kson.dll存在?}
    H -->|No| D4[dialog: Cannot find kson.dll → end]
    H -->|Yes| I{kson.dllバージョン>=1752?}
    I -->|No| D5[dialog: 最新版kson.dll必要 → end]
    I -->|Yes| J{hspinet.dll存在?}
    J -->|No| D6[dialog: Cannot find hspinet.dll → end]
    J -->|Yes| K{bass_vst.dll存在?}
    K -->|No| D7[dialog: Cannot find bass_vst.dll → end]
    K -->|Yes| L{bassconv.dll存在?}
    L -->|No| D8[dialog: lang.0.3 → end]
    L -->|Yes| M{bass.dll存在?}
    M -->|No| D9[dialog: lang.0.4 → end]
    M -->|Yes| N[BASS_Init]
    N --> O{初期化成功?}
    O -->|No| D10[dialog: lang.0.5 → end]
    O -->|Yes| P[起動シーケンス続行]
```

## データベース参照・更新仕様

### 参照テーブル一覧

本通知はデータベースを使用しない。ファイルシステム上のDLLファイル存在確認のみ。

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| N/A | N/A | ファイルシステムチェックのみ |

### テーブル別参照項目詳細

該当なし。

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| N/A | N/A | 更新処理なし |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| msvcr100.dll未発見 | Visual C++ 2010ランタイム未インストール | ダイアログ表示後、アプリケーション終了。ユーザーにVC++ランタイムのインストールを促す |
| kshlib.dll未発見 | K-Shoot MANIA固有ライブラリ不足 | ダイアログ表示後、アプリケーション終了 |
| kshlib.dllバージョン不足 | 古いバージョンのkshlib.dll | ダイアログ表示後、アプリケーション終了。最新版のコピーを促す |
| kson.dll未発見 | KSON処理ライブラリ不足 | ダイアログ表示後、アプリケーション終了 |
| kson.dllバージョン不足 | 古いバージョンのkson.dll | ダイアログ表示後、アプリケーション終了。最新版のコピーを促す |
| hspinet.dll未発見 | HSPネットワーク通信ライブラリ不足 | ダイアログ表示後、アプリケーション終了 |
| bass_vst.dll未発見 | BASS VSTプラグインライブラリ不足 | ダイアログ表示後、アプリケーション終了 |
| bassconv.dll未発見 | BASSコンバーターライブラリ不足 | ダイアログ表示後（多言語メッセージ）、アプリケーション終了 |
| bass.dll未発見 | BASSオーディオライブラリ不足 | ダイアログ表示後（多言語メッセージ）、アプリケーション終了 |
| BASS_Init失敗 | オーディオデバイス初期化失敗 | ダイアログ表示後（多言語メッセージ）、アプリケーション終了 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（アプリケーション終了後の再起動が必要） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | N/A（起動時1回限り） |
| 1日あたり上限 | N/A |

### 配信時間帯

制限なし。アプリケーション起動時のみ発生。

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

- DLLの存在確認のみで、DLLの内容検証（署名チェック等）は行わない
- DLLハイジャック攻撃のリスクがあるが、本通知機能の範囲外
- エラーメッセージにファイルパスは含まない（ファイル名のみ）

## 備考

- DLLチェックは起動シーケンスの中で言語リソース読み込み（`*refreshlang`）の直後に実行される（kshootmania.hsp:747-772）
- msvcr100.dllはMicrosoft Visual C++ 2010 Redistributableに含まれる
- kshlib.dllの最低バージョンは1663（v1.663相当）
- kson.dllの最低バージョンは1752（v1.752相当）
- Msftedit.dllの存在チェック（kshootmania.hsp:190）も行われるが、これは任意のRichEditコントロール用で、未発見でもエラーにはならない
- すべてのDLLチェックは`exist`命令と`strsize`変数の組み合わせで実装される（strsize=-1でファイル未発見）
- DLLチェック順序: msvcr100.dll → kshlib.dll → kson.dll → hspinet.dll → bass_vst.dll → bassconv.dll → bass.dll → BASS_Init

---

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

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

### 推奨読解順序

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

DLLチェックで使用される変数と定数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | HSP3の`exist`命令は指定ファイルの存在を確認し、結果をシステム変数`strsize`に格納する（-1=未発見） |

**読解のコツ**: HSP3の`exist`命令は`strsize`システム変数にファイルサイズを返す。ファイルが存在しない場合は`strsize=-1`になる。`dialog`命令の第2引数が1の場合は警告アイコン（!マーク）付きのダイアログが表示される。`end`命令はアプリケーションを即座に終了する。

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

DLLチェックはkshootmania.hspのメイン初期化シーケンス内で実行される。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshootmania.hsp | `kshootmania.hsp` | 747行目: `gosub *refreshlang` - 言語リソース読み込み（DLLチェック前の前提処理） |
| 2-2 | kshootmania.hsp | `kshootmania.hsp` | 750-772行目: DLLの存在確認とバージョン検証の逐次チェック |

**主要処理フロー**:
1. **750-751行目**: `exist "msvcr100.dll"` → `dialog "Cannot find the file MSVCR100.dll.",1,lang.0.2:end`
2. **752-753行目**: `exist "kshlib.dll"` → `dialog "Cannot find the file kshlib.dll.",1,lang.0.2:end`
3. **754-756行目**: `KSHLib_GetVersion()<1663` → バージョン不適合ダイアログ → `end`
4. **757行目**: `KSHLib_Init dir_default` - kshlib.dllの初期化
5. **758-759行目**: `exist "kson.dll"` → 未発見ダイアログ → `end`
6. **760-762行目**: `KSON_GetVersion()<1752` → バージョン不適合ダイアログ → `end`
7. **763-764行目**: `exist "hspinet.dll"` → 未発見ダイアログ → `end`
8. **765-766行目**: `exist "bass_vst.dll"` → 未発見ダイアログ → `end`
9. **767-768行目**: `exist "bassconv.dll"` → 多言語メッセージダイアログ → `end`
10. **769-770行目**: `exist "bass.dll"` → 多言語メッセージダイアログ → `end`
11. **771-772行目**: `BASS_Init` → 初期化失敗ダイアログ → `end`

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

```
kshootmania.hsp (メインスクリプト)
    |
    +-- gosub *refreshlang (言語リソース読み込み)
    |
    +-- [DLL存在チェックシーケンス] (750-772行)
    |       +-- exist "msvcr100.dll" → dialog → end
    |       +-- exist "kshlib.dll"   → dialog → end
    |       +-- KSHLib_GetVersion()  → dialog → end
    |       +-- KSHLib_Init dir_default
    |       +-- exist "kson.dll"     → dialog → end
    |       +-- KSON_GetVersion()    → dialog → end
    |       +-- exist "hspinet.dll"  → dialog → end
    |       +-- exist "bass_vst.dll" → dialog → end
    |       +-- exist "bassconv.dll" → dialog → end
    |       +-- exist "bass.dll"     → dialog → end
    |       +-- BASS_Init            → dialog → end
    |
    +-- [起動シーケンス続行] (774行以降)
```

### データフロー図

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

ファイルシステム
  msvcr100.dll ──────┐
  kshlib.dll ────────┤
  kson.dll ──────────┤
  hspinet.dll ───────┼──▶ exist命令 ──────────▶ strsize変数
  bass_vst.dll ──────┤     (ファイル存在確認)        |
  bassconv.dll ──────┤                               v
  bass.dll ──────────┘                        strsize=-1?
                                                     |
                                              ┌──────┴──────┐
                                              |Yes          |No
                                              v             v
                                        dialog → end   バージョンチェック
                                                            |
                                                     Version OK?
                                                     ┌──────┴──────┐
                                                     |No           |Yes
                                                     v             v
                                               dialog → end   次のDLLチェック
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kshootmania.hsp | `kshootmania.hsp` | ソース | メインスクリプト。DLL存在確認・バージョン検証・エラーダイアログ表示の全処理を含む |
| kshlib.as | `src/kshlib.as` | ソース | kshlib.dllのインターフェース定義（KSHLib_GetVersion, KSHLib_Init等） |
| kson.as | `src/kson.as` | ソース | kson.dllのインターフェース定義（KSON_GetVersion等） |
| bass.as | `src/bass.as` | ソース | bass.dllのインターフェース定義（BASS_Init等） |
| bass_vst.as | `src/bass_vst.as` | ソース | bass_vst.dllのインターフェース定義 |
| bassconv.as | `src/bassconv.as` | ソース | bassconv.dllのインターフェース定義 |
