IDA SDK

- Main Page
- Header Files
- Classes
- Modules

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Attributes | Public Member Functions | List of all members
areacb_t Class Reference

## Detailed Description

Definition of areas control block.

Each type of areas has its own control block. Access to all areas of one type is made using this control block.

## Public Attributes
void(idaapi * | read_cb )(const uchar *packed, const uchar *end, area_t *a)
| Read callback: read area from the database. More...
size_t(idaapi * | write_cb )(const area_t *a, uchar *packbuf, uchar *packend)
| Write callback: write area to the database. More...
void(idaapi * | delcache_cb )(area_t *a)
| Destroy callback: remove an area from the internal cache. More...
int(idaapi * | edit_cb )(area_t *a)
| The following three callbacks are used in open_areas_window() function. More...
int(idaapi * | kill_cb )(area_t *a)
| Callback to handle "Del" keystroke in open_areas_window() function. More...
int(idaapi * | new_cb )(void)
| Callback to handle "Ins" keystroke in open_areas_window() function This callback may be NULL. More...

## Public Member Functions
void | zero (void)
| Constructor. More...
| areacb_t (void)
| Constructor. More...
void | terminate (void)
| Destructor. More...
| ~areacb_t (void)
| Destructor. More...
uval_t | get_netnode (void) const
| Accessors.
void | save (void)
| Flush area control block to Btree.
bool | link (const char *file, const char *name, int _infosize)
| Link area control block to Btree. More...
bool | create (const char *file, const char *name, uint _infosize)
| Create area information node in Btree. More...
void | kill (void)
| Delete area information in Btree. More...
bool | create_area (const area_t *info)
| Create an area. More...
bool | update (const area_t *info)
| Update information about area in Btree. More...
area_t * | get_area (ea_t ea)
| Get pointer to area structure by address. More...
area_t * | getn_area (unsigned int n)
| Get pointer to area structure by its number. More...
int | get_area_num (ea_t ea)
| Get number of area by address. More...
ea_t | prepare_to_create (ea_t start, ea_t end)
| Prepare to create a new area. More...
int | get_next_area (ea_t ea)
| Get number of the next area. More...
int | get_prev_area (ea_t ea)
| Get number of the previous area. More...
area_t * | next_area_ptr (ea_t ea)
| Get the next area. More...
area_t * | prev_area_ptr (ea_t ea)
| Get the previous area. More...
area_t * | first_area_ptr (void)
| Get the first area. More...
area_t * | last_area_ptr (void)
| Get the last area. More...
bool | del_area (ea_t ea, bool delcmt=true)
| Delete an area. More...
bool | may_start_at (uint n, ea_t newstart)
| Check if the specified area may start at the specified address. More...
bool | may_end_at (uint n, ea_t newend)
| Check if the specified area may end at the specified address. More...
bool | set_start (uint n, ea_t newstart)
| Change start address of the area. More...
bool | set_end (uint n, ea_t newend)
| Change end address of the area. More...
void | make_hole (ea_t ea1, ea_t ea2, bool create_tail_area)
| Make a hole at the specified address by deleting or modifying existing areas. More...
bool | resize_areas (uint n, ea_t newstart)
| Resize adjacent areas simultaneously. More...
uint | get_area_qty (void) const
| Get number of areas. More...
area_t * | choose_area (int flags, int width, char *(idaapi *getl)(areacb_t *obj, uint32 n, char *buf), const char *title, int icon, int x0=-1, int y0=-1, int x1=-1, int y1=-1, const char *const *popup_menus=NULL, ea_t defea=BADADDR)
| Let the user choose an area. More...
area_t * | choose_area2 (int flags, int ncol, const int *widths, void(idaapi *getl)(areacb_t *obj, uint32 n, char *const *arrptr), const char *title, int icon, int x0=-1, int y0=-1, int x1=-1, int y1=-1, const char *const *popup_menus=NULL, ea_t defea=BADADDR)
| Let the user choose an area. More...
ea_t | find_prev_gap (ea_t ea)
| Find previous gap in areas. More...
ea_t | find_next_gap (ea_t ea)
| Find next gap in areas. More...
bool | set_area_cmt (const area_t *a, const char *cmt, bool repeatable)
| Set area comment. More...
void | del_area_cmt (const area_t *a, bool repeatable)
| Delete area comment. More...
char * | get_area_cmt (const area_t *a, bool repeatable) const
| Get area comment. More...
int | move_areas (ea_t from, ea_t to, asize_t size, int(idaapi *area_mover)(area_t *a, adiff_t delta, void *ud)=NULL, void *ud=NULL)
| Move area information to the specified addresses. More...
int | for_all_areas2 (ea_t ea1, ea_t ea2, area_visitor2_t &av)
| Call a function for all areas in the specified range. More...
bool | may_lock_area (const area_t *a)
| It is ok to lock an area? If returns 'false', lock_area() should not be called.

