Module `ida_dirtree`

Types involved in grouping of item into folders.

The dirtree_t class is used to organize a directory tree on top of any collection that allows for accessing its elements by an id (inode).

No requirements are imposed on the inodes apart from the forbidden value -1 (it is used ot denote a bad inode).

The dirspec_t class is used to specialize the dirtree. It can be used to introduce a directory structure for:

local types
structs
enums
functions
names
etc

note: you should be manipulating dirtree_t (and, if implementing a new tree

backend, dirspec_t) instances, not calling top-level functions in this file directly.

Global variables

var DIRTREE_BPTS: DIRTREE_BPTS = 9
var DIRTREE_END: DIRTREE_END = 10
var DIRTREE_ENUMS: DIRTREE_ENUMS = 2
var DIRTREE_ENUMS_BOOKMARKS: DIRTREE_ENUMS_BOOKMARKS = 8
var DIRTREE_FUNCS: DIRTREE_FUNCS = 3
var DIRTREE_IDAPLACE_BOOKMARKS: DIRTREE_IDAPLACE_BOOKMARKS = 6
var DIRTREE_IMPORTS: DIRTREE_IMPORTS = 5
var DIRTREE_LOCAL_TYPES: DIRTREE_LOCAL_TYPES = 0
var DIRTREE_NAMES: DIRTREE_NAMES = 4
var DIRTREE_STRUCTS: DIRTREE_STRUCTS = 1
var DIRTREE_STRUCTS_BOOKMARKS: DIRTREE_STRUCTS_BOOKMARKS = 7
var DTE_ALREADY_EXISTS: DTE_ALREADY_EXISTS = 1
var DTE_BAD_PATH: DTE_BAD_PATH = 5
var DTE_CANT_RENAME: DTE_CANT_RENAME = 6
var DTE_LAST: DTE_LAST = 9
var DTE_MAX_DIR: DTE_MAX_DIR = 8
var DTE_NOT_DIRECTORY: DTE_NOT_DIRECTORY = 3
var DTE_NOT_EMPTY: DTE_NOT_EMPTY = 4
var DTE_NOT_FOUND: DTE_NOT_FOUND = 2
var DTE_OK: DTE_OK = 0
var DTE_OWN_CHILD: DTE_OWN_CHILD = 7
var DTN_DISPLAY_NAME: use short, displayable form of the entry name. for example, 'std::string' instead of 'std::basic_string<char, ...>'. Note that more than one "full name" can have the same displayable name.
var DTN_FULL_NAME: use long form of the entry name. That name is unique.

Functions

def dirtree_cursor_t_root_cursor(*args) ‑> dirtree_cursor_t: dirtree_cursor_t_root_cursor() -> dirtree_cursor_t
def dirtree_t_errstr(*args) ‑> char const *: dirtree_t_errstr(err) -> char const *
err: enum dterr_t
def get_std_dirtree(*args) ‑> dirtree_t *: get_std_dirtree(id) -> dirtree_t
id: enum dirtree_id_t

Classes

class direntry_t (*args)

Proxy of C++ direntry_t class.

__init__(self, i=BADIDX, d=False) -> direntry_t

i: uval_t

d: bool

Class variables

var BADIDX
var ROOTIDX

Instance variables

var idx: diridx_t or inode_t
var isdir: is 'idx' a diridx_t, or an inode_t

Methods

def valid(self, *args) ‑> bool: valid(self) -> bool

class direntry_vec_t (*args)

Proxy of C++ qvector< direntry_t > class.

__init__(self) -> direntry_vec_t

__init__(self, x) -> direntry_vec_t

x: qvector< direntry_t > const &

Methods

