HSPからWin32 API関数を利用する方法を簡単に解説

HSPからWindows API（Win32 API）関数の利用

「Windows API」はWindowsのシステムそのものが用意してる命令のようなもの（正確には関数）です。特にWindows 95以降の32ビットプロセッサ上で利用するものを「Win32 API」と呼びます。

無料（フリーソフト）でWindows向けツールを作成できるプログラミングツール「HSP」のバージョン2.x（HSP2）時代は、tomさんが製作した拡張プラグイン「loadlib.dll」＋モジュール「llmod.as」の組み合わせで、Win32 APIを呼ぶのが一般的でした。（後に「loadlib.dll」の機能がHSP2本体に組み込まれ、拡張プラグインの同封が不要になる）

HSPのバージョン3.x（HSP3）では、Win32 API関数をより手軽に扱うための命令が新たに定義されました。（HSP2とHSP3で互換がなくなってる部分）
　利用するライブラリを指定する「#uselib」、命令宣言を行う「#func」、関数宣言を行う「#cfunc」の各プリプロセッサ命令です。（#uselib命令と#func命令はHSP2でもサポートしていたもので、HSP3では機能が拡張され、HSP2向け下位互換もあわせ持つ）

Win32 API関数を呼んでみる

例として、MessageBox関数を呼んでみるミニ講座です。これはメッセージボックス（ダイアログボックス）を表示するWin32 API関数で、HSPでいうdialog命令のタイプ0～3の真の正体です。
　この関数の説明は、HSP向けに書かれてあるちょくとさんのページや、Microsoft本家のMSDNページ（英語）をチェック！関数名をキーワードに検索すれば、HSP向けではないですが日本語の情報はたくさんヒットします。

//	MSDNのページより
int MessageBox(
	HWND hWnd,
	LPCTSTR lpText,
	LPCTSTR lpCaption,
	UINT uType
);

上のCの宣言コードは下と同じで、横幅があるから改行して表現してるだけです。先頭の「int」はMessageBox関数の戻り値の型を示してます。そして、この関数には４つのパラメータ＝引数（ひきすう）が存在します。

int MessageBox(HWND hWnd, LPCTSTR lpText, LPCTSTR lpCaption, UINT uType);

HSPでこれを表現するには、まずはこの関数が「user32.dll」というWindowsのシステムに入ってるライブラリ内に用意されてるものなので、これを#uselib命令で指定します。（「.dll」の文字列は省略可能）

#uselib "user32.dll"

次に、HSPで実際にMessageBox関数を呼べるよう、#uselibの直後に#func命令の宣言を用意します。
　#func命令の１番目のパラメータはスクリプト上で実際に使う命令文字列です。２番目のパラメータは関数名です。その後ろにパラメータの型を指定していきます。HSPでパラメータの型は「int」が整数値、「str」が文字列を意味します。

#uselib "user32.dll"
#func MessageBox "MessageBoxA" int, str, str, int

準備は整ったので、実際に関数を利用します。
　MessageBox関数の第１パラメータはオーナーとなるウィンドウハンドル値を指定します。HSPにはない概念ですがウィンドウIDに相当するもので、システム変数「hwnd」に代入されてます。第２-３パラメータはそのまま文字を、第４パラメータはメッセージボックスのタイプを指定する数値です。０は単純に[はい]ボタンが表示されるタイプです。
　結果はシステム変数statに返ります。

#uselib "user32.dll"
#func MessageBox "MessageBoxA" int, str, str, int

	MessageBox hwnd, "ボックス内", "タイトル部分", 0
	mes stat

ちなみに、#func命令の１番目のパラメータは別に何でも構いません。下のように自分が使いたい名称を指定することもできます。（が、混乱の元になるので推奨しません。）

#uselib "user32.dll"
#func メッセージボックス "MessageBoxA" int, str, str, int

	メッセージボックス hwnd, "ボックス内", "タイトル部分", 0
	mes stat

#func宣言でのパラメータの型と、命令として利用するパラメータは下のような感じで一致してることを把握しといてください。

