Process Module
#Data Types

Several process functions operate on a variety of data types. The below table lists the accepted data types and their respective sizes.

TypeDescriptionValue range
"byte"A single byte-127 to 127
"ubyte"A single unsigned byte0 to 255
"short"Two bytes-32,767 to 32,767
"ushort"Two unsigned bytes0 to 65,535
"int"Four bytes-2,147,483,647 to 2,147,483,647
"uint"Four unsigned bytes0 to 4,294,967,295
"int64"Eight bytes-9,223,372,036,854,775,807 to 9,223,372,036,854,775,807
"uint64"Eight unsigned bytes0 to 18,446,744,073,709,551,615
"float"Four bytes~7 digits precision
"double"Eight bytes~15 digits precision
"string"Character stringNULL-terminated
"ustring"Unicode character stringNULL-terminated
#process.open handle process.open(number processId)

Attempt to open and return a handle to a process for reading/writing. Accepts only the process's ID to open.

#process.close process.close(handle procHandle)

Closes an opened handle. If you set an open handle to nil, or if a handle goes out of scope, it will automatically close itself.

#process.read number process.read(handle procHandle, string type, number address) string process.read(handle procHandle, string type, number address, number length)

Attempt to read memory from process 'procHandle' at the given address. 'type' should be "byte", "ubyte", "short", "ushort", etc. When reading a string, a maximum bytes to read should be given as 'length', otherwise do not specify length.

The type of data returned depends on the type requested. That is, requesting a byte, short, int, int64, float, or double returns a number while requesting a string returns a string. If this function should fail, it will return nil.

See Data Types for a list of available types.

#process.readPtr number process.readPtr(handle procHandle, string type, number address, number|table offsets) string process.readPtr(handle procHandle, string type, number address, number|table offsets, number length)

Exactly like process.read(), except it reads from a pointer.

'offsets' can be a number (single offset) or a table (multiple offsets). If a table is given for 'offsets', each value should be of type number.

#process.readBatch number process.readBatch(handle procHandle, number address, string mask)

Exactly like process.read(), except it reads from a pointer.

Attempt to read concurrent memory from process 'proc' at the given address. 'mask' dictates what type(s) and how many variables should be read. Each character in 'mask' specifies the type to read or skip. A number prefixing the type can dictate the number to read (number types) or the length of a string.

Each character in 'mask' should be one of the below (to specify types), or a number (to specify how many or length)

CharacterType
bbyte
Bunsigned byte
sshort
Sunsigned short
iint
Iunsigned int
hint64
Hunsigned int64
ffloat
Fdouble
cstring
_   (underscore)(skip ahead x bytes; do not return this)

For example, a mask of "3i" means "read 3 integers" while "3c" means "read a string of length 3." You may also chain multiple reads together, such as "3i4f16_bs" to mean "read 3 integers, then 4 floats, then skip 16 bytes, read a byte, then read a short."

#process.readChunk chunk process.readChunk(handle procHandle, number address, number length)

Reads a chunk of memory of a given size from a location. 'length' represents the number of bytes to read.

The chunk is an object that you can then use to extract the various data from. It is generally faster to read a chunk then extract from it than it is to do many single reads with process.read().

#process.write boolean process.write(handle procHandle, string type, number address, number|string data)

Attempt to write memory to process 'procHandle' at the given address. 'type' does not need to indicate signedness; do not includes 'u' prefix when writing. Strings also do not require length to be given.

Returns true on success, false on failure.

See Data Types for a list of available types.

#process.writePtr boolean process.writePtr(handle procHandle, string type, number address, number|table offsets, number|string data)

Exactly like process.write(), except it is for writing to pointers.

'offsets' can be a number (single offset) or a table (multiple offsets). If a table is given for 'offsets', each value should be of type number.

Returns true on success, false on failure.

#process.findPattern number process.findPattern(handle procHandle, number address, number length, string bitmask, string szmask)

Attempt to find a pattern within a process, beginning at memory address 'address', with a max scan length of 'length' (in bytes). 'bitmask' should contain an 'x' for a match, and '?' for wildcard. i.e. "xxxx?xx". 'szmask' should contain the actual data we are checking against for a match. i.e. "ABCD?FG"

#process.findByWindow number process.findByWindow(number hwnd)

Returns the process ID that a window with handle 'hwnd' is owned by. If the function fails, it returns nil.

#process.findByExe number process.findByExe(string processName)

Look up a process ID by checking for its running executable. i.e. "explorer.exe"

If the process you are looking for is 64-bit, then you must use a 64-bit copy of MicroMacro, otherwise the process cannot be found.

If this process fails, it returns nil.

#process.getModuleAddress number process.getModuleAddress(number processId, string moduleName)

Look up the address of a module within a process and return its origin address. Often this is used to lookup the location where a DLL is loaded or the beginning address of the main executable. 'moduleName' should be the full name. i.e. "whatever.dll" If the function fails or it could not locate the module, it returns nil.

#process.getModuleFilename string process.getModuleFilename(handle procHandle)

Returns the fully qualified path of the main executable of an opened (see process.open()) process.

#process.getModules string process.getModules(number processId)

Returns a table of key/value pairs of every module found within the process specified by the process ID. Module names will be the key and the address within the program will be the value. If the function fails, it returns nil.

#process.attachInput boolean process.attachInput(number hwnd)

Attach our input thread to the target window. Returns true on success, false on failure.

Attaching input to a target window may allow synthetic input (see Keyboard Module) to be better received if it is otherwise not working.

#process.detachInput boolean process.detachInput(number hwnd)

Detach our input thread to the target window. Returns true on success, false on failure.

#process.is32bit boolean process.is32bit(handle procHandle)

Returns true if the target process is 32-bit, otherwise returns false.

#process.is64bit boolean process.is64bit(handle procHandle)

Returns true if the target process is 64-bit, otherwise returns false.

#process.terminate boolean process.terminate(handle procHandle) boolean process.terminate(handle procHandle, number exitCode)

Attempts to terminate the target process. Returns true on success, or false on failure. 'exitCode' is an optional identifier (default 0) you can use to specify the reason it is being terminated.

#process.getWindows table process.getWindows(number processId)

Returns a list of tables containing the 'hwnd' (handle to window), 'name' (window title), and 'class' of each window that belongs to the process specified by the process ID.

For more information on the return value, see window.findList().

Page last updated at 2018-09-25 20:48:20


Copyright 2018