Skip to content

Exe Object

Jump to bottom
Neo edited this page Feb 21, 2022 · 13 revisions

Exe

The Exe object always points to the currently loaded application.

It provides a bunch of properties and a generous set of functions for accessing its internals and for setting up changes for a patch.

Table of Contents


Properties

Property name Description
Exe.PEoffset The PHYSICAL address of the PE header
Exe.ImageBase Base Address where the exe is loaded in memory
Exe.BuildDate The application's build date in the form yyyymmdd
Exe.Version The major linker version used for building this app
Exe.MinorVer The minor linker version used for building this app
Exe.Unpacked Boolean value. Self explanatory
Exe.FileSize Self explanatory
Exe.FilePath Self explanatory

User Input functions

GetUserInput

Allows you to collect inputs from user (by means of an Input Dialog containing the relevant controls) in your Patches & Extensions. The controls are added to the dialog based on the DataType specified.

You can either use the value returned from the function or retrieve it later with the GetSavedInput function .

Syntax:

Exe.GetUserInput(varName, dtype, title, prompt, defValue, constraints)
Argument Description
varName Every input value needs a way to refer it later.
For this purpose, we make use of a 'variable name'.
dtype DataType of the user input expected.
The controls shown in the Input dialog will differ based on this.
title The title text to use for the Input dialog shown.
prompt The prompt text to use for the Input dialog shown.
Ideally you should briefly describe what the input is for.
defValue Default value for the input.
This value is seperately displayed in the Input dialog shown and also serves as an initial value.

You can opt to save or ignore the default value by means of the saveDefault constraint explained below.
constraints This is an optional hash map specifying the constraints which vary based on the type of input.

The constraints if specified, need to be in the form:

{
    name1: <value1>,
    name2: <value2>
}

Currently the following constraint names are recognized:

Name Applicable
DataTypes		 Default Value Description
minWidth
minHeight 		All of them Auto fit to contents Override the minimum width & height of the dialog.
Useful when the prompt & input field(s) make the dialog too small.
maxWidth
maxHeight 		All of them Window size Override the maximum width & height of the dialog.
Useful if you want to restrict the dialog to a certain size.
acceptText All of them Yes for D_Bool
OK for the other DataTypes		 Label to use for the accept button.
rejectText All of them No for D_Bool
Cancel for the other DataTypes		 Label to use for the reject button.
saveDefault All of them true for D_InFile, D_OutFile & D_Folder
false for other DataTypes		 Indicates whether the tool should save default values or not when the user chooses them.
If the default value need not be saved then the function returns false when the user picks the default value.
saveAsBytes All of them false for D_Vec*, D_MultiChoice & D_Bool
true for other DataTypes		 Indicates whether the tool should save the internal byte array representation as well.
min , max D_Int*
D_Uint*
D_FontSize
D_Float
D_VecI*
D_VecU*
D_VecF 		-128, 127 for D_Int8 & D_VecI8
-32768, 32767 for D_Int16 & D_VecI16
-2147483647, 2147483647 for D_Int32 & D_VecI32
0, 255 for D_Uint8 & D_VecU8
0, 65535 for D_Uint16 & D_VecU16
0, 2147483647 for D_Uint32 & D_VecU32
1, 255 for D_FontSize
0.0, 100.0 for D_Float & D_VecF 		Lower & Upper limits for numeric DataTypes.
For vector types, the limit will apply for all individual members.
stepSize D_Int*
D_Uint*
D_Float
D_VecI*
D_VecU*
D_VecF		 0.1 for D_Float & D_VecF
1 for the others		 Increments to be used for numeric inputs i.e. value to be added/subtracted when the +/- is clicked respectively.
For vector types, the limit will apply for all individual members.
precision D_Float
D_VecF		 1.0 Precision value to use for floating point inputs i.e. no of decimal digits needed.
minLen
maxLen 		D_Text
D_FontName
D_InFile
D_OutFile
D_Folder		 1 - 32768 characters for the others Length limits for string DataTypes.
If the user enters a string less than minimum length then a blank space is added.
align D_Text
D_FontName
D_InFile
D_OutFile
D_Folder		 right Alignment for the string (in case padding needs to be done).
Possible values are right or left .
encoding D_Text
D_FontName
D_InFile
D_OutFile
D_Folder		 ASCII Specifies the Encoding to use while saving the string internally.
byteCount D_Hex 1 Length limit for Hex DataType.
If the user enters lesser characters, 0 is padded to the left.
endian D_Hex big Specifies the endianness of the displayed value.
Can be either big or little.
min0 , max0
min1 , max1
min2 , max2
min3 , max3 		D_VecI*
D_VecU*
D_VecF		 Same as min & max specified above Lower & Upper limits for each individual member of the vector
(upto 4 members are allowed, hence the 4 set of constraints).
name0
name1
name2
name3
 D_VecI*
D_VecU*
D_VecF		 Index0
Index1
Index2
Index3
 Names to be used for indicating the purpose of each individual member of the vector
For e.g. coordinates can have name0: "X", name1: "Y" .
stepSize0
stepSize1
stepSize2
stepSize3
 D_VecI*