## Constructor & Destructor Documentation

areacb_t::areacb_t | ( | void |  | ) |
| inline

Constructor.

Initialized area control block. You need to link area control block to existing area information in Btree (link) or to create a new area information structure in Btree (create).

areacb_t::~areacb_t | ( | void |  | ) |
| inline

Destructor.

Flushes all information to Btree, deallocates caches and unlinks area control block from Btree.

## Member Function Documentation

void areacb_t::zero | ( | void |  | ) |
| inline

Constructor.

Initialized area control block. You need to link area control block to existing area information in Btree (link) or to create a new area information structure in Btree (create).

void areacb_t::terminate | ( | void |  | ) |
| inline

Destructor.

Flushes all information to Btree, deallocates caches and unlinks area control block from Btree.

bool areacb_t::link | ( | const char * | file,
|  | const char * | name,
|  | int | _infosize
| ) |  |
| inline

Link area control block to Btree.

Allocate cache, etc. Btree should contain information about the specified areas. After calling this function you may work with areas.

Parameters

  file | name of input file being disassembled. Doesn't matter if useva==0. This parameter is used to build name of the file with the virtual array.
  name | name of area information in Btree. The name should start with "$ " (yes, including a space) You may use any name you like. For example, area control block keeping information about separation of program regions to different output files might be: "$ here is info about output file areas"
  _infosize | size of a structure with actual area information (size of class based on class area_t) This function properly terminates work with the previous area control block in Btree if the current class was used to access information.

Return values

  1 | ok
  0 | failure (no such node in Btree)

bool areacb_t::create | ( | const char * | file,
|  | const char * | name,
|  | uint | _infosize
| ) |  |
| inline

Create area information node in Btree.

This function usually is used when a new file is loaded into the database. See link() for explanations of input parameters. This function properly terminates work with the previous area control block in Btree if the current class was used to access information.

Return values

  1 | ok
  0 | failure (Btree already contains node with the specified name)

void areacb_t::kill | ( | void |  | ) |
| inline

Delete area information in Btree.

All information about the current type of areas is deleted. Deallocate cache.

bool areacb_t::create_area | ( | const area_t * | info | ) |
| inline

Create an area.

The new area should not overlap with existing ones.

Parameters

  info | structure containing information about a new area. startEA and endEA specify address range. startEA should be less than endEA

Return values

  1 | ok
  0 | failure, area overlaps with another area or bad address range.

bool areacb_t::update | ( | const area_t * | info | ) |
| inline

Update information about area in Btree.

This function can't change startEA and endEA fields. Its only purpose is to update additional characteristics of the area.

area_t* areacb_t::get_area | ( | ea_t | ea | ) |
| inline

Get pointer to area structure by address.

Parameters

  ea | any address in the area

Returns
  NULL: no area occupies the specified address otherwise returns pointer to area structure.

area_t* areacb_t::getn_area | ( | unsigned int | n | ) |
| inline

Get pointer to area structure by its number.