def add_unique(self, *args) ‑> bool: add_unique(self, x) -> bool
x: direntry_t const &
def at(self, *args) ‑> direntry_t const &: at(self, _idx) -> direntry_t
_idx: size_t
def back(self)
def begin(self, *args) ‑> qvector< direntry_t >::const_iterator: begin(self) -> direntry_t
def capacity(self, *args) ‑> size_t: capacity(self) -> size_t
def clear(self, *args) ‑> void: clear(self)
def empty(self, *args) ‑> bool: empty(self) -> bool
def end(self, *args) ‑> qvector< direntry_t >::const_iterator: end(self) -> direntry_t
def erase(self, *args) ‑> qvector< direntry_t >::iterator: erase(self, it) -> direntry_t
it: qvector< direntry_t >::iterator

erase(self, first, last) -> direntry_t
first: qvector< direntry_t >::iterator

last: qvector< direntry_t >::iterator
def extract(self, *args) ‑> direntry_t *: extract(self) -> direntry_t
def find(self, *args) ‑> qvector< direntry_t >::const_iterator: find(self, x) -> direntry_t
x: direntry_t const &
def front(self)
def grow(self, *args) ‑> void: grow(self, x=direntry_t())

x: direntry_t const &
def has(self, *args) ‑> bool: has(self, x) -> bool
x: direntry_t const &
def inject(self, *args) ‑> void: inject(self, s, len)
s: direntry_t *

len: size_t
def insert(self, *args) ‑> qvector< direntry_t >::iterator: insert(self, it, x) -> direntry_t
it: qvector< direntry_t >::iterator

x: direntry_t const &
def pop_back(self, *args) ‑> void: pop_back(self)
def push_back(self, *args) ‑> direntry_t &: push_back(self, x)
x: direntry_t const &

push_back(self) -> direntry_t
def qclear(self, *args) ‑> void: qclear(self)
def reserve(self, *args) ‑> void: reserve(self, cnt)
cnt: size_t
def resize(self, *args) ‑> void: resize(self, _newsize, x)
_newsize: size_t

x: direntry_t const &

resize(self, _newsize)
_newsize: size_t
def size(self, *args) ‑> size_t: size(self) -> size_t
def swap(self, *args) ‑> void: swap(self, r)
r: qvector< direntry_t > &
def truncate(self, *args) ‑> void: truncate(self)

class dirspec_t (*args)

Proxy of C++ dirspec_t class.

__init__(self, nm=None, f=0) -> dirspec_t

nm: char const *

f: uint32

Class variables

var DSF_INODE_EA
var DSF_ORDERABLE
var DSF_PRIVRANGE

Instance variables

var flags: flags
var id: id
var nodename: id

Methods

def get_attrs(self, *args) ‑> qstring: get_attrs(self, inode) -> qstring
inode: inode_t
def get_inode(self, *args) ‑> inode_t: get_inode(self, dirpath, name) -> inode_t
get the entry inode in the specified directory

dirpath: (C++: const char *) the absolute directory path with trailing slash

name: (C++: const char *) the entry name in the directory

return: the entry inode
def get_name(self, *args) ‑> bool: get_name(self, inode, name_flags=DTN_FULL_NAME) -> bool
get the entry name. for example, the structure name

inode: (C++: inode_t) inode number of the entry

name_flags: (C++: uint32) how exactly the name should be retrieved. combination of bits
for get_...name() methods bits

return: false if the entry does not exist.
def is_orderable(self, *args) ‑> bool: is_orderable(self) -> bool
def rename_inode(self, *args) ‑> bool: rename_inode(self, inode, newname) -> bool
rename the entry

inode: (C++: inode_t)

newname: (C++: const char *)

return: success
def unlink_inode(self, *args) ‑> void: unlink_inode(self, inode)
inode: (C++: inode_t)

class dirtree_cursor_t (*args)

Proxy of C++ dirtree_cursor_t class.

__init__(self, _parent=BADIDX, _rank=size_t(-1)) -> dirtree_cursor_t

_parent: diridx_t

_rank: size_t

Static methods

def root_cursor(*args) ‑> dirtree_cursor_t: root_cursor() -> dirtree_cursor_t

Instance variables

var parent: the parent directory
var rank: the index into the parent directory

Methods

