squitter-ffi 0.1.1

C FFI bindings for the squitter 1090ES/DF17 (ADS-B extended squitter) decoder
Documentation
#ifndef SQUITTER_H
#define SQUITTER_H

/* Generated by cbindgen from crates/squitter-ffi/src/lib.rs. Do not edit by hand: run `cbindgen --config crates/squitter-ffi/cbindgen.toml --crate squitter-ffi --output crates/squitter-ffi/include/squitter.h` and commit the result. */

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

/**
 * Error codes returned by [`squitter_decode_line`].
 */
enum SquitterError
#if __STDC_VERSION__ >= 202311L
  : uint8_t
#endif // __STDC_VERSION__ >= 202311L
 {
  /**
   * No error.
   */
  SQUITTER_ERROR_OK = 0,
  /**
   * The `line` pointer was NULL.
   */
  SQUITTER_ERROR_NULL_INPUT = 1,
  /**
   * `line` was not valid UTF-8.
   */
  SQUITTER_ERROR_INVALID_UTF8 = 2,
  /**
   * The frame itself was malformed (wrong length, bad checksum,
   * unsupported downlink format).
   */
  SQUITTER_ERROR_FRAME = 3,
  /**
   * The `ME` payload was truncated or otherwise malformed at the bit level.
   */
  SQUITTER_ERROR_BIT = 4,
  /**
   * The message type is unknown/undecoded, or a field held an invalid value.
   */
  SQUITTER_ERROR_MESSAGE = 5,
};
#if __STDC_VERSION__ >= 202311L
typedef enum SquitterError SquitterError;
#else
typedef uint8_t SquitterError;
#endif // __STDC_VERSION__ >= 202311L

/**
 * Opaque handle to a decoded ADS-B message, owned by the caller until
 * freed with [`squitter_message_free`].
 */
typedef struct SquitterMessage SquitterMessage;

/**
 * Decodes a single hex-encoded DF17 frame (bare hex or dump1090's
 * `*...;` framing).
 *
 * On success, returns a non-NULL handle (free it with
 * [`squitter_message_free`] when done) and, if `out_error` is non-NULL,
 * writes [`SquitterError::Ok`] through it. On failure, returns NULL and,
 * if `out_error` is non-NULL, writes the reason through it.
 *
 * # Safety
 * `line` must be NULL or a pointer to a NUL-terminated C string valid for
 * reads for the duration of this call. `out_error` must be NULL or a
 * pointer valid for a single `u8`-sized write.
 */
struct SquitterMessage *squitter_decode_line(const char *line, SquitterError *out_error);

/**
 * Frees a message handle returned by [`squitter_decode_line`]. Passing
 * NULL is a no-op.
 *
 * # Safety
 * `msg` must be NULL or a pointer previously returned by
 * [`squitter_decode_line`] that has not already been freed.
 */
void squitter_message_free(struct SquitterMessage *msg);

/**
 * Which message family this handle holds: `1` = identification, `2` =
 * surface position, `3` = airborne position, `4` = airborne velocity, `0`
 * for a NULL handle.
 *
 * # Safety
 * `msg` must be NULL or a valid, non-freed handle from [`squitter_decode_line`].
 */
uint8_t squitter_message_kind(const struct SquitterMessage *msg);

/**
 * The transmitting aircraft's 24-bit ICAO address.
 *
 * # Safety
 * `msg` must be NULL or a valid, non-freed handle from [`squitter_decode_line`].
 */
uint32_t squitter_message_icao_address(const struct SquitterMessage *msg);

/**
 * Reads the aircraft callsign into `buf` as a NUL-terminated string.
 *
 * Returns `true` and fills `buf` if this is an identification message and
 * `buf_len` is large enough (the callsign is always 8 characters or
 * fewer, so a 9-byte buffer always suffices); returns `false` (leaving
 * `buf` untouched) otherwise.
 *
 * # Safety
 * `msg` must be NULL or a valid, non-freed handle from
 * [`squitter_decode_line`]. `buf` must be NULL or valid for writes of
 * `buf_len` bytes.
 */
