# Interface: com.pnfsoftware.jeb.core.units.code.android.ir.IDState

`dexdec` IR state \(referred as "State"\), used to perform IR evaluations, emulation and sandboxing. After use, a state must be [disposed](#dispose()) 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](AbstractDOptimizer)\), see methods [IDGlobalContext#createState()](IDGlobalContext#createState()) and [IDGlobalContext#getThreadSharedState()](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](IDImm) objects: they represent both immediate values, as well as object references living in a State object.

## Static Field: DEFAULT_MAX_DURATION
Type: `int`

Constant value: `1000`
Description: Default maximum duration, in milliseconds.

## Static Field: DEFAULT_MAX_INVOCATION_DEPTH
Type: `int`

Constant value: `50`
Description: Default maximum depth for method invocations.

## Static Field: DEFAULT_MAX_ITERCOUNT
Type: `int`

Constant value: `100`
Description: Default maximum iteration count.

## Static Field: FIELDACCESS_ALLOW_ALL
Type: `int`

Constant value: `255`
Description: Field access policy: this special flag allows all field access.

## Static Field: FIELDACCESS_ALLOW_READ_EXTERNAL_INSTANCE
Type: `int`

Constant value: `1`
Description: Field access policy: this flag allows reads of external instance fields.

## Static Field: FIELDACCESS_ALLOW_READ_EXTERNAL_STATIC
Type: `int`

Constant value: `16`
Description: Field access policy: this flag allows reads of external static fields.

## Static Field: FIELDACCESS_ALLOW_READ_INTERNAL_INSTANCE
Type: `int`

Constant value: `4`
Description: Field access policy: this flag allows reads of internal instance fields.

## Static Field: FIELDACCESS_ALLOW_READ_INTERNAL_STATIC
Type: `int`

Constant value: `64`
Description: Field access policy: this flag allows reads of internal static fields.

## Static Field: FIELDACCESS_ALLOW_WRITE_EXTERNAL_INSTANCE
Type: `int`

Constant value: `2`
Description: Field access policy: this flag allows writes of external instance fields.

## Static Field: FIELDACCESS_ALLOW_WRITE_EXTERNAL_STATIC
Type: `int`

Constant value: `32`
Description: Field access policy: this flag allows writes of external static fields.

## Static Field: FIELDACCESS_ALLOW_WRITE_INTERNAL_INSTANCE
Type: `int`

Constant value: `8`
Description: Field access policy: this flag allows writes of internal instance fields.

## Static Field: FIELDACCESS_ALLOW_WRITE_INTERNAL_STATIC
Type: `int`

Constant value: `128`
Description: Field access policy: this flag allows writes of internal static fields.

## Static Field: FIELDACCESS_DENY_ALL
Type: `int`

Constant value: `0`
Description: Field access policy: this flag forbids all field access.

## Static Field: SUBEXEC_ALLOW_ALL
Type: `int`

Constant value: `255`
Description: Sub\-routine execution policy: this special flag allows everything.

## Static Field: SUBEXEC_ALLOW_EXTERNAL
Type: `int`

Constant value: `2`
Description: Sub\-routine execution policy: this flag allows external routines.

## Static Field: SUBEXEC_ALLOW_INTERNAL
Type: `int`

Constant value: `1`
Description: Sub\-routine execution policy: this flag allows internal routines.

## Static Field: SUBEXEC_DENY_ALL
Type: `int`

Constant value: `0`
Description: Sub\-routine execution policy: this flag forbids the emulation of sub\-routines.

## Method: addClassfilesToSandbox
- parameter: `f`, type: `java.io.File`

Description: Convenience method to add class files \(single class or Jar\) to the sandbox classloader.
parameter: f: a class file, directory, or Jar file to add
throws: if the entry cannot be added

## Method: canRun
- return type: `boolean`

Description: Quickly determine whether this State is usable, that is, can code be emulated \(e.g. did we reach the max iteration count or timeout?\)
return: true if emulation may continue

## Method: cloneArray
- parameter: `arrayRef`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: Clone an array.
parameter: arrayRef: source array reference
return: the cloned array \(as defined by the JLS's `array.clone` protected method\)
throws: if the array cannot be cloned

## Method: createArray
- parameter: `type`, type: `com.pnfsoftware.jeb.core.units.code.java.IJavaType`
- parameter: `len`, type: `int`
- parameter: `initialValues`, type: `java.util.List<? extends com.pnfsoftware.jeb.core.units.code.android.ir.IDImm>`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: Create an array. The array object will live in this emulator.
parameter: type: the array type e.g. int\[\]\[\]\[\], or String\[\]\[\], or X\[\]
parameter: len: the length of the first dimension, re\-using the examples above, would indicate an            array int\[N\]\[\]\[\], String\[N\]\[\], X\[N\]
parameter: initialValues: a list of initial values, non\-null, whose length must in \[0, N\]
return: the IR constant wrapping the array
throws: if the array cannot be created

## Method: createArray
- parameter: `typesig`, type: `java.lang.String`
- parameter: `len`, type: `int`
- parameter: `initialValues`, type: `java.util.List<? extends com.pnfsoftware.jeb.core.units.code.android.ir.IDImm>`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: Create an array. The array object will live in this emulator.
parameter: typesig: the array type signature, '\[\[\[I' or '\[\[Ljava/lang/String;'
parameter: len: the length of the first dimension
parameter: initialValues: a list of initial values, non\-null, whose length must in \[0, N\]
return: the IR constant wrapping the array
throws: if the array cannot be created

## Method: createNewInstance
- parameter: `constructorSignature`, type: `java.lang.String`
- parameter: `constructorParameters`, type: `java.util.Collection<com.pnfsoftware.jeb.core.units.code.android.ir.IDExpression>`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: Create a new instance of an object. This method is similar to [Class#newInstance()](Class#newInstance()); it allocates an object and executes a constructor method.
parameter: constructorSignature: full signature, e.g. `Lcom/abc/Foo-><init>(II)V`
parameter: constructorParameters: parameters
return: the newly\-created instance
throws: if the instance cannot be created

## Method: createNewInstance
- parameter: `classSignature`, type: `java.lang.String`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: Create a new instance of a class without invoking an explicit constructor signature.
parameter: classSignature: class signature
return: the newly\-created instance
throws: if the instance cannot be created

## Method: deleteTopContext
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDEmuContext`

Description: Delete the most recent \(top\) execution context.
return: the removed context

## Method: deleteTopFrame
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDEmuFrame`

Description: Delete the most recent \(top\) frame of the current execution context.
return: the removed frame

## Method: deleteVariable
- parameter: `varid`, type: `int`
- return type: `boolean`

Description: Convenience method to remove a defined variable in the current frame \(top frame of the top context\).
parameter: varid: variable id
return: true if the variable was removed
throws: if no current frame is available

## Method: dispose

Description: Dispose of this emulator's resources.

## Method: enableEmulator
- parameter: `enabled`, type: `boolean`

Description: Enable or disable the emulator. The emulator must be enabled to permit the execution of [IDInstruction#evaluate(Map)](IDInstruction#evaluate(Map)).
parameter: enabled: true to enable the emulator, false to disable it

## Method: enableExceptionHandling
- parameter: `enabled`, type: `boolean`

Description: 
deprecated: use [#setExceptionHandlingEnabled(boolean)](#setExceptionHandlingEnabled(boolean)) instead
parameter: enabled: true to enable exception handling, false to disable it

## Method: enableNativeCodeEmulator
- parameter: `enabled`, type: `boolean`

Description: 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\).
parameter: 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`\)

## Method: enableSandbox
- parameter: `enabled`, type: `boolean`
- return type: `boolean`

Description: 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\).
parameter: enabled: true to enable the sandbox, false to disable it
return: success indicator

## Method: execute
- parameter: `info`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.DExecutionParameters`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: 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](DExecutionParameters#pcExpectedTermination) 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.
parameter: info: execution parameters, including the IR instructions
return: the execution return value
throws: if execution fails

## Method: executeDexMethod
- parameter: `m`, type: `com.pnfsoftware.jeb.core.units.code.android.dex.IDexMethod`
- parameter: `args`, type: `java.util.List<com.pnfsoftware.jeb.core.units.code.android.ir.IDExpression>`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: 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)](#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)](#createNewInstance(String, Collection)).
parameter: m: a dex internal method
parameter: args: method arguments
return: the return value upon completion, if there is one
throws: an evaluation exception occurred

## Method: getAndroidAppEmulator
- return type: `com.pnfsoftware.jeb.core.units.code.android.IAndroidAppEmulator`

Description: Retrieve a reference to the lower\-level Android app emulator. That component is used to emulate the Android Linux subsystem used to run an application.
return: the Android app emulator, or null if it is not available

## Method: getApk
- return type: `com.pnfsoftware.jeb.core.units.code.android.IApkUnit`

Description: Retrieve the parent APK unit of the Dex unit that is being emulated.
return: an apk unit; maybe null

## Method: getArrayElement
- parameter: `arrayRef`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`
- parameter: `index`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: Read an array element.
parameter: arrayRef: array reference
parameter: index: zero\-based element index
return: the array element value
throws: if the element cannot be read

## Method: getArrayObject
- parameter: `ref`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`
- return type: `java.lang.Object`

Description: Retrieve an array by reference.
parameter: ref: array reference
return: the array object
throws: if the reference does not resolve to an array

## Method: getArrayObjectLength
- parameter: `ref`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`
- return type: `int`

Description: Get the length of an array.
parameter: ref: array reference
return: the array length
throws: if the reference does not resolve to an array

## Method: getClassReference
- parameter: `classname`, type: `java.lang.String`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: Retrieve a classref reference by name. The class is not initialized.
parameter: classname: fully\-qualified name, e.g. `Lcom/abc/Foo;`
return: the class object reference
throws: if the class reference cannot be resolved

## Method: getContexts
- return type: `java.util.Collection<com.pnfsoftware.jeb.core.units.code.android.ir.IDEmuContext>`

Description: Retrieve a read\-only collection of emulation contexts.
return: the read\-only collection of contexts

## Method: getCountOfContexts
- return type: `int`

Description: A convenience method to get the count of contexts.
return: the number of contexts

## Method: getCurrentContext
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDEmuContext`

Description: Convenience method to retrieve the current \(newest\) context.
return: the current context, or null if none exists

## Method: getCurrentDuration
- return type: `long`

Description: Set the emulator timeout value. 

 If a run exceeds the timeout, the emulation fails and a [DexDecEvalTimeoutExceededException](DexDecEvalTimeoutExceededException) exception is raised.
return: in ms

## Method: getCurrentFrame
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDEmuFrame`

Description: Convenience method to retrieve the top frame of the current \(newest\) context.
return: the current frame, or null if no current frame exists

## Method: getCurrentIterationCount
- return type: `int`

Description: 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](DexDecEvalItercountExceededException) exception is be raised.
return: the number of statements already emulated or executed

## Method: getData
- parameter: `key`, type: `java.lang.String`
- return type: `java.lang.Object`

Description: Get \(retrieve\) a piece of data attached to this emulator object.
parameter: key: non\-null key
return: the data, null if none

## Method: getDecompiler
- return type: `com.pnfsoftware.jeb.core.units.code.android.IDexDecompilerUnit`

Description: Convenience method.
return: never null

## Method: getDex
- return type: `com.pnfsoftware.jeb.core.units.code.android.IDexUnit`

Description: Convenience method.
return: never null

## Method: getEmulatedEnvironment
- return type: `com.pnfsoftware.jeb.core.units.code.android.IEmulatedAndroid`

Description: Retrieve the optional "emulated Android" manager of this dex code emulator.
return: the emulated Android environment, or null if none is configured

## Method: getEmulatedMemberForPseudoMember
- parameter: `m`, type: `java.lang.reflect.Member`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDEmuMember`

Description: Retrieve the emulated\-member object associated with a native Java reflection member object.
parameter: m: a native Java reflection member object
return: the associated emulated\-member object, null if there is none
throws: if the member cannot be resolved

## Method: getExecutionHelpers
- return type: `java.util.Collection<com.pnfsoftware.jeb.core.units.code.android.ir.IDMethodExecutionHelper>`

Description: Retrieve the collection of all registered method execution helpers.
return: the registered method execution helpers

## Method: getExternalPolicy
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.DEmuExternalPolicy`

Description: Retrieve the current emulation policy for environment\-related, time and date\-related, and other API methods yielding unpredictable results.
return: may be null

## Method: getFieldAccessPolicy
- return type: `int`

Description: Retrieve the emulation policy for accessing fields.
return: a combination of `FIELDACCESS_xxx` flags

## Method: getGlobalContext
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDGlobalContext`

Description: Retrieve the global IR context that was used to create this State.
return: the global context that owns this state

## Method: getInstanceField
- parameter: `fsig`, type: `java.lang.String`
- parameter: `instance`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: Retrieve the value of an instance field.
parameter: fsig: field signature
parameter: instance: instance reference
return: the field value
throws: if the field cannot be read

## Method: getIterationCountLeft
- return type: `int`

Description: Retrieve the number of iterations left.
return: the number of iterations remaining before the iteration limit is reached

## Method: getMaxDuration
- return type: `long`

Description: Retrieve the emulator timeout value.
return: max duration in ms

## Method: getMaxInvocationDepth
- return type: `int`

Description: Get the maximum allowed depth for method invocations.
return: the current maximum depth \(defaults to [#DEFAULT_MAX_INVOCATION_DEPTH](#DEFAULT_MAX_INVOCATION_DEPTH)\)

## Method: getMaxIterationCount
- return type: `int`

Description: Retrieve the max iteration count value.
return: max iteration count

## Method: getNativeEmulator
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.EEmulator`

Description: Retrieve the native emulator. This method will throw if native code emulation is disabled.
return: 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\)

## Method: getNativeLibraries
- return type: `java.util.List<com.pnfsoftware.jeb.core.units.code.android.INativeLibrary>`

Description: Get the list of native libraries loaded in the native emulator.
return: a list of library objects, possibly empty
throws: if native library information cannot be retrieved

## Method: getObject
- parameter: `ref`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`
- return type: `java.lang.Object`

Description: Retrieve an object value by its reference.
parameter: ref: a wrapped reference or a string immediate
return: an object
throws: if the reference cannot be resolved

## Method: getObject
- parameter: `ref`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`
- parameter: `provideNativeObject`, type: `boolean`
- return type: `java.lang.Object`

Description: Retrieve an object value by its reference.
parameter: ref: a wrapped reference or a string immediate
parameter: provideNativeObject: true to allow returning the underlying native Java object
return: an object, or null \(which does not indicate an error, but the null reference\)
throws: if the reference cannot be resolved

## Method: getObject
- parameter: `objid`, type: `int`
- return type: `java.lang.Object`

Description: Convenience method to retrieve an object by its reference id.
parameter: objid: an object id
return: the object \(null if the provided id was 0 \- the null reference\)
throws: if no object with the provided id exists

## Method: getObjectClass
- parameter: `objid`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDEmuClass`

Description: Retrieve the emulated class object for the provided object.
parameter: objid: an object reference id
return: the emulated class object \(null if the provided id was 0 \- the null reference\)
throws: if no object with the provided id exists

## Method: getObjectClassId
- parameter: `objid`, type: `int`
- return type: `int`

Description: 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.
parameter: objid: an object reference id
return: the object's class object reference id \(null if the provided id was 0 \- the null         reference\)
throws: if no object with the provided id exists

## Method: getPC
- return type: `int`

Description: Convenience method to read the IR program counter in the current frame \(top frame of the top context\).
return: the current program counter

## Method: getRegisteredNatives
- return type: `java.util.Map<java.lang.String,java.lang.Long>`

Description: Retrieve the list of native methods registered via JNI. This method will throw if native code emulation is disabled.
return: a map; key= is the native Java method signature, value= native address in the         emulated process space

## Method: getSandboxClassLoader
- return type: `java.net.URLClassLoader`

Description: Retrieve the classloader used by the sandbox.
return: the sandbox classloader, or null if the sandbox is not initialized

## Method: getSandboxDropFolder
- return type: `java.io.File`

Description: Retrieve the sandbox folder containing dropped files.
return: the drop box folder, or null if none was set

## Method: getStaticField
- parameter: `fsig`, type: `java.lang.String`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: 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.
parameter: fsig: field signature
return: the field value
throws: if the field cannot be read

## Method: getStringObject
- parameter: `strOrRef`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`
- return type: `java.lang.String`

Description: Retrieve a string by reference.
parameter: strOrRef: string immediate or string\-object reference
return: the string value
throws: if the object cannot be resolved as a string

## Method: getSubRoutineInvocationPolicy
- return type: `int`

Description: Retrieve the emulation policy for invoking sub\-routines.
return: a combination of `SUBEXEC_xxx` flags

## Method: getTimeLeft
- return type: `long`

Description: Retrieve the amount of emulation time left.
return: in ms, always \>= 0

## Method: getTypeAdapter
- return type: `com.pnfsoftware.jeb.core.units.code.android.IJLSTypeAdapter`

Description: 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;`
return: the Java type\-system adapter used by this state

## Method: getVariable
- parameter: `varid`, type: `int`
- parameter: `softFail`, type: `boolean`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: Convenience method to read the value of a variable in the current frame \(top frame of the top context\).
parameter: varid: variable id
parameter: softFail: true to return a soft\-failure value instead of throwing when the variable is            not set
return: the value \(non\-null\)
throws: if no current frame is available or the variable cannot be             read

## Method: getVariable
- parameter: `varid`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: Convenience method to read the value of a variable in the current frame \(top frame of the top context\). The variable must exist.
parameter: varid: variable id
return: the value \(non\-null\)
throws: thrown if the variable is not set

## Method: getWatchdog
- return type: `com.pnfsoftware.jeb.util.concurrent.Watchdog`

Description: Retrieve the watchdog used to interrupt long\-running emulations.
return: the current watchdog, possibly null

## Method: hasVariable
- parameter: `varid`, type: `int`
- return type: `boolean`

Description: Determine whether a variable is set \(has a value\).
parameter: varid: variable id
return: true if the variable is set
throws: if no current frame is available

## Method: invokeMethod
- parameter: `methodSignature`, type: `java.lang.String`
- parameter: `methodParameters`, type: `java.util.Collection<com.pnfsoftware.jeb.core.units.code.android.ir.IDExpression>`
- parameter: `invokeType`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.DInvokeType`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: 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.
parameter: methodSignature: full signature, e.g. `Lcom/abc/Foo->bar(I)L`
parameter: methodParameters: parameters \(for non\-static methods, the first entry must be the            target object reference\)
parameter: invokeType: invocation type \(it cannot be [NEW](DInvokeType#NEW)\)
return: the returned value \(null for `void` methods\)
throws: if the method cannot be invoked

## Method: invokeMethod
- parameter: `invokeType`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.DInvokeType`
- parameter: `methodSignature`, type: `java.lang.String`
- parameter: `methodParameters`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDExpression[]`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: 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.
parameter: invokeType: invocation type \(it cannot be [NEW](DInvokeType#NEW)\)
parameter: methodSignature: full signature, e.g. `Lcom/abc/Foo->bar(I)L`
parameter: methodParameters: parameters \(for non\-static methods, the first entry must be the            target object reference\)
return: the returned value \(null for `void` methods\)
throws: if the method cannot be invoked

## Method: isEmulatorEnabled
- return type: `boolean`

Description: Determine whether the emulator is enabled. The emulator must be enabled to permit the execution of [IDInstruction#evaluate(Map)](IDInstruction#evaluate(Map)).
return: true if bytecode emulation is enabled

## Method: isExceptionHandlingEnabled
- return type: `boolean`

Description: 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](DexDecEvaluationException).
return: true if exception handling is enabled

## Method: isInstanceOf
- parameter: `obj`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`
- parameter: `clz`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`
- return type: `boolean`

Description: Determine whether an object is assignment\-compatible with a class type.
parameter: obj: object reference
parameter: clz: class object reference
return: true if the object is an instance of the class
throws: if either reference cannot be resolved

## Method: isLazyJNIOnLoadExec
- return type: `boolean`

Description: Determine whether `JNI_OnLoad` should be executed lazily.
return: true if `JNI_OnLoad` execution is deferred until needed

## Method: isNativeCodeEmulatorEnabled
- return type: `boolean`

Description: 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\).
return: 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`\)

## Method: isPerformDirectUnreflection
- return type: `boolean`

Description: Determine if direct unreflection is enabled.
return: true if direct unreflection is enabled

## Method: isRequireNonNullObjectForNonStaticInvoke
- return type: `boolean`

Description: Determine whether non\-static invokes require a non\-null receiver object.
return: true if non\-static invokes require a non\-null receiver

## Method: isSandboxEnabled
- return type: `boolean`

Description: Determine whether the sandbox is enabled.
return: true if the sandbox is enabled

## Method: isStrictClassInit
- return type: `boolean`

Description: Determine how the emulator should behave if the initialization of a class failed.
return: if true, if the initialization of a class to be emulated fails, it is fully removed         from the emulator; otherwise, it is kept and considered loaded \(best\-effort\), and the         fields that were initialized before the class\-initializer failed are kept as well as         their values

## Method: loadClass
- parameter: `csig`, type: `java.lang.String`
- return type: `java.lang.Class<?>`

Description: Find, load and initialize a class. The class may be internal \(defined in dex\) or external.
parameter: csig: fully\-qualified signature, e.g. `Lcom/abc/Foo;`
return: the `Class` object
throws: if the class cannot be loaded

## Method: loadClass
- parameter: `csig`, type: `java.lang.String`
- parameter: `initialize`, type: `boolean`
- return type: `java.lang.Class<?>`

Description: Find a class. The class may be internal \(defined in dex\) or external.
parameter: csig: fully\-qualified signature, e.g. `Lcom/abc/Foo;`
parameter: initialize: if true, the class will be initialized
return: the `Class` object
throws: if the class cannot be loaded

## Method: loadNativeLibrary
- parameter: `lib`, type: `com.pnfsoftware.jeb.core.units.codeobject.IELFUnit`
- return type: `com.pnfsoftware.jeb.core.units.code.android.INativeLibrary`

Description: 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)](#loadNativeLibrary(String)). 

 Upon successful load, the `JNI_OnLoad` method is emulated. The emulator as well as native emulator must be enabled.
parameter: lib: ELF shared object unit located in the project
return: a library description object
throws: if the library cannot be loaded

## Method: loadNativeLibrary
- parameter: `libname`, type: `java.lang.String`
- return type: `com.pnfsoftware.jeb.core.units.code.android.INativeLibrary`

Description: 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.
parameter: libname: a library name, as provided to a call to [System#loadLibrary(String)](System#loadLibrary(String))
return: a library description object
throws: if the library cannot be loaded

## Method: loadNativeLibrary
- parameter: `libname`, type: `java.lang.String`
- parameter: `isPath`, type: `boolean`
- return type: `com.pnfsoftware.jeb.core.units.code.android.INativeLibrary`

Description: 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.
parameter: libname: a library path or library name
parameter: 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\)
return: a library description object
throws: if the library cannot be loaded

## Method: pushContext
- parameter: `name`, type: `java.lang.String`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDEmuContext`

Description: Create and push a new execution context. IR emulation takes place within the top emulation context.
parameter: name: context name
return: the newly\-pushed context

## Method: pushFrame
- parameter: `methodSignature`, type: `java.lang.String`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDEmuFrame`

Description: Create and push a frame within the current \(top\) emulation context. A frame \(method frame\) contains the current PC, variables, etc.
parameter: methodSignature: method signature associated with the frame
return: the newly\-pushed frame

## Method: registerEmulatorHooks
- parameter: `hooks`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDEmulatorHooks`
- return type: `int`

Description: Register emulator hooks. Refer to [IDEmulatorHooks](IDEmulatorHooks) for details.
parameter: hooks: an emulator sandbox hooks object
return: the hooks object id

## Method: registerExecutionHelper
- parameter: `helper`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDMethodExecutionHelper`

Description: 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.
parameter: helper: the helper to register

## Method: registerNativeEmulatorHooks
- parameter: `hooks`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.IEEmulatorHooks`
- return type: `int`

Description: Register a native emulator hooks.
parameter: hooks: an evaluation hooks object registered with the native emulator
return: the hooks object id

## Method: registerNativeEmulatorMemoryHooks
- parameter: `hooks`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEStateHooks`
- return type: `int`

Description: Register a native emulator memory hooks.
parameter: hooks: an evaluation hooks object registered with the native emulator
return: the hooks object id

## Method: registerObject
- parameter: `o`, type: `java.lang.Object`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: Register an object.
parameter: o: object to register
return: the object reference

## Method: registerSandboxHooks
- parameter: `hooks`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDSandboxHooks`
- return type: `int`

Description: Register sandbox hooks. Refer to [IDSandboxHooks](IDSandboxHooks) for details.
parameter: hooks: an emulator sandbox hooks object
return: the hooks object id

## Method: releaseObject
- parameter: `ref`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`
- return type: `java.lang.Object`

Description: Release an object currently living in this State. Watch out\! References are not checked. Other objects may use the deleted object.
parameter: ref: object reference
return: the released object, or null for the null reference
throws: if the reference cannot be resolved

## Method: setArrayElement
- parameter: `arrayRef`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`
- parameter: `index`, type: `int`
- parameter: `val`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: Write an array element.
parameter: arrayRef: array reference
parameter: index: zero\-based element index
parameter: val: new element value
throws: if the element cannot be written

## Method: setData
- parameter: `key`, type: `java.lang.String`
- parameter: `value`, type: `java.lang.Object`

Description: Set \(attach\) a piece data to this emulator object.
parameter: key: non\-null key
parameter: value: non\-null value

## Method: setExceptionHandlingEnabled
- parameter: `enabled`, type: `boolean`
- return type: `boolean`

Description: Enable or disable the handling of exceptions generated by the emulated code.
parameter: enabled: true to enable exception handling, false to disable it
return: the previous value of this setting

## Method: setExternalPolicy
- parameter: `policy`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.DEmuExternalPolicy`
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.DEmuExternalPolicy`

Description: Set an emulation policy for environment\-related, time and date\-related, and other API methods yielding unpredictable results.
parameter: policy: the new policy
return: the former policy \(if any, may be null\)

## Method: setFieldAccessPolicy
- parameter: `fieldAccessPolicy`, type: `int`
- return type: `int`

Description: Set the emulation policy for accessing fields.
parameter: fieldAccessPolicy: a combination of `FIELDACCESS_xxx` flags
return: the previous value of this setting

## Method: setInstanceField
- parameter: `fsig`, type: `java.lang.String`
- parameter: `instance`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`
- parameter: `val`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: Update the value of an instance field.
parameter: fsig: field signature
parameter: instance: instance reference
parameter: val: new field value
throws: if the field cannot be written

## Method: setLazyJNIOnLoadExec
- parameter: `lazy`, type: `boolean`
- return type: `boolean`

Description: Set whether `JNI_OnLoad` should be executed lazily.
parameter: lazy: true to defer `JNI_OnLoad` execution until needed
return: the previous value of this setting

## Method: setMaxDuration
- parameter: `maxDuration`, type: `long`
- return type: `long`

Description: Set the emulator timeout value. 

 If a run exceeds the timeout, the emulation fails and a [DexDecEvalTimeoutExceededException](DexDecEvalTimeoutExceededException) exception is raised.
parameter: maxDuration: duration in ms \(a negative value means the maximum\)
return: the previous value of this setting

## Method: setMaxInvocationDepth
- parameter: `maxInvocationDepth`, type: `int`
- return type: `int`

Description: Set the maximum depth for method invocations. 

 This attribute is also used as a safety mechanism to prevent stack overflows during emulation.
parameter: maxInvocationDepth: a positive value
return: the previous value of this setting

## Method: setMaxIterationCount
- parameter: `maxInsnCount`, type: `int`
- return type: `int`

Description: Set or reset the max iteration count. 

 If the maximum iteration count is reached, a [DexDecEvalItercountExceededException](DexDecEvalItercountExceededException) exception is be raised.
parameter: maxInsnCount: iteration count \(a negative value means the maximum\)
return: the previous value of this setting

## Method: setPC
- parameter: `pc`, type: `int`

Description: Convenience method to write the IR program counter in the current frame \(top frame of the top context\).
parameter: pc: program counter value

## Method: setPerformDirectUnreflection
- parameter: `performDirectUnreflection`, type: `boolean`
- return type: `boolean`

Description: 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.
parameter: performDirectUnreflection: true to enable direct unreflection
return: the previous value of this setting

## Method: setRequireNonNullObjectForNonStaticInvoke
- parameter: `required`, type: `boolean`
- return type: `boolean`

Description: Set whether non\-static invokes require a non\-null receiver object.
parameter: required: true to require a non\-null receiver
return: the previous value of this setting

## Method: setStaticField
- parameter: `fsig`, type: `java.lang.String`
- parameter: `val`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: 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.
parameter: fsig: field signature
parameter: val: new field value
throws: if the field cannot be written

## Method: setStrictClassInit
- parameter: `strictClassInit`, type: `boolean`
- return type: `boolean`

Description: Set how the emulator should behave if the initialization of a class failed.
parameter: strictClassInit: if true, if the initialization of a class to be emulated fails, it is            fully removed from the emulator; otherwise, it is kept and considered loaded            \(best\-effort\), and the fields that were initialized before the class\-initializer            failed are kept as well as their values
return: the previous value of this setting

## Method: setSubRoutineInvocationPolicy
- parameter: `subRoutineInvocationPolicy`, type: `int`
- return type: `int`

Description: Set the emulation policy for invoking sub\-routines.
parameter: subRoutineInvocationPolicy: a combination of `SUBEXEC_xxx` flags
return: the previous value of this setting

## Method: setVariable
- parameter: `varid`, type: `int`
- parameter: `value`, type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDImm`

Description: Convenience method to write the value of a variable in the current frame \(top frame of the top context\).
parameter: varid: variable id
parameter: value: the value to be written
throws: if no current frame is available

## Method: setWatchdog
- parameter: `watchdog`, type: `com.pnfsoftware.jeb.util.concurrent.Watchdog`
- return type: `com.pnfsoftware.jeb.util.concurrent.Watchdog`

Description: Set a watchdog. Similarly to the max\-iteration count or max\-duration limits, the watchdog is regularly checked and an emulation may throw [OperationTimedOutException](OperationTimedOutException) is the watchdog timed\-out.
parameter: watchdog: an optional watchdog
return: the previous value

## Method: shallowCopy
- return type: `com.pnfsoftware.jeb.core.units.code.android.ir.IDState`

Description: Reserved for internal use. 

 Generate a partial copy of this state.
return: a partial copy of this state

## Method: unregisterEmulatorHooks
- parameter: `hookId`, type: `int`
- return type: `boolean`

Description: Unregister emulator hooks.
parameter: hookId: hooks object id, returned by [registerEmulatorHooks](#registerEmulatorHooks(IDEmulatorHooks))
return: success indicator

## Method: unregisterExecutionHelper
- parameter: `methodSignature`, type: `java.lang.String`
- return type: `boolean`

Description: Remove a method execution helper.
parameter: methodSignature: the signature of the method associated with the helper
return: true if a helper was removed

## Method: unregisterNativeEmulatorHooks
- parameter: `id`, type: `int`
- return type: `boolean`

Description: Unregister a native emulator hooks.
parameter: id: hooks object id
return: success indicator

## Method: unregisterNativeEmulatorMemoryHooks
- parameter: `id`, type: `int`
- return type: `boolean`

Description: Unregister a native emulator memory hooks.
parameter: id: hooks object id
return: success indicator

## Method: unregisterSandboxHooks
- parameter: `hookId`, type: `int`
- return type: `boolean`

Description: Unregister sandbox hooks.
parameter: hookId: hooks object id, returned by [registerSandboxUserHooks](#registerSandboxHooks(IDSandboxHooks))
return: success indicator