Skip to content

parameter-declaration.md

Latest commit

 

History

History
99 lines (73 loc) · 4.34 KB

parameter-declaration.md

File metadata and controls

99 lines (73 loc) · 4.34 KB
Raw

Parameter Declaration

params lists the parameters of a method or function, in order. In Java hooks, their types select the overload. In native hooks, they tell frooky how to read the arguments, since a native function has no type information at runtime.

Forms

Form Example
Type int
Type + name [int, len]
Type + settings ["[B", { maxItems: 32 }]
Type + name + settings ["void *", buf, { direction: out, length: len }]
Object { type: "void *", name: buf, direction: out, maxItems: 32 }

The object form has the same settings as the tuple forms, next to type and name.

The name is optional, but name your parameters: events show it next to the value, and length and offset refer to other parameters by it. A name is an identifier (letters, digits, _ and $, not starting with a digit), e.g. buf or out_len; $ret is the return value and can't be a name. A name that length or offset refer to must be unique within the hook.

A type must be written as the hook's platform writes types: frooky skips a hook with a C type in a Java hook or the other way round, and suggests the descriptor for a Java type written the Java way, e.g. [B for byte[].

YAML needs quotes around a type that starts with [ ("[B") or contains [] ("char *const []"). Quote pointer types as well ("char *"), as the examples do: a type that starts with * would otherwise be read as a YAML alias.

Java Parameters

Java types are written as type descriptors:

javaClass: android.webkit.WebView
hooks:
  - method: $init
    overloads:
      - params:
          - [android.content.Context, context]
      - params:
          - [android.content.Context, context]
          - [android.util.AttributeSet, attrs]
          - [int, defStyleAttr]
          - [boolean, privateBrowsing]

This hooks these two constructors:

WebView(context: Context)
WebView(context: Context, attrs: AttributeSet?, defStyleAttr: Int, privateBrowsing: Boolean)

frooky decodes a Java argument by its runtime class, not by the declared type, see How frooky Picks a Java Decoder. Without overloads, every overload is hooked and its parameters are taken from reflection, without names.

Native Parameters

Native types are written as in C. Parameters without a name can be mixed with named ones:

module: libsqlite.so
hooks:
  - symbol: sqlite3_exec
    returns: int
    params:
      - "sqlite3 *"
      - ["const char *", sql]
      - ["void *", callback]
      - "void *"
      - ["char **", errmsg]

This hooks sqlite3_exec:

int sqlite3_exec(
  sqlite3*,                                  /* An open database */
  const char *sql,                           /* SQL to be evaluated */
  int (*callback)(void*,int,char**,char**),  /* Callback function */
  void *,                                    /* 1st argument to callback */
  char **errmsg                              /* Error msg written here */
);

Declare the parameters up to the last one you want to decode; the ones after it can be left out. How each type is decoded is described in Decoders for Native Hooks.

Decoder Settings

The settings of a parameter override the decoder settings of its hook, collection and file. Only a parameter can have direction, length, offset and argFilter:

params:
  - [<type>, <name>, { direction: out, length: $ret, maxItems: 256 }]

See Decoder Settings for every setting.