Struct CheckedPacket

Source

pub struct CheckedPacket { /* private fields */ }

Implementations§

Source §

impl CheckedPacket

Source

pub fn assume_checked(unchecked: UncheckedPacket) -> Self

If you know the packet isn’t corrupted, this function bypasses the checksum verification.

Source

pub fn invalidate_check(self) -> UncheckedPacket

If you intend to mutate the packet’s internals, you must first convert it to an unchecked packet so it isn’t marked as checked.

Source

pub fn empty() -> Self

The empty packet is used when you get a packet which you just don’t understand. Replying an empty packet means “I don’t support this feature”.

let mut encoded = Vec::new();
CheckedPacket::empty().encode(&mut encoded);
assert_eq!(encoded, b"$#00")

Source

pub fn from_data(kind: Kind, data: Vec<u8>) -> Self

Creates a packet from the inputted binary data, and generates the checksum from it.

assert_eq!(
    CheckedPacket::from_data(Kind::Packet, b"Hello, World!".to_vec()).invalidate_check(),
    UncheckedPacket {
        kind: Kind::Packet,
        data: b"Hello, World!".to_vec(),
        checksum: *b"69"
    },
)

Examples found in repository ?

examples/repl.rs (line 23)

4fn main() -> Result<(), Error> {
5    println!("Listening on port 1337...");
6    let mut server = GdbServer::listen("0.0.0.0:1337")?;
7    println!("Connected!");
8
9    while let Some(packet) = server.next_packet()? {
10        println!(
11            "-> {:?} {:?}",
12            packet.kind,
13            std::str::from_utf8(&packet.data)
14        );
15
16        print!(": ");
17        io::stdout().flush()?;
18        let mut response = String::new();
19        io::stdin().read_line(&mut response)?;
20        if response.ends_with('\n') {
21            response.truncate(response.len() - 1);
22        }
23        let response = CheckedPacket::from_data(Kind::Packet, response.into_bytes());
24
25        let mut bytes = Vec::new();
26        response.encode(&mut bytes).unwrap();
27        println!("<- {:?}", std::str::from_utf8(&bytes));
28
29        server.dispatch(&response)?;
30    }
31
32    println!("EOF");
33    Ok(())
34}

Methods from Deref<Target = UncheckedPacket>§

Source

pub fn expected_checksum(&self) -> Result<u8, Error>

Return the integer parsed from the hexadecimal expected checksum.

let packet = UncheckedPacket {
    kind: Kind::Packet,
    data: b"Hello, World!".to_vec(),
    checksum: *b"BA",
};
assert_eq!(packet.expected_checksum().unwrap(), 186);

Source

pub fn actual_checksum(&self) -> u8

Return the actual checksum, derived from the data.

let packet = UncheckedPacket {
    kind: Kind::Packet,
    data: b"Hello, World!".to_vec(),
    checksum: *b"BA",
};
assert_eq!(packet.actual_checksum(), 105);

As per the GDB specification, this is currently a sum of all characters, modulo 256. The same result can be compared with

(input.bytes().map(|x| usize::from(x)).sum::<usize>() % 256) as u8

however, this function is more efficient and won’t go out of bounds.

Source

pub fn is_valid(&self) -> bool

Returns true if the checksums match.

assert_eq!(UncheckedPacket {
    kind: Kind::Packet,
    data: b"Rust is an amazing programming language".to_vec(),
    checksum: *b"00",
}.is_valid(), false);
assert_eq!(UncheckedPacket {
    kind: Kind::Packet,
    data: b"Rust is an amazing programming language".to_vec(),
    checksum: *b"ZZ",
}.is_valid(), false);
assert_eq!(UncheckedPacket {
    kind: Kind::Packet,
    data: b"Rust is an amazing programming language".to_vec(),
    checksum: *b"C7",
}.is_valid(), true);

Source

pub fn encode<W>(&self, w: &mut W) -> Result<()>
where W: Write,

Encode the packet into a long binary string, written to a writer of choice. You can receive a Vec by taking advantage of the fact that they implement io::Write:

let mut encoded = Vec::new();
UncheckedPacket {
    kind: Kind::Packet,
    data: b"these must be escaped: # $ } *".to_vec(),
    checksum: *b"00",
}.encode(&mut encoded);
assert_eq!(
    encoded,
    b"$these must be escaped: }\x03 }\x04 }] }\x0a#00".to_vec()
);

Currently multiple series repeated characters aren’t shortened, however, this may change at any time and you should not rely on the output of this function being exactly one of multiple representations.

Examples found in repository ?

examples/repl.rs (line 26)

4fn main() -> Result<(), Error> {
5    println!("Listening on port 1337...");
6    let mut server = GdbServer::listen("0.0.0.0:1337")?;
7    println!("Connected!");
8
9    while let Some(packet) = server.next_packet()? {
10        println!(
11            "-> {:?} {:?}",
12            packet.kind,
13            std::str::from_utf8(&packet.data)
14        );
15
16        print!(": ");
17        io::stdout().flush()?;
18        let mut response = String::new();
19        io::stdin().read_line(&mut response)?;
20        if response.ends_with('\n') {
21            response.truncate(response.len() - 1);
22        }
23        let response = CheckedPacket::from_data(Kind::Packet, response.into_bytes());
24
25        let mut bytes = Vec::new();
26        response.encode(&mut bytes).unwrap();
27        println!("<- {:?}", std::str::from_utf8(&bytes));
28
29        server.dispatch(&response)?;
30    }
31
32    println!("EOF");
33    Ok(())
34}