def compare(self, *args) ‑> int: compare(self, r) -> int
r: dirtree_cursor_t const &
def is_root_cursor(self, *args) ‑> bool: is_root_cursor(self) -> bool
def set_root_cursor(self, *args) ‑> void: set_root_cursor(self)
def valid(self, *args) ‑> bool: valid(self) -> bool

class dirtree_cursor_vec_t (*args)

Proxy of C++ qvector< dirtree_cursor_t > class.

__init__(self) -> dirtree_cursor_vec_t

__init__(self, x) -> dirtree_cursor_vec_t

x: qvector< dirtree_cursor_t > const &

Subclasses

dirtree_selection_t

Methods

def add_unique(self, *args) ‑> bool: add_unique(self, x) -> bool
x: dirtree_cursor_t const &
def at(self, *args) ‑> dirtree_cursor_t const &: at(self, _idx) -> dirtree_cursor_t
_idx: size_t
def back(self)
def begin(self, *args) ‑> qvector< dirtree_cursor_t >::const_iterator: begin(self) -> dirtree_cursor_t
def capacity(self, *args) ‑> size_t: capacity(self) -> size_t
def clear(self, *args) ‑> void: clear(self)
def empty(self, *args) ‑> bool: empty(self) -> bool
def end(self, *args) ‑> qvector< dirtree_cursor_t >::const_iterator: end(self) -> dirtree_cursor_t
def erase(self, *args) ‑> qvector< dirtree_cursor_t >::iterator: erase(self, it) -> dirtree_cursor_t
it: qvector< dirtree_cursor_t >::iterator

erase(self, first, last) -> dirtree_cursor_t
first: qvector< dirtree_cursor_t >::iterator

last: qvector< dirtree_cursor_t >::iterator
def extract(self, *args) ‑> dirtree_cursor_t *: extract(self) -> dirtree_cursor_t
def find(self, *args) ‑> qvector< dirtree_cursor_t >::const_iterator: find(self, x) -> dirtree_cursor_t
x: dirtree_cursor_t const &
def front(self)
def grow(self, *args) ‑> void: grow(self, x=dirtree_cursor_t())

x: dirtree_cursor_t const &
def has(self, *args) ‑> bool: has(self, x) -> bool
x: dirtree_cursor_t const &
def inject(self, *args) ‑> void: inject(self, s, len)
s: dirtree_cursor_t *

len: size_t
def insert(self, *args) ‑> qvector< dirtree_cursor_t >::iterator: insert(self, it, x) -> dirtree_cursor_t
it: qvector< dirtree_cursor_t >::iterator

x: dirtree_cursor_t const &
def pop_back(self, *args) ‑> void: pop_back(self)
def push_back(self, *args) ‑> dirtree_cursor_t &: push_back(self, x)
x: dirtree_cursor_t const &

push_back(self) -> dirtree_cursor_t
def qclear(self, *args) ‑> void: qclear(self)
def reserve(self, *args) ‑> void: reserve(self, cnt)
cnt: size_t
def resize(self, *args) ‑> void: resize(self, _newsize, x)
_newsize: size_t

x: dirtree_cursor_t const &

resize(self, _newsize)
_newsize: size_t
def size(self, *args) ‑> size_t: size(self) -> size_t
def swap(self, *args) ‑> void: swap(self, r)
r: qvector< dirtree_cursor_t > &
def truncate(self, *args) ‑> void: truncate(self)

class dirtree_iterator_t (*args)

Proxy of C++ dirtree_iterator_t class.

__init__(self) -> dirtree_iterator_t

Instance variables

var cursor: cursor
var pattern: pattern

class dirtree_selection_t (*args)

Proxy of C++ dirtree_selection_t class.

__init__(self) -> dirtree_selection_t

Ancestors

dirtree_cursor_vec_t

Inherited members

dirtree_cursor_vec_t:
- add_unique
- at
- begin
- capacity
- clear
- empty
- end
- erase
- extract
- find
- grow
- has
- inject
- insert
- pop_back
- push_back
- qclear
- reserve
- resize
- size
- swap
- truncate

