Activities and Actions

For allowing to define interaction between the user-interface and the plugins Bip define BipActivity . The intended way to use BipActivity and BipAction is using the Activity decorators with a BipPlugin.

The BipActivity is an abstract class allowing to define interaction with the IDA API and UI, in practice there is few reason to use them directly.

The BipActivityContainer is a BipActivity containing several other BipActivity, it is used internally for allowing to have several decorators (and so BipActivity) on the same method of a BipPlugin.

The BipAction (which inherit from BipActivity) allows to define hotkeys (shortcut() decorator) or entries in the IDA menu (menu() decorator). It can be created directly as an object for defining actions dynamically and not link to a particular plugin.

Implementation internals

This part as the goal to describe the internal of the BipActivity: how they interface with BipPlugin and how to create a new kind of BipActivity . It is not necessary to read it for simply using them.

Creating a new BipActivity

All BipActivity subclasses should implement the methods:

• register(): register the interface with IDA. This will be called when a plugin is loaded.
• unregister(): register the interface with IDA. This is the oposite of register(), it will be called when a plugin is unloaded.
• handler(): the handler function of the activity which actually does the action. It is not necessary to implement this function if the handler parameter for the constructor is defined. This method will also be called if the object is called.

Those are the only mandatory methods to implement.

Activities have for main goal to be used as decorator when writing a plugin and as such are callable object. Calling this object will triger a call to the handler() method.

Activity and decorator

Some decorators are define for being use inside a BipPlugin class for defining interactions with IDA. Those decorators will dynamically create BipActivity objects.

When a BipPlugin class is created, its constructor will create a list of the BipActivity associtated with the plugin (stored in _activities) and when the plugin object is created it will set itself in the BipActivity.plugin of each BipActivity it contains.

For allowing several BipActivity decorators to be used on the same method the BipActivityContainer class is defined. The decorator will still need to be able to define the handler function for the new BipActivity decorators after the first one, this is done by storing the function in the BipActivityContainer which is accessible through the get_original_method() method.

All decorators should return a BipActivityContainer which will contain the BipActivity to define. If the container was already defined it should simply add the new one using the add_activity() method.

BipAction API

class bip.gui.BipAction(name, handler=None, label=None, shortcut=None, path_menu=None, tooltip=None, icon=None)

Bip object for representing an action in IDA. Action can have shortcuts, tollbar action, icon, name and must have an handler. This is the equivalent of the idaapi.action_handler_t for Bip.

The main use of this class can be made through decorator which should allow to simplify the life of the developer. See Activity decorators.

Todo

handle ctx and access to it

Todo

Make properties for every attribute

Todo

handle activate and update

Todo

Handle tooltip & icon

__init__(name, handler=None, label=None, shortcut=None, path_menu=None, tooltip=None, icon=None)

Constructor for a BipAction object.

Warning

tooltip & icon are ignored for now.

Todo

Handle tooltip & icon, remove previous warning

Parameters:

• name – Unique internal name for this action.
• handler – Handler function for this action. If it is None the handler() method will be used instead.
• label – Label for the action. If None is provided (default) the name of the action will be used.
• shortcut (str) – Optional shortcut for triggering the action. This should be a string representing the shortcut (ex: Ctrl-H).
• path_menu (str) – Optional path in the menu at which register the action. This should be a string representing the path (ex: Edit/Plugins/)
• tooltip – Optional tooltip for the action.
• icon – Option icon for the action.

_ida_action_handler = None

Internal idaapi.action_handler_t object

is_register = None

Boolean attribute which indicate if the action is registerd

_activate(action_handler, ctx)

Intenal function which is used for the idaapi.action_handler_t.activate function.

This only call the handler() method.

Todo

This should be rewritten for allowing more advance control

_update(action_handler, ctx)

Intenal function which is used for the idaapi.action_handler_t.update function.

This is always AST_ENABLE_ALWAYS.

Todo

This should be rewritten for allowing more advance control

_create_action_handler()

Internal function which will create the idaapi.action_handler_t object.

