diff --git a/frida/device.go b/frida/device.go index 80f1dd6..0a88294 100644 --- a/frida/device.go +++ b/frida/device.go @@ -113,6 +113,9 @@ func (d *Device) IsLost() bool { return false } +// ParamsCtx runs Params but with context. +// This function will properly handle cancelling the frida operation. +// It is advised to use this rather than handling Cancellable yourself. func (d *Device) ParamsCtx(ctx context.Context) (map[string]any, error) { paramC := make(chan map[string]any, 1) errC := make(chan error, 1) @@ -143,6 +146,21 @@ func (d *Device) ParamsCtx(ctx context.Context) (map[string]any, error) { } // Params returns system parameters of the device +// You can add an option with the variadic opts argument. +// +// Example: +// +// params, err := device.Params() +// +// +// // or WithCancel +// +// cancel := frida.NewCancellable() +// params, err := device.Params(frida.WithCancel(c)) +// +// // ... +// +// cancel.Cancel() func (d *Device) Params(opts ...OptFunc) (map[string]any, error) { o := setupOptions(opts) return d.params(o) @@ -186,12 +204,26 @@ func (d *Device) FrontmostApplication(scope Scope) (*Application, error) { return nil, errors.New("could not obtain frontmost app for nil device") } +// EnumerateApplications will return slice of applications on the device +// You can add an option with the variadic opts argument +// +// Example: +// +// apps, err := device.EnumerateApplications("", frida.ScopeFull) +// +// // or providing the option to cancel +// +// cancel := frida.NewCancellable() +// apps, err := device.EnumerateApplications("", frida.ScopeFull, frida.WithCancel(c)) +// +// // ... +// +// cancel.Cancel() func (d *Device) EnumerateApplications(identifier string, scope Scope, opts ...OptFunc) ([]*Application, error) { o := setupOptions(opts) return d.enumerateApplications(identifier, scope, o) } -// EnumerateApplications will return slice of applications on the device func (d *Device) enumerateApplications(identifier string, scope Scope, opts options) ([]*Application, error) { if d.device == nil { return nil, errors.New("could not enumerate applications for nil device") diff --git a/frida/misc.go b/frida/misc.go index f735cdb..a00b71c 100644 --- a/frida/misc.go +++ b/frida/misc.go @@ -13,16 +13,23 @@ type Cancellable struct { cancellable *C.GCancellable } +// NewCancellable wraps GCancellable +// used to provide ability to cancel frida funcs. +// Reminder that the caller must either `Cancellable.Cancel()` or +// `Cancellable.Unref()` to unref the underlying C data. func NewCancellable() *Cancellable { return &Cancellable{ cancellable: C.g_cancellable_new(), } } +// Cancel sends the cancel signal to GCancellable +// as well unrefs func (c *Cancellable) Cancel() { C.g_cancellable_cancel(c.cancellable) } +// Unref unrefs the wrapped GCancellable func (c *Cancellable) Unref() { C.g_object_unref((C.gpointer)(c.cancellable)) } @@ -41,6 +48,12 @@ func setupOptions(opts []OptFunc) options { type OptFunc func(o *options) +// WithCancel is inteded to be used a varadic option. +// Provides the ability to to pass GCancellable to +// frida functions. +// +// Note: it is advisable to use the `FuncCtx` +// version of functions rather than handling this yourself. func WithCancel(cancel *Cancellable) OptFunc { return func(o *options) { o.cancellable = cancel.cancellable