Module index

# 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 (used to 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 DTE_ALREADY_EXISTS`

  item already exists

`var DTE_BAD_PATH`

  invalid path

`var DTE_CANT_RENAME`

  failed to rename an item

`var DTE_MAX_DIR`

  maximum directory count achieved

`var DTE_NOT_DIRECTORY`

  item is not a directory

`var DTE_NOT_EMPTY`

  directory is not empty

`var DTE_NOT_FOUND`

  item not found

`var DTE_OK`

  ok

`var DTE_OWN_CHILD`

  moving inside subdirectory of itself

`var DTN_DISPLAY_NAME`

  use short, displayable form of the entry name. for example, 'std::string' instead of 'std::basic_string'. 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 get_std_dirtree(id: dirtree_id_t)`

  get_std_dirtree(id) -> dirtree_t

  @param id: enum dirtree_id_t

## Classes

`class direntry_t (*args)`

  Proxy of C++ direntry_t class.

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

  @param i: uval_t @param d: bool

  ### Class variables

  `var BADIDX`
  `var ROOTIDX`

  ### Instance variables

  `var idx : uval_t`

    diridx_t or inode_t

  `var isdir : bool`

    is 'idx' a diridx_t, or an inode_t

  `var thisown`

    The membership flag

  ### Methods

  `def valid(self) ‑> 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

  @param x: qvector< direntry_t > const &

  ### Instance variables

  `var thisown`

    The membership flag

  ### Methods

  `def add_unique(self, x: direntry_t) ‑> bool`

    add_unique(self, x) -> bool

    @param x: direntry_t const &

  `def at(self, _idx: size_t)`

    at(self, _idx) -> direntry_t

    @param _idx: size_t

  `def back(self)`
  `def begin(self, *args)`

    begin(self) -> direntry_t

  `def capacity(self)`

    capacity(self) -> size_t

  `def clear(self)`

    clear(self)

  `def empty(self) ‑> bool`

    empty(self) -> bool

  `def end(self, *args)`

    end(self) -> direntry_t

  `def erase(self, *args)`

    erase(self, it) -> direntry_t

    @param it: qvector< direntry_t >::iterator

    erase(self, first, last) -> direntry_t

    @param first: qvector< direntry_t >::iterator @param last: qvector< direntry_t >::iterator

  `def extract(self)`

    extract(self) -> direntry_t

  `def find(self, *args)`

    find(self, x) -> direntry_t

    @param x: direntry_t const &

  `def front(self)`
  `def grow(self, *args)`

    grow(self, x=direntry_t())

    @param x: direntry_t const &

  `def has(self, x: direntry_t) ‑> bool`

    has(self, x) -> bool

    @param x: direntry_t const &

  `def inject(self, s: direntry_t, len: size_t)`

    inject(self, s, len)

    @param s: direntry_t * @param len: size_t

  `def insert(self, it: direntry_t, x: direntry_t)`

    insert(self, it, x) -> direntry_t

    @param it: qvector< direntry_t >::iterator @param x: direntry_t const &

  `def pop_back(self)`

    pop_back(self)

  `def push_back(self, *args)`

    push_back(self, x)

    @param x: direntry_t const &

    push_back(self) -> direntry_t

  `def qclear(self)`

    qclear(self)

  `def reserve(self, cnt: size_t)`

    reserve(self, cnt)

    @param cnt: size_t

  `def resize(self, *args)`

    resize(self, _newsize, x)

    @param _newsize: size_t @param x: direntry_t const &

    resize(self, _newsize)

    @param _newsize: size_t

  `def size(self)`

    size(self) -> size_t

  `def swap(self, r: direntry_vec_t)`

    swap(self, r)

    @param r: qvector< direntry_t > &

  `def truncate(self)`

    truncate(self)

