3. API

SampleExtInfo

ifw::rtmslib::SampleExtInfo serialises the optional leader extension. It supports three valid layouts only:

  • empty (0 bytes) - no extended info

  • timestamp only (8-byte double, seconds since epoch)

  • full block (timestamp + datatype + width + height + offset-x + offset-y, total SIZE_SAMPLE_EXT_INFO)

Any other combination throws std::runtime_error when packing or unpacking. Inline setters/getters configure the fields, while Pack() and Unpack() move between structured fields and raw byte vectors. GetExtInfoSize() returns the current packed size and is helpful for buffer sizing.

Extended info modes

ifw::rtmslib::ExtendedInfoMode expresses the sender/receiver contract and drives buffer allocation and validation:

  • None - leader carries no extended info

  • TimestampOnly - leader carries only the timestamp

  • BasicImageInfo - leader carries the full block (timestamp + datatype + geometry + offsets)

Use ExtInfoSizeFromMode() to derive the expected byte count and ExtInfoSummary() to produce a human-readable string when logging extended info payloads.

SenderConfig and RtmsSender

rtmslib_llnetio/rtmsSender.hpp exposes ifw::rtmslib::RtmsSender, a thin wrapper around the llnetio UDP, MUDPI and RTMS senders.

Construction requires the source/destination IPs, destination port, bytes-per-pixel, total raw image size, and an optional SenderConfig containing:

  • mtu_size - MTU for packetisation (default 1500)

  • topic_id and component_id - identifiers placed in leader headers

  • simulation - bypasses socket binding when true

  • ext_info_mode - how much extended info to pack into leaders

  • packet_send_delay - optional per-packet pacing delay in microseconds (<= 0 disables); applied as a deadline-based busy-spin, not a sleep

  • ignore_connection_refused - keep retrying when no receiver is listening

SendSample() packs the extended info, performs the handshake (leader + payload packets + trailer) and returns 0 on success. Transport errors raise exceptions; connection-refused conditions are throttled in logs. GetPixelsPerSample() exposes the pixel count derived from the constructor arguments so tooling can slice FITS cubes accordingly.

ReceiverConfig and RtmsReceiver

rtmslib_llnetio/rtmsReceiver.hpp defines ifw::rtmslib::RtmsReceiver, the base class for subscribers. Construction accepts the receiver IP (unicast or multicast), interface name, UDP port, expected datatype, and an optional ReceiverConfig with:

  • rxbuf_size - receive buffer size in bytes (default 16 MiB)

  • topic_id - expected topic identifier

  • mtu_size - expected MTU for validation

  • width / height - expected geometry hints

  • checksum_force_ignore - skip checksum validation when true

  • ext_info_mode - contract for allowed leader extended info size

ReceiveLoop() repeatedly calls ReceiveSample() until StopReceiver() or RequestStop() flips s_execute to false. ReceiveSample() blocks for a caller-provided timeout, decodes SampleExtInfo, fills the payload vector and returns true on success. Derived classes must override HandleSampleUser() to consume payloads; helpers such as GetLostFramesCount() and GetSampleId() expose runtime stats.

Internally the receiver resizes the extended-info buffer when a larger leader block is observed, tracks lost frames and timeouts, and can update its geometry dynamically from the packed extended info when the sender changes image size mid-run.

Logging controls

Setting the RTMSLIB_DEBUG environment variable enables debug logging inside the library (see RTMSLIB_DEBUG constant in rtmslib_llnetio/common.hpp). Connection-refused events are aggregated and throttled to avoid log flooding when a receiver is not yet running.