class dirtree_t (*args)

Proxy of C++ dirtree_t class.

__init__(self, ds) -> dirtree_t

ds: dirspec_t *

Static methods

def errstr(*args) ‑> char const *: errstr(err) -> char const *
Get textual representation of the error code.

err: (C++: dterr_t) enum dterr_t

Methods

def change_rank(self, *args) ‑> dterr_t: change_rank(self, path, rank_delta) -> dterr_t
Change ordering rank of an item.

path: (C++: const char *) path to the item

rank_delta: (C++: ssize_t) the amount of the change. positive numbers mean to move down
in the list; negative numbers mean to move up.

return: dterr_t error code

note: this function may disable natural ordering of the parent folder

see: set_natural_order()
def chdir(self, *args) ‑> dterr_t: chdir(self, path) -> dterr_t
Change current directory

path: (C++: const char *) new current directory

return: dterr_t error code
def find_entry(self, *args) ‑> dirtree_cursor_t: find_entry(self, de) -> dirtree_cursor_t
Find the cursor corresponding to an entry of a directory

de: (C++: const direntry_t &) directory entry

return: cursor corresponding to the directory entry
def findfirst(self, *args) ‑> bool: findfirst(self, ff, pattern) -> bool
Start iterating over files in a directory

ff: (C++: dirtree_iterator_t *) directory iterator. it will be initialized by the function

pattern: (C++: const char *) pattern to search for

return: success
def findnext(self, *args) ‑> bool: findnext(self, ff) -> bool
Continue iterating over files in a directory

ff: (C++: dirtree_iterator_t *) directory iterator

return: success
def get_abspath(self, *args) ‑> qstring: get_abspath(self, cursor, name_flags=DTN_FULL_NAME) -> qstring
Construct an absolute path from the specified relative path. This function verifies the directory part of the specified path. The last component of the specified path is not verified.

cursor: dirtree_cursor_t const &

name_flags: uint32

return: path. empty path means wrong directory part of RELPATH

get_abspath(self, relpath) -> qstring
relpath: char const *
def get_dir_size(self, *args) ‑> ssize_t: get_dir_size(self, diridx) -> ssize_t
Get dir size

diridx: (C++: diridx_t) directory index

return: number of entries under this directory; if error, return -1
def get_entry_attrs(self, *args) ‑> qstring: get_entry_attrs(self, de) -> qstring
Get entry attributes

de: (C++: const direntry_t &) directory entry

return: name
def get_entry_name(self, *args) ‑> qstring: get_entry_name(self, de, name_flags=DTN_FULL_NAME) -> qstring
Get entry name

de: (C++: const direntry_t &) directory entry

name_flags: (C++: uint32) how exactly the name should be retrieved. combination of bits
for get_...name() methods bits

return: name
def get_id(self, *args) ‑> char const *: get_id(self) -> char const *
netnode name
def get_nodename(self, *args) ‑> char const *: get_id(self) -> char const *
netnode name
def get_parent_cursor(self, *args) ‑> dirtree_cursor_t: get_parent_cursor(self, cursor) -> dirtree_cursor_t
Get parent cursor.

cursor: (C++: const dirtree_cursor_t &) a valid ditree cursor

return: cursor's parent
def get_rank(self, *args) ‑> ssize_t: get_rank(self, diridx, de) -> ssize_t
Get ordering rank of an item.

diridx: (C++: diridx_t) index of the parent directory

de: (C++: const direntry_t &) directory entry

return: number in a range of [0..n) where n is the number of entries in the
parent directory. -1 if error
def getcwd(self, *args) ‑> qstring: getcwd(self) -> qstring
Get current directory

return: the current working directory
def is_dir_ordered(self, *args) ‑> bool: is_dir_ordered(self, diridx) -> bool
Is dir ordered?

diridx: (C++: diridx_t)

return: true if the dirtree has natural ordering
def is_orderable(self, *args) ‑> bool: is_orderable(self) -> bool
Is dirtree orderable?