Will set it in BipAction._ida_action_handler attribute and return it.

Todo

Should check if already created ?

handler(*args, **kwargs)

Call the handler pass as argument of the constructor if defined or raise a RuntimeError if it is not defined. The arguments are passed to the internal handler, as is the return value.

This is the main method of the BipAction and the one which will be called one the action is triggered.

register()

Register the action in IDA and attach it to a menu if needed.

Internally this will create the action handler if needed, then the action descriptor and register it in IDA. If a path_menu argument as been define in the constructor it will also perform the attachement to the menu (using attach_to_menu().

attach_to_menu(path, flags=<sphinx.ext.autodoc.importer._MockObject object>)

Attach this BipAction as an element in the menu. The name of the action will be the one defined as the label of the constructor.

This will be called automatically when the BipAction is register() if the path is provided in argument of the constructor as path_menu. If the path_menu is not provided in the constructor this can be done by calling this function but the register() must first be called.

Attaching into the Edit/Plugins/ menu when IDA is loading may create problem as this menu seems to be remade later and the entry may be overwritten (this seems to depend of IDA version and how early this method is called).

Returns:True if the action succeded, False otherwise.

unregister()

Unregister the action in IDA, if this action was not register this function does nothing. Unregistering should also delete the entry from the menu if any.

BipActivity API

class bip.gui.BipActivity

Class allowing to make the link between the IDA API and a BipPlugin . In particular this will allow to define BipAction (including shortcut() and menu() entry) or callbacks.

All BipActivity object link to a BipPlugin have a property plugin which give them access to the plugin object.

Activities have for main goal to be used as decorator when writing a plugin and as such are callable object. Calling this object will triger a call to the handler() method.

plugin = None

BipPlugin object if this activity is link to a plugin. This will be set automatically by the constructor of the BipPlugin. If this BipActivity is not link to a BipPlugin this attribute should be None.

__call__(...) <==> x(...)

register()

Abstract method which register the activity inside the IDA interface. By default will raise a RuntimeError.

This should be implemented by child classes for interfacing with IDA.

unregister()

Abstract method which register the activity inside the IDA interface. By default will raise a RuntimeError.

This should be implemented by child classes for interfacing with IDA.

handler(*args, **kwargs)

Abstract method which represent the action to realise when the activity is triger by IDA. In most case each BipActivity object will want a different handler. By default this will raise a RuntimeError.

This should be implemented by child classes or object for interfacing with IDA.

__weakref__

list of weak references to the object (if defined)

BipActivityContainer API

class bip.gui.BipActivityContainer(original_func)

This class is a BipActivity which contains several bip activities with the same handler.

In particular this class allow to use several decorators on the same BipPlugin method for defining several BipActivity. For this to work with the decorators, the original function should be stored.

__init__(original_func)

Constructor for a BipActivityContainer object.

Parameters:handler – Handler function for this action. If it is None the handler() method will raise a RuntimeError if not redefined.

_activities = None

List of BipActivity contained in this container.

_org_func = None

Property which contain the original function

_plugin = None

BipPlugin object internal, this is needed for redefining the plugin attribute in the internal activites.

get_original_method()

Method allowing to get the original method used when creating this BipActivityContainer.

Returns:A function corresponding to the original function as originally define.

add_activity(activity)

Add an activity in this container. The activity should be a correctly setup activity including its handler.

Parameters:activity – An object which inherit from BipActivity.

__len__()

Return the number of BipActivity register in this container.

handler(*args, **kwargs)

Call the original function with the BipPlugin in first argument. This is implemented for allowing the call from a plugin object.

register()

Register all contained activities in IDA. Internally this will just call the register() method for each contained BipActivity object.

unregister()

Unregister all contained activities in IDA. Internally this will just call the unregister() method for each contained BipActivity object.

classmethod get_container(func)

Classmethod allowing to get an object of this class from a function or a container.

This class method is made for being used by decorator for them not having the problem to handle type of argument and if it is the first decorator or not.