Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history 
Signed-off-by: Guillaume W. Bres <[email protected]>
  • Loading branch information
@gwbres
gwbres committed Nov 2, 2024
1 parent adb2d1b commit 5a40e6c
Show file tree
Hide file tree
Showing 3 changed files with 27 additions and 53 deletions.
49 changes: 7 additions & 42 deletions binex/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,49 +26,13 @@ Message Decoding
================

Use the BINEX `Decoder` to decode a `Readable` interface streaming
BINEX messages. Decoder exposes open source Message that
it fully interprated:
BINEX messages. Decoder exposes both open source Messages that
were fully interprated and closed source Messages (undisclosed prototypes)
that it cannot interprate:

```rust
use std::fs::File;
use binex::prelude::{OpenSourceDecoder, Error};

let fd = File::open("../test_resources/BIN/mfle20190130.bnx")
.unwrap();

let mut decoder = OpenSourceDecoder::new(fd);

loop {
match decoder.next() {
Some(Ok(msg)) => {
// process decoded [Message]
},
Some(Err(e)) => {
// it is possible that some frames may not
// be supported yet.
// Any I/O error should not happen.
},
None => {
// end of stream
break;
},
}
}
```

The [OpenSourceDecoder] will solely decode documented
open source [Message]s that the stream contains.
But BINEX is flexiblea and allows the description of closed
source messages, not realesed to the general public yet.

You can use the [Decoder] object that will decode
both disclosed [Message] and undisclosed frames in form of
[ClosedSourceElement]s of the data stream. It is then up to you
to complete the stream interpretation:

```rust
use std::fs::File;
use binex::prelude::{Decoder, Provider, StreamElement, Error};
use binex::prelude::{Decoder, StreamElement, Provider, Error};

let fd = File::open("../test_resources/BIN/mfle20190130.bnx")
.unwrap();
Expand All @@ -88,15 +52,16 @@ loop {
let mid = element.mid;
let mlen = element.mlen;
// now proceed to custom interpratetion
element.interprate(|data| {
element.interprate(&|data| {
match mid {
// process custom mid and custom data
// using undisclosed method
_ => {},
}
});
}
},
Some(Err(e)) => {
Some(Err(e)) => {
// it is possible that some frames may not
// be supported yet.
// Any I/O error should not happen.
Expand Down
4 changes: 4 additions & 0 deletions binex/src/decoder.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -255,6 +255,10 @@ impl<'a, R: Read> Iterator for Decoder<'a, R> {
}
return Some(Err(Error::IncompleteMessage(meta.mlen)));
},
Error::UnknownMessage => {
// panic!("unknown message\nrd_ptr={}\nbuf={:?}", self.rd_ptr, &self.buf[self.rd_ptr-1..self.rd_ptr+4]);
self.rd_ptr += 1;
},
_ => {
// bad content that does not look like valid BINEX.
// This is very inefficient. If returned error would increment
Expand Down
27 changes: 16 additions & 11 deletions binex/src/message/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,32 +86,32 @@ impl Message {
let time_res = TimeResolution::QuarterSecond;

// 1. locate SYNC byte
if let Some(offset) = Self::locate(Constants::FWDSYNC_BE_STANDARD_CRC, buf) {
if let Some(offset) = Self::find(Constants::FWDSYNC_BE_STANDARD_CRC, buf) {
big_endian = true;
sync_off = offset;
} else if let Some(offset) = Self::locate(Constants::FWDSYNC_LE_STANDARD_CRC, buf) {
} else if let Some(offset) = Self::find(Constants::FWDSYNC_LE_STANDARD_CRC, buf) {
sync_off = offset;
big_endian = false;
} else if let Some(offset) = Self::locate(Constants::FWDSYNC_BE_ENHANCED_CRC, buf) {
} else if let Some(offset) = Self::find(Constants::FWDSYNC_BE_ENHANCED_CRC, buf) {
big_endian = true;
enhanced_crc = true;
sync_off = offset;
} else if let Some(offset) = Self::locate(Constants::FWDSYNC_LE_ENHANCED_CRC, buf) {
} else if let Some(offset) = Self::find(Constants::FWDSYNC_LE_ENHANCED_CRC, buf) {
enhanced_crc = true;
sync_off = offset;
} else if let Some(offset) = Self::locate(Constants::REVSYNC_LE_STANDARD_CRC, buf) {
} else if let Some(offset) = Self::find(Constants::REVSYNC_LE_STANDARD_CRC, buf) {
reversed = true;
sync_off = offset;
} else if let Some(offset) = Self::locate(Constants::REVSYNC_BE_STANDARD_CRC, buf) {
} else if let Some(offset) = Self::find(Constants::REVSYNC_BE_STANDARD_CRC, buf) {
reversed = true;
big_endian = true;
sync_off = offset;
} else if let Some(offset) = Self::locate(Constants::REVSYNC_BE_ENHANCED_CRC, buf) {
} else if let Some(offset) = Self::find(Constants::REVSYNC_BE_ENHANCED_CRC, buf) {
reversed = true;
big_endian = true;
enhanced_crc = true;
sync_off = offset;
} else if let Some(offset) = Self::locate(Constants::REVSYNC_LE_ENHANCED_CRC, buf) {
} else if let Some(offset) = Self::find(Constants::REVSYNC_LE_ENHANCED_CRC, buf) {
reversed = true;
enhanced_crc = true;
sync_off = offset;
Expand Down Expand Up @@ -144,6 +144,11 @@ impl Message {
// 2. parse MID
let (bnxi, mid_1_4) = Self::decode_bnxi(&buf[ptr..], big_endian);
let mid = MessageID::from(bnxi);

if mid == MessageID::Unknown {
return Err(Error::UnknownMessage);
}

ptr += mid_1_4;

// make sure we can parse up to 4 byte MLEN
Expand All @@ -154,9 +159,9 @@ impl Message {
// 3. parse MLEN
let (mlen, mlen_1_4) = Self::decode_bnxi(&buf[ptr..], big_endian);
let mlen = mlen as usize;
// println!("mlen={}", mlen);
//println!("mid={:?}/mlen={}/ptr={}", mid, mlen, ptr);

if buf_len - ptr < mlen {
if ptr + mlen > buf_len {
// buffer does not contain complete message!
return Err(Error::IncompleteMessage(mlen));
}
Expand Down Expand Up @@ -325,7 +330,7 @@ impl Message {
}

/// Tries to locate desired byte within buffer
fn locate(to_find: u8, buf: &[u8]) -> Option<usize> {
fn find(to_find: u8, buf: &[u8]) -> Option<usize> {
buf.iter().position(|b| *b == to_find)
}

Expand Down

0 comments on commit 5a40e6c

Please sign in to comment.