bool squitter_message_callsign(const struct SquitterMessage *msg, char *buf, uintptr_t buf_len);

/**
 * Reads barometric altitude, in feet, off a message.
 *
 * Returns `true` and writes `*out_feet` if this is an airborne position
 * message with a modern (non-Gillham) barometric altitude; returns
 * `false` otherwise (including for the legacy Gillham encoding or GNSS
 * height - see [`squitter_message_altitude_gnss_meters`]).
 *
 * # Safety
 * `msg` must be NULL or a valid, non-freed handle from
 * [`squitter_decode_line`]. `out_feet` must be a valid pointer to a
 * writable `i32`.
 */
bool squitter_message_altitude_feet(const struct SquitterMessage *msg, int32_t *out_feet);

/**
 * Reads GNSS height, in meters, off a message.
 *
 * Returns `true` and writes `*out_meters` if this is an airborne position
 * message with GNSS height (type codes 20-22); returns `false` otherwise.
 *
 * # Safety
 * `msg` must be NULL or a valid, non-freed handle from
 * [`squitter_decode_line`]. `out_meters` must be a valid pointer to a
 * writable `u16`.
 */
bool squitter_message_altitude_gnss_meters(const struct SquitterMessage *msg, uint16_t *out_meters);

/**
 * Reads the raw CPR-encoded position fields off a message.
 *
 * Returns `true` and writes the outputs (`*out_odd`: `true` = odd-format,
 * `false` = even-format; `*out_lat_cpr`/`*out_lon_cpr`: the raw 17-bit
 * encoded values) if this is a position message (airborne or surface);
 * returns `false` otherwise. These are *not* a resolved
 * latitude/longitude - see the module-level docs.
 *
 * # Safety
 * `msg` must be NULL or a valid, non-freed handle from
 * [`squitter_decode_line`]. `out_odd`, `out_lat_cpr`, and `out_lon_cpr`
 * must each be a valid pointer to writable memory of the matching type.
 */
bool squitter_message_cpr(const struct SquitterMessage *msg,
                          bool *out_odd,
                          uint32_t *out_lat_cpr,
                          uint32_t *out_lon_cpr);

/**
 * Reads ground speed, in knots, off a message.
 *
 * Returns `true` and writes `*out_knots` if this message carries a
 * resolvable ground speed (an airborne velocity message with both
 * east-west and north-south components available, or a surface position
 * message with movement information); returns `false` otherwise.
 *
 * # Safety
 * `msg` must be NULL or a valid, non-freed handle from
 * [`squitter_decode_line`]. `out_knots` must be a valid pointer to a
 * writable `f64`.
 */
bool squitter_message_ground_speed_knots(const struct SquitterMessage *msg, double *out_knots);

/**
 * Reads vertical rate, in feet/minute (positive = climb), off a message.
 *
 * Returns `true` and writes `*out_fpm` if this is an airborne velocity
 * message with a known vertical rate; returns `false` otherwise.
 *
 * # Safety
 * `msg` must be NULL or a valid, non-freed handle from
 * [`squitter_decode_line`]. `out_fpm` must be a valid pointer to a
 * writable `i32`.
 */
bool squitter_message_vertical_rate_fpm(const struct SquitterMessage *msg, int32_t *out_fpm);

/**
 * True airspeed/indicated airspeed heading, in decimal degrees, off an
 * airspeed-subtype airborne velocity message.
 *
 * Returns `true` and writes `*out_degrees` if this is an airborne
 * velocity message reporting airspeed (not ground speed) with a known
 * heading; returns `false` otherwise.
 *
 * # Safety
 * `msg` must be NULL or a valid, non-freed handle from
 * [`squitter_decode_line`]. `out_degrees` must be a valid pointer to a
 * writable `f64`.
 */
bool squitter_message_heading_degrees(const struct SquitterMessage *msg, double *out_degrees);

/**
 * The `squitter` crate version, as a NUL-terminated, statically allocated
 * string (e.g. `"0.1.1"`). Do not free.
 */
const char *squitter_version(void);

#endif  /* SQUITTER_H */