D_VecU*
D_VecF		 Same as stepSize specified above Increment to be used for individual members of the vector
choices D_Choice
D_MultiChoice		 None Mandatory argument for specifying the list of choices to select from.
There is no type restriction on the individual elements.
format D_Color ARGB Specifies the order in which the Red, Green, Blue & Alpha components need to be kept.

Can be any combination of letters A, R, G, B and any component that is not specified will not be altered.

You can use the keys below to set the skipped components' value for displaying in dialog.
R, G, B, A D_Color 255 Specifies the fixed value to use for the component color not included in the format.
dataSize D_Bool 1 Specifies the number of bytes to be used for saving the boolean result internally.

Returns: the saved value or false if it got cancelled OR input value was not saved


GetSavedInput

Retrieve an existing user input value that was previously saved with GetUserInput.

Syntax:

Exe.GetSavedInput(varName)
Argument Description
varName Variable Name which was used for saving the user input earlier.

Returns: the saved value or empty value if varName was not found


ClearSavedInput

Clears an existing user input that was previously saved with GetUserInput.

Syntax:

Exe.ClearSavedInput(varName)
Argument Description
varName Variable Name which was used for saving the user input earlier.
More useful for Test Bench when the Keep test inputs option is ON.

|


Patch setup functions

SetActivePatch

Sets a patch as the active one. All other Set* and Add* functions setup changes into the active patch. This is equivalent to setting Exe.ActivePatch to the patch name directly.

Syntax:

Exe.SetActivePatch(name)
Argument Description
name The name of the Patch.

ClearPatch

Clears any modifications/changes staged and address allocations (in DIFF section) for the specified patch.

Syntax:

Exe.ClearPatch(name)
Argument Description
name The name of the Patch.

ActivateGlobal

The Exe has an inbuilt Global patch that can be used for staging changes and address allocations common to multiple patches. This function sets up the Global patch as active one.

Syntax:

Exe.ActivateGlobal()

ClearGlobal

Clears all modifications/changes staged and address allocations made with Global patch.

Syntax:

Exe.ClearGlobal()

Section retrieval functions

GetSectBegin

Retrieves the starting address of a section.

Syntax:

Exe.GetSectBegin(stype, [atype])
Argument Description
stype SectionType specifying the section.
atype Optional AddrType of the returned address.
If omitted the PHYSICAL address is returned.

Returns: the requested address or -1 in case of failure.


GetSectEnd

Retrieve the ending address of a section.

Syntax:

Exe.GetSectEnd(stype, [atype])
Argument Description
stype SectionType specifying the section.
atype Optional AddrType of the returned address.
If omitted the PHYSICAL address is returned.

Returns: the requested address or -1 in case of failure.


GetSectSize

Retrieve the size of the section. Equivalent to Exe.GetSectEnd - Exe.GetSectBegin.

Syntax:

Exe.GetSectSize(stype, [atype])
Argument Description
stype SectionType specifying the section.
atype Optional AddrType denoting the size required.
If omitted the PHYSICAL size is returned.

Returns: the requested size or 0 in case of failure.


Data Directory retrieval functions

GetDirAddr

Retrieve the starting address of an Image Data Directory. It is also possible to 'reflect' the change from patches

Syntax:

Exe.GetDirAddr(dtype, [atype], [reflect])
Exe.GetDirAddr(dtype, [reflect])
Argument Description
dtype DirType specifying the Data Directory.
atype Optional AddrType of the returned address.
If omitted the VIRTUAL address is returned.
reflect Optional boolean to indicate whether existing changes done by patches should be 'reflect'ed.
Default is false.

Returns: the requested address or -1 in case of failure.


GetDirSize

Retrieve the size of an Image Data Directory. There is no PHYSICAL & VIRTUAL distinction for this one. As before, reflection can be done.

Syntax:

Exe.GetDirSize(dtype, [reflect])
Argument Description
dtype DirType specifying the Data Directory.
reflect Optional boolean to indicate whether existing changes done by patches should be 'reflect'ed.
Default is false.

Returns: the requested size or 0 in case of failure.


Address Converters

Phy2Vir

Converts a PHYSICAL address to VIRTUAL.

Syntax:

Exe.Phy2Vir(addr, [stype])
Argument Description
addr The PHYSICAL address to be converted.
stype Optional SectionType to restrict conversion to a specific section
i.e. addr is only converted if it is in the section specified.

Returns: the VIRTUAL address or -1 in case of failure.


Phy2Rva

Converts a PHYSICAL address to Relative VIRTUAL address. Basically same as above - ImageBase.

Syntax:

