/*
 * Copyright (c) 2016-2017 Satlab Aps <satlab@satlab.com>
 * All rights reserved. Do not distribute without permission.
 */

/**
 * @file polaris_adsb_store.h
 *
 * Each received ADS-B message is tagged with a 32-bit sequence number and
 * stored in SDRAM with estimated signal strength in dBFS and a 64-bit
 * timestamp (number of nanoseconds since midnight on January 1st, 1970). The
 * store is a ring buffer and wraps around every 1048576 messages.
 *
 * Frames can be selectively downloaded by their sequence number through the
 * store CSP service, and provides access to the full ADS-B message and
 * metadata.
 *
 * Received frames are passed to a callback function matching
 * sl_polaris_adsb_frame_cb_t() prototype.
 *
 * The example below shows a simple frame callback function that just prints
 * the length and first byte of received frames, and a request_frames()
 * function that requests the last 8 frames from the CSP node on address 23.
 * Error handling has been left out for brevity.
 *
 * @code{.c}
 * static int frameprint_cb(sl_polaris_adsb_store_frame_t *frame, void *arg)
 * {
 *     printf("Got a %u byte frame and the first byte is %02hhx\n",
 *            frame->length, frame->data[0]);
 *     return 0;
 * }
 *
 * void request_frames(void)
 * {
 *      // Prepare bitmap for 8 frames
 *      uint8_t bitmap[SL_POLARIS_ADSB_STORE_BITMAP_SIZE] = {0xff};
 *      // Request from CSP node 23, call callback for each frame
 *      sl_polaris_adsb_store_read(23, 1000, 0, bitmap, frameprint_cb, NULL);
 * }
 * @endcode
 */

#ifndef _SL_POLARIS_ADSB_CLIENT_STORE_H_
#define _SL_POLARIS_ADSB_CLIENT_STORE_H_

#include <unistd.h>
#include <stdint.h>

#include <satlab/polaris_adsb.h>

/**
 * @brief Frame callback function prototype
 *
 * Callback function prototype used by store read function.
 *
 * @param frame Pointer to structure with frame data. The structure data has been
 * converted to host byte order.
 * @param arg Arbitrary data pointer passed from the mirror/read function call.
 * Can be used to pass any additional data required by the callback function.
 *
 * @returns 0 to continue iteration over received frames, or a non-zero value to abort the iteration.
 */
typedef int (*sl_polaris_adsb_frame_cb_t)(sl_polaris_adsb_store_frame_t *frame, void *arg);

/**
 * @brief Request ADS-B frames from store
 *
 * This function requests a number of received ADS-B frames from the store.
 * Frames are selected using a starting sequence number and a bitmap. The last
 * sequence number to be received can be read using the store.seq property or
 * start=0 can be used to request the most recent frames.
 *
 * Frames are requested backwards from start, i.e. the start fields selects the
 * maximum sequence number to request.
 *
 * The bitmap field is used to request selected messages backwards from the
 * start sequence number. If bit n is set, the receiver will send the message
 * with sequence number start - n, i.e. bit 0 must be set to request the
 * message with sequence number start. Bit 0 is the bit immediately after the
 * start field and bit 255 is the last bit in the packet.
 *
 * E.g. to request messages with sequence number 10, 9, 8, 7, 2 and 1 set:
 *
 * start = 10, bitmap = [0xf0, 0xc0, 0x00, 0x00, ..., 0x00]
 *
 * The @p bitmap argument must be SL_POLARIS_ADSB_STORE_BITMAP_SIZE bytes (currently
 * 32, allowing up to 256 frames per request).
 *
 * @param node CSP address of the Polaris node.
 * @param timeout Timeout of the command in milliseconds.
 * @param start Start frame request number. Use 0 to request from most recent frame.
 * @param bitmap Bitmap of frames from start to request.
 * @param cb Frame callback function.
 * @param arg Pointer argument passed to callback function.
 *
 * @returns 0 on success, and a negative error code on error.
 */
int sl_polaris_adsb_store_read(uint8_t node, uint32_t timeout, uint32_t start, uint8_t *bitmap, sl_polaris_adsb_frame_cb_t cb, void *arg);

#endif /* _SL_POLARIS_ADSB_CLIENT_STORE_H_ */
