rtcm3-ffi 0.1.0

C FFI bindings for the rtcm3 RTCM3 GNSS RTK correction decoder
Documentation
#ifndef RTCM3_H
#define RTCM3_H

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

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

/**
 * Largest number of satellites a single MSM message can describe (the
 * satellite mask is 64 bits wide, per the RTCM3 wire format itself).
 */
#define RTCM3_FFI_MAX_SATELLITES 64

/**
 * Largest number of satellite/signal cells a single MSM message can
 * describe (the cell mask is 64 bits wide, per the RTCM3 wire format
 * itself).
 */
#define RTCM3_FFI_MAX_CELLS 64

/**
 * Error codes returned by [`rtcm3_decode`].
 */
enum Rtcm3FfiError
#if __STDC_VERSION__ >= 202311L
  : uint8_t
#endif // __STDC_VERSION__ >= 202311L
 {
  /**
   * No error.
   */
  RTCM3_FFI_ERROR_OK = 0,
  /**
   * The `buf` pointer was NULL.
   */
  RTCM3_FFI_ERROR_NULL_INPUT = 1,
  /**
   * The frame itself was malformed (bad preamble, wrong length, bad
   * CRC-24Q).
   */
  RTCM3_FFI_ERROR_FRAME = 2,
  /**
   * A bit-level read failed while decoding the message.
   */
  RTCM3_FFI_ERROR_BIT = 3,
  /**
   * The message type is unknown/undecoded.
   */
  RTCM3_FFI_ERROR_MESSAGE = 4,
};
#if __STDC_VERSION__ >= 202311L
typedef enum Rtcm3FfiError Rtcm3FfiError;
#else
typedef uint8_t Rtcm3FfiError;
#endif // __STDC_VERSION__ >= 202311L

/**
 * Opaque handle to a decoded RTCM3 message, owned by the caller until
 * freed with [`rtcm3_message_free`].
 */
typedef struct Rtcm3FfiMessage Rtcm3FfiMessage;

/**
 * Stationary RTK Reference Station ARP (type 1005): the base station's
 * antenna reference point position.
 */
typedef struct Rtcm3StationArp {
  /**
   * Reference station ID (DF003).
   */
  uint16_t reference_station_id;
  /**
   * ITRF realization year (DF021).
   */
  uint8_t itrf_realization_year;
  /**
   * Whether GPS observations are included in this station's stream (DF022).
   */
  bool gps_indicator;
  /**
   * Whether GLONASS observations are included (DF023).
   */
  bool glonass_indicator;
  /**
   * Whether Galileo observations are included (DF024).
   */
  bool galileo_indicator;
  /**
   * Reference-station indicator (DF141).
   */
  bool reference_station_indicator;
  /**
   * Antenna reference point ECEF X, raw units of 0.0001m (DF025).
   */
  int64_t ecef_x_raw;
  /**
   * Single-receiver oscillator indicator (DF142).
   */
  bool single_oscillator_indicator;
  /**
   * Antenna reference point ECEF Y, raw units of 0.0001m (DF026).
   */
  int64_t ecef_y_raw;
  /**
   * Quarter-cycle phase shift indicator (DF364).
   */
  uint8_t quarter_cycle_indicator;
  /**
   * Antenna reference point ECEF Z, raw units of 0.0001m (DF027).
   */
  int64_t ecef_z_raw;
} Rtcm3StationArp;

/**
 * GLONASS Code-Phase Biases (type 1230). Each bias field is only
 * meaningful when its `_present` flag is `true` - the underlying signal
 * wasn't present in the station's stream otherwise, and `_raw` reads `0`.
 */
