public 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 frames, 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 Details

    • DEFAULT_MAX_ITERCOUNT

      static final int DEFAULT_MAX_ITERCOUNT
      Default maximum iteration count.
      See Also:
    • DEFAULT_MAX_DURATION

      static final int DEFAULT_MAX_DURATION
      Default maximum duration, in milliseconds.
      See Also:
    • DEFAULT_MAX_INVOCATION_DEPTH

      static final int DEFAULT_MAX_INVOCATION_DEPTH
      Default maximum depth for method invocations.
      See Also:
    • SUBEXEC_DENY_ALL

      static final int SUBEXEC_DENY_ALL
      Sub-routine execution policy: this flag forbids the emulation of sub-routines.
      See Also:
    • SUBEXEC_ALLOW_INTERNAL

      static final int SUBEXEC_ALLOW_INTERNAL
      Sub-routine execution policy: this flag allows internal routines.
      See Also:
    • SUBEXEC_ALLOW_EXTERNAL

      static final int SUBEXEC_ALLOW_EXTERNAL
      Sub-routine execution policy: this flag allows external routines.
      See Also:
    • SUBEXEC_ALLOW_ALL

      static final int SUBEXEC_ALLOW_ALL
      Sub-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 of SUBEXEC_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 of IDInstruction#evaluate().
    • isEmulatorEnabled

      boolean isEmulatorEnabled()
      Determine whether the emulator is enabled. The emulator must be enabled to permit the execution of IDInstruction#evaluate().
    • registerEmulatorHooks

      int registerEmulatorHooks(IDEmulatorHooks hooks)
      Register emulator hooks. Refer to IDEmulatorHooks 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 by registerEmulatorHooks
      Returns:
      success indicator
    • registerExecutionHelper

      void registerExecutionHelper(IDMethodExecutionHelper helper)
      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.

      Parameters:
      helper -
    • unregisterExecutionHelper

      boolean unregisterExecutionHelper(String methodSignature)
      Remove a method execution helper.
      Parameters:
      methodSignature -
      Returns:
    • getExecutionHelpers

      Collection<IDMethodExecutionHelper> getExecutionHelpers()
      Retrieve the collection of all registered method execution helpers.
      Returns:
    • setExternalPolicy

      DEmuExternalPolicy setExternalPolicy(DEmuExternalPolicy policy)
      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 a DexDecEvaluationException.
      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

      void addClassfilesToSandbox(File f) throws IOException
      Convenience method to add class files (single class or Jar) to the sandbox classloader.
      Parameters:
      f -
      Throws:
      IOException
    • registerSandboxHooks

      int registerSandboxHooks(IDSandboxHooks hooks)
      Register sandbox hooks. Refer to IDSandboxHooks 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 by registerSandboxUserHooks
      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

      int registerNativeEmulatorHooks(IEEmulatorHooks hooks)
      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

      int registerNativeEmulatorMemoryHooks(IEStateHooks hooks)
      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

      IDImm getStaticField(String fsig) throws DexDecEvaluationException
      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

      void setStaticField(String fsig, IDImm val) throws DexDecEvaluationException
      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

      IDImm getInstanceField(String fsig, IDImm instance) throws DexDecEvaluationException
      Retrieve the value of an instance field.
      Parameters:
      fsig -
      instance -
      Returns:
      Throws:
      DexDecEvaluationException
    • setInstanceField

      void setInstanceField(String fsig, IDImm instance, IDImm val) throws DexDecEvaluationException
      Update the value of an instance field.
      Parameters:
      fsig -
      instance -
      val -
      Throws:
      DexDecEvaluationException
    • loadClass

      Class<?> loadClass(String csig) throws DexDecEvaluationException
      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

      Class<?> loadClass(String csig, boolean initialize) throws DexDecEvaluationException
      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

      String getStringObject(IDImm strOrRef) throws DexDecEvaluationException
      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

      IDImm cloneArray(IDImm arrayRef) throws DexDecEvaluationException
      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

      Object getArrayObject(IDImm ref) throws DexDecEvaluationException
      Retrieve an array by reference.
      Parameters:
      ref -
      Returns:
      Throws:
      DexDecEvaluationException
    • getArrayObjectLength

      int getArrayObjectLength(IDImm ref) throws DexDecEvaluationException
      Get the length of an array.
      Parameters:
      ref -
      Returns:
      Throws:
      DexDecEvaluationException
    • getArrayElement

      IDImm getArrayElement(IDImm arrayRef, int index) throws DexDecEvaluationException
      Read an array element.
      Parameters:
      arrayRef -
      index -
      Returns:
      Throws:
      DexDecEvaluationException
    • setArrayElement

      void setArrayElement(IDImm arrayRef, int index, IDImm val) throws DexDecEvaluationException
      Write an array element.
      Parameters:
      arrayRef -
      index -
      val -
      Throws:
      DexDecEvaluationException
    • getClassReference

      IDImm getClassReference(String classname) throws DexDecEvaluationException
      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

      boolean isInstanceOf(IDImm obj, IDImm clz) throws DexDecEvaluationException
      Determine whether an object is assignment-compatible with a class type.
      Parameters:
      obj -
      clz -
      Returns:
      Throws:
      DexDecEvaluationException
    • registerObject

      IDImm registerObject(Object o)
      Register an object.
      Parameters:
      o -
      Returns:
    • getObject

      Object getObject(IDImm ref) throws DexDecEvaluationException
      Retrieve an object value by its reference.
      Parameters:
      ref - a wrapped reference or a string immediate
      Returns:
      an object
      Throws:
      DexDecEvaluationException
    • getObject

      Object getObject(IDImm ref, boolean provideNativeObject) throws DexDecEvaluationException
      Retrieve an object value by its reference.
      Parameters:
      ref - a wrapped reference or a string immediate
      provideNativeObject -
      Returns:
      an object, or null (which does not indicate an error, but the null reference)
      Throws:
      DexDecEvaluationException
    • releaseObject

      Object releaseObject(IDImm ref) throws DexDecEvaluationException
      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

      Object getObject(int objid) throws DexDecEvaluationException
      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

      int getObjectClassId(int objid) throws DexDecEvaluationException
      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

      IDEmuClass getObjectClass(int objid) throws DexDecEvaluationException
      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

      IDEmuContext pushContext(String name)
      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

      IDEmuFrame pushFrame(String methodSignature)
      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

      void setVariable(int varid, IDImm value) throws DexDecEvaluationException
      Convenience method to write the value of a variable in the current frame (top frame of the top context).
      Parameters:
      varid - variable id
      value - the value to be written
      Throws:
      DexDecEvaluationException
    • getVariable

      IDImm getVariable(int varid, boolean softFail) throws DexDecEvaluationException
      Convenience method to read the value of a variable in the current frame (top frame of the top context).
      Parameters:
      varid - variable id
      softFail -
      Returns:
      the value (non-null)
      Throws:
      DexDecEvaluationException
    • getVariable

      IDImm getVariable(int varid) throws DexDecEvaluationException
      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

      boolean hasVariable(int varid) throws DexDecEvaluationException
      Determine whether a variable is set (has a value).
      Parameters:
      varid - variable id
      Returns:
      Throws:
      DexDecEvaluationException
    • deleteVariable

      boolean deleteVariable(int varid) throws DexDecEvaluationException
      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 to Class.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

      IDImm createNewInstance(String classSignature) throws DexDecEvaluationException
      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 be NEW)
      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 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)
      Returns:
      the returned value (null for void methods)
      Throws:
      DexDecEvaluationException
    • executeDexMethod

      IDImm executeDexMethod(IDexMethod m, List<IDExpression> args) throws 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).

      Parameters:
      m - a dex internal method
      args - 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 because pcExpectedTermination 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

      List<INativeLibrary> getNativeLibraries() throws DexDecEvaluationException
      Get the list of native libraries loaded in the native emulator.
      Returns:
      a list of library objects, possibly empty
      Throws:
      DexDecEvaluationException
    • loadNativeLibrary

      INativeLibrary loadNativeLibrary(IELFUnit lib) throws 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.

      Parameters:
      lib - ELF Shared Objec unit located in the project
      Returns:
      a library description object
      Throws:
      DexDecEvaluationException
    • loadNativeLibrary

      INativeLibrary loadNativeLibrary(String libname) throws 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.

      Parameters:
      libname - a library name, as provided to a call to System.loadLibrary(String)
      Returns:
      a library description object
      Throws:
      DexDecEvaluationException
    • loadNativeLibrary

      INativeLibrary loadNativeLibrary(String libname, boolean isPath) throws 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.

      Parameters:
      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)
      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

      Map<String,Long> 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

      void setData(String key, Object value)
      Set (attach) a piece data to this emulator object.
      Parameters:
      key - non-null key
      value - non-null value
    • getData

      Object getData(String key)
      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: