feat: add stream buffer peek and snapshot API

Signed-off-by: Srikanth Patchava <spatchava@meta.com>

include/stream_buffer_ext.h

@@ -0,0 +1,130 @@
+/*
+ * FreeRTOS Kernel V11.1.0
+ * Copyright (C) 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * https://www.FreeRTOS.org
+ * https://github.com/FreeRTOS
+ */
+
+/**
+ * @file stream_buffer_ext.h
+ * @brief Extended stream buffer operations: peek, snapshot, and inspection
+ *        without consuming data from the buffer.
+ *
+ * These functions are designed to work alongside the core stream_buffer API
+ * and provide read-only inspection capabilities.
+ */
+
+#ifndef STREAM_BUFFER_EXT_H
+#define STREAM_BUFFER_EXT_H
+
+#include "FreeRTOS.h"
+#include "stream_buffer.h"
+
+#if defined( __cplusplus )
+    extern "C" {
+#endif
+
+/**
+ * @brief Opaque snapshot of stream buffer state at a point in time.
+ */
+typedef struct StreamBufferSnapshot
+{
+    size_t xReadableBytes;     /**< Number of bytes available to read. */
+    size_t xWritableBytes;     /**< Number of bytes available to write. */
+    size_t xBufferCapacity;    /**< Total capacity of the buffer. */
+    size_t xHead;              /**< Write index at snapshot time. */
+    size_t xTail;              /**< Read index at snapshot time. */
+    uint8_t ucIsFull;          /**< 1 if buffer was full at snapshot time. */
+    uint8_t ucIsEmpty;         /**< 1 if buffer was empty at snapshot time. */
+} StreamBufferSnapshot_t;
+
+/**
+ * @brief Peek at data in the stream buffer without consuming it.
+ *
+ * Copies up to xBufferLengthBytes from the stream buffer into pvRxData
+ * without advancing the read pointer. The data remains in the buffer
+ * for subsequent peek or receive operations.
+ *
+ * @param[in] xStreamBuffer The handle of the stream buffer.
+ * @param[out] pvRxData Pointer to the buffer into which data is copied.
+ * @param[in] xBufferLengthBytes Maximum number of bytes to peek.
+ *
+ * @return The number of bytes actually copied into pvRxData.
+ */
+size_t xStreamBufferPeek( StreamBufferHandle_t xStreamBuffer,
+                           void * pvRxData,
+                           size_t xBufferLengthBytes );
+
+/**
+ * @brief Peek at data starting from a specific offset within the buffer.
+ *
+ * Similar to xStreamBufferPeek(), but starts reading from xOffset bytes
+ * past the current read pointer. Useful for inspecting data deeper in
+ * the buffer without reading preceding bytes.
+ *
+ * @param[in] xStreamBuffer The handle of the stream buffer.
+ * @param[in] xOffset Byte offset from the current read position.
+ * @param[out] pvRxData Buffer to copy data into.
+ * @param[in] xBufferLengthBytes Maximum bytes to copy.
+ *
+ * @return The number of bytes actually copied. Returns 0 if xOffset
+ *         exceeds the available data.
+ */
+size_t xStreamBufferPeekAt( StreamBufferHandle_t xStreamBuffer,
+                             size_t xOffset,
+                             void * pvRxData,
+                             size_t xBufferLengthBytes );
+
+/**
+ * @brief Take a consistent snapshot of the stream buffer's current state.
+ *
+ * Captures readable/writable byte counts, head/tail positions, and
+ * full/empty status atomically (with respect to single-reader/writer).
+ *
+ * @param[in] xStreamBuffer The handle of the stream buffer.
+ * @param[out] pxSnapshot Pointer to the snapshot structure to fill.
+ *
+ * @return pdTRUE if the snapshot was taken successfully, pdFALSE if
+ *         any parameter is NULL.
+ */
+BaseType_t xStreamBufferSnapshot( StreamBufferHandle_t xStreamBuffer,
+                                   StreamBufferSnapshot_t * pxSnapshot );
+
+/**
+ * @brief Get the number of bytes available to read without consuming them.
+ *
+ * This is equivalent to xStreamBufferBytesAvailable() but implemented
+ * in the extension module for consistency.
+ *
+ * @param[in] xStreamBuffer The handle of the stream buffer.
+ *
+ * @return The number of readable bytes in the buffer.
+ */
+size_t xStreamBufferGetReadableLength( StreamBufferHandle_t xStreamBuffer );
+
+#if defined( __cplusplus )
+    }
+#endif
+
+#endif /* STREAM_BUFFER_EXT_H */