typedef struct Rtcm3GlonassBias {
  /**
   * Reference station ID (DF003).
   */
  uint16_t reference_station_id;
  /**
   * GLONASS code-phase bias indicator (DF421).
   */
  bool code_phase_bias_indicator;
  /**
   * Whether the L1 C/A bias field is present (DF423).
   */
  bool l1_ca_bias_present;
  /**
   * L1 C/A code-phase bias, raw units of 0.02m, if present.
   */
  int32_t l1_ca_bias_raw;
  /**
   * Whether the L1 P bias field is present (DF424).
   */
  bool l1_p_bias_present;
  /**
   * L1 P code-phase bias, raw units of 0.02m, if present.
   */
  int32_t l1_p_bias_raw;
  /**
   * Whether the L2 C/A bias field is present (DF425).
   */
  bool l2_ca_bias_present;
  /**
   * L2 C/A code-phase bias, raw units of 0.02m, if present.
   */
  int32_t l2_ca_bias_raw;
  /**
   * Whether the L2 P bias field is present (DF426).
   */
  bool l2_p_bias_present;
  /**
   * L2 P code-phase bias, raw units of 0.02m, if present.
   */
  int32_t l2_p_bias_raw;
} Rtcm3GlonassBias;

/**
 * One satellite's data block within a [`Rtcm3GpsMsm7`] message.
 */
typedef struct Rtcm3SatelliteData {
  /**
   * Integer milliseconds in the satellite's rough range (DF397).
   */
  uint8_t rough_range_ms_raw;
  /**
   * Extended satellite information (DF419).
   */
  uint8_t extended_info_raw;
  /**
   * Rough range modulo 1 millisecond, raw units of 2^-10 ms (DF398).
   */
  uint16_t rough_range_mod_raw;
  /**
   * Rough phase range rate, m/s (DF399).
   */
  int16_t rough_phase_range_rate_raw;
} Rtcm3SatelliteData;

/**
 * One satellite/signal cell's data block within a [`Rtcm3GpsMsm7`]
 * message.
 */
typedef struct Rtcm3CellData {
  /**
   * Fine pseudorange, raw units of 2^-29 ms (DF405).
   */
  int32_t fine_pseudorange_raw;
  /**
   * Fine phase range, raw units of 2^-31 ms (DF406).
   */
  int32_t fine_phase_range_raw;
  /**
   * Phase range lock time indicator, extended range/resolution (DF407).
   */
  uint16_t lock_time_raw;
  /**
   * Half-cycle ambiguity indicator (DF420).
   */
  bool half_cycle_ambiguity;
  /**
   * Carrier-to-noise ratio, raw units of 2^-4 dB-Hz (DF408).
   */
  uint16_t cnr_raw;
  /**
   * Fine phase range rate, raw units of 0.0001 m/s (DF404).
   */
  int16_t fine_phase_range_rate_raw;
} Rtcm3CellData;

/**
 * GPS Full Pseudoranges and `PhaseRanges` plus CNR, high resolution
 * (type 1077). `num_satellites`/`num_signals`/`num_cells` say how many
 * entries of `satellites`/`cells` are meaningful; the rest are unused
 * padding, matching the core crate's own mask-derived counts.
 */
typedef struct Rtcm3GpsMsm7 {
  /**
   * Reference station ID (DF003).
   */
  uint16_t reference_station_id;
  /**
   * GPS epoch time (time of week), raw milliseconds (DF004).
   */
  uint32_t gps_epoch_time_tow_ms;
  /**
   * Multiple message bit: more MSM messages follow for this epoch (DF393).
   */
  bool multiple_message_bit;
  /**
   * Issue of data station (DF409).
   */
  uint8_t issue_of_data_station;
  /**
   * Clock steering indicator (DF411).
   */
  uint8_t clock_steering_indicator;
  /**
   * External clock indicator (DF412).
   */
  uint8_t external_clock_indicator;
  /**
   * GNSS divergence-free smoothing indicator (DF417).
   */
  bool smoothing_indicator;
  /**
   * GNSS smoothing interval, raw encoding (DF418).
   */
  uint8_t smoothing_interval_raw;
  /**
   * Satellite mask (DF394).
   */
  uint64_t satellite_mask;
  /**
   * Signal mask (DF395).
   */
  uint32_t signal_mask;
  /**
   * Cell mask (DF396).
   */
  uint64_t cell_mask;
  /**
   * Number of satellites present (popcount of `satellite_mask`).
   */
  uint32_t num_satellites;
  /**
   * Number of signal types present (popcount of `signal_mask`).
   */
  uint32_t num_signals;
  /**
   * Number of satellite/signal cells present (popcount of `cell_mask`).
   */
  uint32_t num_cells;
  /**
   * Per-satellite data blocks, indexed in mask-bit order.
   */
  struct Rtcm3SatelliteData satellites[RTCM3_FFI_MAX_SATELLITES];
  /**
   * Per-cell data blocks, indexed in mask-bit order.
   */
  struct Rtcm3CellData cells[RTCM3_FFI_MAX_CELLS];
} Rtcm3GpsMsm7;

