Skip to content

v4.0.0
Compare
Choose a tag to compare
@chad-earthscope chad-earthscope released this 07 Aug 00:58
· 22 commits to main since this release
v4.0.0
ac68221

A new major release that seamlessly supports both the new, SeedLink version 4 protocol, and the previous protocol, referred to in this project as version 3.x. The protocol version will automatically be selected during negotiation and the library will, in most cases, adapt user-input as needed for the protocol needs.

Key features of SeedLink v4 include:

  • Optional use of TLS (SSL) for encrypted connections and a default port to use for TLS-based connections (18500).
  • Optional capability to submit authentication credentials. The specification identifies user-password and JWT mechanisms, and allows for others to be added in the future.
  • Ability to transfer different payload types, with identifiers for miniSEED versions 2 and 3, and allowing for future additions.
  • Ability to use wildcards in station ID patterns.

This release supports all of those features.

A number of API changes were made to allow for new features and improve usability.

The full list of changes is as follows, API changes below:

  • Add TLS (SSL) support for encrypted connections. The following environment variables allow for debugging and providing locations of Certificate Authorities to use:
    • LIBSLINK_CA_CERT_FILE = location of a CA cert file to load
    • LIBSLINK_CA_CERT_PATH = path to CA cert files to load
    • LIBSLINK_TLS_DEBUG = TLS debugging output level (integer)
    • LIBSLINK_CERT_UNVERIFIED_OK = Allow unverified certs (for TLS 1.2)
  • Update internal sequence numbers to unsigned 64-bit values.
  • Header contains separate major, minor, patch versioning, thanks @yensoon2!
  • Internal date-time representation now ISO compatible format, conversion to-from legacy SeedLink time format included.
  • Saved state file now using combined station ID syntax instead of separate network and station. Both new and old formats are supported when reading.
  • Stream list file now uses a single station ID instead of separate network and station codes. The old format is NOT supported.
  • Convert v3 selector syntax to v4 when protocol v4 is negotiated.
  • Sort the stream list alphanumerically and from more to less specific regarding wildcards. Ensuring that wildcards in station ID selections are sent after those without wildcards.
  • Add callback function hooks to support caller-provided authorization with v4.
  • Do not interpret the version following SeedLink in the HELLO response as a protocol version, instead parse SLPROTO declarations and default to 3.x if no recognized protocols are found.
  • Add special sequence number value SL_ALLDATASEQEUNCE to request all data from a server for a stream (v4 only). This value is also used internally for v3 uni-station mode.
  • Warning messages for non-support of features for ancient server versions < 3 are removed. Capabilty is not reduced, but the library will not prevent issuing commands against very old servers, which should return errors for unsupported commands.
  • Add sl_payload_summary() and sl_payload_info() for extracting basic details from recognized payload types.
  • Add sl_set_serveraddress() to set the server address, with support for parsing addresses like raw IPv6 enclosed in square brackets.
  • Add sl_set_timewindow() to set time range for the streams.
  • Add sl_set_auth_params() to set authentication parameters.
  • Add sl_set_keepalive(), sl_set_iotimeout(), sl_set_idletimeout() and sl_set_reconnectdelay().
  • Add sl_set_blockingmode(), sl_setdialupmode(), and sl_setbachmode().
  • Add sl_printslcd() to print SLCD details.
  • Add sl_set_allstation_params() to replace sl_setuniparams().
  • Add sl_set_termination_handler() to set signal handlers to trigger connection termination for clean shutdown. Not thread safe.

API changes:

  • sl_newslcd() was replaced by sl_initslcd() and now takes two arguments of client name and version.
  • sl_collect() now takes a buffer provided by the caller as a destination for received packet payload.
  • sl_read_streamlist() is renamed sl_add_streamlist_file() and reads a new format incompatible with the legacy stream list.
  • sl_parse_streamlist() is renamed sl_add_streamlist() and updated to recognized the combination of SeedLink v3 and v4 selections.
  • sl_typestr() renamed sl_formatstr(), now takes a subformat argument.
  • sl_addstream() replaced with sl_add_stream() and now takes a combined station ID instead of separeate net and sta.
  • sl_collect_nb() removed, non-blocking collection can be performed using sl_collect() when SLCD.noblock is set.
  • sl_packettype() and sl_sequence() removed, similar details are provided in an SLpacketinfo strucuture. The historic packet type is no longer derived as the heuristic of blockette discovery is unreliable.
  • sl_checkversion() and sl_checkslcd() removed.
  • sl_openfile() and sl_readline() removed.
  • sl_strparse() removed.
  • sl_gswap3() and all sl_gswapXa() routines removed.
  • Remove all miniSEED specific routines and structures. A few details from miniSEED payloads can be extracted using sl_payload_info() but programs that need more details, or decoded data samples should use a miniSEED parsing library.

Contributors

yensoon2
Assets 2
Loading