IDState

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.

Convenience method to add class files (single class or Jar) to the sandbox classloader.

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.

Create an array. The array object will live in this emulator.

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.

Create a new instance of an object. This method is similar to newInstance(); it allocates an object and executes a constructor method.

Delete the most recent (top) execution context.

Delete the most recent (top) frame of the current execution context.

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 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. 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.

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).

Execute an external (non dex) non-constructor method.

Read an array element.@return

Retrieve an array by reference.@return

Get the length of an array.@return

Retrieve a classref reference by name.@return

Get the count of contexts.

Get the number of frames in the provided context.

Set the emulator timeout value.

If a run exceeds the timeout, the emulation fails and a DexDecEvalTimeoutExceededException exception is raised.

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.

Retrieve the collection of all registered method execution helpers.

Retrieve the global IR context that was used to create this State.

Retrieve the value of an instance field.@return

Retrieve the number of iterations left.

Get the maximum allowed depth for method invocations.

Retrieve the method signature or name for a given frame.@return

Retrieve an object value by its reference.

Retrieve an object value by its reference.

Retrieve the IR program counter in a given frame.@return

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

Retrieve a string by reference.@return

Retrieve the emulation policy for invoking sub-routines.

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;

Retrieve the value of a variable in a given frame.@return

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

Determine if direct unreflection is enabled.

Determine whether the sandbox is enabled.

Load a class. The class may be internal (defined in dex) or external.

Register emulator hooks. Refer to IDEmulatorHooks for details.

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 an object.

Register sandbox hooks. Refer to IDSandboxHooks for details.

Release an object currently living in this State. Watch out! References are not checked. Other objects may use the deleted object.@return

Write an array element.

Set (attach) a piece data to this emulator object.

Update the value of an instance field.

Set the emulator timeout value.

If a run exceeds the timeout, the emulation fails and a DexDecEvalTimeoutExceededException exception is raised.

Set the maximum depth for method invocations.

This attribute is also used as a safety mechanism to prevent stack overflows during emulation.

Set or reset the max iteration count.

If the maximum iteration count is reached, a DexDecEvalItercountExceededException exception is be raised.

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.

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.

Set the emulation policy for invoking sub-routines.

Set the value of a variable in a given frame.

Unregister emulator hooks.

Remove a method execution helper.

Unregister sandbox hooks.