/**
 * @file qdx_tcp_logic.h
 * @brief Zero-Copy TCP Network Logic and State Machine tailored for MCU
 *
 * Implements connection management (Dual Stream 5511/5512),
 * packet handling, heartbeating, config caching, and callbacks.
 */

#ifndef QDX_TCP_LOGIC_H
#define QDX_TCP_LOGIC_H

#include "qdx_protocol.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Initialize the TCP logic module
 *
 * @param deviceUUID Provide standard UUID for the device.
 * @param authToken Optional auth token for connections.
 * @return 0 on success, < 0 on failure.
 */
int8_t TcpLogic_Init(const uint8_t *deviceUUID, const uint8_t *authToken);

/**
 * @brief Wait for and start non-blocking network connection attempts.
 *
 * It will spawn background threads for Control and Data streams
 * connecting to the server.
 */
void TcpLogic_Start(void);

/**
 * @brief Encapsulate and send a temperature frame without generic memory copy.
 *
 * Uses the pre-filled `TcpTxBuffer_t` (containing image array) to prepend
 * the required nested headers directly into the buffer offset.
 *
 * @param io_buffer The user-allocated buffer containing Image payload starting
 * at HeadOffset
 * @param processMeta Real-time analysis metadata for the image data
 * @param frameType Frame type: 0=LIVE, 1=TRIGGER, 2=MASKED
 * @param is2D 1 for 2D matrix, 0 for 1D array
 * @return 0 successfully sent to transmission queue, < 0 if failed
 */
int8_t
TcpLogic_BuildAndSendTemperatureFrame(TcpTxBuffer_t *io_buffer,
                                      const PreprocessResult_t *processMeta,
                                      uint8_t frameType, uint8_t is2D);

/**
 * @brief Retrieves a distinct copy of the latest active configuration
 * structure.
 *
 * Recommended for safe reads of configuration during offline or fallback
 * scenarios. Requires pointers to pre-allocated Config* structures.
 *
 * @param out_common Required pointer to common config structure.
 * @param out_cfg2d Required pointer to 2d config structure.
 * @param out_cfg1d Required pointer to 1d config structure.
 * @return 0 on success, -1 if no configuration has been stored or received.
 */
int8_t TcpLogic_GetLatestConfig(ConfigCommon_t *out_common,
                                Config2D_t *out_cfg2d, Config1D_t *out_cfg1d);

/**
 * @brief Register configuration parsing event callback.
 *
 * Fired immediately after the host sends a Configuration payload and it is
 * safely cached to the internal registers.
 *
 * @param cb Callable function matching the interface
 */
void TcpLogic_RegisterConfigCallback(ConfigUpdateCallback_t cb);

/**
 * @brief Register remote decision consequence callback (e.g. Reject / Ok
 * processing result).
 *
 * Fired shortly after the host finishes processing a sent 2D or 1D target
 * frame.
 *
 * @param cb Callable function matching the interface
 */
void TcpLogic_RegisterDetectionCallback(DetectionResultCallback_t cb);

/**
 * @brief Callback for when host requests a temperature frame.
 *
 * Fired when the host sends a TYPE_TEMP_FRAME request (typically empty or
 * carrying trigger context). The device should capture an image and reply by
 * calling TcpLogic_BuildAndSendTemperatureFrame.
 *
 * @param is2dRequest Non-zero if request is specifically for 2D frame, zero if
 * for 1D.
 */
typedef void (*TempFrameRequestCallback_t)(uint8_t is2dRequest);

/**
 * @brief Register host temperature frame request callback.
 *
 * @param cb Callable function matching the interface
 */
void TcpLogic_RegisterTempFrameRequestCallback(TempFrameRequestCallback_t cb);

/**
 * @brief Inject configuration directly (for test mode without server).
 *
 * Sets the internal config cache and fires the config callback.
 * Only non-NULL parameters are updated.
 */
void TcpLogic_InjectTestConfig(const ConfigCommon_t *common,
                               const Config2D_t *cfg2d,
                               const Config1D_t *cfg1d);

#ifdef __cplusplus
}
#endif

#endif /* QDX_TCP_LOGIC_H */