Skip to content

Commit

Permalink
fix up more tinyframe references (#60)
Browse files Browse the repository at this point in the history
  • Loading branch information
charlesnicholson authored Aug 4, 2024
1 parent 643cbc9 commit 4523b95
Show file tree
Hide file tree
Showing 4 changed files with 12 additions and 12 deletions.
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,12 +114,12 @@ if (r != COBS_RET_SUCCESS) { /* handle your error, return / assert, whatever */

If you can guarantee that your payloads are shorter than 254 bytes, then you can use the "tinyframe" API, which lets you both decode and encode in-place in a single buffer. The COBS protocol requires an extra byte at the beginning and end of the payload. If encoding and decoding in-place, it becomes your responsibility to reserve these extra bytes. It's easy to mess this up and just put your own data at byte 0, but your data must start at byte 1. For safety and sanity, `cobs_encode_tinyframe` will error with `COBS_RET_ERR_BAD_PAYLOAD` if the first and last bytes aren't explicitly set to the sentinel value. You have to put them there.

(Note that `64` is an arbitrary size in this example, you can use any size you want up to `COBS_INPLACE_SAFE_BUFFER_SIZE`)
(Note that `64` is an arbitrary size in this example, you can use any size you want up to `COBS_TINYFRAME_SAFE_BUFFER_SIZE`)

```
char buf[64];
buf[0] = COBS_SENTINEL_VALUE; // You have to do this.
buf[63] = COBS_SENTINEL_VALUE; // You have to do this.
buf[0] = COBS_TINYFRAME_SENTINEL_VALUE; // You have to do this.
buf[63] = COBS_TINYFRAME_SENTINEL_VALUE; // You have to do this.
// Now, fill buf[1 .. 63] with whatever data you want.
Expand All @@ -135,7 +135,7 @@ if (result == COBS_RET_SUCCESS) {

`cobs_decode_tinyframe` is also provided and offers byte-layout-parity to `cobs_encode_tinyframe`. This lets you, for example, decode a payload, change some bytes, and re-encode it all in the same buffer:

Accumulate data from your source until you encounter a COBS frame delimiter byte of `0x00`. Once you've got that, call `cobs_decode_inplace` on that region of a buffer to do an in-place decoding. The zeroth and final bytes of your payload will be replaced with the `COBS_SENTINEL_VALUE` bytes that, were you _encoding_ in-place, you would have had to place there anyway.
Accumulate data from your source until you encounter a COBS frame delimiter byte of `0x00`. Once you've got that, call `cobs_decode_inplace` on that region of a buffer to do an in-place decoding. The zeroth and final bytes of your payload will be replaced with the `COBS_TINYFRAME_SENTINEL_VALUE` bytes that, were you _encoding_ in-place, you would have had to place there anyway.

```
char buf[64];
Expand All @@ -145,7 +145,7 @@ unsigned const length = you_fill_buf_with_data(buf);
cobs_ret_t const result = cobs_decode_tinyframe(buf, length);
if (result == COBS_RET_SUCCESS) {
// decoding succeeded, 'buf' bytes 0 and length-1 are COBS_SENTINEL_VALUE.
// decoding succeeded, 'buf' bytes 0 and length-1 are COBS_TINYFRAME_SENTINEL_VALUE.
// your data is in 'buf[1 ... length-2]'
} else {
// decoding failed, look to 'result' for details.
Expand Down
2 changes: 1 addition & 1 deletion cobs.h
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ enum {
COBS_TINYFRAME_SENTINEL_VALUE = 0x5A,

// In-place encodings that fit in a buffer of this size will always succeed.
COBS_INPLACE_SAFE_BUFFER_SIZE = 256
COBS_TINYFRAME_SAFE_BUFFER_SIZE = 256
};

// COBS_ENCODE_MAX
Expand Down
6 changes: 3 additions & 3 deletions tests/test_cobs_decode_tinyframe.cc
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ TEST_CASE("Inplace decoding") {
}

SUBCASE("Safe payload, all zero bytes") {
byte_vec_t buf(COBS_INPLACE_SAFE_BUFFER_SIZE);
byte_vec_t buf(COBS_TINYFRAME_SAFE_BUFFER_SIZE);
std::fill(std::begin(buf), std::end(buf), byte_t{ 0x01 });
buf[buf.size() - 1] = 0x00;
REQUIRE(cobs_decode_vec(buf) == COBS_RET_SUCCESS);
Expand All @@ -77,7 +77,7 @@ TEST_CASE("Inplace decoding") {
}

SUBCASE("Safe payload, no zero bytes") {
byte_vec_t buf(COBS_INPLACE_SAFE_BUFFER_SIZE);
byte_vec_t buf(COBS_TINYFRAME_SAFE_BUFFER_SIZE);
std::iota(std::begin(buf), std::end(buf), byte_t{ 0x00 });
buf[0] = 0xFF;
buf[buf.size() - 1] = 0x00;
Expand Down Expand Up @@ -138,7 +138,7 @@ void fill_encode_inplace(byte_t *inplace, size_t payload_len, byte_t f) {
} // namespace

TEST_CASE("Decode: Inplace == External") {
std::array<byte_t, COBS_INPLACE_SAFE_BUFFER_SIZE> inplace;
std::array<byte_t, COBS_TINYFRAME_SAFE_BUFFER_SIZE> inplace;

SUBCASE("Fill with zeros") {
for (auto i{ 0u }; i < inplace.size() - 2; ++i) {
Expand Down
6 changes: 3 additions & 3 deletions tests/test_cobs_encode_tinyframe.cc
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ TEST_CASE("Inplace encoding") {
}

SUBCASE("Safe payload, all zero bytes") {
byte_vec_t buf(COBS_INPLACE_SAFE_BUFFER_SIZE);
byte_vec_t buf(COBS_TINYFRAME_SAFE_BUFFER_SIZE);
std::fill(std::begin(buf), std::end(buf), byte_t{ 0x00 });
buf[0] = CSV;
buf[buf.size() - 1] = CSV;
Expand All @@ -89,7 +89,7 @@ TEST_CASE("Inplace encoding") {
}

SUBCASE("Safe payload, no zero bytes") {
byte_vec_t buf(COBS_INPLACE_SAFE_BUFFER_SIZE);
byte_vec_t buf(COBS_TINYFRAME_SAFE_BUFFER_SIZE);
std::iota(std::begin(buf), std::end(buf), byte_t{ 0x00 });
buf[0] = CSV;
buf[buf.size() - 1] = CSV;
Expand Down Expand Up @@ -145,7 +145,7 @@ void fill_inplace(byte_t *inplace, size_t payload_len, byte_t f) {
} // namespace

TEST_CASE("Encode: Inplace == External") {
byte_t inplace[COBS_INPLACE_SAFE_BUFFER_SIZE];
byte_t inplace[COBS_TINYFRAME_SAFE_BUFFER_SIZE];

SUBCASE("Fill with zeros") {
for (auto i = 0u; i < sizeof(inplace) - 2; ++i) {
Expand Down

0 comments on commit 4523b95

Please sign in to comment.