/**
 * 日期: 2026-03-31
 * 作者: coffee
 * 描述: 基于 HMem 的发送缓冲区
 *       默认预留前头空间, 便于上层先构建内容, 下层再补发包前头
 */

#ifndef __H_SEND_BUFFER_H__
#define __H_SEND_BUFFER_H__

#include <stddef.h>
#include <stdint.h>

/**
 * @brief 默认预留的前头空间
 */
#ifndef HSEND_BUFFER_FIRST_OFFSET
#define HSEND_BUFFER_FIRST_OFFSET 30u
#endif

/**
 * @brief 创建发送缓冲区
 * @param size 初始可用数据区大小
 * @return 成功返回数据区指针, 失败返回 NULL
 */
void *HSendBufferGet(size_t size);

/**
 * @brief 调整发送缓冲区当前使用长度
 * @param ptr 发送缓冲区指针
 * @param size 新的当前数据长度(包含已经补上的前头)
 * @return 成功返回新的缓冲区指针, 失败返回 NULL
 */
void *HSendBufferRealloc(void *ptr, size_t size);

/**
 * @brief 往前头追加数据
 * @param ptr 发送缓冲区指针
 * @param data 要写入前头的数据, 传 NULL 时仅预留空间
 * @param size 前头追加长度
 * @return
 *   - 成功返回新的缓冲区指针
 *   - 前头空间不足时返回原指针
 *   - 非法指针返回 NULL
 */
void *HSendBufferAddHead(void *ptr, const void *data, uint8_t size);

/**
 * @brief 增加引用计数
 * @param ptr 发送缓冲区指针
 * @return 成功返回原指针, 失败返回 NULL
 */
void *HSendBufferAddRef(void *ptr);

/**
 * @brief 释放发送缓冲区
 * @param ptr 发送缓冲区指针
 * @return 成功返回1, 失败返回0
 */
uint8_t HSendBufferFree(void *ptr);

/**
 * @brief 判断是否为 HSendBuffer
 * @param ptr 待判断指针
 * @return 是返回1, 否返回0
 */
uint8_t HSendBufferIsValid(const void *ptr);

/**
 * @brief 获取当前剩余前头偏移
 * @param ptr 发送缓冲区指针
 * @return 偏移量, 非法指针返回0
 */
uint8_t HSendBufferGetFrontOffset(const void *ptr);

/**
 * @brief 获取当前前头剩余大小
 * @param ptr 发送缓冲区指针
 * @return 剩余前头大小, 非法指针返回0
 */
uint8_t HSendBufferGetHeadRemainSize(const void *ptr);

#endif // __H_SEND_BUFFER_H__