Memory Reference

Reference for the object created with api.Memory(), which handles native memory (structures and buffers).

• It is an object for reading and writing, from JavaScript, structures passed to the Win32 API (such as RECT, POINT, and LOGFONT) and buffers exchanged by pointer.
• Related: te Reference, api Reference (api.Memory and others), FolderItems Reference

Notation: P = property, M = method. Member names and field names are matched case-insensitively (rc.left and rc.Left are the same). In actual scripts, however, the spelling used in the structure definition (rc.left, pt.x, mii.fMask, and so on) is used.

Table of Contents

1. How to Obtain
2. Common Members
3. Read / Write and VT Constants
4. Structure Fields
5. Primitive-Type Memory
6. Notes
7. Examples

1. How to Obtain

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

• If creation fails (for example, an unknown type name with no number specified), empty (undefined) is returned.
• For structures whose first member is a cbSize-type field, the structure size is set automatically in the first 4 bytes at creation time (those marked ✓ in the "Auto cbSize" column of Chapter 4).
• Structure names are matched case-insensitively. For the type names you can use, see Chapter 4 and Chapter 5.

2. Common Members

Behavior of Item

• When the element size (Size / Count) is 1, 2, or 4 bytes: returns an integer (signed; note that BYTE is also read as signed, like char).
• 8 bytes: returns a 64-bit integer (int64) except for POINT. For POINT, it returns a Memory (a view of the element below).
• Otherwise: returns a Memory that points to that element (a view of the same memory; not a copy). This can be used for arrays of structures.
• Writing is valid only when the element size is 1 to 8 bytes. When you write a string to a BSTR / LPWSTR type, the Memory holds an internal copy and stores its pointer.

3. Read / Write and VT Constants

For vt in Read(offset, vt [, len]) / Write(offset, vt, value [, len]), use the VT_* constants of consts.js or the numbers in the table below.

• The constants defined in consts.js are 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 are not defined, so specify them by number (11 / 64 / 6 / 28 / 72).
• offset is the number of bytes from the start. No range checking is performed, so make sure not to exceed the size of the buffer.
• If you specify an unsupported vt to Read, empty is returned. With Write, nothing happens.

4. Structure Fields

A Memory created with a structure name can be read and written through properties named after the fields (for example rc.left, pt.x = 10). Field names are exactly the names in the structure definition, and are not case-sensitive.

How to read the types: no mark = int (a 4-byte integer), (ptr) = a pointer value, (string) = reading and writing a fixed-length string (a WCHAR array) inside the structure, (string*) = a string pointer (when assigned, the Memory holds a copy of the string and stores its pointer), (RECT) / (POINT) = returns the structure as a value (RECT is a copy in a new Memory, POINT is {x,y}), (WORD) = 2 bytes, (BYTE) = 1 byte, (bool) = BOOL.

Fixed-length string fields such as LOGFONT.lfFaceName, SHFILEINFO.szDisplayName, WIN32_FIND_DATA.cFileName, and NOTIFYICONDATA.szTip are read and written as strings. ftCreationTime / ftLastAccessTime / ftLastWriteTime of WIN32_FIND_DATA can be read as UNIX time (ms). CHOOSEFONT also exposes an internal reserved field for alignment (___MISSING_ALIGNMENT__), but you normally do not use it. Only the first byte of PAINTSTRUCT.rgbReserved is referenced.

5. Primitive-Type Memory

Type names that are not structures can also be specified to api.Memory(). To read and write element by element, use Item(i) / mem[i].

6. Notes

• When you assign a string to a string pointer (BSTR / LPWSTR type), the Memory holds an internal copy. It stays valid until you Free() the Memory or it is discarded. While you are passing it to an API, keep the Memory in a variable.
• Memory(size, count, ptr) only refers to existing memory and does not own it. Do not access it after the original memory has been freed.
• After Free(), the Memory's P is 0 and it cannot be read or written.
• To create an array of structures, specify the element count as in api.Memory("POINT", n) and use it as mem[i].x (the elements are views of the same memory).

7. Examples

// Get a 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;

// String buffer (WCHAR)
const s = api.Memory("WCHAR", "Hello");
const text = s.Read(0, VT_LPWSTR);        // "Hello"
s.Write(0, VT_LPWSTR, "World");           // overwrite within the buffer

// Set structure fields (cbSize is set automatically)
const mii = api.Memory("MENUITEMINFO");
mii.fMask = MIIM_STRING | MIIM_ID;
mii.wID = 1;
mii.dwTypeData = "Item";                    // the Memory holds the string
api.InsertMenuItem(hMenu, 0, true, mii);

// Conversion to and from a binary string (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 bytes)

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

// Clone and free
const copy = rc.Clone();
copy.Free();

Related

• te Reference
• api Reference
• FolderItems Reference