HSP3（HSP 3.x）からWin32 API関数を利用。API関数の宣言の引数と、実際の命令の引数のつながり。

☆ 「MessageBoxA」と「MessageBoxW」

上では触れてませんが、#func命令の関数名が「～A」となってます。MessageBox関数には、ANSI版の「MessageBoxA」と Windows NT系以降（Windows 2000/XP/Vista/7）で利用できるUnicode版の「MessageBoxW」（「～W」タイプ）の２種類が存在し、基本的に「MessageBoxA」（「～A」タイプ）の方を利用します。「MessageBoxW」は、Windows 9x系OS（Windows 98/Me）では対応してません。

で、注意したいのは、別にすべてのWin32 API関数に２種類のバージョンがあるわけではないです。
　ちょくとさんのページでは「MessageBox(A)」というタイトルで、MSDNページでは最下部付近の「Function Information」の表で「Unicode - Implemented as ANSI and Unicode versions.」（日本語翻訳ページだと、「Windows NT/2000 は Unicode 版と ANSI 版を実装」）という形で紹介して、２種類存在する関数であることを示してます。（基本的に文字列がらみの処理が含まれてる関数だと２種類ある）

☆ Win32 API関数宣言の定義ファイル

Win32 API関数を利用するたびに#uselib命令と#func命令を用意するのはちょっと面倒です。
　HSP3ではあらかじめWin32 API関数が宣言されてる定義ファイルがcommonフォルダ内に用意されてます。「user32.dll」ライブラリ用のものは「user32.as」なので、これを#include命令でインクルードしましょう。

#include "user32.as"

	MessageBox hwnd, "ボックス内", "タイトル部分", 0
	mes stat

その他の定義ファイルを挙げると、「gdi32.as」（gdi32.dll）、「kernel32.as」（kernel32.dll）、「advapi32.as」（advapi32.dll）、「comctl32.as」（comctl32.dll）、「winmm.as」（winmm.dll）、「shell32.as」（shell32.dll）、「ole32.as」（ole32.dll）です。
　これらのライブラリはWindowsのシステムにあらかじめ用意されてるもの（Windows OSの根幹に関わる重要なファイル）で、すべてのWindowsマシンに含まれてます。Microsoftの著作物なので、HSP拡張プラグインのように実行ファイルといっしょに同封して配布したりするものではないのでご注意を。

ちなみに、HSP 3.0/3.0aでは、この定義ファイルをインクルードすると、実行ファイルのサイズがバカでかくなる問題がありましたが、HSP 3.1以降では不要な宣言がコンパイルの際に削ぎ落とされるよう改良されてます。

Win32 API関数を関数形式で

これまでは命令形式でWin32 API関数を利用してきましたが、#func命令の宣言部分をそのまま#cfunc命令にすれば、HSP3から対応した関数形式でWin32 API関数を利用できます。
　メッセージボックスの表示とともに関数そのものが結果を返すため、それをmes命令にそのまま指定できています。

#uselib "user32.dll"
#cfunc MessageBox "MessageBoxA" int, str, str, int

	mes MessageBox(hwnd, "ボックス内", "タイトル部分", 0)

ちなみに、HSPがあらかじめ用意してある定義ファイル「user32.as」などは、すべて命令形式で記述されてるので、自前で宣言を行わない限り関数形式は利用できません。（自前の宣言と定義ファイルのインクルードは関数名が被ってしまうため両立不可です）

● おわりに

ここで説明したWin32 API関数はさわりの部分で、これで終わりではありません。ちょくとさんのページに用意されてる「Advanced HSP」というコンテンツがとても詳しいので勉強してください。ただ、HSPにはない概念・用語がたーくさん登場するので、初めての人は挫折するのが必死じゃないかと思います。（＾＾;
　このサイトの筆者は、HSP3あれこれのページにてWin32 API関数を駆使したHSP 3.x向けサンプルコードをいくつか公開してます。

Win32 API関数を呼んでみる

☆ 「MessageBoxA」と「MessageBoxW」

☆ Win32 API関数宣言の定義ファイル

Win32 API関数を関数形式で

● おわりに

キーワード de HSP