/** @file set_trends.h
 * @brief Shared GUI trend decoding and GUI v1 GAS subscription payloads.
 * No transport, rendering, allocation or global state. JNI/ctypes call the
 * same exported functions; flags use the existing AA55 bridge ABI.
 */
#ifndef SET_TRENDS_H
#define SET_TRENDS_H
#include "pcan_abi.h"

#ifdef __cplusplus
extern "C" {
#endif

#define SET_TREND_CAN_GAS 1U
#define SET_TREND_CAN_RAW 2U
#define SET_TREND_NO_VALUE INT32_MIN
#define SET_TREND_WATCH_MAX 64U

/** Convert one wire word, without implementation-defined signed casts. */
PCAN_ABI_API int32_t set_trend_word_value(uint16_t word, uint8_t is_signed);

/** Return a decoded value or SET_TREND_NO_VALUE for a nonmatching/invalid frame.
 * GAS requires Route=FROM_DEVICE, exact DeviceType/DeviceID, and an even DLC.
 * TX echoes, RTR and error frames are always ignored. RAW offset is in bytes.
 */
PCAN_ABI_API int32_t set_trend_can_value(
    uint8_t source, uint32_t address, uint8_t device_type, uint8_t device,
    uint8_t byte_offset, uint8_t extended, uint8_t is_signed,
    uint32_t can_id, uint8_t flags, const uint8_t *data, size_t size);

/** Encode period:u16 + count:u16 + addresses[count]:u16, little-endian.
 * A zero period/count is an unsubscribe. Returns 0 on invalid arguments.
 */
PCAN_ABI_API size_t set_trend_watch_request(
    uint16_t period_ms, const uint16_t *addresses, size_t count,
    uint8_t *output, size_t capacity);

/** Accept only an exact acknowledgement of the entire ordered subscription.
 * The device may omit unknown addresses. Partial acceptance must NOT be used:
 * its acknowledgement has no address list, so index-to-address mapping is lost.
 */
PCAN_ABI_API int set_trend_watch_ack(
    const uint8_t *payload, size_t size, uint16_t period_ms, size_t count);

/** Decode timestamp:u32 + count:u16 + words. Returns count, or -1 on error.
 * Timestamp is device-local; GUI plot clocks should use their own monotonic time.
 */
PCAN_ABI_API int set_trend_watch_values(
    const uint8_t *payload, size_t size, uint16_t *words, size_t capacity);

/** Decode the complete GAS_WATCH_DATA payload including its device timestamp.
 * This is the preferred ABI for GUI ports; the older values-only symbol remains
 * available for binary compatibility.
 */
PCAN_ABI_API int set_trend_watch_decode(const uint8_t *payload, size_t size,
    uint32_t *timestamp_ms, uint16_t *words, size_t capacity);

#ifdef __cplusplus
}
#endif
#endif