// serivce.h - Defines INCP service interface and functions to implement per subsystem.

#pragma once

#include "incp2.h"
#include "messaging.h"
#include "asn1/out/incp_generated.h"



// ==========================
// === RTOS SETUP RELATED ===
// ==========================

/// @brief [DO NOT CALL] Entry point for the receiver task of the INCP service.
/// @param args Not used
/// @remark Do not call directly, instead, pass it to the RTOS during task creation.
void incp_receiver_task(void *args);



// ========================
// === INCP SERVICE API ===
// ========================

/// @brief Sends a datareq message of a given ID to a given subsystem.
/// @param subsystem The subsystem to target.
/// @param id The ID of the variable/report to request.
/// @return ERR_SUCCESS if successfully transmitted, an adequate error otherwise.
err_t incp_async_datareq(endpoint_t subsystem, U32 id);

/// @brief Sends a ping message to a given subsystem.
/// @param subsystem The subsystem to target.
/// @param bytes The data to populate the ping with. Must NULL or contain 32 readable bytes.
/// @return ERR_SUCCESS if successfully transmitted, an adequate error otherwise.
err_t incp_async_ping(endpoint_t subsystem, uint8_t *bytes);



// ==================================
// === TO IMPLEMENT PER SUBSYSTEM ===
// ==================================

/// @brief Implement this function to send (through whatever means, that's a you problem) the given buffer to a given
///        destination. 
/// @param destination Where to send the buffer.
/// @param buf The buffer to send.
/// @param size The length of the data in the buffer.
/// @return ERR_SUCCESS if successful, an adequate error otherwise.
/// @remark Do not __attribute__((weak)) to force linker error.
err_t impl_transmit(endpoint_t destination, void *buf, size_t size);

/// @brief Implement this function to populate msg_buf with the requested variables.
/// @param data The destination to write to. Includes the variable/report id, which should not be changed.
/// @return ERR_SUCCESS if successful, an adequate error otherwise.
/// @remark Do not __attribute__((weak)) to force linker error.
err_t impl_populate_dataret(AnyData *data);



// === Callbacks ===

/// @brief Implement this function as the callback handler to a dataret message. Can (but shoudln't) be empty.
/// @param source The subsystem that send the message.
/// @param data The buffer that holds the data. (See remarks)
/// @remark Do not copy this value by reference, it's validity is only ensured during the execution of this function.
/// @remark Do not __attribute__((weak)) to force linker error if undefined.
void impl_callback_dataret(endpoint_t source, AnyData *data);

/// @brief Implement this function as the callback handler to a pong message. Can (but shoudln't) be empty.
/// @param source The subsystem that send the message.
/// @param pong The received pong. (See remarks)
/// @remark Do not copy this value by reference, it's validity is only ensured during the execution of this function.
/// @remark Do not __attribute__((weak)) to force linker error if undefined.
void impl_callback_pong(endpoint_t source, PingMsg *pong);