Parameters

  n | - number of area (0..get_area_qty()-1)

Returns
  NULL if the specified area doesn't exist. otherwise returns pointer to area structure.

int areacb_t::get_area_num | ( | ea_t | ea | ) |
| inline

Get number of area by address.

Parameters

  ea | - any address in the area

Returns
  -1 if no area occupies the specified address. otherwise returns number of the specified area (0..get_area_qty()-1)

ea_t areacb_t::prepare_to_create | ( | ea_t | start,
|  | ea_t | end
| ) |  |
| inline

Prepare to create a new area.

This function checks whether the new area overlap with an existing one and trims an existing area to make enough address range for the creation of the new area. If the trimming of the existing area doesn't make enough room for the new area, the existing area is simply deleted.

Parameters

  start | start address of the new area
  end | end address of the new area

Returns
  an adjusted end address for the new area. The end address may require some adjustment if another (next) area exists and occupies some addresses from (start..end) range. In this case we don't delete the existing area but adjust end address of the new area.

int areacb_t::get_next_area | ( | ea_t | ea | ) |
| inline

Get number of the next area.

This function returns number of the next (higher in the addressing space) area.

Parameters

  ea | any address in the program

Returns
  -1 if no (more) areas otherwise returns number in the range (0..get_area_qty()-1)

int areacb_t::get_prev_area | ( | ea_t | ea | ) |
| inline

Get number of the previous area.

This function returns number of the previous (lower in the addressing space) area.

Parameters

  ea | any address in the program

Returns
  -1 if no (more) areas. otherwise returns number in the range (0..get_area_qty()-1)

area_t* areacb_t::next_area_ptr | ( | ea_t | ea | ) |
| inline

Get the next area.

Parameters

  ea | any address in the program

Returns
  NULL if there are no (more) areas

area_t* areacb_t::prev_area_ptr | ( | ea_t | ea | ) |
| inline

Get the previous area.

Parameters

  ea | any address in the program

Returns
  NULL if there are no (more) areas

area_t* areacb_t::first_area_ptr | ( | void |  | ) |
| inline

Get the first area.

Returns
  NULL if there are no areas

area_t* areacb_t::last_area_ptr | ( | void |  | ) |
| inline

Get the last area.

Returns
  NULL if there are no areas

bool areacb_t::del_area | ( | ea_t | ea,
|  | bool | delcmt = `true`
| ) |  |
| inline

Delete an area.

Parameters

  ea | any address in the area
  delcmt | delete area comments. you may choose not to delete comments if you want to create a new area with the same start address immediately. In this case the new area will inherit old area comments.

Return values

  1 | ok
  0 | failure (no such area)

bool areacb_t::may_start_at | ( | uint | n,
|  | ea_t | newstart
| ) |  |
| inline

Check if the specified area may start at the specified address.

This function checks whether the specified area can be changed so that its start address would be 'newstart'.

Parameters

  n | number of area to check
  newstart | new start address for the area

Return values

  1 | yes, it can
  0 | if: the specified area doesn't exist new start address is higher or equal to end address the area would overlap with another area

bool areacb_t::may_end_at | ( | uint | n,
|  | ea_t | newend
| ) |  |
| inline

Check if the specified area may end at the specified address.

This function checks whether the specified area can be changed so that its end address would be 'newend'.

Parameters

  n | number of area to check
  newend | new end address for the area

Return values

  1 | yes, it can
  0 | if: the specified area doesn't exist new start address is higher or equal to end address the area would overlap with another area

bool areacb_t::set_start | ( | uint | n,
|  | ea_t | newstart
| ) |  |
| inline

Change start address of the area.

Parameters

  n | number of area to change
  newstart | new start address for the area This function doesn't modify other areas.

Return values

  1 | ok, area is changed
  0 | if: the specified area doesn't exist new start address is higher or equal to end address the area would overlap with another area

bool areacb_t::set_end | ( | uint | n,
|  | ea_t | newend
| ) |  |
| inline

