Difference between revisions of "Process Functions"
m (Protected "Process Functions" ([edit=sysop] (indefinite) [move=sysop] (indefinite))) |
(→getModuleAddress) |
||
Line 469: | Line 469: | ||
<source lang="lua"> | <source lang="lua"> | ||
local notepadOrigin = getModuleAddress(notepadProc, "notepad.exe"); | local notepadOrigin = getModuleAddress(notepadProc, "notepad.exe"); | ||
+ | </source> | ||
+ | |||
+ | |||
+ | == flashWindow == | ||
+ | '''flashWindow(window, count)''' | ||
+ | |||
+ | Causes the specified window to "flash" in an attempt to grab the users attention. If 'window' is not specified, the calling MicroMacro instance will be used. 'count' refers to how many times the window will flash. If 'count' is 0, the window will continue to flash until it is pulled into the foreground by the user. | ||
+ | |||
+ | '''Example:''' | ||
+ | <source lang="lua"> | ||
+ | flashWindow(); -- flash MicroMacro window until user focuses it | ||
+ | flashWindow(nil, 10);-- flash MicroMacro window 10 times | ||
+ | flashWindow(findWindow("notepad"), 0);-- flash Notepad until it is focused | ||
+ | flashWindow(nil, -1); -- Stop flashing MicroMacro window | ||
</source> | </source> |
Revision as of 23:53, 1 August 2011
Contents
- 1 attach
- 2 attachKeyboard
- 3 attachMouse
- 4 detach
- 5 getAttachedHwnd()
- 6 openProcess
- 7 closeProcess
- 8 findProcess
- 9 findProcessByExe
- 10 findProcessByWindow
- 11 findWindow
- 12 findWindowList
- 13 foregroundWindow
- 14 windowValid
- 15 getHwnd
- 16 getWindowName
- 17 getWindowClassName
- 18 setWindowName
- 19 windowRect
- 20 openDC
- 21 closeDC
- 22 makeColor
- 23 getR
- 24 getG
- 25 getB
- 26 getPixel
- 27 setPixel
- 28 pixelSearch
- 29 drawLine
- 30 drawRect
- 31 saveScreenshot
- 32 showWindow
- 33 findPatternInProcess
- 34 getModuleAddress
- 35 flashWindow
attach
attach(window)
Attaches MicroMacro's input to another window. You may only attach to a single window at a time. When using attached input, MicroMacro will send input directly to the specified window; meaning it will not interfere with other windows if you switch focus and may allow you to continue sending input while it is in a minimized state. Note that this does not work for all applications, and you may still need to keep the window focused for input to register.
While in an attached state, the start and stop hotkeys will only work if MicroMacro or it's attached window are currently focused (ie. on top). This is intentional.
Example
attach( findWindow("mygame") );
attachKeyboard
attachKeyboard(window)
Exactly like attach(), except that it only attached keyboard input instead of both keyboard and mouse input.
attachMouse
attachMouse(window)
Exactly like attach(), except that it only attached mouse input instead of both keyboard and mouse input.
detach
detach()
Removes the attachment to whichever window was specified when using attach(). After detaching, MicroMacro will no longer specifically target it's previously attached window.
Example
attach( findWindow("mygame") );
yrest(100);
detach();
getAttachedHwnd()
number getAttachedHwnd()
Returns the handle to window of the currently attached window. If a window is not attached, this function will return 0.
openProcess
handle openProcess(proc)
Opens the process for reading/writing of memory. Returns a handle to the process, or 0 on failure. Accepts a process ID. You should use findProcess() if applicable. You should use closeProcess() to close the process handle when you are done, however, no serious problems will arise if you forget.
You should store the handle in a variable; You will need it for reading and writing memory.
Example - Using process ID
myProcess = openProcess( 1234 );
if( myProcess == 0 ) then
print("Could not find and open the process");
end
Example - Using window name
myProcess = openProcess( findProcess("The window name") );
if( myProcess == 0 ) then
print("Could not find and open the process");
end
closeProcess
closeProcess(proc)
Closes the specified handle to the process. You should close any handles that you are no longer using, but it is not necessary. MicroMacro will automatically close any handles that have gone out of scope in your scripts. Closing process handles will help to free system resources when needed, but is unnecessary unless you are opening hundreds of processes in a short amount of time.
Example
myProcess = openProcess( findProcess("The window name") );
closeProcess( myProcess ); -- myprocess is closed. You must re-open it in order to
-- read or write memory from/to it.
findProcess
process findProcess(windowname)
Finds the window's process with the specified window name. Must be exact, but accepts wild cards '*' and '?'. Returns a process ID on success, 0 on failure. This will only return on the first window to match; so you might not find the correct window if multiple windows have the same, or similar, names.
Example - No wild cards
myProcess = openProcess( findProcess("Mozilla Firefox") );
This example will target only windows named exactly "Mozilla Firefox".
Example - Single character wild cards
myProcess = openProcess( findProcess("M?zilla F?refox") );
This example will target windows named "M_zilla F_refox" where _ can be any single character. This would match "Mozilla Firefox" as well as "Mazilla Forefox".
Example - Full wild cards
myProcess = openProcess( findProcess("Mozilla *") );
This example will target windows named that start with "Mozilla ", including "Mozilla Firefox" as well as "Mozilla Thunderbird", but not "Mozilla" (because of the lack of a trailing space).
findProcessByExe
process findProcessByExe(exeName)
Finds the application's process with the specified name. Accepts wildcards '*' and '?'. Returns a process ID on success, 0 on failure. This will only return on the first process to match; so you might not find the correct process if multiple processes have the same, or similar, names.
Returns 0 if the process is not found.
See findProcess() for more information on wild cards.
Example
myProcess = openProcess( findProcessById("mygame.exe") );
findProcessByWindow
process findProcessByWindow(window)
Finds the process which belongs to the specified window. Returns a process ID on success, 0 on failure.
See findProcess() for more information on wild cards.
Example
win = findWindow("Untitled - Notepad");
proc = findProcessByWindow(win)
findWindow
number findWindow(windowName) number findWindow(windowName, className)
Finds the window with the specified name. Accepts wildcards '*' and '?'. Returns a handle to the window on success, 0 on failure. This will only return on the first window to match; so you might not find the correct window if multiple windows have the same, or similar, names.
You may also, optionally, provide a class name to target specific processes or parts of processes. In example, the section of Notepad in which you can type has a classname of 'EDIT'. Using findWindow() and providing the 'EDIT' class name will allow you to find the handle to the edit box so that you are able to attach to it.
In some games, the client window will be given a specific classname. For example, Runes of Magic uses the class name "Radiant Arcana". You can use this to make sure you are finding the correct window rather than anything with "Runes of Magic" in the title (such as if you are browsing the Runes of Magic website, your web browser will contain "Runes of Magic" in the window title).
See findProcess() for more information on wild cards.
Example
myWindow = findWindow("Untitled - Notepad");
findWindowList
table findWindowList(windowName)
Finds all windows that match the specified mask. Accepts wildcards '*' and '?'. Returns a full table on success, or an empty table on failure. You may use getWindowName() to find each window's name.
See findProcess() for more information on wild cards.
Example
myList = findWindowList("Untitled - Notepad");
for i = 1,#myList do
printf("Found window %x [%s]\n", myList[i], getWindowName(myList[i]));
end
foregroundWindow
window foregroundWindow()
Finds the window that is on top. Returns a handle to the window on success, 0 on failure.
Example
myWindow = foregroundWindow();
windowValid
bool windowValid(win)
Returns true if a window handle is still valid or not. You may use this to detect if a window has been closed.
Do not rely on this too heavily; Windows recycles handles and it is possible a new window was created with the same handle.
Example
win = findWindow("Something");
printf("Close the window \'Something\'\n");
while( windowValid(win) ) do -- wait for the window to be closed.
yrest(100);
end
getHwnd
window getHwnd()
Returns MicroMacro's window. You can use this to set the window title of the calling MicroMacro window.
Example
mmwin = getHwnd();
setWindowName(mmwin, "This is an example");
getWindowName
string getWindowName(window)
Returns the window title of the specified window.
Example
win = findWindow("*");
printf("Found window is named: %x\n", getWindowName(win));
getWindowClassName
string getWindowClassName(window)
Returns the window's class name of the specified window.
Example
win = findWindow("*");
printf("Found window's class name is named: %x\n", getWindowClassName(win));
setWindowName
setWindowName(window, name)
Changes the specified window's title.
Example
win = findWindow("*");
setWindowName(win, "Changed");
After running the above example, the first window found by findWindow() will have it's window title changed to "Changed".
windowRect
x,y,w,h windowRect(window)
Returns the rectangle that contains the window. 4 integers are returned: x, y, width, height (in that order). If the window is minimized, x and y will be -32000 while width and height will be 0. Variables x and y represent the top-left corner of the client region of the window. Variables width and height represent the width and height of the client area within the window. This can be used to find the top left corner of the window to be used as offset values in functions such as mouseSet() to ensure that the coordinates are within the window's boundaries. It may also be used to find which resolution a user is running the target program under.
Example
window = findWindow("Untitled - Notepad");
x,y,w,h = windowRect(window);
printf("window is at (%d,%d) and is %d wide, and %d high.", x, y, w, h);
openDC
hdc openDC(window)
Returns the Handle to Device Context (HDC) of the specified window. Some functions may require an HDC to read/draw to and from their screen bitmaps.
Typically, you will want to only open an HDC to a window once and leave it open until it is no longer needed. Do not continuously re-open an HDC to the same window all the time, as this consumes system resources.
Example
window = findWindow("Untitled - Notepad");
hdc = openDC(window);
closeDC
closeDC(hdc)
Releases a Handle to Device Context that was retrieved using openDC(). You do not need to use this function, as the HDC will automatically be closed once the variable goes out of scope, however, it is in good practice to do so.
Example
window = findWindow("Untitled - Notepad");
hdc = openDC(window);
closeDC(hdc);
makeColor
color makeColor(r, g, b)
Returns a color value for the given red, green, blue values. r, g, and b should be an integer between 0 and 255.
Example
pink = makeColor(255, 0, 255);
getR
int getR(color)
Returns the red channel value for the given color. The returned value will be between 0 and 255.
Example
pink = makeColor(255, 0, 247);
red = getR(pink); -- red will be 255
getG
int getG(color)
Returns the green channel value for the given color. The returned value will be between 0 and 255.
Example
pink = makeColor(255, 0, 247);
green = getG(pink); -- green will be 0
getB
int getB(color)
Returns the blue channel value for the given color. The returned value will be between 0 and 255.
Example
pink = makeColor(255, 0, 247);
blue = getB(pink); -- blue will be 247
getPixel
r,g,b getPixel(hdc, x, y)
Returns the red, green, and blue values of the pixel located at (x,y) on the HDC (opened by openDC()). This can be used to read color values from the screen. The coordinates, x and y, are window coordinates, not screen coordinates! The returned values (r, g, b) will be integers between 0 (none) and 255 (full).
Note that if the user is running under different color depth, has a vastly different video card, or different video settings, it could cause the color values returned to be different by up to (on average) +- 15 per channel. You should always allow for a wide range per channel if you are checking a specific pixel for information.
Example
hdc = openDC( findWindow("Untitled - Notepad") );
r,g,b = getPixel(hdc, 12, 24);
printf("RGB: %d, %d, %d", r, g, b);
setPixel
setPixel(hdc, x, y, color)
Draws a pixel onto the HDC at (x,y) with color 'color'. 'color' should be generated through the use of makeColor().
If you will be writing pixels to the screen often (say, in a for loop), then it is not good practice to continuously call makeColor() to generate a color value. If you will be using the same color over and over, generate the color once, store it in a variable, and use the variable instead.
Example
hdc = openDC( findWindow("Untitled - Notepad") );
setPixel(hdc, 12, 24, makeColor(255,0,255));
pixelSearch
x,y pixelSearch(hdc, color, x1, y1, x2, y2)
x,y pixelSearch(hdc, color, x1, y1, x2, y2, accuracy)
x,y pixelSearch(hdc, color, x1, y1, x2, y2, accuracy, step)
Scans 'hdc' within the rectangle represented by (x1,y1)(x2,y2) for a pixel that matches the given color.
If 'accuracy' is not given, it is assumed to be 0 (exact match). Otherwise, all color channels must be within 'accuracy' units of the given color for a match to take place. A higher 'accuracy' level means that the colors do not need to match as closely.
If 'step' is not given, it is assumed to be 1. Otherwise, the algorithm will skip some number of pixels. For example, if 'step' is 2, then every other pixel will be scanned (across both X and Y axis). Using a higher 'step' value will cause the search to be quicker in most cases, however, it may skip pixels that should otherwise cause a match.
If the pixel is not found within the specified area, then pixelSearch() will return -1, -1.
Example
hdc = openDC( findWindow("Untitled - Notepad") );
matchcolor = makeColor(0, 0, 0); -- we're looking for black (text)
x,y = pixelSearch(hdc, matchcolor, 0, 0, 1024, 768, 0, 4);
--(x,y) should now represent a point near the very first detected character
--entered into notepad that is on the screen.
drawLine
drawLine(hdc, x1, y1, x2, y2, color, size)
Draws a line onto the hdc from (x1,y1) to (x2,y2) with the given color and size. 'color' should be generated using makeColor(), and size should be an integer specifying the width of the line in pixels.
Example
window = findWindow("Untitled - Notepad");
hdc = openDC(window);
drawLine(hdc, 32,32, 128,64, makeColor(255, 0, 255), 2);
drawRect
drawRect(hdc, x1, y1, x2, y2, color, size)
Draws a rectangle onto the hdc from (x1,y1) to (x2,y2) with the given color and size. 'color' should be generated using makeColor(), and size should be an integer specifying the width of the lines in pixels.
Example
window = findWindow("Untitled - Notepad");
hdc = openDC(window);
drawRect(hdc, 32,32, 128,64, makeColor(255, 0, 255), 2);
saveScreenshot
saveScreenshot(window, filename)
This will save a bitmap screenshot of a specified window (or use 0 for the desktop) as the given filename. 'filename' may include a full or relative path, and should include the '.bmp' extension.
showWindow
showWindow(window, command)
Allows you to show, hide, minimize, and maximize windows. 'window' should be obtained through findWindow() or similar functions. 'command' should be one of the following:
sw.show -- activate (show and set focus to) the window sw.shownormal -- activate and restore to original size and position sw.hide -- hide the window sw.forceminimize -- forcefully minimize (also hides the window) sw.minimize -- minimize the window sw.maximize -- activate and maximize the window sw.restore -- activate the window and restore to original size and position (used after minimizing)
Example
window = findWindow("Untitled - Notepad");
showWindow(window, sw.show);
findPatternInProcess
number findPatternInProcess(process, pattern, mask, startAddress, length)
Returns the address of the start of a pattern within a process. 'process' should be gathered by using openProcess. 'pattern' will be a string of bytes containing values you which to search, and 'mask' will be a string-mask explaining which values must match and which ones can be 'wild-cards'. 'startAddress' will denote where to begin searching, and 'length' will be the number of bytes to scan before giving up.
In most cases, you will be looking for a series of bytes. In this case, it makes more sense to take advantage of string.char() rather than using a direct string of bytes. In your 'mask', you should use the character 'x' to represent a character that should match, and the character '?' to represent a 'wild-card'.
If the pattern is not found, findPatternInProcess() will return 0.
Example:
local pattern = string.char(0x8B, 0x07, 0x8B, 0x0D, 0xFF, 0xFF, 0xE8, 0x50);
local mask = "xxxx??xx";
-- Using this pattern and mask combination, we'll be looking for:
-- 8B 07 8B 0D ?? ?? E8 50
local foundAddress = findPatternInProcess(proc, pattern, mask, 0x400000, 0x10000);
if( foundAddress == 0 ) then
printf("Failed to find the pattern in the process.\n");
end
getModuleAddress
number getModuleAddress(procid, module)
Returns the address of a given module inside of the specified address. This can be used to find the origin of a process (by specifying "whatever.exe" for the module name) or to find the location of a dynamic link library in memory (by providing "whatever.dll" for the module name).
Note that 'procid' should be the process identifier (use findProcess* functions for this), not a handle returned by openProcess().
Example:
local notepadOrigin = getModuleAddress(notepadProc, "notepad.exe");
flashWindow
flashWindow(window, count)
Causes the specified window to "flash" in an attempt to grab the users attention. If 'window' is not specified, the calling MicroMacro instance will be used. 'count' refers to how many times the window will flash. If 'count' is 0, the window will continue to flash until it is pulled into the foreground by the user.
Example:
flashWindow(); -- flash MicroMacro window until user focuses it
flashWindow(nil, 10);-- flash MicroMacro window 10 times
flashWindow(findWindow("notepad"), 0);-- flash Notepad until it is focused
flashWindow(nil, -1); -- Stop flashing MicroMacro window