Memory リファレンス

api.Memory() で作る、ネイティブメモリ(構造体・バッファ)を扱うオブジェクトのリファレンスです。

• Win32 API に渡す構造体(RECT、POINT、LOGFONT など)や、ポインタで受け渡すバッファを JavaScript から読み書きするためのオブジェクトです。
• 関連: te リファレンス、api リファレンス(api.Memory ほか)、FolderItems リファレンス

記法: P=プロパティ、M=メソッド。メンバー名・フィールド名の照合は大文字小文字を区別しません(rc.left と rc.Left は同じ)。ただし、実際のスクリプトでは構造体の定義どおりの表記(rc.left、pt.x、mii.fMask など)が使われています。

目次

1. 取得方法
2. 共通メンバー
3. Read / Write と VT 定数
4. 構造体のフィールド
5. プリミティブ型の Memory
6. 注意点
7. 使用例

1. 取得方法

api.Memory(type [, count [, ptr]])

• 生成に失敗する(未知の型名で数値も指定されていない場合など)と、空(undefined)が返ります。
• 構造体のうち先頭が cbSize 系のものは、作成時に先頭の4バイトへ構造体サイズが自動設定されます(4章の「cbSize自動」列が○のもの)。
• 構造体名の照合は大文字小文字を区別しません。使える型名は 4章 と 5章 を参照してください。

2. 共通メンバー

Item の動作

• 要素サイズ(Size / Count)が 1・2・4バイト: 整数を返す(符号付き。BYTE も char として符号付きで読まれる点に注意)。
• 8バイト: POINT 以外は64bit整数(int64)を返す。POINT のときは Memory(下の要素へのビュー)を返す。
• それ以外: その要素を指す Memory(同じメモリへのビュー。コピーではない)を返す。構造体の配列に使える。
• 書き込みは要素サイズが1〜8バイトの場合のみ有効。BSTR / LPWSTR 型に文字列を書くと、Memory が内部コピーを保持して、そのポインタを格納する。

3. Read / Write と VT 定数

Read(offset, vt [, len]) / Write(offset, vt, value [, len]) の vt には、consts.js の VT_* 定数、または下表の数値を使います。

• consts.js に定義があるのは VT_EMPTY VT_NULL VT_I1 VT_I2 VT_I4 VT_I8 VT_UI1 VT_UI2 VT_UI4 VT_UI8 VT_R4 VT_R8 VT_BSTR VT_UTF8 VT_LPSTR VT_LPWSTR VT_PTR VT_VARIANT VT_RECORD VT_USERDEFINED VT_ARRAY です。VT_BOOL VT_FILETIME VT_CY VT_CARRAY VT_CLSID は未定義なので、数値(11 / 64 / 6 / 28 / 72)で指定してください。
• offset は先頭からのバイト数です。範囲の検査は行われないため、バッファのサイズを超えないようにしてください。
• 非対応の vt を Read に指定すると空が返ります。Write では何も起こりません。

4. 構造体のフィールド

構造体名で作った Memory は、フィールド名のプロパティで読み書きできます(例: rc.left、pt.x = 10)。フィールド名は構造体定義の名前そのままで、大文字小文字は区別されません。

型の読み方: 無印=int(4バイト整数)、(ptr)=ポインタ値、(string)=構造体内の固定長文字列(WCHAR 配列)の読み書き、(string*)=文字列ポインタ(代入すると Memory が文字列のコピーを保持してそのポインタを格納)、(RECT)/(POINT)=構造体を値として返す(RECT は新しい Memory のコピー、POINT は {x,y})、(WORD)=2バイト、(BYTE)=1バイト、(bool)=BOOL。

LOGFONT.lfFaceName、SHFILEINFO.szDisplayName、WIN32_FIND_DATA.cFileName、NOTIFYICONDATA.szTip などの固定長文字列フィールドは、文字列として読み書きします。WIN32_FIND_DATA の ftCreationTime / ftLastAccessTime / ftLastWriteTime は UNIX 時刻(ms)で読み取れます。 CHOOSEFONT には、内部の位置調整用の予約フィールド(___MISSING_ALIGNMENT__)も見えますが、通常は使いません。 PAINTSTRUCT.rgbReserved は先頭の1バイトのみ参照されます。

5. プリミティブ型の Memory

構造体ではない型名でも api.Memory() に指定できます。要素単位の読み書きには Item(i) / mem[i] を使います。

6. 注意点

• 文字列ポインタ(BSTR / LPWSTR 型)に文字列を代入すると、Memory が内部コピーを保持します。 Memory を Free() するか破棄するまで有効です。API に渡している間は、Memory を変数に保持しておいてください。
• Memory(size, count, ptr) は、既存のメモリを参照するだけで所有しません。 元のメモリが解放されたあとにアクセスしないでください。
• Free() 後の Memory は P が 0 になり、読み書きできません。
• 構造体の配列を作るときは api.Memory("POINT", n) のように要素数を指定し、mem[i].x のように使います(要素は同じメモリへのビュー)。

7. 使用例

// RECT を取得
const rc = api.Memory("RECT");
api.GetWindowRect(te.hwnd, rc);
const w = rc.right - rc.left;
const h = rc.bottom - rc.top;

// POINT
const pt = api.Memory("POINT");
api.GetCursorPos(pt);
const x = pt.x, y = pt.y;

// 文字列バッファ(WCHAR)
const s = api.Memory("WCHAR", "Hello");
const text = s.Read(0, VT_LPWSTR);        // "Hello"
s.Write(0, VT_LPWSTR, "World");           // バッファの範囲内で上書き

// 構造体のフィールドを設定 (cbSize は自動設定される)
const mii = api.Memory("MENUITEMINFO");
mii.fMask = MIIM_STRING | MIIM_ID;
mii.wID = 1;
mii.dwTypeData = "Item";                    // 文字列は Memory が保持する
api.InsertMenuItem(hMenu, 0, true, mii);

// バイナリ文字列(BSTR)との変換
const mem = api.Memory(4);
mem.Write(0, VT_I4, 0x12345678);
const n = mem.Read(0, VT_I4);                   // 0x12345678
const bytes = mem.Read(0, VT_UI1 | VT_ARRAY);   // SafeArray(4バイト)

// 日付(FILETIME)
const fd = api.Memory("WIN32_FIND_DATA");
const hFind = api.FindFirstFile("C:\\Windows\\notepad.exe", fd);
const modified = new Date(fd.ftLastWriteTime);   // UNIX時刻(ms)

// 複製と解放
const copy = rc.Clone();
copy.Free();

関連

• te リファレンス
• api リファレンス
• FolderItems リファレンス