return: true if the dirtree is orderable
def isdir(self, *args) ‑> bool: isdir(self, de) -> bool
de: direntry_t const &

isdir(self, path) -> bool
path: char const *
def isfile(self, *args) ‑> bool: isfile(self, de) -> bool
de: direntry_t const &

isfile(self, path) -> bool
path: char const *
def link(self, *args) ‑> dterr_t: link(self, path) -> dterr_t
Add an inode into the current directory

path: char const *

return: dterr_t error code

link(self, inode) -> dterr_t
inode: inode_t
def load(self, *args) ‑> bool: load(self) -> bool
Load the tree structure from the netnode. If dirspec_t::id is empty, the operation will be considered a success. In addition, calling load() more than once will not do anything, and will be considered a success.

return: success

see: dirspec_t::id.
def mkdir(self, *args) ‑> dterr_t: mkdir(self, path) -> dterr_t
Create a directory.

path: (C++: const char *) directory to create

return: dterr_t error code
def notify_dirtree(self, *args) ‑> void: notify_dirtree(self, added, inode)
Notify dirtree about a change of an inode.

added: (C++: bool) are we adding or deleting an inode?

inode: (C++: inode_t) inode in question
def rename(self, *args) ‑> dterr_t: rename(self, _from, to) -> dterr_t
Rename a directory entry.

from: (C++: const char *) source path

to: (C++: const char *) destination path

return: dterr_t error code

note: This function can also rename the item
def resolve_cursor(self, *args) ‑> direntry_t: resolve_cursor(self, cursor) -> direntry_t
Resolve cursor

cursor: (C++: const dirtree_cursor_t &) to analyze

return: directory entry; if the cursor is bad, the resolved entry will be
invalid.

note: see also get_abspath()
def resolve_path(self, *args) ‑> direntry_t: resolve_path(self, path) -> direntry_t
Resolve path

path: (C++: const char *) to analyze

return: directory entry
def rmdir(self, *args) ‑> dterr_t: rmdir(self, path) -> dterr_t
Remove a directory.

path: (C++: const char *) directory to delete

return: dterr_t error code
def save(self, *args) ‑> bool: save(self) -> bool
Save the tree structure to the netnode.

return: success

see: dirspec_t::id.
def set_id(self, *args) ‑> void: set_id(self, nm)
nm: char const *
def set_natural_order(self, *args) ‑> bool: set_natural_order(self, diridx, enable) -> bool
Enable/disable natural inode order in a directory.

diridx: (C++: diridx_t) directory index

enable: (C++: bool) action to do TRUE - enable ordering: re-order existing entries so
that all subdirs are at the to beginning of the list, file entries are sorted and placed after the subdirs FALSE - disable ordering, no changes to existing entries

return: SUCCESS
def set_nodename(self, *args) ‑> void: set_id(self, nm)
nm: char const *
def traverse(self, *args) ‑> ssize_t: traverse(self, v) -> ssize_t
Traverse dirtree, and be notified at each entry If the the visitor returns anything other than 0, iteration will stop, and that value returned. The tree is traversed using a depth-first algorithm. It is forbidden to modify the dirtree_t during traversal; doing so will result in undefined behavior.

v: (C++: dirtree_visitor_t &) the callback

return: 0, or whatever the visitor returned
def unlink(self, *args) ‑> dterr_t: unlink(self, path) -> dterr_t
Remove an inode from the current directory

path: char const *

return: dterr_t error code

unlink(self, inode) -> dterr_t
inode: inode_t

class dirtree_visitor_t (*args)

Proxy of C++ dirtree_visitor_t class.

__init__(self) -> dirtree_visitor_t

self: PyObject *

Methods

def visit(self, *args) ‑> ssize_t: visit(self, c, de) -> ssize_t
Will be called for each entry in the dirtree_t If something other than 0 is returned, iteration will stop.

c: (C++: const dirtree_cursor_t &) the current cursor

de: (C++: const direntry_t &) the current entry

return: 0 to keep iterating, or anything else to stop