Structures¶

This part describe the structures (BipStruct) and structure members (BStructMember). This two objects inherit from BipRefElt which make them able to be referenced by xref and possible to recuperate using the GetElt() function.

Those classes represent the element view in the Struct tab. of IDA and are different from the BipType which is used for referencing the type of some elements in IDA, however they are obviously linked.

Except xrefs the most common way to get a structure is using the get() class method which expect its name. For creating one the create() class method is available. Once a struct has been recuperated it is possible to access the members as a dict by using their name or their offset (this is not a list and so it is the offset of the member which is expected not its index).

BipStruct API¶

class bip.base.BipStruct(st)¶

Class for representing and manipulating a structure in IDA. Static functions create() and get() allow to easilly get an instance of those object.

Todo

get/set alignement

Todo

support deletion of members

Todo

allow to iterate on all structure and other stuff like that

Todo

test

__init__(st)¶

Constructor for a BipStruct object. There is few reason to directly use this constructor, see functions get() or create().

Parameters:	st – A structure `struc_t` from IDA such as return by `get_struc` or an sid (int) representing a structure.
Raises:	ValueError – If an integer is provided and is not a valid sid, or if an incorrect type is provided as `st`.

__init__(st)

Constructor for a BipStruct object. There is few reason to directly use this constructor, see functions get() or create().

Parameters:	st – A structure `struc_t` from IDA such as return by `get_struc` or an sid (int) representing a structure.
Raises:	ValueError – If an integer is provided and is not a valid sid, or if an incorrect type is provided as `st`.

_struct = None¶: Internal struct_t object from IDA.

_sid¶

Property which return the sid for this BipStruct object. The sid is the struct id number (tid_t) from IDA and there is no reason it should be used except for interfacing with the standard API from IDA.

Returns:	An int corresponding to the sid.

classmethod _is_this_elt(idelt)¶: Return true if idelt correspond to a sid.

name¶: Property which return the name (as a string) of this structure.

size¶: Property returning the size of the structure as an integer.

__str__() <==> str(x)¶

comment¶: Property which return the comment associated with a structure. For repeatable comment see rcomment()

rcomment¶: Property which return the repeatable comment associated with this BipStruct object.

is_hidden¶

Property for knowing if a struct is fully shown in the gui.

Returns:	True if the structure is “collapsed”, False if it is shown.

nb_members¶: Property which return the number of members in this BipStruct object.

members¶

Property which return a list of BStructMember objects representing the members of this structure.

Return type:	A list of `BStructMember` object.

members_iter¶

Property returning an iterable of BStructMember representing the different members of this struct. This is similar to BipStruct.members().

Todo

maybe delete this ? I am worried because of the get_member property which may create problem if the number of members change during the iteration.

Return type:	Iterable of `BStructMember` object.

member_at(off)¶

Method which return the member of this BipStruct at the offset provided in argument. This will return the correct member even if the offset is not aligned.

Parameters:	off (int) – The offset of the member to get.
Raises:	IndexError – If the member was not found (offset bigger than the struct).
Returns:	An `BStructMember` object corresponding to the member.

member_by_name(name)¶

Method which return the member of this BipStruct from its name.

Parameters:	name (str) – The name of the member to get.
Raises:	KeyError – If the member was not found.
Returns:	An `BStructMember` object corresponding to the member.

__getitem__(key)¶

Getitem method which allow access to the members of the struct.

Parameters:	key – If key is a string it will search the member by name, if it is a integer it will search the member by offset.
Raises:	ValueError – If the member was not found. TypeError – If `key` is not an integer or a string.
Returns:	An `BStructMember` object corresponding to the member.

__iter__()¶

Iter method for accessing the members as a list. This is equivalent to members_iter().

Note

By default python will try to use the __getitem__ method which is not what we want because the __getitem__ method takes offset.

Returns:	An iterator on the `BStructMember` object of this struct.

add(name, size, comment=None, offset=None)¶

Add a new member to the structure (at the end by default).

Parameters:	name (str) – The name of the field to add. If None or an empty string the default name used by IDA will be used (`field_`). size (int) – The size of the field to add in bytes, can be 1, 2, 4 or 8. comment (str) – Optional parameter which allow to add a comment associated with the new member. offset (int) – The offset at which to add the new member, by default (None) it will be added at the end.
Raises:	TypeError – If one argument is not of the correct type or with the correct value. ValueError – If an error occur when adding the member.
Returns:	An `BStructMember` object corresponding to the member added.

add_varsize(name, comment=None)¶

Add a variable size new member at the end of the structure.

Parameters:	name (str) – The name of the field to add. comment (str) – Optional parameter which allow to add a comment associated with the new member.
Raises:	ValueError – If an error occur when adding the member.
Returns:	An `BStructMember` object corresponding to the member added.

fill(size, prefix='field_')¶

Add new members to the structure until it reach size . Thie function add field the size of a pointer at the end of the structure.

Parameters:	size (int) – The size in bytes wanted for the structure. prefix (str) – Prefix for the name of the structure member. Default is `field_` .

classmethod get(name)¶

Class method allowing to get a BipStruct object from the name of an existing structure.

Todo

