EKA2L1

• Index

Contents

• Functions
• Fields

Modules

• common
• cpu
• events
• ipc.context
• kernel
• mem
• std

Topics

• Note about scripting
• Debugging with IDA

Module events

Events module provides abilities to register callbacks at certain events in the emulator.

The current supported callback types are: breakpoint and IPC (Inter-process communication) callback. For breakpoint callback, it's always preferred to not spend too much time in the callback, which may impact emulated app performance.

Each script is allowed to have a limit of 2^32 callbacks, but the true number depends on the memory of your system and how much the Lua runner can hold. All callbacks are discarded on script unload.

Functions

registerLibraryHook (libName, ord, processUid, func)	Register a callback on library function being called.
registerBreakpointHook (libName, addr, processUid, func)	Register a callback on a breakpoint.
registerIpcHook (serverName, opcode, when, func)	Register a callback on IPC request send/complete.
clearHook (handle)	Unregistering a callback.

Fields

EVENT_IPC_SEND	Passed to registerIpcHook, indicating that IPC callback will be invoked when the client process first sends message to the server process.
EVENT_IPC_COMPLETE	Passed to registerIpcHook, indicating that IPC callback will be invoked after the server process finished processing the request and tell the emulator to notify back to the waiting client.
INVALID_HOOK_HANDLE	Constant indicating an invalid handle returned from callback registering.

Functions

registerLibraryHook (libName, ord, processUid, func)

Register a callback on library function being called.

This is registerBreakpointHook in disguise, but with automated address detection. This is preferred for the callback to work across many emulated devices, because address of the library function may change, but the ordinal is consistent.

Parameters:

• libName Name of the library that contains the target library function.
• ord The ordinal of the function inside the library.
• processUid UID3 of the process you want this callback to be triggered on. Use 0 for any active process.
• func Callback function with no parameter and no return.

Returns:

A handle to this callback (> 0), which can later be used for unregistering. INVALID_HOOK_HANDLE on failure.

See also:

• clearHook
• registerBreakpointHook

registerBreakpointHook (libName, addr, processUid, func)

Register a callback on a breakpoint.

The address passed to this function should be relative to the original code base address found in disassemble/image explorer program. The emulator will rebase the address relatively to where the library is loaded in memory.

In case the breakpoint address is constant and should not be related to any libraries or executables, pass the string "constantaddr" to the libName variable.

Parameters:

• libName Name of the library that contains the target breakpoint. Use "constantaddr" for no library.
• addr The address of the breakpoint, relative to the library's original code base address if libName is not "constantaddr"
• processUid UID3 of the process you want this callback to be triggered on. Use 0 for any active process.
• func Callback function with no parameter and no return.

Returns:

A handle to this callback (> 0), which can later be used for unregistering. INVALID_HOOK_HANDLE on failure.

See also:

• clearHook
• registerLibraryHook

registerIpcHook (serverName, opcode, when, func)

Register a callback on IPC request send/complete.

For IPC send callback, you have the ability to read data the client sent before the request is delivered to the server process.

For IPC complete callback, you will receive the message context before the request is signaled to be completed to the client process.

Both the callback will receive an ipc.context object as its parameter.

Parameters:

• serverName Name of the server to intercept IPC messages.
• opcode The target message opcode to intercept.
• when The moment to receive the callback. Two options are EVENT_IPC_SEND and EVENT_IPC_COMPLETE
• func The callback function, with ipc.context object as its only parameter.

Returns:

A handle to this callback (> 0), which can later be used for unregistering. INVALID_HOOK_HANDLE on failure.

See also:

clearHook

clearHook (handle)

Unregistering a callback.

This method is safe to call inside a callback. The callback will still continue to do the rest of its job after the delete.

Note that failure is silent, and may only be reported on the log channel.

Parameters:

• handle The handle retrieved from registering.

Fields

EVENT_IPC_SEND

Passed to registerIpcHook, indicating that IPC callback will be invoked when the client process first sends message to the server process.

EVENT_IPC_COMPLETE

Passed to registerIpcHook, indicating that IPC callback will be invoked after the server process finished processing the request and tell the emulator to notify back to the waiting client.

INVALID_HOOK_HANDLE

Constant indicating an invalid handle returned from callback registering.