`Exe.Phy2Rva(addr, [stype])
Argument Description
addr The PHYSICAL address to be converted.
stype Optional SectionType to restrict conversion to a specific section
i.e. addr is only converted if it is in the section specified.

Returns: the relative VIRTUAL address or -1 in case of failure.


Vir2Phy

Converts a VIRTUAL address to PHYSICAL.

Syntax:

Exe.Vir2Phy(addr, [stype])
Argument Description
addr The VIRTUAL address to be converted.
stype Optional SectionType to restrict conversion to a specific section
i.e. addr is only converted if it is in the section specified.

Returns: the PHYSICAL address or -1 in case of failure.


Rva2Phy

Converts a relative VIRTUAL address to PHYSICAL.

Syntax:

Exe.Rva2Phy(addr, [stype])
Argument Description
addr The relative VIRTUAL address to be converted.
stype Optional SectionType to restrict conversion to a specific section
i.e. addr is only converted if it is in the section specified.

Returns: the PHYSICAL address or -1 in case of failure.


Content Extractors

All the functions in this category allow for reflection of changes staged by patches while retrieving the data.

GetInt*

Extracts 8 / 16 / 32 bits (1 / 2 / 4 bytes) of data as a signed integer from specified address.

Syntax:

Exe.GetInt8(from, [reflect])
Exe.GetInt16(from, [reflect])
Exe.GetInt32(from, [reflect])
Argument Description
from The address in the Exe from where we need to extract the integer.
reflect Optional boolean to indicate whether existing changes done by patches should be 'reflect'ed.
Default is false.

Returns: the extracted integer or 0 in case of failure.


GetUint*

Extracts 8 / 16 / 32 bits (1 / 2 / 4 bytes) of data as an unsigned integer from specified address.

Syntax:

Exe.GetUint8(from, [reflect])
Exe.GetUint16(from, [reflect])
Exe.GetUint32(from, [reflect])
Argument Description
from The address in the Exe from where we need to extract the integer.
reflect Optional boolean to indicate whether existing changes done by patches should be 'reflect'ed.
Default is false.

Returns: the extracted integer or 0 in case of failure.


GetFloat

Extracts 32 bits (4 bytes) of data as a floating point number from specified address.

Syntax:

Exe.GetFloat(from, [reflect])
Argument Description
from The address in the Exe from where we need to extract the number.
reflect Optional boolean to indicate whether existing changes done by patches should be 'reflect'ed.
Default is false.

Returns: the extracted floating point number or 0 in case of failure.


GetBytes

Extracts the specified number of bytes as a list (with all members as 8 bit unsigned integers).

Syntax:

Exe.GetBytes(from, size, [reflect])
Argument Description
from The address in the Exe from where we need to extract the bytes.
If it comes at the end of the file or is at a NULL byte, then an empty string is returned.
size No of bytes to be read.
reflect Optional boolean to indicate whether existing changes done by patches should be 'reflect'ed.
Default is false.

Returns: the extracted list or an empty list in case of failure.


GetHex

Extracts the specified number of bytes as a hex string.

Syntax:

Exe.GetHex(from, size, [reflect])
Argument Description
from The address in the Exe from where we need to extract the bytes.
If it comes at the end of the file then an empty string is returned.
size No of bytes to be read.
reflect Optional boolean to indicate whether existing changes done by patches should be 'reflect'ed.
Default is false.

Returns: the extracted hex string or empty string in case of failure.


GetText

Extracts the specified number of bytes (or till \0) as a text string.

Syntax:

Exe.GetText(from, size, [reflect])
Exe.GetText(from, enc, [reflect])
Exe.GetText(from, enc, size, [reflect])
Argument Description
from The address in the Exe from where we need to extract the bytes.
If it comes at the end of the file or is at a NULL byte, then an empty string is returned.
size No of bytes to be read. The default is -1.
If it is negative then the tool looks for NULL termination to determine the size.
enc Optional Encoding of the text string. If omitted, the text will be ASCII encoded.
reflect Optional boolean to indicate whether existing changes done by patches should be 'reflect'ed.
Default is false.

Returns: the extracted text string or empty string in case of failure.


GetTgtAddr

Extracts the specified number of bytes as a distance value and calculate the target address.

The address specified is expected to be following a Direct Call or Jump opcode.

Syntax:

Exe.GetTgtAddr(source, [reflect])
Exe.GetTgtAddr(source, atype, [reflect])
Exe.GetTgtAddr(source, travel, [reflect])
Exe.GetTgtAddr(source, atype, travel, [reflect])
Argument Description
source The source address from where we need to retrieve the distance value.
travel No of bytes to read. Should be either 1, 2 or 4. Default is 4.
atype Optional AddrType of the returned address.
If omitted the VIRTUAL address is returned.
reflect Optional boolean to indicate whether existing changes done by patches should be 'reflect'ed.
Default is false.

Returns: the calculated target address or -1 in case of failure.


Content query functions

FindHex

Searches the Exe for a hex pattern in forward direction.

Syntax:

Exe.FindHex(pattern, [from], [to])
Argument Description
pattern The hex pattern to look for. It can contain wildcard characters such as ?, [, . and ].
See Writing scripts for more details.
from The address where the search should start. The default is -1.
If it is negative, then the search starts from the beginning of the CODE section.
to The address where the search should end. The default is -1.
If it is negative, then the search proceeds till the end of the CODE section.

Returns: the matched address or -1 in case of failure.


FindHexN

Same as FindHex but looks for multiple matches.

Syntax:

Exe.FindHexN(pattern, [from], [to])
Exe.FindHexN(maxCount, pattern, [from], [to])
Exe.FindHexN(minCount, maxCount, pattern, [from], [to])
Argument Description
minCount Optional minimum no. of matches to pick up.
If there isn't enough matches then an empty list is returned.
maxCount Optional maximum no. of matches to pick up.
If omitted, all the matching addresses are retrieved (> minCount if specified).
pattern The hex pattern to look for.
It can contain wildcard characters such as ?, [, . and ].
See Writing scripts for more details.
from Optional address where the search should start.
If omitted or negative, then the search starts from the beginning of the CODE section.
to Optional address where the search should end.
If omitted or negative, then the search proceeds till the end of the CODE section.

Returns: the list of matching addresses or an empty list in case of failure.


FindLastHex

Searches the Exe for a hex pattern in reverse direction i.e. greater to lesser addresses. Therefore the last match is picked up.

Syntax:

Exe.FindLastHex(pattern, [from], [to])
Argument Description
pattern The hex pattern to look for.
It can contain wildcard characters such as ?, [, . and ].
See Writing scripts for more details.
from Optional address where the search should start.
If omitted or negative, then the search starts from the end of the CODE section.
to Optional address where the search should end.
If omitted or negative, then the search proceeds till the beginning of the CODE section.

Returns: the matched address or -1 in case of failure.


FindLastHexN

Same as FindLastHex but looks for multiple matches. The last match is picked up first and the list will be in descending order as a result.

Syntax:

Exe.FindLastHexN(pattern, [from], [to])
Exe.FindLastHexN(maxCount, pattern, [from], [to])
Exe.FindLastHexN(minCount, maxCount, pattern, [from], [to])
Argument Description
minCount Optional minimum no. of matches to pick up.
If there isn't enough matches then an empty list is returned.
maxCount Optional maximum no. of matches to pick up.
If omitted, all the matching addresses are retrieved (> minCount if specified).
pattern The hex pattern to look for. It can contain wildcard characters such as ?, [, . and ].
See Writing scripts for more details.
from Optional address where the search should start.
If omitted or negative, then the search starts from the end of the CODE section.
to Optional address where the search should end.
If omitted or negative, then the search proceeds till the beginning of the CODE section.

Returns: the list of matching addresses or an empty list in case of failure.


FindText

Searches the Exe for a text string in forward direction with options for encoding & case sensitivity.

Syntax:

Exe.FindText(text, [from], [to])
Exe.FindText(text, atype, [from], [to])
Exe.FindText(text, atype, prefixNull, [from], [to])
Exe.FindText(text, prefixNull, [from], [to])
Exe.FindText(text, prefixNull, suffixNull, [from], [to])
Exe.FindText(text, atype, prefixNull, suffixNull, [from], [to])

Exe.FindText(text, cs, [from], [to])
Exe.FindText(text, cs, atype, [from], [to])
Exe.FindText(text, cs, atype, prefixNull, [from], [to])
Exe.FindText(text, cs, prefixNull, [from], [to])
Exe.FindText(text, cs, prefixNull, suffixNull, [from], [to])
Exe.FindText(text, cs, atype, prefixNull, suffixNull, [from], [to])

Exe.FindText(text, enc, [from], [to])
Exe.FindText(text, enc, atype, [from], [to])
Exe.FindText(text, enc, atype, prefixNull, [from], [to])
Exe.FindText(text, enc, prefixNull, [from], [to])
Exe.FindText(text, enc, prefixNull, suffixNull, [from], [to])
Exe.FindText(text, enc, atype, prefixNull, suffixNull, [from], [to])
Argument Description
text The text string to look for.
cs Optional case Sensitivity of the text string.
If omitted, match will be CASE_SENSITIVE.
Only works with the default encoding i.e. ASCII.
enc Optional Encoding of the text string.
If omitted, the text will be considered to be ASCII encoded.
atype Optional AddrType of the returned address.
If omitted, the VIRTUAL address is returned.
prefixNull Optional Boolean indicating whether we should only match when a NULL byte is present before the text string.
If omitted, NULL is prefixed
suffixNull Optional Boolean indicating whether we should only match when a NULL byte is present after the text string.
If omitted, NULL is suffixed
from Optional address where the search should start.
If omitted or negative, then the search occurs within both DATA & DATA2 sections.
to Optional address where the search should end.
If omitted or negative, then the search proceeds till the end of the DATA/DATA2 sections OR the end of the file if from address is provided

Returns: the matched address or -1 in case of failure.


FindTextN

Same as FindText but looks for multiple matches.

Syntax:

Exe.FindTextN(text, [from], [to])
Exe.FindTextN(text, atype, [from], [to])
Exe.FindTextN(text, atype, prefixNull, [from], [to])
Exe.FindTextN(text, prefixNull, [from], [to])
Exe.FindTextN(text, prefixNull, suffixNull, [from], [to])
Exe.FindTextN(text, atype, prefixNull, suffixNull, [from], [to])

Exe.FindTextN(text, cs, [from], [to])
Exe.FindTextN(text, cs, atype, [from], [to])
Exe.FindTextN(text, cs, atype, prefixNull, [from], [to])
Exe.FindTextN(text, cs, prefixNull, [from], [to])
Exe.FindTextN(text, cs, prefixNull, suffixNull, [from], [to])
Exe.FindTextN(text, cs, atype, prefixNull, suffixNull, [from], [to])

Exe.FindTextN(text, enc, [from], [to])
Exe.FindTextN(text, enc, atype, [from], [to])
Exe.FindTextN(text, enc, atype, prefixNull, [from], [to])
Exe.FindTextN(text, enc, prefixNull, [from], [to])
Exe.FindTextN(text, enc, prefixNull, suffixNull, [from], [to])
Exe.FindTextN(text, enc, atype, prefixNull, suffixNull, [from], [to])

Exe.FindTextN(count, text, [from], [to])
Exe.FindTextN(count, text, atype, [from], [to])
Exe.FindTextN(count, text, atype, prefixNull, [from], [to])
Exe.FindTextN(count, text, prefixNull, [from], [to])
Exe.FindTextN(count, text, prefixNull, suffixNull, [from], [to])
Exe.FindTextN(count, text, atype, prefixNull, suffixNull, [from], [to])

Exe.FindTextN(count, text, cs, [from], [to])
Exe.FindTextN(count, text, cs, atype, [from], [to])
Exe.FindTextN(count, text, cs, atype, prefixNull, [from], [to])
Exe.FindTextN(count, text, cs, prefixNull, [from], [to])
Exe.FindTextN(count, text, cs, prefixNull, suffixNull, [from], [to])
Exe.FindTextN(count, text, cs, atype, prefixNull, suffixNull, [from], [to])

Exe.FindTextN(count, text, enc, [from], [to])
Exe.FindTextN(count, text, enc, atype, [from], [to])
Exe.FindTextN(count, text, enc, atype, prefixNull, [from], [to])
Exe.FindTextN(count, text, enc, prefixNull, [from], [to])
Exe.FindTextN(count, text, enc, prefixNull, suffixNull, [from], [to])
Exe.FindTextN(count, text, enc, atype, prefixNull, suffixNull, [from], [to])
Argument Description
count Optional maximum no of matches to pick up.
If omitted, all the matching addresses are retrieved.
text The text string to look for.
cs Optional case Sensitivity of the text string.
If omitted, match will be CASE_SENSITIVE.
Only works with the default encoding i.e. ASCII.
enc Optional Encoding of the text string.
If omitted, the text will be considered to be ASCII encoded.
atype Optional AddrType of the returned address.
If omitted, the VIRTUAL address is returned.
prefixNull Optional Boolean indicating whether we should only match when a NULL byte is present before the text string.
If omitted, NULL is prefixed
suffixNull Optional Boolean indicating whether we should only match when a NULL byte is present after the text string.
If omitted, NULL is suffixed
from Optional address where the search should start.
If omitted or negative, then the search occurs within both DATA & DATA2 sections.
to Optional address where the search should end.
If omitted or negative, then the search proceeds till the end of the DATA/DATA2 sections OR the end of the file if from address is provided

Returns: the list of matching addresses or an empty list in case of failure.


FindLastText

Searches the Exe for a text string in reverse direction i.e. greater to lesser addresses. Therefore the last match is picked up.

Syntax:

Exe.FindLastText(text, [from], [to])
Exe.FindLastText(text, atype, [from], [to])
Exe.FindLastText(text, atype, prefixNull, [from], [to])
Exe.FindLastText(text, prefixNull, [from], [to])
Exe.FindLastText(text, prefixNull, suffixNull, [from], [to])
Exe.FindLastText(text, atype, prefixNull, suffixNull, [from], [to])

Exe.FindLastText(text, cs, [from], [to])
Exe.FindLastText(text, cs, atype, [from], [to])
Exe.FindLastText(text, cs, atype, prefixNull, [from], [to])
Exe.FindLastText(text, cs, prefixNull, [from], [to])
Exe.FindLastText(text, cs, prefixNull, suffixNull, [from], [to])
Exe.FindLastText(text, cs, atype, prefixNull, suffixNull, [from], [to])

Exe.FindLastText(text, enc, [from], [to])
Exe.FindLastText(text, enc, atype, [from], [to])
Exe.FindLastText(text, enc, atype, prefixNull, [from], [to])
Exe.FindLastText(text, enc, prefixNull, [from], [to])
Exe.FindLastText(text, enc, prefixNull, suffixNull, [from], [to])
Exe.FindLastText(text, enc, atype, prefixNull, suffixNull, [from], [to])
Argument Description
text The text string to look for.
cs Optional case Sensitivity of the text string. If omitted, match will be CASE_SENSITIVE.
Only works with the default encoding i.e. ASCII.
enc Optional Encoding of the text string.
If omitted, the text will be considered to be ASCII encoded.
atype Optional AddrType of the returned address.
If omitted, the VIRTUAL address is returned.
prefixNull Optional Boolean indicating whether we should only match when a NULL byte is present before the text string.
If omitted, NULL is prefixed
suffixNull Optional Boolean indicating whether we should only match when a NULL byte is present after the text string.
If omitted, NULL is suffixed
from Optional address where the search should start.
If omitted or negative, then the search occurs within both DATA2 & DATA sections. DATA2 is searched first.
to Optional address where the search should end.
If omitted or negative, then the search proceeds till the beginning of the DATA2/DATA sections OR the beginning of the file if from address is provided.

Returns: the matched address or -1 in case of failure.


FindLastTextN

Same as FindLastText but looks for multiple matches. The last match is picked up first and the list will be in descending order as a result.

Syntax:

Exe.FindLastTextN(text, [from], [to])
Exe.FindLastTextN(text, atype, [from], [to])
Exe.FindLastTextN(text, atype, prefixNull, [from], [to])
Exe.FindLastTextN(text, prefixNull, [from], [to])
Exe.FindLastTextN(text, prefixNull, suffixNull, [from], [to])
Exe.FindLastTextN(text, atype, prefixNull, suffixNull, [from], [to])

Exe.FindLastTextN(text, cs, [from], [to])
Exe.FindLastTextN(text, cs, atype, [from], [to])
Exe.FindLastTextN(text, cs, atype, prefixNull, [from], [to])
Exe.FindLastTextN(text, cs, prefixNull, [from], [to])
Exe.FindLastTextN(text, cs, prefixNull, suffixNull, [from], [to])
Exe.FindLastTextN(text, cs, atype, prefixNull, suffixNull, [from], [to])

Exe.FindLastTextN(text, enc, [from], [to])
Exe.FindLastTextN(text, enc, atype, [from], [to])
Exe.FindLastTextN(text, enc, atype, prefixNull, [from], [to])
Exe.FindLastTextN(text, enc, prefixNull, [from], [to])
Exe.FindLastTextN(text, enc, prefixNull, suffixNull, [from], [to])
Exe.FindLastTextN(text, enc, atype, prefixNull, suffixNull, [from], [to])

Exe.FindLastTextN(count, text, [from], [to])
Exe.FindLastTextN(count, text, atype, [from], [to])
Exe.FindLastTextN(count, text, atype, prefixNull, [from], [to])
Exe.FindLastTextN(count, text, prefixNull, [from], [to])
Exe.FindLastTextN(count, text, prefixNull, suffixNull, [from], [to])
Exe.FindLastTextN(count, text, atype, prefixNull, suffixNull, [from], [to])

Exe.FindLastTextN(count, text, cs, [from], [to])
Exe.FindLastTextN(count, text, cs, atype, [from], [to])
Exe.FindLastTextN(count, text, cs, atype, prefixNull, [from], [to])
Exe.FindLastTextN(count, text, cs, prefixNull, [from], [to])
Exe.FindLastTextN(count, text, cs, prefixNull, suffixNull, [from], [to])
Exe.FindLastTextN(count, text, cs, atype, prefixNull, suffixNull, [from], [to])

Exe.FindLastTextN(count, text, enc, [from], [to])
Exe.FindLastTextN(count, text, enc, atype, [from], [to])
Exe.FindLastTextN(count, text, enc, atype, prefixNull, [from], [to])
Exe.FindLastTextN(count, text, enc, prefixNull, [from], [to])
Exe.FindLastTextN(count, text, enc, prefixNull, suffixNull, [from], [to])
Exe.FindLastTextN(count, text, enc, atype, prefixNull, suffixNull, [from], [to])
Argument Description
count Optional maximum no of matches to pick up.
If omitted, all the matching addresses are retrieved.
text The text string to look for.
cs Optional case Sensitivity of the text string. If omitted, match will be CASE_SENSITIVE.
Only works with the default encoding i.e. ASCII.
enc Optional Encoding of the text string.
If omitted, the text will be considered to be ASCII encoded.
atype Optional AddrType of the returned address.
If omitted, the VIRTUAL address is returned.
prefixNull Optional Boolean indicating whether we should only match when a NULL byte is present before the text string.
If omitted, NULL is prefixed
suffixNull Optional Boolean indicating whether we should only match when a NULL byte is present after the text string.
If omitted, NULL is suffixed
from Optional address where the search should start.
If omitted or negative, then the search occurs within both DATA2 & DATA sections. DATA2 is searched first.
to Optional address where the search should end.
If omitted or negative, then the search proceeds till the beginning of the DATA2/DATA sections OR the beginning of the file if from address is provided.

Returns: the list of matching addresses or an empty list in case of failure.


FindFunc

Searches the Exe for the VIRTUAL address of an imported function.

Any function that was found for a loaded client, gets cached, to avoid repetitive searching.

Syntax:

Exe.FindFunc(name, [dllName])
Exe.FindFunc(ordinal, dllName)
Exe.FindFunc(name, ordinal, [dllName])
Argument Description
name Optional name of the function.
Either this or the ordinal need to be specified.
ordinal Optional ordinal number of the function.
dllName Optional name of the DLL it got imported from.
If provided, then the search gets restricted to that DLL alone.

Returns: The address of the function or -1 if not found.


Allocation Functions

To safely use the Set functions for staging changes in DIFF section, you need to allocate the required number of unused bytes first.

The DIFF section is intended to be a dynamically growing section and these functions end up enabling it's growth.

Allocate

Searches the Exe's DIFF section for the specified number of unused bytes, sets up the allocation and returns the list [ PHYSICAL address, VIRTUAL address, Size allocated ] when successful

The size required can be specified either directly or as a User Input (using it's variable name). In case of failure, a Space Allocation Failed error is flagged/reported.

Syntax:

Exe.Allocate(size, [snap])
Exe.Allocate(varName)
Argument Description
size The no of bytes to allocate
snap Optional snapping value. If provided, the starting address will be a multiple of this value.
The default is 1. One use case is if you want to keep function code aligned to 0x10.
varName Variable name of the previously saved user input.
No of bytes allocated = size of the internal byte array used to save the value.

Returns: [Phy Addr, Vir Addr, Size allocated] or empty list in case of failure.


FreeUp

Used for freeing up previously allocated spaces in DIFF section done with Allocate function

Syntax:

Exe.FreeUp(addr, size)
Argument Description
addr The starting address from where we need to free up the space
size The no of bytes to de-allocate/free

Content setters

All the functions listed below stage changes for overwriting some existing data OR pre-allocated addresses in the DIFF section. They can only be run from Patch Functions.

SetInt*

Adds an entry to overwrite 8 / 16 / 32 bits (1 / 2 / 4 bytes) of data with a signed integer.

Syntax:

Exe.SetInt8(addr, value)
Exe.SetInt16(addr, value)
Exe.SetInt32(addr, value)
Argument Description
addr The address where the data needs to be changed.
value The replacement integer value.

Returns: true if successful else false.


SetUint*

Adds an entry to overwrite 8 / 16 / 32 bits (1 / 2 / 4 bytes) of data with an unsigned integer.

Syntax:

Exe.SetUint8(addr, value)
Exe.SetUint16(addr, value)
Exe.SetUint32(addr, value)
Argument Description
addr The address where the data needs to be changed.
value The replacement integer value.

Returns: true if successful else false.


SetFloat

Adds an entry to overwrite 32 bits (4 bytes) of data with a floating point number.

Syntax:

Exe.SetFloat(addr, value)
Argument Description
addr The address where the data needs to be changed.
value The replacement floating point value.

Returns: true if successful else false.


SetBytes

Adds an entry to overwrite data with the provided list of bytes.

Syntax:

Exe.SetBytes(addr, bytelist)
Argument Description
addr The address where the data needs to be changed.
bytelist The replacement data expressed as a list of bytes.

Returns: the number of bytes affected or 0 in case of failure.


SetHex

Adds an entry to overwrite data with a hex string.

Syntax:

Exe.SetHex(addr, hexstring)
Argument Description
addr The address where the data needs to be changed.
hexstring The replacement data expressed as a hex string.

Returns: the number of bytes affected or 0 in case of failure.


SetText

Adds an entry to overwrite data with a text string.

Syntax:

Exe.SetText(addr, text, [enc])
Argument Description
addr The address where the data needs to be changed.
text The replacement data expressed as a text string.
enc Optional Encoding of the text string. If omitted, the text will be considered to be ASCII encoded.

Returns: the number of bytes affected or 0 in case of failure.


SetFromVar

Adds an entry to overwrite data with a previously saved user input value.

Syntax:

Exe.SetFromVar(addr, varName)
Argument Description
addr The address where the data needs to be changed.
varName Variable name of the user input.
Only works if the value was saved internally as a byte array.
No of bytes to alter = the size of the array.

Returns: the number of bytes affected or 0 in case of failure.


SetNOPs

Adds an entry to overwrite data with NOP instructions.

Syntax:

Exe.SetNOPs(addr, [count])**
Argument Description
addr The address where the data needs to be changed.
count The no of NOPs to be added. If omitted only 1 NOP is added.
Similarly if count > 6, then a JMP instruction is added to skip over the NOP s internally to avoid CPU cycle wastage.

Returns: true if successful else false.


SetJMP

Adds an entry to change the instruction at the specified address to a JMP. Short & Long jumps are taken care of automatically.

Works in 2 ways based on the arguments

  • Enforcing an existing conditional jump OR
  • Create a new jump to specified target address.
Exe.SetJMP(from) => 1st form
Exe.SetJMP(from, to, [extraNOPs])
Exe.SetJMP(from, to, tgtType, [extraNOPs])
Argument Description
from The address where the JMP needs to be put.
For the 1st form, there should be a conditional jump at this location.
to The destination address for the JMP.
tgtType Optional AddrType of the to address.
If omitted, then the to address is expected to be VIRTUAL.
extraNOPs Optional no. of extra NOP instructions to add after the JMP.
If omitted none are added. Used for alignment purposes.

Returns: true if successful else false.


SetCALL

Adds an entry to change the instruction at the specified address to a CALL.

Syntax:

Exe.SetCALL(from, to, [extraNOPs])
Exe.SetCALL(from, to, tgtType, [extraNOPs])
Argument Description
from The address where the CALL needs to be put.
to The destination address for the CALL.
tgtType Optional AddrType of the to address.
If omitted, then the to address is expected to be VIRTUAL.
extraNOPs Optional no. of extra NOP instructions to add after the CALL.
If omitted none are added. Used for alignment purposes.

Returns: true if successful else false.


SetTgtAddr

Adds an entry to overwrite data with a distance value targeting another address (like after JMP).

Syntax:

Exe.SetTgtAddr(from, to, [tgtType])
Argument Description
from The address from where the distance value need to be calculated and placed as well.
to The destination address.
tgtType Optional AddrType of the to address.
If omitted, then the to address is expected to be VIRTUAL.

Returns: true if successful else false.


SetDirAddr

Adds an entry to change the starting address of an Image Data Directory.

Syntax:

Exe.SetDirAddr(dtype, addr, [atype])
Argument Description
dtype DirType of the Data Directory.
addr The new starting address.
atype Optional AddrType of the target.
If omitted, then addr is expected to be VIRTUAL.

Returns: true if successful else false.


SetDirSize

Adds an entry to change the size of an Image Data Directory.

Syntax:

Exe.SetDirSize(dtype, size)
Argument Description
dtype DirType of the Data Directory.
size The new size.

Returns: true if successful else false.


Direct insertion functions

All the functions listed below stage changes for adding new data to the DIFF section without needing to pre-allocate the addresses seperately.

Essentially they are combinations of Allocate function with the Setters listed above.

Just like the 'setters', these functions can only be run from Patch Functions as well.


AddInt*

Adds an entry to insert a signed integer occupying 8 / 16 / 32 bits (1 / 2 / 4 bytes) of space.

Syntax:

Exe.AddInt8(value)
Exe.AddInt16(value)
Exe.AddInt32(value)
Argument Description
value The new signed integer value to be inserted.

Returns: [PHYSICAL address, VIRTUAL address, Size allocated] or empty list in case of failure


AddUint*

Adds an entry to insert an unsigned integer occupying 8 / 16 / 32 bits (1 / 2 / 4 bytes) of space.

Syntax:

Exe.AddUint8(value)
Exe.AddUint16(value)
Exe.AddUint32(value)
Argument Description
value The new unsigned integer value to be inserted.

Returns: [PHYSICAL address, VIRTUAL address, Size allocated] or empty list in case of failure


AddFloat

Adds an entry to insert a floating point number occupying 32 bits (4 bytes) of space.

Syntax:

Exe.AddFloat(value)
Argument Description
value The new floating point value to be inserted.

Returns: [PHYSICAL address, VIRTUAL address, Size allocated] or empty list in case of failure


AddBytes

Adds an entry to insert a list of bytes.

Syntax:

Exe.AddBytes(bytelist)
Argument Description
bytelist The data to be inserted expressed as a list of bytes.

Returns: [PHYSICAL address, VIRTUAL address, Size allocated] or empty list in case of failure


AddHex

Adds an entry to insert a hex string.

Syntax:

Exe.AddHex(hexstring)
Argument Description
hexstring The data to be inserted expressed as a hex string.

Returns: [PHYSICAL address, VIRTUAL address, Size allocated] or empty list in case of failure


AddText

Adds an entry to insert a text string.

Syntax:

Exe.AddText(text, [enc])
Argument Description
text The data to be inserted expressed as a text string.
enc Optional Encoding of the text string.
If omitted, the text will be considered to be ASCII encoded.

Returns: [PHYSICAL address, VIRTUAL address, Size allocated] or empty list in case of failure


AddFromVar

Adds an entry to insert a previously saved user input value.

Syntax:

Exe.AddFromVar(addr, varName)
Argument Description
varName Variable name of the user input.
Only works if the value was saved internally as a byte array

Returns: [PHYSICAL address, VIRTUAL address, Size allocated] or empty list in case of failure


Change related functions

UndoChanges

Both the Setters & Inserters can be used to stage changes.

While deselecting a patch automatically removes it's associated modifications, sometimes you need to revert a particular set of changes explicitly. For this purpose you can use this function.

Syntax:

Exe.UndoChanges(addr, size)
Argument Description
addr Starting address from where we need to remove the changes
size The no. of bytes that need to be reverted back to original state

RevealChanges

Enables reporting of changes that are going to be made while applying patches.

Exe object makes use of a script function called PatchReporter to report the changes. Currently it adds the info to the Script Window and to the log file if Logging has started.

Syntax:

Exe.RevealChanges()

ConcealChanges

Direct opposite of the above. Useful for hiding changes from prying eyes.

Syntax:

Exe.ConcealChanges()

Tagging functions

The Exe now supports 'tagging' a set of staged changes and allocations with a name irrespective of which patch has them. This enables checking for presence of these changes as well as clearing them easily if not needed.

BeginTag

Used for enabling the Exe to save all changes and allocations that follow under this tag. When the patch is over, the recordng is automatically stopped.

Similarly if you use BeginTag again with the same name, previous staged changes (and optionally allocations) are removed.

Syntax:

Exe.BeginTag(name, [freePrev])
Argument Description
name The name of the tag to enable.
freePrev Optional boolean to indicate whether any allocations previously made under this tag need to be freed too.

EndTag

Counterpart to BeginTag for stopping the save to tag procedure.

Exe.EndTag()

DelTag

Removes an existing tag and all changes & allocations attached to it.

Exe.DelTag()

HasTag

Checks for the presence of an existing tag previously defined with Exe.BeginTag function.

Exe.HasTag()

Returns: true if present else false.


Return to top


Further reading

Home

Links for Users

Links for Devs

Guides

APIs

Front-End

Clone this wiki locally