support providing a sid directly instead of a name ?

Todo

support typedef on struct

Parameters:	name (str) – The name of the structure to get.
Raises:	ValueError – if the structure `name` does not exist.
Returns:	A `BipStruct` object corresponding to the structure identified by the name provided.

classmethod create(name)¶

Class method allowing to create a new empty struct.

Parameters:	name (str) – The name of the structure to create.
Raises:	ValueError – If the structure `name` already exist. BipError – If it was not possible to create the structure.
Return type:	A `Struct` object.

static delete(name)¶

Static method allowing to delete a struct by its name.

Parameters:	name (str) – The name of the structure to delete.
Raises:	ValueError – If the structure `name` does not exist. RuntimeError – If it was not possible to delete the strucutre.

BStructMember API¶

class bip.base.BStructMember(member, istruct=None)¶

Class for representing and manipulating a member of an BipStruct structure.

Todo

flags

Todo

implement comparaison with other members (mid) and test for presence in a struct.

__init__(member, istruct=None)¶

Constructor for a BStructMember object. There is no reason this constructor should be used.

There is few reason to use directly this constructor except for interfacing directly with IDA.

Parameters:	member – A `member_t` object from ida corresponding to this member or a member id (int, long) corresponding to this member. istruct – A `BipStruct` object corresponding to the structure from which member this member is part of. If it is `None` the structure will found dynamically.
Raises:	ValueError – If the parameter is incorrect.

__init__(member, istruct=None)

Constructor for a BStructMember object. There is no reason this constructor should be used.

There is few reason to use directly this constructor except for interfacing directly with IDA.

Parameters:	member – A `member_t` object from ida corresponding to this member or a member id (int, long) corresponding to this member. istruct – A `BipStruct` object corresponding to the structure from which member this member is part of. If it is `None` the structure will found dynamically.
Raises:	ValueError – If the parameter is incorrect.

_member = None¶: member_t object from ida corresponding to this member.

struct = None¶: BipStruct parent of this member.

classmethod _is_this_elt(idelt)¶: Return true if idelt correspond to a mid.

_mid¶: Property which return the member id corresponding to this object. This is used internally by IDA and there should be few reason to use this except for interfacing with IDA native interface.

name¶: Property which return the name of this member.

fullname¶: Property which return the full name of this member. The fullname correspond to the struct name follow by the name of this member seperated by a point: STRUCT.MEMBER .

size¶: Property which return the size of this member as an integer.

offset¶: Property providing access to the start offset of this member in the structure as an integer.

end_offset¶: Property which return the end offset of this member as an integer. This should be equivalent to use offset + size .

__str__() <==> str(x)¶

comment¶: Return the comment associated with this member as a string.

rcomment¶: Return the repeatable comment associated with this member as a string.

has_type¶: Property which return True if this member as a type defined (which can be recuperated through BStructMember.type()) False if no type is defined for this member.

del_type()¶: Method which allow to delete the type for this member.

Todo

handle failure

set_type(new_type, userspecified=True, may_destroy=False, compatible=False, funcarg=False, bytil=False)¶

Method which allow to change the type of this member.

Parameters:

new_type – An object which inherit from BipType which represent the new type for this member.
userspecified (bool) – Is this type specified by the user, True by default.
may_destroy (bool) – Is the setting of this type can destroy other members of the struct, default is False.
compatible (bool) – The new type should be compatible with the previous one. Default is False.
funcarg (bool) – Is the member used as argument of a function, in particular this forbid the setting of array. Default is False.
bytil (bool) – The new type was created by the type subsystem. Default False.

Raises:

RuntimeError – If setting the type failed.
TypeError – If the argument is not an BipType object.

type¶

Property which return an object which inherit from BipType and represent the type of this member.

Raises:	RuntimeError – If it was not possible to get the type of this member, this may happen in particular if `has_type()` returned false.

is_nested¶: Return True if this member represent a nested struct included inside the current one. The structure can be recuperated using nested_struct() .

nested_struct¶

If this member represent a nested structure this property allows to get the BipStruct corresponding to the nested struct.

Raises:	RuntimeError – If this member does not have a nested struct. This can be tested using `is_nested()`.
Returns:	An `BipStruct` object corresponding to the nested struct.

static _is_member_id(mid)¶

Allow to check if an id (address) from IDA represent a member id. This is a wrapper on ida_struct.is_member_id and there should not be any reason to use this method except for interfacing with the IDAPython interface.

Parameters:	mid (int) – The id to check for being a member id.
Returns:	`True` if `mid` is a member id which can be used for getting a `BStructMember` object, `False` otherwise.

classmethod _from_member_id(mid)¶

Class method for getting a BStructMember object from an id which represent a member in IDA. There should be no reason to use this method except for interfacing with the IDAPython interface.

Parameters:	mid (int) – The member id to convert to a `BStructMember`.
Raises:	ValueError – If the argument `mid` is not a valid member id. This can be check using the static method `_is_member_id()` .
Returns:	A `BStructMember` object corresponding to the member with id `mid`.

Structures¶

BipStruct API¶

BStructMember API¶

Table of Contents

Previous topic

Next topic

This Page