Change end address of the area.

This function doesn't modify other areas.

Parameters

  n | number of area to change
  newend | new end address for the area

Return values

  1 | ok, area is changed
  0 | if: the specified area doesn't exist new end address is lower or equal to start address the area would overlap with another area

void areacb_t::make_hole | ( | ea_t | ea1,
|  | ea_t | ea2,
|  | bool | create_tail_area
| ) |  |
| inline

Make a hole at the specified address by deleting or modifying existing areas.

Parameters

  ea1,ea2 | range to clear
  create_tail_area | in the case if there is a big area overlapping the specified range, should it be divided in two areas? if 'false', then it will be truncated and the tail will be left without any covering area

bool areacb_t::resize_areas | ( | uint | n,
|  | ea_t | newstart
| ) |  |
| inline

Resize adjacent areas simultaneously.

Parameters

  n | number of area to change. The adjacent (previous) area will be trimmed or expanded if it exists and two areas are contiguous. Otherwise this function behaves like set_start() function.

Returns
  success

uint areacb_t::get_area_qty | ( | void |  | ) | const
| inline

Get number of areas.

Returns
  number of areas ( >= 0 )

area_t* areacb_t::choose_area | ( | int | flags,
|  | int | width,
|  | char *(idaapi *)(areacb_t *obj, uint32 n, char *buf) | getl,
|  | const char * | title,
|  | int | icon,
|  | int | x0 = `-1`,
|  | int | y0 = `-1`,
|  | int | x1 = `-1`,
|  | int | y1 = `-1`,
|  | const char *const * | popup_menus = `NULL`,
|  | ea_t | defea = `BADADDR`
| ) |  |
| inline

Let the user choose an area.

(1-column chooser). This function displays a window with a list of areas and allows the user to choose an area from the list.

Parameters

  flags | Generic chooser flags
  width | width of the window
  getl | callback function to get text representation of an area. obj: pointer to area control block n: (number of area + 1). if n==0 then getl() should return text of a header line. buf: buffer for the text representation

getl() should return pointer to text representation string (not necessarily the same pointer as 'buf')

Parameters

  title | title of the window.
  icon | number of icon to display
  defea | address which points to the default area. The cursor will be position to this area.
  x0,y0,x1,y1 | window position on the screen. -1 values specify default window position. txt:upper left corner of the screen gui:centered on the foreground window
  popup_menus | default is insert, delete, edit, refresh

Returns
  NULL if the user pressed Esc. otherwise a pointer to the selected area.

area_t* areacb_t::choose_area2 | ( | int | flags,
|  | int | ncol,
|  | const int * | widths,
|  | void(idaapi *)(areacb_t *obj, uint32 n, char *const *arrptr) | getl,
|  | const char * | title,
|  | int | icon,
|  | int | x0 = `-1`,
|  | int | y0 = `-1`,
|  | int | x1 = `-1`,
|  | int | y1 = `-1`,
|  | const char *const * | popup_menus = `NULL`,
|  | ea_t | defea = `BADADDR`
| ) |  |
| inline

Let the user choose an area.

(n-column chooser). This function displays a window with a list of areas and allows the user to choose an area from the list.

Parameters

  flags | Generic chooser flags
  ncol | number of columns
  widths | widths of each column in characters (may be NULL)
  getl | callback function to get text representation of an area obj: pointer to area control block n: (number of area + 1). if n==0 then getl() should return text of a header line. arrptr: array of buffers for the text representation
  title | title of the window.
  icon | number of icon to display
  defea | address which points to the default area. The cursor will be position to this area.
  x0,y0,x1,y1 | window position on the screen. -1 values specify default window position. txt:upper left corner of the screen gui:centered on the foreground window
  popup_menus | default is insert, delete, edit, refresh

Returns
  NULL if the user cancelled the selection otherwise a pointer to the selected area.

ea_t areacb_t::find_prev_gap | ( | ea_t | ea | ) |

