com.pnfsoftware.jeb.core.units.code.android.ir.IDState |
dexdec
IR state (referred as "State"), used to perform IR evaluations, emulation and
sandboxing.
Note: 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
createState()
and 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.
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | DEFAULT_MAX_DURATION | Default maximum duration, in milliseconds. | |||||||||
int | DEFAULT_MAX_INVOCATION_DEPTH | Default maximum depth for method invocations. | |||||||||
int | DEFAULT_MAX_ITERCOUNT | Default maximum iteration count. | |||||||||
int | SUBEXEC_ALLOW_ALL | Sub-routine execution policy: this special flag allows everything. | |||||||||
int | SUBEXEC_ALLOW_EXTERNAL | Sub-routine execution policy: this flag allows external routines. | |||||||||
int | SUBEXEC_ALLOW_INTERNAL | Sub-routine execution policy: this flag allows internal routines. | |||||||||
int | SUBEXEC_DENY_ALL | Sub-routine execution policy: this flag forbids the emulation of sub-routines. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
abstract void |
addClassfilesToSandbox(File f)
Convenience method to add class files (single class or Jar) to the sandbox classloader.
| ||||||||||
abstract boolean |
canRun()
Quickly determine whether this State is usable, that is, can code be emulated (e.g.
| ||||||||||
abstract IDImm |
cloneArray(IDImm arrayRef)
Clone an array.
| ||||||||||
abstract IDImm |
createArray(IJavaType type, int len, List<? extends IDImm> initialValues)
Create an array.
| ||||||||||
abstract IDEmuContext |
createContext(String name)
This method is deprecated.
use
pushContext(String)
| ||||||||||
abstract IDEmuFrame |
createFrame(String methodSignature)
This method is deprecated.
use
pushFrame(String)
| ||||||||||
abstract IDImm |
createNewInstance(String classSignature)
@return
| ||||||||||
abstract IDImm |
createNewInstance(String constructorSignature, Collection<IDExpression> constructorParameters)
Create a new instance of an object.
| ||||||||||
abstract IDEmuContext |
deleteTopContext()
Delete the most recent (top) execution context.
| ||||||||||
abstract IDEmuFrame |
deleteTopFrame()
Delete the most recent (top) frame of the current execution context.
| ||||||||||
abstract boolean |
deleteVariable(int varid)
Convenience method to remove a defined variable in the current frame (top frame of the top
context).
| ||||||||||
abstract void |
enableEmulator(boolean enabled)
Enable or disable the emulator.
| ||||||||||
abstract void |
enableExceptionHandling(boolean enabled)
Enable or disable the handling of exceptions generated by the emulated code.
| ||||||||||
abstract void |
enableNativeCodeEmulator(boolean enabled)
Enable or disable the native code emulator.
| ||||||||||
abstract boolean |
enableSandbox(boolean enabled)
Enable or disable the sandbox.
| ||||||||||
abstract IDImm |
execute(DExecutionParameters info)
Execute some IR.
| ||||||||||
abstract IDImm |
executeDexMethod(IDexMethod m, List<IDExpression> args)
Execute (emulate) an IR method within a new context.
| ||||||||||
abstract IDImm |
executeExternalMethod(String methodSignature, Collection<IDExpression> methodParameters, DInvokeType invokeType)
This method is deprecated.
use
invokeMethod(String, Collection, DInvokeType) instead
| ||||||||||
abstract IApkUnit |
getApk()
Retrieve the parent APK unit of the Dex unit that is being emulated.
| ||||||||||
abstract IDImm |
getArrayElement(IDImm arrayRef, int index)
Read an array element.@return
| ||||||||||
abstract Object |
getArrayObject(IDImm ref)
Retrieve an array by reference.@return
| ||||||||||
abstract int |
getArrayObjectLength(IDImm ref)
Get the length of an array.@return
| ||||||||||
abstract IDImm |
getClassReference(String classname)
Retrieve a classref reference by name.@return
| ||||||||||
abstract Collection<IDEmuContext> |
getContexts()
Retrieve a read-only collection of emulation contexts.
| ||||||||||
abstract int |
getCountOfContexts()
A convenience method to get the count of contexts.
| ||||||||||
abstract IDEmuContext |
getCurrentContext()
Convenience method to retrieve the current (newest) context.
| ||||||||||
abstract long |
getCurrentDuration()
Set the emulator timeout value.
| ||||||||||
abstract IDEmuFrame |
getCurrentFrame()
Convenience method to retrieve the top frame of the current (newest) context.
| ||||||||||
abstract int |
getCurrentIterationCount()
Retrieve the current total iteration count, that is, the total number of statements emulated
or executed by this object.
| ||||||||||
abstract Object |
getData(String key)
Get (retrieve) a piece of data attached to this emulator object.
| ||||||||||
abstract IDexDecompilerUnit |
getDecompiler()
Convenience method.
| ||||||||||
abstract IDexUnit |
getDex()
Convenience method.
| ||||||||||
abstract IEmulatedAndroid |
getEmulatedEnvironment()
Retrieve the optional "emulated Android" manager of this dex code emulator.
| ||||||||||
abstract Collection<IDMethodExecutionHelper> |
getExecutionHelpers()
Retrieve the collection of all registered method execution helpers.
| ||||||||||
abstract DEmuExternalPolicy |
getExternalPolicy()
Retrieve the current emulation policy for environment-related, time and date-related, and
other API methods yielding unpredictable results.
| ||||||||||
abstract IDGlobalContext |
getGlobalContext()
Retrieve the global IR context that was used to create this State.
| ||||||||||
abstract IDImm |
getInstanceField(String fsig, IDImm instance)
Retrieve the value of an instance field.@return
| ||||||||||
abstract int |
getIterationCountLeft()
Retrieve the number of iterations left.
| ||||||||||
abstract long |
getMaxDuration()
Retrieve the emulator timeout value.
| ||||||||||
abstract int |
getMaxInvocationDepth()
Get the maximum allowed depth for method invocations.
| ||||||||||
abstract int |
getMaxIterationCount()
Retrieve the max iteration count value.
| ||||||||||
abstract EEmulator |
getNativeEmulator()
Retrieve the native emulator.
| ||||||||||
abstract List<INativeLibrary> |
getNativeLibraries()
Get the list of native libraries loaded in the native emulator.
| ||||||||||
abstract Object |
getObject(IDImm ref, boolean provideNativeObject)
Retrieve an object value by its reference.
| ||||||||||
abstract Object |
getObject(int objid)
Convenience method to retrieve an object by its reference id.
| ||||||||||
abstract Object |
getObject(IDImm ref)
Retrieve an object value by its reference.
| ||||||||||
abstract IDEmuClass |
getObjectClass(int objid)
Retrieve the emulated class object for the provided object.
| ||||||||||
abstract int |
getObjectClassId(int objid)
Retrieve the class object reference id of the provided object.
| ||||||||||
abstract int |
getPC()
Convenience method to read the IR program counter in the current frame (top frame of the top
context).
| ||||||||||
abstract Map<String, Long> |
getRegisteredNatives()
Retrieve the list of native methods registered via JNI.
| ||||||||||
abstract URLClassLoader |
getSandboxClassLoader()
Retrieve the classloader used by the sandbox.
| ||||||||||
abstract File |
getSandboxDropFolder()
Retrieve the sandbox folder containing dropped files.
| ||||||||||
abstract IDImm |
getStaticField(String fsig)
Retrieve the value of a static field.
| ||||||||||
abstract String |
getStringObject(IDImm strOrRef)
Retrieve a string by reference.@return
| ||||||||||
abstract int |
getSubRoutineInvocationPolicy()
Retrieve the emulation policy for invoking sub-routines.
| ||||||||||
abstract long |
getTimeLeft()
Retrieve the amount of emulation time left.
| ||||||||||
abstract IJLSTypeAdapter |
getTypeAdapter()
Provide the type adapter used by the emulator and sandbox.
| ||||||||||
abstract IDImm |
getVariable(int varid, boolean softFail)
Convenience method to read the value of a variable in the current frame (top frame of the top
context).
| ||||||||||
abstract IDImm |
getVariable(int varid)
Convenience method to read the value of a variable in the current frame (top frame of the top
context).
| ||||||||||
abstract boolean |
hasVariable(int varid)
Determine whether a variable is set (has a value).@return
| ||||||||||
abstract IDImm |
invokeMethod(String methodSignature, Collection<IDExpression> methodParameters, DInvokeType invokeType)
Invoke (execute) a method.
| ||||||||||
abstract IDImm |
invokeMethod(DInvokeType invokeType, String methodSignature, IDExpression... methodParameters)
Invoke (execute) a method.
| ||||||||||
abstract boolean |
isEmulatorEnabled()
Determine whether the emulator is enabled.
| ||||||||||
abstract boolean |
isExceptionHandlingEnabled()
Determine whether handling of exceptions generated by the emulated code is enabled.
| ||||||||||
abstract boolean |
isInstanceOf(IDImm obj, IDImm clz)
Determine whether an object is assignment-compatible with a class type.@return
| ||||||||||
abstract 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). | ||||||||||
abstract boolean |
isPerformDirectUnreflection()
Determine if direct unreflection is enabled.
| ||||||||||
abstract boolean |
isSandboxEnabled()
Determine whether the sandbox is enabled.
| ||||||||||
abstract Class<?> |
loadClass(String csig, boolean initialize)
Find a class.
| ||||||||||
abstract Class<?> |
loadClass(String csig)
Find, load and initialize a class.
| ||||||||||
abstract INativeLibrary |
loadNativeLibrary(String libname)
Load (or retrieve a reference to an already-loaded) native SO library.
| ||||||||||
abstract INativeLibrary |
loadNativeLibrary(IELFUnit lib)
Load (or retrieve a reference to an already-loaded) native SO library.
| ||||||||||
abstract INativeLibrary |
loadNativeLibrary(String libname, boolean isPath)
Load (or retrieve a reference to an already-loaded) native SO library.
| ||||||||||
abstract IDEmuContext |
pushContext(String name)
Create and push a new execution context.
| ||||||||||
abstract IDEmuFrame |
pushFrame(String methodSignature)
Create and push a frame within the current (top) emulation context.
| ||||||||||
abstract int |
registerEmulatorHooks(IDEmulatorHooks hooks)
Register emulator hooks.
| ||||||||||
abstract void |
registerExecutionHelper(IDMethodExecutionHelper helper)
Register a method execution helper.
| ||||||||||
abstract int |
registerNativeEmulatorHooks(IEEmulatorHooks hooks)
Register a native emulator hooks.
| ||||||||||
abstract int |
registerNativeEmulatorMemoryHooks(IEStateHooks hooks)
Register a native emulator memory hooks.
| ||||||||||
abstract IDImm |
registerObject(Object o)
Register an object.
| ||||||||||
abstract int |
registerSandboxHooks(IDSandboxHooks hooks)
Register sandbox hooks.
| ||||||||||
abstract Object |
releaseObject(IDImm ref)
Release an object currently living in this State.
| ||||||||||
abstract void |
setArrayElement(IDImm arrayRef, int index, IDImm val)
Write an array element.
| ||||||||||
abstract void |
setData(String key, Object value)
Set (attach) a piece data to this emulator object.
| ||||||||||
abstract DEmuExternalPolicy |
setExternalPolicy(DEmuExternalPolicy policy)
Set an emulation policy for environment-related, time and date-related, and other API methods
yielding unpredictable results.
| ||||||||||
abstract void |
setInstanceField(String fsig, IDImm instance, IDImm val)
Update the value of an instance field.
| ||||||||||
abstract void |
setMaxDuration(long maxDuration)
Set the emulator timeout value.
| ||||||||||
abstract void |
setMaxInvocationDepth(int maxInvocationDepth)
Set the maximum depth for method invocations.
| ||||||||||
abstract void |
setMaxIterationCount(int maxInsnCount)
Set or reset the max iteration count.
| ||||||||||
abstract void |
setPC(int pc)
Convenience method to write the IR program counter in the current frame (top frame of the top
context).
| ||||||||||
abstract void |
setPerformDirectUnreflection(boolean performDirectUnreflection)
Enable or disable direct unreflection (disabled by default).
| ||||||||||
abstract File |
setSandboxDroppedFilesCollection(String locationName, boolean allowFileRemoval)
Specify where files written by sandboxed code should be written to.
| ||||||||||
abstract void |
setStaticField(String fsig, IDImm val)
Update the value of a static field.
| ||||||||||
abstract void |
setSubRoutineInvocationPolicy(int subRoutineInvocationPolicy)
Set the emulation policy for invoking sub-routines.
| ||||||||||
abstract 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).
| ||||||||||
abstract IDState |
shallowCopy()
Reserved for internal use.
| ||||||||||
abstract boolean |
unregisterEmulatorHooks(int hookId)
Unregister emulator hooks.
| ||||||||||
abstract boolean |
unregisterExecutionHelper(String methodSignature)
Remove a method execution helper.
| ||||||||||
abstract boolean |
unregisterNativeEmulatorHooks(int id)
Unregister a native emulator hooks.
| ||||||||||
abstract boolean |
unregisterNativeEmulatorMemoryHooks(int id)
Unregister a native emulator memory hooks.
| ||||||||||
abstract boolean |
unregisterSandboxHooks(int hookId)
Unregister sandbox hooks.
|
Default maximum duration, in milliseconds.
Default maximum depth for method invocations.
Default maximum iteration count.
Sub-routine execution policy: this special flag allows everything.
Sub-routine execution policy: this flag allows external routines.
Sub-routine execution policy: this flag allows internal routines.
Sub-routine execution policy: this flag forbids the emulation of sub-routines.
Convenience method to add class files (single class or Jar) to the sandbox classloader.
IOException |
---|
Quickly determine whether this State is usable, that is, can code be emulated (e.g. did we reach the max iteration count or timeout?)
Clone an array.
arrayRef | source array reference |
---|
array.clone
protected method)DexDecEvaluationException |
---|
Create an array. The array object will live in this emulator.
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] |
DexDecEvaluationException |
---|
@return
DexDecEvaluationException |
---|
Create a new instance of an object. This method is similar to newInstance()
; it
allocates an object and executes a constructor method.
constructorSignature | full signature, e.g. Lcom/abc/Foo-><init>(II)V |
---|---|
constructorParameters | parameters |
DexDecEvaluationException |
---|
Delete the most recent (top) frame of the current execution context.
Convenience method to remove a defined variable in the current frame (top frame of the top context).
varid | variable id |
---|
DexDecEvaluationException |
---|
Enable or disable the emulator. The emulator must be enabled to permit the execution of IDInstruction#evaluate().
Enable or disable the handling of exceptions generated by the emulated code.
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).
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 )
|
---|
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).
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 because pcExpectedTermination
was provided and was reached,
etc.), the current frame is left as-is to allow client code to examine it.
info | execution parameters, including the IR instructions |
---|
DexDecEvaluationException |
---|
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 like getObject(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, use
createNewInstance(String, Collection)
.
m | a dex internal method |
---|---|
args | method arguments |
DexDecEvaluationException | an evaluation exception occurred |
---|
This method is deprecated.
use invokeMethod(String, Collection, DInvokeType)
instead
DexDecEvaluationException |
---|
Retrieve the parent APK unit of the Dex unit that is being emulated.
Read an array element.@return
DexDecEvaluationException |
---|
Retrieve an array by reference.@return
DexDecEvaluationException |
---|
Get the length of an array.@return
DexDecEvaluationException |
---|
Retrieve a classref reference by name.@return
classname | fully-qualified name, e.g. Lcom/abc/Foo; |
---|
DexDecEvaluationException |
---|
Retrieve a read-only collection of emulation contexts.
A convenience method to get the count of contexts.
Convenience method to retrieve the current (newest) context.
Set the emulator timeout value.
If a run exceeds the timeout, the emulation fails and a
DexDecEvalTimeoutExceededException
exception is raised.
Convenience method to retrieve the top frame of the current (newest) context.
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.
Get (retrieve) a piece of data attached to this emulator object.
key | non-null key |
---|
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.
Retrieve the value of an instance field.@return
DexDecEvaluationException |
---|
Retrieve the number of iterations left.
Retrieve the emulator timeout value.
Get the maximum allowed depth for method invocations.
DEFAULT_MAX_INVOCATION_DEPTH
)
Retrieve the max iteration count value.
Retrieve the native emulator. This method will throw if native code emulation is disabled.
Get the list of native libraries loaded in the native emulator.
DexDecEvaluationException |
---|
Retrieve an object value by its reference.
ref | a wrapped reference or a string immediate |
---|
DexDecEvaluationException |
---|
Convenience method to retrieve an object by its reference id.
objid | an object id |
---|
DexDecEvaluationException | if no object with the provided id exists |
---|
Retrieve an object value by its reference.
ref | a wrapped reference or a string immediate |
---|
DexDecEvaluationException |
---|
Retrieve the emulated class object for the provided object.
objid | an object reference id |
---|
DexDecEvaluationException | if no object with the provided id exists |
---|
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.
objid | an object reference id |
---|
DexDecEvaluationException | if no object with the provided id exists |
---|
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. This method will throw if native code emulation is disabled.
Retrieve the classloader used by the sandbox.
Retrieve the sandbox folder containing dropped files.
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.@return
DexDecEvaluationException |
---|
Retrieve a string by reference.@return
DexDecEvaluationException |
---|
Retrieve the emulation policy for invoking sub-routines.
SUBEXEC_xxx
flags
Retrieve the amount of emulation time left.
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;
Convenience method to read the value of a variable in the current frame (top frame of the top context).
varid | variable id |
---|
DexDecEvaluationException |
---|
Convenience method to read the value of a variable in the current frame (top frame of the top context). The variable must exist.
varid | variable id |
---|
DexDecEvaluationException | thrown if the variable is not set |
---|
Determine whether a variable is set (has a value).@return
varid | variable id |
---|
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.
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 be NEW ) |
void
methods)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.
invokeType | invocation type (it cannot be NEW ) |
---|---|
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) |
void
methods)DexDecEvaluationException |
---|
Determine whether the emulator is enabled. The emulator must be enabled to permit the execution of IDInstruction#evaluate().
Determine whether handling of exceptions generated by the emulated code is enabled. If not,
any exception raised during emulation will bubble up as a DexDecEvaluationException
.
Determine whether an object is assignment-compatible with a class type.@return
DexDecEvaluationException |
---|
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).
dexdec-emu.cfg
)
Determine if direct unreflection is enabled.
Determine whether the sandbox is enabled.
Find a class. The class may be internal (defined in dex) or external.
csig | fully-qualified signature, e.g. Lcom/abc/Foo; |
---|---|
initialize | if true, the class will be initialized |
Class
objectDexDecEvaluationException |
---|
Find, load and initialize a class. The class may be internal (defined in dex) or external.
csig | fully-qualified signature, e.g. Lcom/abc/Foo; |
---|
Class
objectDexDecEvaluationException |
---|
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.
libname | a library name, as provided to a call to loadLibrary(String) |
---|
DexDecEvaluationException |
---|
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, see
loadNativeLibrary(String)
.
Upon successful load, the JNI_OnLoad
method is emulated. The emulator as well as
native emulator must be enabled.
lib | ELF Shared Objec unit located in the project |
---|
DexDecEvaluationException |
---|
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.
libname | a library path or library name |
---|---|
isPath | 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) |
DexDecEvaluationException |
---|
Create and push a new execution context. IR emulation takes place within the top emulation context.
Create and push a frame within the current (top) emulation context. A frame (method frame) contains the current PC, variables, etc.
Register emulator hooks. Refer to IDEmulatorHooks
for details.
hooks | an emulator sandbox hooks object |
---|
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
emulate indexOf()
will result in the helper being called. The helper is responsible
for providing the result of execution.
Register a native emulator hooks.
hooks | an evaluation hooks object registered with the native emulator |
---|
Register a native emulator memory hooks.
hooks | an evaluation hooks object registered with the native emulator |
---|
Register sandbox hooks. Refer to IDSandboxHooks
for details.
hooks | an emulator sandbox hooks object |
---|
Release an object currently living in this State. Watch out! References are not checked. Other objects may use the deleted object.@return
DexDecEvaluationException |
---|
Write an array element.
DexDecEvaluationException |
---|
Set (attach) a piece data to this emulator object.
key | non-null key |
---|---|
value | non-null value |
Set an emulation policy for environment-related, time and date-related, and other API methods yielding unpredictable results.
policy | the new policy |
---|
Update the value of an instance field.
DexDecEvaluationException |
---|
Set the emulator timeout value.
If a run exceeds the timeout, the emulation fails and a
DexDecEvalTimeoutExceededException
exception is raised.
maxDuration | in ms |
---|
Set the maximum depth for method invocations.
This attribute is also used as a safety mechanism to prevent stack overflows during emulation.
maxInvocationDepth | a positive value |
---|
Set or reset the max iteration count.
If the maximum iteration count is reached, a DexDecEvalItercountExceededException
exception is be raised.
Convenience method to write the IR program counter in the current frame (top frame of the top context).
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.
Specify where files written by sandboxed code should be written to. All files written during emulation will be dropped to this folder.
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 |
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.
DexDecEvaluationException |
---|
Set the emulation policy for invoking sub-routines.
subRoutineInvocationPolicy | a combination of SUBEXEC_xxx flags
|
---|
Convenience method to write the value of a variable in the current frame (top frame of the top context).
varid | variable id |
---|---|
value | the value to be written |
DexDecEvaluationException |
---|
Reserved for internal use.
Generate a partial copy of this state.
Unregister emulator hooks.
hookId | hooks object id, returned by registerEmulatorHooks |
---|
Remove a method execution helper.
Unregister a native emulator hooks.
id | hooks object id |
---|
Unregister a native emulator memory hooks.
id | hooks object id |
---|
Unregister sandbox hooks.
hookId | hooks object id, returned by registerSandboxUserHooks |
---|