`class dirspec_t (nm: char const * = None, f: uint32 = 0)`

  Proxy of C++ dirspec_t class.

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

  @param nm: char const * @param f: uint32

  ### Class variables

  `var DSF_INODE_EA`
  `var DSF_ORDERABLE`
  `var DSF_PRIVRANGE`

  ### Instance variables

  `var flags : uint32`

    flags

  `var id : qstring`

    id

  `var nodename`

    id

  `var thisown`

    The membership flag

  ### Methods

  `def get_attrs(self, inode: inode_t)`

    get_attrs(self, inode) -> qstring

    @param inode: inode_t

  `def get_inode(self, dirpath: char const *, name: char const *)`

    get_inode(self, dirpath, name) -> inode_t get the entry inode in the specified directory

    @param dirpath: (C++: const char ) the absolute directory path with trailing slash @param name: (C++: const char ) the entry name in the directory @return: the entry inode

  `def get_name(self, inode: inode_t, name_flags: uint32 = 0)`

    get_name(self, inode, name_flags=DTN_FULL_NAME) -> bool get the entry name. for example, the structure name

    @param inode: (C++: inode_t) inode number of the entry @param 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) ‑> bool`

    is_orderable(self) -> bool

  `def rename_inode(self, inode: inode_t, newname: char const *)`

    rename_inode(self, inode, newname) -> bool rename the entry

    @param inode: (C++: inode_t) @param newname: (C++: const char *) @return: success

  `def unlink_inode(self, inode: inode_t)`

    unlink_inode(self, inode)

    @param 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

  @param _parent: diridx_t @param _rank: size_t

  ### Static methods

  `def root_cursor() ‑> dirtree_cursor_t`

    root_cursor() -> dirtree_cursor_t

  ### Instance variables

  `var parent : diridx_t`

    the parent directory

  `var rank : size_t`

    the index into the parent directory

  `var thisown`

    The membership flag

  ### Methods

  `def compare(self, r: dirtree_cursor_t) ‑> int`

    compare(self, r) -> int

    @param r: dirtree_cursor_t const &

  `def is_root_cursor(self) ‑> bool`

    is_root_cursor(self) -> bool

  `def set_root_cursor(self)`

    set_root_cursor(self)

  `def valid(self) ‑> 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

  @param x: qvector< dirtree_cursor_t > const &

  ### Subclasses

  - dirtree_selection_t

  ### Instance variables

  `var thisown`

    The membership flag

  ### Methods

  `def add_unique(self, x: dirtree_cursor_t) ‑> bool`

    add_unique(self, x) -> bool

    @param x: dirtree_cursor_t const &

  `def at(self, _idx: size_t)`

    at(self, _idx) -> dirtree_cursor_t

    @param _idx: size_t

  `def back(self)`
  `def begin(self, *args)`

    begin(self) -> dirtree_cursor_t

  `def capacity(self)`

    capacity(self) -> size_t

  `def clear(self)`

    clear(self)

  `def empty(self) ‑> bool`

    empty(self) -> bool

  `def end(self, *args)`

    end(self) -> dirtree_cursor_t

  `def erase(self, *args)`

    erase(self, it) -> dirtree_cursor_t

    @param it: qvector< dirtree_cursor_t >::iterator

    erase(self, first, last) -> dirtree_cursor_t

    @param first: qvector< dirtree_cursor_t >::iterator @param last: qvector< dirtree_cursor_t >::iterator

  `def extract(self)`

    extract(self) -> dirtree_cursor_t

  `def find(self, *args)`

    find(self, x) -> dirtree_cursor_t

    @param x: dirtree_cursor_t const &

  `def front(self)`
  `def grow(self, *args)`

    grow(self, x=dirtree_cursor_t())

    @param x: dirtree_cursor_t const &

  `def has(self, x: dirtree_cursor_t) ‑> bool`

    has(self, x) -> bool

    @param x: dirtree_cursor_t const &

  `def inject(self, s: dirtree_cursor_t, len: size_t)`

    inject(self, s, len)

    @param s: dirtree_cursor_t * @param len: size_t

  `def insert(self, it: dirtree_cursor_t, x: dirtree_cursor_t)`

    insert(self, it, x) -> dirtree_cursor_t

    @param it: qvector< dirtree_cursor_t >::iterator @param x: dirtree_cursor_t const &

  `def pop_back(self)`

    pop_back(self)

  `def push_back(self, *args)`

    push_back(self, x)

    @param x: dirtree_cursor_t const &

    push_back(self) -> dirtree_cursor_t

  `def qclear(self)`

    qclear(self)

  `def reserve(self, cnt: size_t)`

    reserve(self, cnt)

    @param cnt: size_t

  `def resize(self, *args)`

    resize(self, _newsize, x)

    @param _newsize: size_t @param x: dirtree_cursor_t const &

    resize(self, _newsize)

    @param _newsize: size_t

  `def size(self)`

    size(self) -> size_t

  `def swap(self, r: dirtree_cursor_vec_t)`

    swap(self, r)

    @param r: qvector< dirtree_cursor_t > &

  `def truncate(self)`

    truncate(self)

