idalib/
bookmarks.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
use std::ffi::CString;
use std::marker::PhantomData;

use crate::ffi::bookmarks::{
    idalib_bookmarks_t_erase, idalib_bookmarks_t_find_index, idalib_bookmarks_t_get,
    idalib_bookmarks_t_get_desc, idalib_bookmarks_t_mark, idalib_bookmarks_t_size,
};
use crate::ffi::BADADDR;

use crate::idb::IDB;
use crate::{Address, IDAError};

pub type BookmarkIndex = u32;

const BOOKMARKS_BAD_INDEX: BookmarkIndex = 0xffffffff; // (uint32(-1))

pub struct Bookmarks<'a> {
    _marker: PhantomData<&'a IDB>,
}

impl<'a> Bookmarks<'a> {
    pub(crate) fn new(_: &'a IDB) -> Self {
        Self {
            _marker: PhantomData,
        }
    }

    pub fn mark(&self, ea: Address, desc: impl AsRef<str>) -> Result<BookmarkIndex, IDAError> {
        self.mark_with(ea, self.len(), desc)
    }

    // Notes:
    // * Adding a bookmark at an already marked address creates an overlaid bookmark
    // * Adding a bookmark at an already used index has no effect and no error is returned
    // * Adding a bookmark at an index > `len()` increments `len()` accordingly, while leaving
    //   the unused bookmark slots empty
    // * The `MAX_MARK_SLOT` limit (1024) doesn't seem to play an actual role ¯\_(ツ)_/¯
    pub fn mark_with(
        &self,
        ea: Address,
        idx: BookmarkIndex,
        desc: impl AsRef<str>,
    ) -> Result<BookmarkIndex, IDAError> {
        let desc = CString::new(desc.as_ref()).map_err(IDAError::ffi)?;

        let slot = unsafe { idalib_bookmarks_t_mark(ea.into(), idx.into(), desc.as_ptr()) };

        if slot != BOOKMARKS_BAD_INDEX {
            Ok(slot)
        } else {
            Err(IDAError::ffi_with(format!(
                "failed to set bookmark at address {ea:#x}, index {idx}"
            )))
        }
    }

    pub fn get_description(&self, ea: Address) -> Option<String> {
        self.get_description_by_index(self.find_index(ea)?)
    }

    // Note: The `bookmarks_t::get` function is used here only to get the address
    pub fn get_address(&self, idx: BookmarkIndex) -> Option<Address> {
        let addr = unsafe { idalib_bookmarks_t_get(idx.into()) };

        if addr == BADADDR {
            None
        } else {
            Some(addr.into())
        }
    }

    // Note: The address parameter has been removed because it is unused by IDA's API
    pub fn get_description_by_index(&self, idx: BookmarkIndex) -> Option<String> {
        let s = unsafe { idalib_bookmarks_t_get_desc(idx.into()) };

        if s.is_empty() {
            None
        } else {
            Some(s)
        }
    }

    pub fn erase(&self, ea: Address) -> Result<(), IDAError> {
        self.erase_by_index(self.find_index(ea).ok_or(IDAError::ffi_with(format!(
            "failed to find bookmark index for address {ea:#x}"
        )))?)
    }

    // Notes:
    // * When a bookmark is erased, all the following indexes are decremented to fill the gap
    // * The address parameter has been removed because it is unused by IDA's API
    pub fn erase_by_index(&self, idx: BookmarkIndex) -> Result<(), IDAError> {
        // Prevent IDA's internal error 1312 that triggers when an invalid index is supplied
        if idx >= self.len() {
            return Err(IDAError::ffi_with(format!(
                "failed to erase bookmark at index {idx}"
            )));
        }
        if unsafe { idalib_bookmarks_t_erase(idx.into()) } {
            Ok(())
        } else {
            Err(IDAError::ffi_with(format!(
                "failed to erase bookmark at index {idx}"
            )))
        }
    }

    pub fn find_index(&self, ea: Address) -> Option<BookmarkIndex> {
        let index = unsafe { idalib_bookmarks_t_find_index(ea.into()) };

        if index != BOOKMARKS_BAD_INDEX {
            Some(index)
        } else {
            None
        }
    }

    // Note: The address parameter has been removed because it is unused by IDA's API
    pub fn len(&self) -> BookmarkIndex {
        unsafe { idalib_bookmarks_t_size() }
    }

    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }
}