# 機能設計書 118-Win32 APIバインディング

## 概要

本ドキュメントは、K-Shoot MANIAにおけるWin32 APIバインディング機能の設計を記述する。LoadLibrary/GetLongPathName/GetTempPath/GetRasterStatus等のWin32 APIラッパー機能を提供する。

### 本機能の処理概要

Windows APIの各種関数をHSPから呼び出すためのバインディング(宣言)を提供するヘッダファイルである。user32.dll、kernel32.dll、gdi32.dll、msvcrt.dll、comctl32.dllの5つのDLLからの関数宣言を含む。

**業務上の目的・背景**：HSPの標準命令では対応できないWindows固有の操作（ウィンドウ操作、ファイルシステム操作、GDI描画、クリップボード操作等）を実現するために、Win32 APIを直接呼び出す必要がある。このファイルがその橋渡し役を担う。

**機能の利用シーン**：エディタのUI制御(ウィンドウ最小化判定、ウィンドウテキスト設定)、ファイル操作(パス変換、一時ファイル)、メニュー制御(CheckMenuItem、EnableMenuItem)、ツールバー制御、クリップボード操作など、アプリケーション全体で利用される。

**主要な処理内容**：
1. user32.dll: ウィンドウ操作(IsIconic, ShowWindow, EnableWindow, SetWindowTextW等)、メニュー操作(CheckMenuItem, EnableMenuItem)、クリップボード(OpenClipboard, SetClipboardData等)、ポップアップメニュー(TrackPopupMenuEx)
2. kernel32.dll: DLL管理(LoadLibraryA, FreeLibrary)、パス操作(GetLongPathNameA, GetTempPathA)、ファイル操作(DeleteFileA, MoveFileA, RemoveDirectoryA)
3. gdi32.dll: フォント(CreateFontIndirect, DeleteObject)、DC操作(CreateCompatibleDC, SelectObject, BitBlt, DeleteDC)
4. msvcrt.dll: ファイルリネーム(rename)
5. comctl32.dll: コモンコントロール初期化(InitCommonControls)

**関連システム・外部連携**：Windows OS の各種DLLとの連携。

**権限による制御**：権限による制御はない。OS権限に従う。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全画面共通 | 補助機能 | ウィンドウ操作・メニュー制御・クリップボード操作等 |

## 機能種別

API宣言 / ユーティリティ

## 入力仕様

### 入力パラメータ

各Win32 API関数固有のパラメータ。HSPの`#func`/`#cfunc`宣言で型が定義されている。

### 入力データソース

- アプリケーション内部からの関数呼び出し

## 出力仕様

### 出力データ

各Win32 API関数固有の戻り値。

### 出力先

- 各Win32 API関数の戻り値
- OSへの副作用（ウィンドウ操作、ファイル操作等）

## 処理フロー

### 処理シーケンス

本ファイルはAPI宣言のみであり、処理フローは呼び出し元に依存する。

```
1. #include "winapi.as" でAPI宣言を読み込み
2. 呼び出し元で各API関数を使用
```

### フローチャート

```mermaid
flowchart TD
    A[呼び出し元コード] --> B{API関数呼び出し}
    B --> C[HSPバインディング経由]
    C --> D[Win32 DLL関数実行]
    D --> E[結果を返す]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-118-01 | インクルードガード | WINAPI_ASが定義済みの場合は二重読み込みを防止 | #include時 |
| BR-118-02 | ANSI版使用 | 文字列APIはANSI版(xxxA)を使用し、マクロでエイリアスを定義 | 常時 |
| BR-118-03 | Unicode対応 | SetWindowTextW/GetWindowTextWのみワイド文字版を使用 | ウィンドウテキスト設定時 |

### 計算ロジック

- LOWORDマクロ: `(%1 & 0xFFFF)` - 32bit値の下位16bitを取得

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

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

データベース操作はない。

## エラー処理

### エラーケース一覧

各Win32 API関数固有のエラー処理は呼び出し元が行う。本ファイルではエラー処理を含まない。

### リトライ仕様

リトライ処理はない。

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

トランザクション管理はない。

## パフォーマンス要件

Win32 API呼び出しは低レベル操作であり、パフォーマンスへの影響は最小限。

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

- LoadLibraryAで任意のDLLを読み込む可能性があるが、アプリケーション内部使用のため低リスク

## 備考

- HSPの`#uselib`でDLLを指定し、`#func`で関数宣言を行うパターン
- `#cfunc`は戻り値を持つ関数(stat変数に結果が入る)、`#func`は命令形式
- ウィンドウスタイル定数(WS_CHILD等)やメッセージ定数(WM_SETFONT等)の定義も含む