`class dirtree_iterator_t`

  Proxy of C++ dirtree_iterator_t class.

  init(self) -> dirtree_iterator_t

  ### Instance variables

  `var cursor : dirtree_cursor_t`

    cursor

  `var pattern : qstring`

    pattern

  `var thisown`

    The membership flag

`class dirtree_selection_t`

  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`
    - `thisown`
    - `truncate`
`class dirtree_t (ds: dirspec_t)`

  Proxy of C++ dirtree_t class.

  init(self, ds) -> dirtree_t

  @param ds: dirspec_t *

  ### Static methods

  `def errstr(err: dterr_t)`

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

    @param err: (C++: dterr_t) enum dterr_t

  ### Instance variables

  `var thisown`

    The membership flag

  ### Methods

  `def change_rank(self, path: char const *, rank_delta: ssize_t)`

    change_rank(self, path, rank_delta) -> dterr_t Change ordering rank of an item.

    @param path: (C++: const char *) path to the item @param 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, path: char const *)`

    chdir(self, path) -> dterr_t Change current directory

    @param path: (C++: const char *) new current directory @return: dterr_t error code

  `def find_entry(self, de: direntry_t) ‑> dirtree_cursor_t`

    find_entry(self, de) -> dirtree_cursor_t Find the cursor corresponding to an entry of a directory

    @param de: (C++: const direntry_t &) directory entry @return: cursor corresponding to the directory entry

  `def findfirst(self, ff: dirtree_iterator_t, pattern: char const *)`

    findfirst(self, ff, pattern) -> bool Start iterating over files in a directory

    @param ff: (C++: dirtree_iterator_t ) directory iterator. it will be initialized by the function @param pattern: (C++: const char ) pattern to search for @return: success

  `def findnext(self, ff: dirtree_iterator_t) ‑> bool`

    findnext(self, ff) -> bool Continue iterating over files in a directory

    @param ff: (C++: dirtree_iterator_t *) directory iterator @return: success

  `def get_abspath(self, *args)`

    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.

    @param cursor: dirtree_cursor_t const & @param name_flags: uint32

    @return: path. empty path means wrong directory part of RELPATH get_abspath(self, relpath) -> qstring

    @param relpath: char const *

  `def get_dir_size(self, diridx: diridx_t)`

    get_dir_size(self, diridx) -> ssize_t Get dir size

    @param diridx: (C++: diridx_t) directory index @return: number of entries under this directory; if error, return -1

  `def get_entry_attrs(self, de: direntry_t)`

    get_entry_attrs(self, de) -> qstring Get entry attributes

    @param de: (C++: const direntry_t &) directory entry @return: name

  `def get_entry_name(self, de: direntry_t, name_flags: uint32 = 0)`

    get_entry_name(self, de, name_flags=DTN_FULL_NAME) -> qstring Get entry name

    @param de: (C++: const direntry_t &) directory entry @param 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)`

    get_id(self) -> char const * netnode name

  `def get_nodename(self)`

    get_id(self) -> char const * netnode name

  `def get_parent_cursor(self, cursor: dirtree_cursor_t) ‑> dirtree_cursor_t`

    get_parent_cursor(self, cursor) -> dirtree_cursor_t Get parent cursor.

    @param cursor: (C++: const dirtree_cursor_t &) a valid ditree cursor @return: cursor's parent

  `def get_rank(self, diridx: diridx_t, de: direntry_t)`

    get_rank(self, diridx, de) -> ssize_t Get ordering rank of an item.

    @param diridx: (C++: diridx_t) index of the parent directory @param 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)`

    getcwd(self) -> qstring Get current directory

    @return: the current working directory

  `def is_dir_ordered(self, diridx: diridx_t)`

    is_dir_ordered(self, diridx) -> bool Is dir ordered?

    @param diridx: (C++: diridx_t) @return: true if the dirtree has natural ordering

  `def is_orderable(self) ‑> bool`

    is_orderable(self) -> bool Is dirtree orderable?

    @return: true if the dirtree is orderable

  `def isdir(self, *args) ‑> bool`

    isdir(self, de) -> bool

    @param de: direntry_t const &

    isdir(self, path) -> bool

    @param path: char const *

  `def isfile(self, *args) ‑> bool`

    isfile(self, de) -> bool

    @param de: direntry_t const &

    isfile(self, path) -> bool

    @param path: char const *

  `def link(self, *args)`

    link(self, path) -> dterr_t Add an inode into the current directory

    @param path: char const *

    @return: dterr_t error code link(self, inode) -> dterr_t

    @param inode: inode_t

  `def load(self) ‑> 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, path: char const *)`

    mkdir(self, path) -> dterr_t Create a directory.

    @param path: (C++: const char *) directory to create @return: dterr_t error code

  `def notify_dirtree(self, added: bool, inode: inode_t)`

    notify_dirtree(self, added, inode) Notify dirtree about a change of an inode.

    @param added: (C++: bool) are we adding or deleting an inode? @param inode: (C++: inode_t) inode in question

  `def rename(self, _from: char const *, to: char const *)`

    rename(self, _from, to) -> dterr_t Rename a directory entry.

    @param from: (C++: const char ) source path @param to: (C++: const char ) destination path @return: dterr_t error code @note: This function can also rename the item

  `def resolve_cursor(self, cursor: dirtree_cursor_t) ‑> direntry_t`

    resolve_cursor(self, cursor) -> direntry_t Resolve cursor

    @param 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, path: char const *)`

    resolve_path(self, path) -> direntry_t Resolve path

    @param path: (C++: const char *) to analyze @return: directory entry

  `def rmdir(self, path: char const *)`

    rmdir(self, path) -> dterr_t Remove a directory.

    @param path: (C++: const char *) directory to delete @return: dterr_t error code

  `def save(self) ‑> bool`

    save(self) -> bool Save the tree structure to the netnode.

    @return: success @see: dirspec_t::id.

  `def set_id(self, nm: char const *)`

    set_id(self, nm)

    @param nm: char const *

  `def set_natural_order(self, diridx: diridx_t, enable: bool)`

    set_natural_order(self, diridx, enable) -> bool Enable/disable natural inode order in a directory.

    @param diridx: (C++: diridx_t) directory index @param 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, nm: char const *)`

    set_id(self, nm)

    @param nm: char const *

  `def traverse(self, v: dirtree_visitor_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.

    @param v: (C++: dirtree_visitor_t &) the callback @return: 0, or whatever the visitor returned

  `def unlink(self, *args)`

    unlink(self, path) -> dterr_t Remove an inode from the current directory

    @param path: char const *

    @return: dterr_t error code unlink(self, inode) -> dterr_t

    @param inode: inode_t

`class dirtree_visitor_t`

  Proxy of C++ dirtree_visitor_t class.

  init(self) -> dirtree_visitor_t

  @param self: PyObject *

  ### Instance variables

  `var thisown`

    The membership flag

  ### Methods

  `def visit(self, c: dirtree_cursor_t, de: direntry_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.

    @param c: (C++: const dirtree_cursor_t &) the current cursor @param de: (C++: const direntry_t &) the current entry @return: 0 to keep iterating, or anything else to stop