/**
 * Decodes a single RTCM3 frame from the start of `buf` (`len` bytes
 * long). `buf` may contain trailing bytes after the frame (e.g. the
 * start of the next frame in a stream); only the leading frame is
 * parsed.
 *
 * On success, returns a non-NULL handle (free it with
 * [`rtcm3_message_free`] when done) and, if `out_error` is non-NULL,
 * writes [`Rtcm3FfiError::Ok`] through it. On failure, returns NULL and,
 * if `out_error` is non-NULL, writes the reason through it.
 *
 * # Safety
 * `buf` must be NULL or valid for reads of `len` bytes. `out_error` must
 * be NULL or a pointer valid for a single write.
 */
struct Rtcm3FfiMessage *rtcm3_decode(const uint8_t *buf, uintptr_t len, Rtcm3FfiError *out_error);

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

/**
 * The message's RTCM3 message type (DF002, e.g. `1005` for a Stationary
 * RTK Reference Station ARP), or `0xFFFF` for a NULL handle or a variant
 * this header doesn't know about yet.
 *
 * # Safety
 * `msg` must be NULL or a valid, non-freed handle from [`rtcm3_decode`].
 */
uint16_t rtcm3_message_type(const struct Rtcm3FfiMessage *msg);

/**
 * Reads `msg`'s message as a Stationary RTK Reference Station ARP
 * (type 1005) into `out`, returning `true` on a match. Returns `false`
 * without writing to `out` if `msg` is NULL or holds a different message
 * type.
 *
 * # Safety
 * `msg` must be NULL or a valid, non-freed handle from [`rtcm3_decode`].
 * `out` must be a valid write target.
 */
bool rtcm3_message_as_station_arp(const struct Rtcm3FfiMessage *msg, struct Rtcm3StationArp *out);

/**
 * Reads `msg`'s message as a GLONASS Code-Phase Biases message
 * (type 1230) into `out`, returning `true` on a match. Returns `false`
 * without writing to `out` if `msg` is NULL or holds a different message
 * type.
 *
 * # Safety
 * `msg` must be NULL or a valid, non-freed handle from [`rtcm3_decode`].
 * `out` must be a valid write target.
 */
bool rtcm3_message_as_glonass_bias(const struct Rtcm3FfiMessage *msg, struct Rtcm3GlonassBias *out);

/**
 * Reads `msg`'s message as a GPS MSM7 message (type 1077) into `out`,
 * returning `true` on a match. Returns `false` without writing to `out`
 * if `msg` is NULL or holds a different message type.
 *
 * # Safety
 * `msg` must be NULL or a valid, non-freed handle from [`rtcm3_decode`].
 * `out` must be a valid write target.
 */
bool rtcm3_message_as_gps_msm7(const struct Rtcm3FfiMessage *msg, struct Rtcm3GpsMsm7 *out);

/**
 * This crate's version string, as a NUL-terminated C string with static
 * lifetime.
 */
const char *rtcm3_version(void);

#endif  /* RTCM3_H */