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

An interface for user\-defined hooks called by `dexdec`'s IR sandbox when executing external \(not in DEX\) code. 

 Tutorial on how to use sandbox hooks: in the JEB `coreplugins/scripts/` folder, refer to `DOptEmuSandboxHooksExample.py.DISABLED` for an example \(removed the .DISABLED extension to enable the plugin\).

## Method: examineCreatedInstance
- parameter: `reqid`, type: `long`
- parameter: `obj`, type: `java.lang.Object`

Description: This method is called after an object instance was constructed.
parameter: reqid: internal request id, matching a previous call to            [newInstance](#newInstance(long, String, String, List))
parameter: obj: the constructed instance, giving a hook an opportunity to modify it

## Method: examineFieldValue
- parameter: `reqid`, type: `long`
- parameter: `value`, type: `java.lang.Object`
- return type: `com.pnfsoftware.jeb.util.base.Wrapper<java.lang.Object>`

Description: This method is called after the sandbox has read a field value. It provides the field value and offers a chance for the hook to modify or replace it.
parameter: reqid: internal request id, matching a previous call to            [getField](#getField(long, String, String, Object))
parameter: value: the field value that was read
return: the hook may provide an object \(wrapped in a Wrapper object; the object itself may be         null\); returning null means proceed as normal \(other hooks will be tried, and         eventually, the sandbox will resume and provide the value previously retrieved\)

## Method: examineMethodResult
- parameter: `reqid`, type: `long`
- parameter: `result`, type: `java.lang.Object`
- return type: `com.pnfsoftware.jeb.util.base.Wrapper<java.lang.Object>`

Description: This method is called after the sandbox has invoked a non\-constructor method. It provides the return value and offers a chance for the hook to modify or replace it.
parameter: reqid: internal request id, matching a previous call to            [invokeMethod](#invokeMethod(long, String, String, Object, List))
parameter: result: the method's return value
return: the hook may provide an object \(wrapped in a Wrapper object; the object itself may be         null\); returning null means proceed as normal \(other hooks will be tried, and         eventually, the sandbox execution will resume and provide the original returned         value\)

## Method: getField
- parameter: `reqid`, type: `long`
- parameter: `addr`, type: `java.lang.String`
- parameter: `fsig`, type: `java.lang.String`
- parameter: `obj`, type: `java.lang.Object`
- return type: `com.pnfsoftware.jeb.util.base.Wrapper<java.lang.Object>`

Description: This method is called when the sandbox is about to get a field's value.
parameter: reqid: internal request id \(if this method returned null, the same value will be            provided to the subsequent call to [examineFieldValue](#examineFieldValue(long, Object))\)
parameter: addr: caller location
parameter: fsig: field signature
parameter: obj: field object \(not the value\!\)
return: the hook may provide an object \(wrapped in a Wrapper object; the object itself may be         null\); returning null means proceed as normal \(other hooks will be tried, and         eventually, the sandbox may attempt to read the field itself\)
throws: to report an exception generated by the emulated             code

## Method: invokeMethod
- parameter: `reqid`, type: `long`
- parameter: `addr`, type: `java.lang.String`
- parameter: `msig`, type: `java.lang.String`
- parameter: `obj`, type: `java.lang.Object`
- parameter: `args`, type: `java.util.List<java.lang.Object>`
- return type: `com.pnfsoftware.jeb.util.base.Wrapper<java.lang.Object>`

Description: This method is called when the sandbox is about to execute a non\-constructor method.
parameter: reqid: internal request id \(if this method returned null, the same value will be            provided to the subsequent call to [examineMethodResult](#examineMethodResult(long, Object))\)
parameter: addr: caller location
parameter: msig: method signature
parameter: obj: the target object \(null for a static method\)
parameter: args: method invocation arguments; the arguments may be modified, and modifications            will be visible to subsequent handlers
return: the hook may provide a result, in which case other hooks will not be tried; if null         is returned, other hooks will be tried and eventually, the sandbox will proceed and         attempt invocation itself
throws: to report an exception generated by the emulated             code

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

Description: This method is called when an external class is to be loaded by the sandbox. A hook implementation may attempt to load the class first. If a class is loaded, this method should return it. No other hooks nor the sandbox will then attempt to load the class. 

 Important: this method is called within the context of a sandbox thread. For safety reasons, execution of the code will be restricted. In particular, most classes outside the standard JDK \(java.\* packages\) will refused to be loaded.
parameter: name: binary name of the class
return: a loaded class or null, indicating other hooks or the sandbox should proceed
throws: to report an exception generated by the emulated             code

## Method: newInstance
- parameter: `reqid`, type: `long`
- parameter: `addr`, type: `java.lang.String`
- parameter: `msig`, type: `java.lang.String`
- parameter: `args`, type: `java.util.List<java.lang.Object>`
- return type: `com.pnfsoftware.jeb.util.base.Wrapper<java.lang.Object>`

Description: This method is called when an instance is about to be constructed.
parameter: reqid: internal request id \(the same value will be provided to the subsequent call to            [examineCreatedInstance](#examineCreatedInstance(long, Object))\)
parameter: addr: caller location
parameter: msig: constructor signature
parameter: args: constructor arguments, giving a chance for this hook to modify the arguments            before the constructor is called \(the modifications will also be seen by other            handlers if this method returns null\)
return: the hook may provide a result, in which case other hooks will not be tried; if null         is returned, other hooks will be tried and eventually, the sandbox will proceed and         attempt creation itself
throws: to report an exception generated by the emulated             code

## Method: setField
- parameter: `reqid`, type: `long`
- parameter: `addr`, type: `java.lang.String`
- parameter: `fsig`, type: `java.lang.String`
- parameter: `obj`, type: `java.lang.Object`
- parameter: `avalue`, type: `java.lang.Object[]`
- return type: `java.lang.Boolean`

Description: This method is called when the sandbox is about to set a field's value.
parameter: reqid: internal request id
parameter: addr: caller location
parameter: fsig: field signature
parameter: obj: field object
parameter: avalue: a one\-element array containing the value to be set \(this is an input/output            array; if this method returns false, the value located in the array will be used            by the sandbox to set the field\)
return: null to indicate that nothing was done and execution should proceed as normal; false         to indicate that the hook provided a field value to be set by the sandbox itself \(no         other hook will run, the sandbox will set the field located in the \`avalue\` array\);         true to indicate that the hook has completed the operation \(no other hook will run,         the sandbox will not set the the field\)
throws: to report an exception generated by the emulated             code