---

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

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

### 推奨読解順序

#### Step 1: ファイル構造を理解する

DLLごとのセクション分けを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | winapi.as | `src/winapi.as` | **1-2行目**: インクルードガード(#ifndef WINAPI_AS) |
| 1-2 | winapi.as | `src/winapi.as` | **4行目**: LOWORDマクロ定義 |

**読解のコツ**: HSPの`#uselib`はDLLを指定、`#func`は関数宣言、`#cfunc`は戻り値付き関数宣言。パラメータ型は`int`, `sptr`(ポインタ), `str`(文字列), `wptr`(ワイド文字列)。

#### Step 2: user32.dll宣言を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | winapi.as | `src/winapi.as` | **6-18行目**: ウィンドウ操作・クリップボード関連API |
| 2-2 | winapi.as | `src/winapi.as` | **21-26行目**: メニュー操作・ポップアップメニューAPI |
| 2-3 | winapi.as | `src/winapi.as` | **28-38行目**: メニュー・ツールバー関連定数 |

**主要処理フロー**:
- **7行目**: `IsIconic` - ウィンドウ最小化判定
- **12行目**: `SetWindowTextW` - ウィンドウタイトル設定(Unicode)
- **15行目**: `OpenClipboard` - クリップボードオープン
- **21行目**: `CheckMenuItem` - メニュー項目のチェック状態変更

#### Step 3: kernel32.dll宣言を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | winapi.as | `src/winapi.as` | **40-52行目**: DLL管理・パス操作・ファイル操作API |

**主要処理フロー**:
- **41行目**: `c_LoadLibrary "LoadLibraryA"` - DLL動的読み込み
- **44行目**: `GetTempPathA` - 一時ディレクトリパス取得
- **46行目**: `GetLongPathNameA` - 短縮パスから長いパスへの変換
- **48行目**: `DeleteFileA` - ファイル削除

#### Step 4: gdi32.dll/その他の宣言を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | winapi.as | `src/winapi.as` | **54-61行目**: GDI描画API |
| 4-2 | winapi.as | `src/winapi.as` | **63-74行目**: ウィンドウスタイル・メッセージ定数 |
| 4-3 | winapi.as | `src/winapi.as` | **76行目**: msvcrt.dllのrename関数 |
| 4-4 | winapi.as | `src/winapi.as` | **78-79行目**: comctl32.dllのInitCommonControls |

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

```
アプリケーションコード
    |
    +-- user32.dll
    |       +-- IsIconic, ShowWindow, EnableWindow
    |       +-- SetWindowTextW, GetWindowTextW
    |       +-- OpenClipboard, SetClipboardData, etc.
    |       +-- CheckMenuItem, EnableMenuItem
    |       +-- TrackPopupMenuEx, DestroyMenu
    |
    +-- kernel32.dll
    |       +-- LoadLibraryA, FreeLibrary
    |       +-- GetTempPathA, GetLongPathNameA
    |       +-- DeleteFileA, MoveFileA, RemoveDirectoryA
    |
    +-- gdi32.dll
    |       +-- CreateFontIndirect, DeleteObject
    |       +-- CreateCompatibleDC, SelectObject, BitBlt, DeleteDC
    |
    +-- msvcrt.dll
    |       +-- rename
    |
    +-- comctl32.dll
            +-- InitCommonControls
```

### データフロー図

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

HSP関数呼び出し ---> #func/#cfunc宣言 ---------> Win32 DLL関数実行
パラメータ                                        戻り値/副作用
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| winapi.as | `src/winapi.as` | ソース | Win32 APIバインディング宣言ファイル(全81行) |
| kshootmania.hsp | `kshootmania.hsp` | ソース | ゲーム本体。winapi.asをインクルードして使用 |
| kshooteditor.hsp | `kshooteditor.hsp` | ソース | エディタ。winapi.asをインクルードして使用 |
