Interface IDState
dexdec
IR state (referred as "State"), used to perform IR evaluations, emulation and
sandboxing. After use, a state must be disposed
to prevent resource leaks.
This interface exposes a significant subset of the State functionalities, but not all. In particular, the sandbox itself cannot be manipulated (it can only be enabled or disabled). Future API extensions may allow third-party clients to access those controls.
A State can be created or retrieved via the global IR context (the g
attribute in
optimizers inheriting AbstractDOptimizer
), see methods
IDGlobalContext.createState()
and IDGlobalContext.getThreadSharedState()
.
The emulation of code takes place within a context
. Each context has a stack of
frame
s, holding the emulator state relative to the method being executed (the top frame
for the current method, the second frame for the caller of the current method, etc.).
Note the special role of IDImm
objects: they represent both immediate values, as well as
object references living in a State object.
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
Default maximum duration, in milliseconds.static final int
Default maximum depth for method invocations.static final int
Default maximum iteration count.static final int
Sub-routine execution policy: this special flag allows everything.static final int
Sub-routine execution policy: this flag allows external routines.static final int
Sub-routine execution policy: this flag allows internal routines.static final int
Sub-routine execution policy: this flag forbids the emulation of sub-routines. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Convenience method to add class files (single class or Jar) to the sandbox classloader.boolean
canRun()
Quickly determine whether this State is usable, that is, can code be emulated (e.g.cloneArray
(IDImm arrayRef) Clone an array.createArray
(IJavaType type, int len, List<? extends IDImm> initialValues) Create an array.createNewInstance
(String classSignature) createNewInstance
(String constructorSignature, Collection<IDExpression> constructorParameters) Create a new instance of an object.Delete the most recent (top) execution context.Delete the most recent (top) frame of the current execution context.boolean
deleteVariable
(int varid) Convenience method to remove a defined variable in the current frame (top frame of the top context).void
dispose()
Dispose of this emulator's resources.void
enableEmulator
(boolean enabled) Enable or disable the emulator.void
enableExceptionHandling
(boolean enabled) Enable or disable the handling of exceptions generated by the emulated code.void
enableNativeCodeEmulator
(boolean enabled) Enable or disable the native code emulator.boolean
enableSandbox
(boolean enabled) Enable or disable the sandbox.execute
(DExecutionParameters info) Execute some IR.executeDexMethod
(IDexMethod m, List<IDExpression> args) Execute (emulate) an IR method within a new context.getApk()
Retrieve the parent APK unit of the Dex unit that is being emulated.getArrayElement
(IDImm arrayRef, int index) Read an array element.getArrayObject
(IDImm ref) Retrieve an array by reference.int
Get the length of an array.getClassReference
(String classname) Retrieve a classref reference by name.Retrieve a read-only collection of emulation contexts.int
A convenience method to get the count of contexts.Convenience method to retrieve the current (newest) context.long
Set the emulator timeout value.Convenience method to retrieve the top frame of the current (newest) context.int
Retrieve the current total iteration count, that is, the total number of statements emulated or executed by this object.Get (retrieve) a piece of data attached to this emulator object.Convenience method.getDex()
Convenience method.Retrieve the optional "emulated Android" manager of this dex code emulator.Retrieve the collection of all registered method execution helpers.Retrieve the current emulation policy for environment-related, time and date-related, and other API methods yielding unpredictable results.Retrieve the global IR context that was used to create this State.getInstanceField
(String fsig, IDImm instance) Retrieve the value of an instance field.int
Retrieve the number of iterations left.long
Retrieve the emulator timeout value.int
Get the maximum allowed depth for method invocations.int
Retrieve the max iteration count value.Retrieve the native emulator.Get the list of native libraries loaded in the native emulator.getObject
(int objid) Convenience method to retrieve an object by its reference id.Retrieve an object value by its reference.Retrieve an object value by its reference.getObjectClass
(int objid) Retrieve the emulated class object for the provided object.int
getObjectClassId
(int objid) Retrieve the class object reference id of the provided object.int
getPC()
Convenience method to read the IR program counter in the current frame (top frame of the top context).Retrieve the list of native methods registered via JNI.Retrieve the classloader used by the sandbox.Retrieve the sandbox folder containing dropped files.getStaticField
(String fsig) Retrieve the value of a static field.getStringObject
(IDImm strOrRef) Retrieve a string by reference.int
Retrieve the emulation policy for invoking sub-routines.long
Retrieve the amount of emulation time left.Provide the type adapter used by the emulator and sandbox.getVariable
(int varid) Convenience method to read the value of a variable in the current frame (top frame of the top context).getVariable
(int varid, boolean softFail) Convenience method to read the value of a variable in the current frame (top frame of the top context).boolean
hasVariable
(int varid) Determine whether a variable is set (has a value).invokeMethod
(DInvokeType invokeType, String methodSignature, IDExpression... methodParameters) Invoke (execute) a method.invokeMethod
(String methodSignature, Collection<IDExpression> methodParameters, DInvokeType invokeType) Invoke (execute) a method.boolean
Determine whether the emulator is enabled.boolean
Determine whether handling of exceptions generated by the emulated code is enabled.boolean
isInstanceOf
(IDImm obj, IDImm clz) Determine whether an object is assignment-compatible with a class type.boolean
Determine whether the native code emulator is enabled.The native code emulator relies on other JEB modules, mainly the native code analysis pipeline,gendec
(JEB's generic decompiler), and specific analysis plugins (such as the x86 or arm processors).boolean
Determine if direct unreflection is enabled.boolean
Determine whether the sandbox is enabled.Class<?>
Find, load and initialize a class.Class<?>
Find a class.Load (or retrieve a reference to an already-loaded) native SO library.loadNativeLibrary
(String libname) Load (or retrieve a reference to an already-loaded) native SO library.loadNativeLibrary
(String libname, boolean isPath) Load (or retrieve a reference to an already-loaded) native SO library.pushContext
(String name) Create and push a new execution context.Create and push a frame within the current (top) emulation context.int
Register emulator hooks.void
Register a method execution helper.int
Register a native emulator hooks.int
Register a native emulator memory hooks.Register an object.int
Register sandbox hooks.releaseObject
(IDImm ref) Release an object currently living in this State.void
setArrayElement
(IDImm arrayRef, int index, IDImm val) Write an array element.void
Set (attach) a piece data to this emulator object.setExternalPolicy
(DEmuExternalPolicy policy) Set an emulation policy for environment-related, time and date-related, and other API methods yielding unpredictable results.void
setInstanceField
(String fsig, IDImm instance, IDImm val) Update the value of an instance field.void
setMaxDuration
(long maxDuration) Set the emulator timeout value.void
setMaxInvocationDepth
(int maxInvocationDepth) Set the maximum depth for method invocations.void
setMaxIterationCount
(int maxInsnCount) Set or reset the max iteration count.void
setPC
(int pc) Convenience method to write the IR program counter in the current frame (top frame of the top context).void
setPerformDirectUnreflection
(boolean performDirectUnreflection) Enable or disable direct unreflection (disabled by default).setSandboxDroppedFilesCollection
(String locationName, boolean allowFileRemoval) Specify where files written by sandboxed code should be written to.void
setStaticField
(String fsig, IDImm val) Update the value of a static field.void
setSubRoutineInvocationPolicy
(int subRoutineInvocationPolicy) Set the emulation policy for invoking sub-routines.void
setVariable
(int varid, IDImm value) Convenience method to write the value of a variable in the current frame (top frame of the top context).Reserved for internal use.boolean
unregisterEmulatorHooks
(int hookId) Unregister emulator hooks.boolean
unregisterExecutionHelper
(String methodSignature) Remove a method execution helper.boolean
unregisterNativeEmulatorHooks
(int id) Unregister a native emulator hooks.boolean
Unregister a native emulator memory hooks.boolean
unregisterSandboxHooks
(int hookId) Unregister sandbox hooks.
-
Field Details
-
DEFAULT_MAX_ITERCOUNT
static final int DEFAULT_MAX_ITERCOUNTDefault maximum iteration count.- See Also:
-
DEFAULT_MAX_DURATION
static final int DEFAULT_MAX_DURATIONDefault maximum duration, in milliseconds.- See Also:
-
DEFAULT_MAX_INVOCATION_DEPTH
static final int DEFAULT_MAX_INVOCATION_DEPTHDefault maximum depth for method invocations.- See Also:
-
SUBEXEC_DENY_ALL
static final int SUBEXEC_DENY_ALLSub-routine execution policy: this flag forbids the emulation of sub-routines.- See Also:
-
SUBEXEC_ALLOW_INTERNAL
static final int SUBEXEC_ALLOW_INTERNALSub-routine execution policy: this flag allows internal routines.- See Also:
-
SUBEXEC_ALLOW_EXTERNAL
static final int SUBEXEC_ALLOW_EXTERNALSub-routine execution policy: this flag allows external routines.- See Also:
-
SUBEXEC_ALLOW_ALL
static final int SUBEXEC_ALLOW_ALLSub-routine execution policy: this special flag allows everything.- See Also:
-
-
Method Details
-
dispose
void dispose()Dispose of this emulator's resources. -
getGlobalContext
IDGlobalContext getGlobalContext()Retrieve the global IR context that was used to create this State.- Returns:
-
getDecompiler
IDexDecompilerUnit getDecompiler()Convenience method.- Returns:
- never null
-
getDex
IDexUnit getDex()Convenience method.- Returns:
- never null
-
getApk
IApkUnit getApk()Retrieve the parent APK unit of the Dex unit that is being emulated.- Returns:
- an apk unit; maybe null
-
getEmulatedEnvironment
IEmulatedAndroid getEmulatedEnvironment()Retrieve the optional "emulated Android" manager of this dex code emulator.- Returns:
-
canRun
boolean canRun()Quickly determine whether this State is usable, that is, can code be emulated (e.g. did we reach the max iteration count or timeout?)- Returns:
-
getMaxIterationCount
int getMaxIterationCount()Retrieve the max iteration count value.- Returns:
- max iteration count
-
setMaxIterationCount
void setMaxIterationCount(int maxInsnCount) Set or reset the max iteration count.If the maximum iteration count is reached, a
DexDecEvalItercountExceededException
exception is be raised.- Parameters:
maxInsnCount
-
-
getCurrentIterationCount
int getCurrentIterationCount()Retrieve the current total iteration count, that is, the total number of statements emulated or executed by this object.If the maximum iteration count is reached, a
DexDecEvalItercountExceededException
exception is be raised.- Returns:
-
getIterationCountLeft
int getIterationCountLeft()Retrieve the number of iterations left.- Returns:
-
getMaxDuration
long getMaxDuration()Retrieve the emulator timeout value.- Returns:
- max duration in ms
-
setMaxDuration
void setMaxDuration(long maxDuration) Set the emulator timeout value.If a run exceeds the timeout, the emulation fails and a
DexDecEvalTimeoutExceededException
exception is raised.- Parameters:
maxDuration
- in ms
-
getCurrentDuration
long getCurrentDuration()Set the emulator timeout value.If a run exceeds the timeout, the emulation fails and a
DexDecEvalTimeoutExceededException
exception is raised.- Returns:
- in ms
-
getTimeLeft
long getTimeLeft()Retrieve the amount of emulation time left.- Returns:
- in ms, always >= 0
-
getTypeAdapter
IJLSTypeAdapter getTypeAdapter()Provide the type adapter used by the emulator and sandbox. Only internal, fully-qualified names are accepted by this adapter, e.g.Lcom/abc/Foo;
- Returns:
-
setSubRoutineInvocationPolicy
void setSubRoutineInvocationPolicy(int subRoutineInvocationPolicy) Set the emulation policy for invoking sub-routines.- Parameters:
subRoutineInvocationPolicy
- a combination ofSUBEXEC_xxx
flags
-
getSubRoutineInvocationPolicy
int getSubRoutineInvocationPolicy()Retrieve the emulation policy for invoking sub-routines.- Returns:
- a combination of
SUBEXEC_xxx
flags
-
setMaxInvocationDepth
void setMaxInvocationDepth(int maxInvocationDepth) Set the maximum depth for method invocations.This attribute is also used as a safety mechanism to prevent stack overflows during emulation.
- Parameters:
maxInvocationDepth
- a positive value
-
getMaxInvocationDepth
int getMaxInvocationDepth()Get the maximum allowed depth for method invocations.- Returns:
- the current maximum depth (defaults to
DEFAULT_MAX_INVOCATION_DEPTH
)
-
enableEmulator
void enableEmulator(boolean enabled) Enable or disable the emulator. The emulator must be enabled to permit the execution ofIDInstruction#evaluate()
. -
isEmulatorEnabled
boolean isEmulatorEnabled()Determine whether the emulator is enabled. The emulator must be enabled to permit the execution ofIDInstruction#evaluate()
. -
registerEmulatorHooks
Register emulator hooks. Refer toIDEmulatorHooks
for details.- Parameters:
hooks
- an emulator sandbox hooks object- Returns:
- the hooks object id
-
unregisterEmulatorHooks
boolean unregisterEmulatorHooks(int hookId) Unregister emulator hooks.- Parameters:
hookId
- hooks object id, returned byregisterEmulatorHooks
- Returns:
- success indicator
-
registerExecutionHelper
Register a method execution helper. A helper is preferred over bytecode emulation or sandbox execution.Example: if a helper is provided for
Ljava/lang/String;->indexOf(I)I
, any attempt to emulateindexOf()
will result in the helper being called. The helper is responsible for providing the result of execution.- Parameters:
helper
-
-
unregisterExecutionHelper
Remove a method execution helper.- Parameters:
methodSignature
-- Returns:
-
getExecutionHelpers
Collection<IDMethodExecutionHelper> getExecutionHelpers()Retrieve the collection of all registered method execution helpers.- Returns:
-
setExternalPolicy
Set an emulation policy for environment-related, time and date-related, and other API methods yielding unpredictable results.- Parameters:
policy
- the new policy- Returns:
- the former policy (if any, may be null)
-
getExternalPolicy
DEmuExternalPolicy getExternalPolicy()Retrieve the current emulation policy for environment-related, time and date-related, and other API methods yielding unpredictable results.- Returns:
- may be null
-
enableExceptionHandling
void enableExceptionHandling(boolean enabled) Enable or disable the handling of exceptions generated by the emulated code.- Parameters:
enabled
-
-
isExceptionHandlingEnabled
boolean isExceptionHandlingEnabled()Determine whether handling of exceptions generated by the emulated code is enabled. If not, any exception raised during emulation will bubble up as aDexDecEvaluationException
.- Returns:
-
setPerformDirectUnreflection
void setPerformDirectUnreflection(boolean performDirectUnreflection) Enable or disable direct unreflection (disabled by default). When enabled, a non-constructor method invocation or field access (read, write) done by reflection, which execution would normally go through the sandbox, will be attempted to be resolved. If the resolution is successful, direct execution may be attempted, thereby saving a potentially costly context-switch to the sandbox.- Parameters:
performDirectUnreflection
-
-
isPerformDirectUnreflection
boolean isPerformDirectUnreflection()Determine if direct unreflection is enabled.- Returns:
-
enableSandbox
boolean enableSandbox(boolean enabled) Enable or disable the sandbox. The sandbox is used to safely execute external code (not present in the form of dex bytecode in the application).- Parameters:
enabled
-- Returns:
- success indicator
-
isSandboxEnabled
boolean isSandboxEnabled()Determine whether the sandbox is enabled.- Returns:
-
getSandboxClassLoader
URLClassLoader getSandboxClassLoader()Retrieve the classloader used by the sandbox.- Returns:
-
addClassfilesToSandbox
Convenience method to add class files (single class or Jar) to the sandbox classloader.- Parameters:
f
-- Throws:
IOException
-
registerSandboxHooks
Register sandbox hooks. Refer toIDSandboxHooks
for details.- Parameters:
hooks
- an emulator sandbox hooks object- Returns:
- the hooks object id
-
unregisterSandboxHooks
boolean unregisterSandboxHooks(int hookId) Unregister sandbox hooks.- Parameters:
hookId
- hooks object id, returned byregisterSandboxUserHooks
- Returns:
- success indicator
-
setSandboxDroppedFilesCollection
File setSandboxDroppedFilesCollection(String locationName, boolean allowFileRemoval) throws IOException Specify where files written by sandboxed code should be written to. All files written during emulation will be dropped to this folder.- Parameters:
locationName
- a simple name (the folder path will be derived from this name)allowFileRemoval
- if true, files dropped by the sandboxed code cannot be removed- Returns:
- the drop box folder
- Throws:
IOException
-
getSandboxDropFolder
File getSandboxDropFolder()Retrieve the sandbox folder containing dropped files.- Returns:
- the drop box folder, or null if none was set
-
enableNativeCodeEmulator
void enableNativeCodeEmulator(boolean enabled) Enable or disable the native code emulator. The native code emulator relies on other JEB modules, mainly the native code analysis pipeline,gendec
(JEB's generic decompiler), and specific architecture plugins (such as the x86 or arm processor plugins). The native code emulator must be enabled to allow the emulation of code invoking native routines through JNI (Java Native Interfaces).- Parameters:
enabled
- true to enable the native code emulator, false to disable it (note that the initial setting is likely to be pulled from your dexdec configuration file,dexdec-emu.cfg
)
-
isNativeCodeEmulatorEnabled
boolean isNativeCodeEmulatorEnabled()Determine whether the native code emulator is enabled.The native code emulator relies on other JEB modules, mainly the native code analysis pipeline,gendec
(JEB's generic decompiler), and specific analysis plugins (such as the x86 or arm processors). The native code emulator must be enabled to allow the emulation of code invoking native routines through JNI (Java Native Interfaces).- Returns:
- true if the native code emulator is enabled, false otherwise (note that the initial
setting is likely to be pulled from your dexdec configuration file,
dexdec-emu.cfg
)
-
registerNativeEmulatorHooks
Register a native emulator hooks.- Parameters:
hooks
- an evaluation hooks object registered with the native emulator- Returns:
- the hooks object id
-
unregisterNativeEmulatorHooks
boolean unregisterNativeEmulatorHooks(int id) Unregister a native emulator hooks.- Parameters:
id
- hooks object id- Returns:
- success indicator
-
registerNativeEmulatorMemoryHooks
Register a native emulator memory hooks.- Parameters:
hooks
- an evaluation hooks object registered with the native emulator- Returns:
- the hooks object id
-
unregisterNativeEmulatorMemoryHooks
boolean unregisterNativeEmulatorMemoryHooks(int id) Unregister a native emulator memory hooks.- Parameters:
id
- hooks object id- Returns:
- success indicator
-
getStaticField
Retrieve the value of a static field.Note: field resolution is performed, just as the
sget
opcode does. Example: if type Y extends type X, X contains field i, and the caller attempts to read Y.i, this method will resolve the field to X.i.- Parameters:
fsig
-- Returns:
- Throws:
DexDecEvaluationException
-
setStaticField
Update the value of a static field.Note: field resolution is performed, just as the
sput
opcode does. Example: if type Y extends type X, X contains field i, and the caller attempts to write Y.i, this method will resolve the field to X.i.- Parameters:
fsig
-val
-- Throws:
DexDecEvaluationException
-
getInstanceField
Retrieve the value of an instance field.- Parameters:
fsig
-instance
-- Returns:
- Throws:
DexDecEvaluationException
-
setInstanceField
Update the value of an instance field.- Parameters:
fsig
-instance
-val
-- Throws:
DexDecEvaluationException
-
loadClass
Find, load and initialize a class. The class may be internal (defined in dex) or external.- Parameters:
csig
- fully-qualified signature, e.g.Lcom/abc/Foo;
- Returns:
- the
Class
object - Throws:
DexDecEvaluationException
-
loadClass
Find a class. The class may be internal (defined in dex) or external.- Parameters:
csig
- fully-qualified signature, e.g.Lcom/abc/Foo;
initialize
- if true, the class will be initialized- Returns:
- the
Class
object - Throws:
DexDecEvaluationException
-
getStringObject
Retrieve a string by reference.- Parameters:
strOrRef
-- Returns:
- Throws:
DexDecEvaluationException
-
createArray
IDImm createArray(IJavaType type, int len, List<? extends IDImm> initialValues) throws DexDecEvaluationException Create an array. The array object will live in this emulator.- Parameters:
type
- the array type e.g. int[][][], or String[][], or X[]len
- the length of the first dimension, re-using the examples above, would indicate an array int[N][][], String[N][], X[N]initialValues
- a list of initial values, non-null, whose length must in [0, N]- Returns:
- the IR constant wrapping the array
- Throws:
DexDecEvaluationException
-
cloneArray
Clone an array.- Parameters:
arrayRef
- source array reference- Returns:
- the cloned array (as defined by the JLS's
array.clone
protected method) - Throws:
DexDecEvaluationException
-
getArrayObject
Retrieve an array by reference.- Parameters:
ref
-- Returns:
- Throws:
DexDecEvaluationException
-
getArrayObjectLength
Get the length of an array.- Parameters:
ref
-- Returns:
- Throws:
DexDecEvaluationException
-
getArrayElement
Read an array element.- Parameters:
arrayRef
-index
-- Returns:
- Throws:
DexDecEvaluationException
-
setArrayElement
Write an array element.- Parameters:
arrayRef
-index
-val
-- Throws:
DexDecEvaluationException
-
getClassReference
Retrieve a classref reference by name. The class is not initialized.- Parameters:
classname
- fully-qualified name, e.g.Lcom/abc/Foo;
- Returns:
- Throws:
DexDecEvaluationException
-
isInstanceOf
Determine whether an object is assignment-compatible with a class type.- Parameters:
obj
-clz
-- Returns:
- Throws:
DexDecEvaluationException
-
registerObject
Register an object.- Parameters:
o
-- Returns:
-
getObject
Retrieve an object value by its reference.- Parameters:
ref
- a wrapped reference or a string immediate- Returns:
- an object
- Throws:
DexDecEvaluationException
-
getObject
Retrieve an object value by its reference.- Parameters:
ref
- a wrapped reference or a string immediateprovideNativeObject
-- Returns:
- an object, or null (which does not indicate an error, but the null reference)
- Throws:
DexDecEvaluationException
-
releaseObject
Release an object currently living in this State. Watch out! References are not checked. Other objects may use the deleted object.- Parameters:
ref
-- Returns:
- Throws:
DexDecEvaluationException
-
getObject
Convenience method to retrieve an object by its reference id.- Parameters:
objid
- an object id- Returns:
- the object (null if the provided id was 0 - the null reference)
- Throws:
DexDecEvaluationException
- if no object with the provided id exists
-
getObjectClassId
Retrieve the class object reference id of the provided object. Be careful: the class will be loaded in the emulator if it hasn't been already.- Parameters:
objid
- an object reference id- Returns:
- the object's class object reference id (null if the provided id was 0 - the null reference)
- Throws:
DexDecEvaluationException
- if no object with the provided id exists
-
getObjectClass
Retrieve the emulated class object for the provided object.- Parameters:
objid
- an object reference id- Returns:
- the emulated class object (null if the provided id was 0 - the null reference)
- Throws:
DexDecEvaluationException
- if no object with the provided id exists
-
pushContext
Create and push a new execution context. IR emulation takes place within the top emulation context.- Parameters:
name
-- Returns:
-
deleteTopContext
IDEmuContext deleteTopContext()Delete the most recent (top) execution context.- Returns:
-
pushFrame
Create and push a frame within the current (top) emulation context. A frame (method frame) contains the current PC, variables, etc.- Parameters:
methodSignature
-- Returns:
-
deleteTopFrame
IDEmuFrame deleteTopFrame()Delete the most recent (top) frame of the current execution context.- Returns:
-
getContexts
Collection<IDEmuContext> getContexts()Retrieve a read-only collection of emulation contexts.- Returns:
-
getCountOfContexts
int getCountOfContexts()A convenience method to get the count of contexts.- Returns:
-
getCurrentContext
IDEmuContext getCurrentContext()Convenience method to retrieve the current (newest) context.- Returns:
-
getCurrentFrame
IDEmuFrame getCurrentFrame()Convenience method to retrieve the top frame of the current (newest) context.- Returns:
-
setVariable
Convenience method to write the value of a variable in the current frame (top frame of the top context).- Parameters:
varid
- variable idvalue
- the value to be written- Throws:
DexDecEvaluationException
-
getVariable
Convenience method to read the value of a variable in the current frame (top frame of the top context).- Parameters:
varid
- variable idsoftFail
-- Returns:
- the value (non-null)
- Throws:
DexDecEvaluationException
-
getVariable
Convenience method to read the value of a variable in the current frame (top frame of the top context). The variable must exist.- Parameters:
varid
- variable id- Returns:
- the value (non-null)
- Throws:
DexDecEvaluationException
- thrown if the variable is not set
-
hasVariable
Determine whether a variable is set (has a value).- Parameters:
varid
- variable id- Returns:
- Throws:
DexDecEvaluationException
-
deleteVariable
Convenience method to remove a defined variable in the current frame (top frame of the top context).- Parameters:
varid
- variable id- Returns:
- true if the variable was removed
- Throws:
DexDecEvaluationException
-
setPC
void setPC(int pc) Convenience method to write the IR program counter in the current frame (top frame of the top context).- Parameters:
pc
-
-
getPC
int getPC()Convenience method to read the IR program counter in the current frame (top frame of the top context).- Returns:
-
createNewInstance
IDImm createNewInstance(String constructorSignature, Collection<IDExpression> constructorParameters) throws DexDecEvaluationException Create a new instance of an object. This method is similar toClass.newInstance()
; it allocates an object and executes a constructor method.- Parameters:
constructorSignature
- full signature, e.g.Lcom/abc/Foo-><init>(II)V
constructorParameters
- parameters- Returns:
- the newly-created instance
- Throws:
DexDecEvaluationException
-
createNewInstance
- Parameters:
classSignature
-- Returns:
- Throws:
DexDecEvaluationException
-
invokeMethod
IDImm invokeMethod(String methodSignature, Collection<IDExpression> methodParameters, DInvokeType invokeType) throws DexDecEvaluationException Invoke (execute) a method. The method cannot be a constructor method. If the method is non-static (direct or virtual method), the first element in the method parameters list must be the object itself.- Parameters:
methodSignature
- full signature, e.g.Lcom/abc/Foo->bar(I)L
methodParameters
- parameters (for non-static methods, the first entry must be the target object reference)invokeType
- invocation type (it cannot beNEW
)- Returns:
- the returned value (null for
void
methods) - Throws:
DexDecEvaluationException
-
invokeMethod
IDImm invokeMethod(DInvokeType invokeType, String methodSignature, IDExpression... methodParameters) throws DexDecEvaluationException Invoke (execute) a method. The method cannot be a constructor method. If the method is non-static (direct or virtual method), the first element in the method parameters list must be the object itself.- Parameters:
invokeType
- invocation type (it cannot beNEW
)methodSignature
- full signature, e.g.Lcom/abc/Foo->bar(I)L
methodParameters
- parameters (for non-static methods, the first entry must be the target object reference)- Returns:
- the returned value (null for
void
methods) - Throws:
DexDecEvaluationException
-
executeDexMethod
Execute (emulate) an IR method within a new context. Upon completion (success or error), the newly-created context is auto-discarded. The execution result is provided; global objects created by the execution can be reviewed with methods likegetObject(IDImm)
; the rest (frame variables, etc.) is discarded.NOTE: This method is currently limited to the execution of dex internal methods (not pure references, not abstract or native). This method is not meant to execute constructor code (
<init>
methods); to create new objects, usecreateNewInstance(String, Collection)
.- Parameters:
m
- a dex internal methodargs
- method arguments- Returns:
- the return value upon completion, if there is one
- Throws:
DexDecEvaluationException
- an evaluation exception occurred
-
execute
Execute some IR.The execution takes place in the current frame (i.e. no new context or frame is created, it is the responsibility of the caller to do so). That current frame is popped only if the method execution completes fully and no
PC-end value
was provided in the parameter. On other cases (e.g., an exception is raised, null is returned return becausepcExpectedTermination
was provided and was reached, etc.), the current frame is left as-is to allow client code to examine it.- Parameters:
info
- execution parameters, including the IR instructions- Returns:
- the execution return value
- Throws:
DexDecEvaluationException
-
getNativeLibraries
Get the list of native libraries loaded in the native emulator.- Returns:
- a list of library objects, possibly empty
- Throws:
DexDecEvaluationException
-
loadNativeLibrary
Load (or retrieve a reference to an already-loaded) native SO library. This low-level method works with a direct ELF unit. For a high-level version of this method, seeloadNativeLibrary(String)
.Upon successful load, the
JNI_OnLoad
method is emulated. The emulator as well as native emulator must be enabled.- Parameters:
lib
- ELF Shared Objec unit located in the project- Returns:
- a library description object
- Throws:
DexDecEvaluationException
-
loadNativeLibrary
Load (or retrieve a reference to an already-loaded) native SO library. This high-level method is looking for libraries in the APK's standard library folder,lib/[arch]/
.Upon successful load, the
JNI_OnLoad
method is emulated. The emulator as well as native emulator must be enabled.- Parameters:
libname
- a library name, as provided to a call toSystem.loadLibrary(String)
- Returns:
- a library description object
- Throws:
DexDecEvaluationException
-
loadNativeLibrary
Load (or retrieve a reference to an already-loaded) native SO library. This high-level method is looking for libraries in the APK's standard library folder,lib/[arch]/
.Upon successful load, the
JNI_OnLoad
method is emulated. The emulator as well as native emulator must be enabled.- Parameters:
libname
- a library path or library nameisPath
- if true, the provide name must be a full path; else, it must be a simple library name of an SO file located in the app's libs folder (not mentioning the architecture, 'lib' prefix, or '.so' suffix)- Returns:
- a library description object
- Throws:
DexDecEvaluationException
-
getNativeEmulator
EEmulator getNativeEmulator()Retrieve the native emulator. This method will throw if native code emulation is disabled.- Returns:
- the emulator or null if the emulator is not ready (the native emulator is initialized lazily, on the first attempt to load a native JNI library)
-
getRegisteredNatives
Retrieve the list of native methods registered via JNI. This method will throw if native code emulation is disabled.- Returns:
- a map; key= is the native Java method signature, value= native address in the emulated process space
-
setData
Set (attach) a piece data to this emulator object.- Parameters:
key
- non-null keyvalue
- non-null value
-
getData
Get (retrieve) a piece of data attached to this emulator object.- Parameters:
key
- non-null key- Returns:
- the data, null if none
-
shallowCopy
IDState shallowCopy()Reserved for internal use.Generate a partial copy of this state.
- Returns:
-