Use constants from public API in implementation to reduce clashes and reuse documentation strings

Author: tstenner

CMakeLists.txt

@@ -97,6 +97,7 @@ endif()
 
 set(headers
 	include/lsl_c.h
+	include/lsl_constants.h
 	include/lsl_cpp.h
 )
 

include/lsl_c.h

@@ -64,86 +64,8 @@ typedef unsigned int uint32_t;
 extern "C" {
 #endif
 
-
-
-/* =========================== */
-/* ==== Defined constants ==== */
-/* =========================== */
-
-/**
-* Constant to indicate that a stream has variable sampling rate.
-*/
-#define LSL_IRREGULAR_RATE 0.0
-
-/**
-* Constant to indicate that a sample has the next successive time stamp.
-* This is an optional optimization to transmit less data per sample.
-* The stamp is then deduced from the preceding one according to the stream's sampling rate 
-* (in the case of an irregular rate, the same time stamp as before will is assumed).
-*/
-#define LSL_DEDUCED_TIMESTAMP -1.0
-
-/**
-* A very large time value (ca. 1 year); can be used in timeouts.
-*/
-#define LSL_FOREVER 32000000.0
-
-/**
-* Constant to indicate that there is no preference about how a data stream shall be chunked for transmission.
-* (can be used for the chunking parameters in the inlet or the outlet).
-*/
-#define LSL_NO_PREFERENCE 0
-
-/**
-* Data format of a channel (each transmitted sample holds an array of channels).
-*/
-typedef enum {
-    cft_float32 = 1,    /* For up to 24-bit precision measurements in the appropriate physical unit */
-                        /* (e.g., microvolts). Integers from -16777216 to 16777216 are represented accurately. */
-    cft_double64 = 2,   /* For universal numeric data as long as permitted by network & disk budget. */
-                        /* The largest representable integer is 53-bit. */
-    cft_string = 3,     /* For variable-length ASCII strings or data blobs, such as video frames, */
-                        /* complex event descriptions, etc. */
-    cft_int32 = 4,      /* For high-rate digitized formats that require 32-bit precision. Depends critically on */
-                        /* meta-data to represent meaningful units. Useful for application event codes or other coded data. */
-    cft_int16 = 5,      /* For very high rate signals (40Khz+) or consumer-grade audio */ 
-                        /* (for professional audio float is recommended). */
-    cft_int8 = 6,       /* For binary signals or other coded data. */
-                        /* Not recommended for encoding string data. */
-    cft_int64 = 7,      /* For now only for future compatibility. Support for this type is not yet exposed in all languages. */
-                        /* Also, some builds of liblsl will not be able to send or receive data of this type. */
-    cft_undefined = 0   /* Can not be transmitted. */
-} lsl_channel_format_t;
-
-/**
-* Post-processing options for stream inlets. 
-*/
-typedef enum {
-	proc_none = 0,			/* No automatic post-processing; return the ground-truth time stamps for manual post-processing */
-							/* (this is the default behavior of the inlet). */
-	proc_clocksync = 1,		/* Perform automatic clock synchronization; equivalent to manually adding the time_correction() value */
-							/* to the received time stamps. */
-	proc_dejitter = 2,		/* Remove jitter from time stamps. This will apply a smoothing algorithm to the received time stamps; */
-							/* the smoothing needs to see a minimum number of samples (30-120 seconds worst-case) until the remaining */
-							/* jitter is consistently below 1ms. */
-	proc_monotonize = 4,	/* Force the time-stamps to be monotonically ascending (only makes sense if timestamps are dejittered). */
-	proc_threadsafe = 8,    /* Post-processing is thread-safe (same inlet can be read from by multiple threads); uses somewhat more CPU. */
-	proc_ALL = 1|2|4|8		/* The combination of all possible post-processing options. */
-} lsl_processing_options_t;
-
-/**
-* Possible error codes.
-*/
-typedef enum {
-    lsl_no_error = 0,           /* No error occurred */
-    lsl_timeout_error = -1,     /* The operation failed due to a timeout. */
-    lsl_lost_error = -2,        /* The stream has been lost. */
-    lsl_argument_error = -3,    /* An argument was incorrectly specified (e.g., wrong format or wrong length). */
-    lsl_internal_error = -4     /* Some other internal error has happened. */
-} lsl_error_code_t;
-
-
-
+// Defined constants
+#include "lsl_constants.h"
 
 /* ===================================================== */
 /* ==== Objects provided by the lab streaming layer ==== */

include/lsl_constants.h

@@ -0,0 +1,108 @@
+#pragma once
+
+/* =========================== */
+/* ==== Defined constants ==== */
+/* =========================== */
+
+//! Constant to indicate that a stream has variable sampling rate.
+#define LSL_IRREGULAR_RATE 0.0
+
+/**
+ * Constant to indicate that a sample has the next successive time stamp.
+ * This is an optional optimization to transmit less data per sample.
+ * The stamp is then deduced from the preceding one according to the stream's sampling rate
+ * (in the case of an irregular rate, the same time stamp as before will is assumed).
+ */
+#define LSL_DEDUCED_TIMESTAMP -1.0
+
+//! A very large time value (ca. 1 year); can be used in timeouts.
+#define LSL_FOREVER 32000000.0
+
+/**
+ * Constant to indicate that there is no preference about how a data stream shall be chunked for
+ * transmission. (can be used for the chunking parameters in the inlet or the outlet).
+ */
+#define LSL_NO_PREFERENCE 0
+
+//! Data format of a channel (each transmitted sample holds an array of channels).
+typedef enum {
+	/*! For up to 24-bit precision measurements in the appropriate physical unit (e.g., microvolts).
+	 * Integers from -16777216 to 16777216 are represented accurately. */
+	cft_float32 = 1,
+
+	/*! For universal numeric data as long as permitted by network & disk budget.
+	 * The largest representable integer is 53-bit. */
+	cft_double64 = 2,
+
+	/*! For variable-length ASCII strings or data blobs, such as video frames, complex event
+	   descriptions, etc. */
+	cft_string = 3,
+
+	/*! For high-rate digitized formats that require 32-bit precision.
+	 * Depends critically on meta-data to represent meaningful units.
+	 * Useful for application event codes or other coded data. */
+	cft_int32 = 4,
+
+	/*! For very high rate signals (40Khz+) or consumer-grade audio.
+	 * For professional audio float is recommended. */
+	cft_int16 = 5,
+
+	/*! For binary signals or other coded data. Not recommended for encoding string data. */
+	cft_int8 = 6,
+
+	/*! For now only for future compatibility. Support for this type is not yet
+							 exposed in all languages. Also, some builds of liblsl will not be able
+	   to send or receive data of this type.*/
+	cft_int64 = 7,
+
+	//! Can not be transmitted.
+	cft_undefined = 0
+} lsl_channel_format_t;
+
+//! Post-processing options for stream inlets.
+typedef enum {
+	/*! No automatic post-processing; return the ground-truth time stamps for manual
+	 * post-processing. This is the default behavior of the inlet. */
+	proc_none = 0,
+
+	/*! Perform automatic clock synchronization;
+	 * equivalent to manually adding the time_correction() value to the received time stamps. */
+	proc_clocksync = 1,
+
+	/*! Remove jitter from time stamps.<br>
+	 * This will apply a smoothing algorithm to the received time stamps;
+	 * the smoothing needs to see a minimum number of samples (30-120 seconds worst-case)
+	 * until the remaining jitter is consistently below 1ms. */
+	proc_dejitter = 2,
+
+	/*! Force the time-stamps to be monotonically ascending.<br>
+	 * Only makes sense if timestamps are dejittered. */
+	proc_monotonize = 4,
+
+	/*! Post-processing is thread-safe (same inlet can be read from by multiple threads);
+	 * uses somewhat more CPU. */
+	proc_threadsafe = 8,
+
+	//! The combination of all possible post-processing options.
+	proc_ALL = 1 | 2 | 4 | 8
+} lsl_processing_options_t;
+
+/**
+ * Possible error codes.
+ */
+typedef enum {
+	//! No error occurred
+	lsl_no_error = 0,
+
+	//! The operation failed due to a timeout.
+	lsl_timeout_error = -1,
+
+	//! The stream has been lost.
+	lsl_lost_error = -2,
+
+	//! An argument was incorrectly specified (e.g., wrong format or wrong length).
+	lsl_argument_error = -3,
+
+	//! Some other internal error has happened.
+	lsl_internal_error = -4
+} lsl_error_code_t;

src/common.h

@@ -1,6 +1,7 @@
 #ifndef COMMON_H
 #define COMMON_H
 
+#include "../include/lsl_constants.h"
 #include <stdexcept>
 #include <boost/version.hpp>
 #include <string>
@@ -55,53 +56,6 @@ namespace lsl {
 	/// Ensure that LSL is initialized.
 	void ensure_lsl_initialized();
 
-	/// Data format of a channel (each transmitted sample holds an array of channels).
-	enum channel_format_t {
-		cf_float32 = 1,		// For up to 24-bit precision measurements in the appropriate physical unit 
-							// (e.g., microvolts). Integers from -16777216 to 16777216 are represented accurately.
-		cf_double64 = 2,	// For universal numeric data as long as permitted by network & disk budget. 
-							// The largest representable integer is 53-bit.
-		cf_string = 3,		// For variable-length ASCII strings or data blobs, such as video frames,
-							// complex event descriptions, etc.
-		cf_int32 = 4,		// For high-rate digitized formats that require 32-bit precision. Depends critically on 
-							// meta-data to represent meaningful units. Useful for application event codes or other coded data.
-		cf_int16 = 5,		// For very high rate signals (40Khz+) or consumer-grade audio
-							// (for professional audio float is recommended).
-		cf_int8 = 6,		// For binary signals or other coded data. 
-							// Not recommended for encoding string data.
-		cf_int64 = 7,		// For now only for future compatibility. Support for this type is not yet exposed in all languages. 
-							// Also, some builds of liblsl will not be able to send or receive data of this type.
-		cf_undefined = 0	// Can not be transmitted.
-	};
-
-	
-	/// Processing options for the time_postprocessor. 
-	enum processing_options_t {
-		post_none = 0,			// No automatic post-processing; return the ground-truth time stamps for manual post-processing
-								// (this is the default behavior of the inlet).
-		post_clocksync = 1,		// Perform automatic clock synchronization; equivalent to manually adding the time_correction() value
-								// to the received time stamps.
-		post_dejitter = 2,		// Remove jitter from time stamps. This will apply a smoothing algorithm to the received time stamps;
-								// the smoothing needs to see a minimum number of samples (30-120 seconds worst-case) until the remaining 
-								// jitter is consistently below 1ms.
-		post_monotonize = 4,	// Force the time-stamps to be monotonically ascending (only makes sense if timestamps are dejittered).
-		post_threadsafe = 8,    // Post-processing is thread-safe (same inlet can be read from by multiple threads); uses somewhat more CPU.
-		post_ALL = 1|2|4|8		// The combination of all possible post-processing options.
-	};
-
-#ifndef LSL_C_H
-	/**
-	* Possible error codes.
-	*/
-	typedef enum {
-	    lsl_no_error = 0,           /* No error occurred */
-	    lsl_timeout_error = -1,     /* The operation failed due to a timeout. */
-	    lsl_lost_error = -2,        /* The stream has been lost. */
-	    lsl_argument_error = -3,    /* An argument was incorrectly specified (e.g., wrong format or wrong length). */
-	    lsl_internal_error = -4     /* Some other internal error has happened. */
-	} lsl_error_code_t;
-#endif
-
 	/// Exception class that indicates that a stream inlet's source has been irrecoverably lost.
 	class LIBLSL_CPP_API lost_error: public std::runtime_error {
 	public:

src/data_receiver.cpp

@@ -166,7 +166,7 @@ void data_receiver::data_thread() {
 					// transmit request parameters
 					server_stream << "Native-Byte-Order: " << BOOST_BYTE_ORDER << "\r\n";
 					server_stream << "Endian-Performance: " << std::floor(measure_endian_performance()) << "\r\n";
-					server_stream << "Has-IEEE754-Floats: " << (format_ieee754[cf_float32] && format_ieee754[cf_double64]) << "\r\n";
+					server_stream << "Has-IEEE754-Floats: " << (format_ieee754[cft_float32] && format_ieee754[cft_double64]) << "\r\n";
 					server_stream << "Supports-Subnormals: " << format_subnormal[conn_.type_info().channel_format()] << "\r\n";
 					server_stream << "Value-Size: " << conn_.type_info().channel_bytes() << "\r\n"; // 0 for strings
 					server_stream << "Data-Protocol-Version: " << proposed_protocol_version << "\r\n";

src/inlet_connection.cpp

@@ -61,7 +61,7 @@ inlet_connection::inlet_connection(const stream_info_impl &info, bool recover):
 			throw std::invalid_argument("When creating an inlet with a constructed (instead of resolved) stream_info, you must assign at least the name, type or source_id of the desired stream.");
 		if (type_info_.channel_count() == 0)
 			throw std::invalid_argument("When creating an inlet with a constructed (instead of resolved) stream_info, you must assign a nonzero channel count.");
-		if (type_info_.channel_format() == cf_undefined)
+		if (type_info_.channel_format() == cft_undefined)
 			throw std::invalid_argument("When creating an inlet with a constructed (instead of resolved) stream_info, you must assign a channel format.");
 
 		// use the protocol that is specified in the config

src/legacy/legacy_abi.cpp

@@ -17,15 +17,15 @@ using namespace pugi;
 // boilerplate code calling the private implementation
 stream_info::stream_info(): impl_(new stream_info_impl())  {  }
 stream_info::stream_info(const stream_info &rhs): impl_(new stream_info_impl(*rhs.impl_)) {  }
-stream_info::stream_info(const std::string &name, const std::string &type, int channel_count, double nominal_srate, channel_format_t channel_format, const std::string &source_id): impl_(new stream_info_impl(name,type,channel_count,nominal_srate,channel_format,source_id)) { }
+stream_info::stream_info(const std::string &name, const std::string &type, int channel_count, double nominal_srate, lsl_channel_format_t channel_format, const std::string &source_id): impl_(new stream_info_impl(name,type,channel_count,nominal_srate,channel_format,source_id)) { }
 stream_info::stream_info(const stream_info_impl *impl): impl_(new stream_info_impl(*impl)) { }
 stream_info::stream_info(const stream_info_impl &impl): impl_(new stream_info_impl(impl)) { }
 stream_info::~stream_info() { delete impl_; }
 const std::string &stream_info::name() const { return impl_->name(); }
 const std::string &stream_info::type() const { return impl_->type(); }
 int stream_info::channel_count() const { return impl_->channel_count(); }
 double stream_info::nominal_srate() const { return impl_->nominal_srate(); }
-channel_format_t stream_info::channel_format() const { return impl_->channel_format(); }
+lsl_channel_format_t stream_info::channel_format() const { return impl_->channel_format(); }
 const std::string &stream_info::source_id() const { return impl_->source_id(); }
 int stream_info::version() const { return impl_->version(); }
 const std::string &stream_info::uid() const { return impl_->uid(); }

src/legacy/legacy_abi.h

@@ -76,13 +76,13 @@ namespace lsl {
 		* @param channel_count Number of channels per sample. This stays constant for the lifetime of the stream.
 		* @param nominal_srate The sampling rate (in Hz) as advertised by the data source, if regular (otherwise set to IRREGULAR_RATE).
 		* @param channel_format Format/type of each channel. If your channels have different formats, consider supplying 
-		*                       multiple streams or use the largest type that can hold them all (such as cf_double64).
+		*                       multiple streams or use the largest type that can hold them all (such as cft_double64).
 		* @param source_id Unique identifier of the device or source of the data, if available (such as the serial number). 
 		*                  This is critical for system robustness since it allows recipients to recover from failure even after the 
 		*				   serving app, device or computer crashes (just by finding a stream with the same source id on the network again).
 		*				   Therefore, it is highly recommended to always try to provide whatever information can uniquely identify the data source itself.
 		*/
-		stream_info(const std::string &name, const std::string &type, int channel_count=1, double nominal_srate=IRREGULAR_RATE, channel_format_t channel_format=cf_float32, const std::string &source_id=std::string());
+		stream_info(const std::string &name, const std::string &type, int channel_count=1, double nominal_srate=IRREGULAR_RATE, lsl_channel_format_t channel_format=cft_float32, const std::string &source_id=std::string());
 
 		// ========================
 		// === Core Information ===
@@ -128,7 +128,7 @@ namespace lsl {
 		* All channels in a stream have the same format. However, a device might offer multiple time-synched streams 
 		* each with its own format.
 		*/
-		channel_format_t channel_format() const;
+		lsl_channel_format_t channel_format() const;
 
 		/**
 		* Unique identifier of the stream's source, if available.

src/lsl_streaminfo_c.cpp

@@ -14,7 +14,7 @@ LIBLSL_C_API lsl_streaminfo lsl_create_streaminfo(const char *name, const char *
 	try {
 		if (!source_id)
 			source_id = "";
-		return (lsl_streaminfo)new stream_info_impl(name,type,channel_count,nominal_srate,(channel_format_t)channel_format,source_id); 
+		return (lsl_streaminfo)new stream_info_impl(name,type,channel_count,nominal_srate,(lsl_channel_format_t)channel_format,source_id); 
 	} catch(std::exception &e) {
 		std::cerr << "Unexpected error during streaminfo construction: " << e.what() << std::endl;
 		return NULL;
@@ -42,7 +42,7 @@ LIBLSL_C_API const char *lsl_get_type(lsl_streaminfo info) { return ((stream_inf
 LIBLSL_C_API const char *lsl_get_name(lsl_streaminfo info) { return ((stream_info_impl*)info)->name().c_str(); }
 LIBLSL_C_API int32_t lsl_get_channel_count(lsl_streaminfo info) { return ((stream_info_impl*)info)->channel_count(); }
 LIBLSL_C_API double lsl_get_nominal_srate(lsl_streaminfo info) { return ((stream_info_impl*)info)->nominal_srate(); }
-LIBLSL_C_API lsl_channel_format_t lsl_get_channel_format(lsl_streaminfo info) { return (lsl_channel_format_t)((stream_info_impl*)info)->channel_format(); }
+LIBLSL_C_API lsl_channel_format_t lsl_get_channel_format(lsl_streaminfo info) { return ((stream_info_impl*)info)->channel_format(); }
 LIBLSL_C_API const char *lsl_get_source_id(lsl_streaminfo info) { return ((stream_info_impl*)info)->source_id().c_str(); }
 LIBLSL_C_API int32_t lsl_get_version(lsl_streaminfo info) { return ((stream_info_impl*)info)->version(); }
 LIBLSL_C_API double lsl_get_created_at(lsl_streaminfo info) { return ((stream_info_impl*)info)->created_at(); }