Find previous gap in areas.

This function finds a gap between areas. Only enabled addresses (see bytes.hpp for explanations on addressing) are used in the search.

Parameters

  ea | any linear address

Returns
  BADADDR if no previous gap is found. otherwise returns maximal address in the previous gap

ea_t areacb_t::find_next_gap | ( | ea_t | ea | ) |

Find next gap in areas.

This function finds a gap between areas. Only enabled addresses (see bytes.hpp for explanations on addressing) are used in the search.

Parameters

  ea | any linear address

Returns
  BADADDR if no next gap is found. otherwise returns start address of the next gap

bool areacb_t::set_area_cmt | ( | const area_t * | a,
|  | const char * | cmt,
|  | bool | repeatable
| ) |  |
| inline

Set area comment.

This function sets area comment.

Parameters

  a | pointer to area structure (may be NULL)
  repeatable | 0: set regular comment, 1: set repeatable comment

void areacb_t::del_area_cmt | ( | const area_t * | a,
|  | bool | repeatable
| ) |  |
| inline

Delete area comment.

Each area may have its comment (a function may have a comment, for example) This function deletes such a comment.

Parameters

  a | pointer to area structure (may be NULL)
  repeatable | 0: delete regular comment, 1: delete repeatable comment

char* areacb_t::get_area_cmt | ( | const area_t * | a,
|  | bool | repeatable
| ) |  | const
| inline

Get area comment.

The caller must qfree() the result.

Parameters

  a | pointer to area structure (may be NULL)
  repeatable | 0: get regular comment, 1: get repeatable comment

int areacb_t::move_areas | ( | ea_t | from,
|  | ea_t | to,
|  | asize_t | size,
|  | int(idaapi *)(area_t *a, adiff_t delta, void *ud) | area_mover = `NULL`,
|  | void * | ud = `NULL`
| ) |  |
| inline

Move area information to the specified addresses.

Returns
  0 if ok, otherwise the code returned by area_mover

int areacb_t::for_all_areas2 | ( | ea_t | ea1,
|  | ea_t | ea2,
|  | area_visitor2_t & | av
| ) |  |
| inline

Call a function for all areas in the specified range.

Stop the enumeration if the function returns non-zero

Returns
  0 if all areas were visited, otherwise the code returned by the callback

Parameters

  av |

## Member Data Documentation

void(idaapi * areacb_t::read_cb) (const uchar *packed, const uchar *end, area_t *a)

Read callback: read area from the database.

This function is called when a (possibly packed) area is read from the database.

Parameters

  packed | stream of packed bytes
  end | ptr to the end of the stream
  a | place to put unpacked version of the area This callback may be NULL. MUST be set (if any) before call to link()

size_t(idaapi * areacb_t::write_cb) (const area_t *a, uchar *packbuf, uchar *packend)

Write callback: write area to the database.

This function is called when an area is about to be written to the database. It may pack the the area to the stream of bytes.

Parameters

  a | area to be written
  packbuf | buffer to hold packed version of the area
  packend | ptr to the end of packbuf

Returns
  the number of bytes in the packed form This callback may be NULL. MUST be set (if any) before call to link()

void(idaapi * areacb_t::delcache_cb) (area_t *a)

Destroy callback: remove an area from the internal cache.

This function is called when an area is freed from the cache. This callback may be NULL.

int(idaapi * areacb_t::edit_cb) (area_t *a)

The following three callbacks are used in open_areas_window() function.

When the user presses Ctrl-E key the following callback is called to edit the selected area. This callback may be NULL.

int(idaapi * areacb_t::kill_cb) (area_t *a)

Callback to handle "Del" keystroke in open_areas_window() function.

This callback may be NULL.

int(idaapi * areacb_t::new_cb) (void)

Callback to handle "Ins" keystroke in open_areas_window() function This callback may be NULL.

The documentation for this class was generated from the following file:

- area.hpp