irmp: rework shared library (style, reliability, TODO items)

Address several style nits in the previous implementation of the PC
library, but keep the core as is to simplify future upstream tracking.

Eliminate camel case identifiers, and in(?)/out prefixes for variables,
only keep s_ for global(?) variables. Fixup whitespace, reduce a little
indentation where appropriate. Separate variable declaration from later
assignments and updates to improve readability. Use C style comments.

Drop initializer values for .bss variables. Decorate the declaration as
well as implementation of routines for symbol export. Improve robustness
of name lookups in the list of known protocols.

Prefer native C language data types in the public API. Normalize data in
the wrapper so that application code need not care. Make the byte buffer
API for IR frame detection optional. The API is limited and overloaded
at the same time, and may need more consideration.

Extend comments in spots which are essential for proper operation, or
which encode non-obvious details of the build system. Control visibility
of public API identifiers on non-Windows platforms, too. Rephrase the
doxygen comments for more formal API documentation. Discuss limitations
in the current implementation. Keep a TODO list in the source code.

1 files changed, 71 insertions, 47 deletions

diff --git a/irmp/irmp-main-sharedlib.h b/irmp/irmp-main-sharedlib.h
index 27f8add..05e7b53 100644
--- a/irmp/irmp-main-sharedlib.h
+++ b/irmp/irmp-main-sharedlib.h
@@ -1,5 +1,5 @@
-/*---------------------------------------------------------------------------------------------------------------------------------------------------
- * irmpharedLib.h
+/*
+ * irmp-main-sharedlib.h
  *
  * Copyright (c) 2009-2019 Frank Meyer - frank(at)fli4l.de
  * Copyright (c) 2009-2019 René Staffen - r.staffen(at)gmx.de
@@ -8,84 +8,108 @@
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version.
- *---------------------------------------------------------------------------------------------------------------------------------------------------
  */
 
-#ifndef IRMP_SHARED_H
-#define IRMP_SHARED_H
+#ifndef IRMP_SHAREDLIB_H
+#define IRMP_SHAREDLIB_H
 
 #include <stdint.h>
+#include <stdlib.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/* Export the public API routines. */
 #ifndef IRMP_DLLEXPORT
-
-#if defined WIN32 && defined _MSC_VER
-# define IRMP_DLLEXPORT __declspec(dllimport)
-#else
-# define IRMP_DLLEXPORT
+#  if defined WIN32 && defined _MSC_VER
+#    define IRMP_DLLEXPORT __declspec(dllexport)
+#  else
+#    define IRMP_DLLEXPORT __attribute__((visibility("default")))
+#  endif
 #endif
-#endif // !IRMP_DLLEXPORT
 
+/* Part of the library API is optional. */
+#define WITH_IRMP_DETECT_BUFFER 0
 
 /**
- * result data
+ * @brief IR decoder result data at the library's public API.
  */
-typedef struct
-{ 
-    uint32_t    protocol;     ///< protocol, e.g. NEC_PROTOCOL
-    const char* protocolName; ///< name of the protocol
-    uint32_t    address;      ///< address
-    uint32_t    command;      ///< command
-    uint32_t    flags;        ///< flags currently only repetition (bit 0)
-    uint32_t    startSample;  ///< the sampleindex there the detected command started
-    uint32_t    endSample;    ///< the sampleindex there the detected command ended
-}  IRMP_DataExt;
-
+struct irmp_result_data {
+	uint32_t protocol;	/**!< protocol, e.g. NEC_PROTOCOL */
+	const char *protocol_name;	/**!< name of the protocol */
+	uint32_t address;	/**!< address */
+	uint32_t command;	/**!< command */
+	uint32_t flags;		/**!< flags currently only repetition (bit 0) */
+	uint32_t start_sample;	/**!< the sampleindex there the detected command started */
+	uint32_t end_sample;	/**!< the sampleindex there the detected command ended */
+};
+
+#define IRMP_DATA_FLAG_REPETITION	(1 << 0)
 
 /**
- * Returns the sample rate for that the irmp library was compiled for.
- * Any data provided has resamble  this sample rate or detection will fail.
+ * @brief Query the IRMP library's configured sample rate.
+ *
+ * The internally used sample rate is a compile time option. Any data
+ * that is provided at runtime needs to match this rate, or detection
+ * will fail.
  */
-IRMP_DLLEXPORT  uint32_t IRMP_GetSampleRate(void);
+IRMP_DLLEXPORT uint32_t irmp_get_sample_rate(void);
 
 /**
- * Resets the internal state of the detector 
- * This has to be called before start processing data.
+ * @brief Reset internal decoder state.
+ *
+ * This must be called before data processing starts.
  */
-IRMP_DLLEXPORT  void IRMP_Reset(void);
+IRMP_DLLEXPORT void irmp_reset_state(void);
 
 /**
- * Feeds a single sample into the detecor.
- * Returns 1 if a ir command was detected.
- * Use IRMP_GetData to retrieve the data.
- * Make sure, that Reset was called before adding first Sample.
+ * @brief Feed an individual sample to the detector.
+ *
+ * See @ref irmp_get_result_data() for result retrieval when detection
+ * of an IR frame completes. Make sure @ref irmp_reset_state() was
+ * called before providing the first sample.
+ *
+ * @param[in] sample The pin value to feed to the detector.
+ *
+ * @returns Non-zero when an IR frame was detected.
  */
-IRMP_DLLEXPORT  uint32_t IRMP_AddSample(const uint8_t i_sample);
-
+IRMP_DLLEXPORT int irmp_add_one_sample(int sample);
 
+#if WITH_IRMP_DETECT_BUFFER
 /**
- * Proceses the given buffer and stops on the first found command and returns it data.
- * Further calls resume the processing at the previously stopped position.
- * Make sure, that Reset was called before first calling Detect.
+ * @brief Process the given buffer until an IR frame is found.
+ *
+ * Stops at the first detected IR frame, and returns its data. Subsequent
+ * calls resume processing at the previously stopped position. Make sure
+ * @ref irmp_reset_state() was called before the first detect call.
+ *
+ * @param[in] buf Pointer to the data buffer.
+ * @param[in] len Number of samples in the Buffer.
  */
-IRMP_DLLEXPORT  IRMP_DataExt IRMP_Detect(const uint8_t* i_buff, uint32_t i_len);
-
+IRMP_DLLEXPORT struct irmp_result_data irmp_detect_buffer(const uint8_t *buf, size_t len);
+#endif
 
 /**
- * If a valid IR frame was detected the provided output structure is filled
- * \returns 1 if data was available, 0 else
+ * @brief Query result data after detection succeeded.
+ *
+ * @param[out] data The caller provided result buffer.
+ *
+ * @returns Non-zero if data was available, zero otherwise.
  */
-IRMP_DLLEXPORT  uint32_t IRMP_GetData(IRMP_DataExt* o_data);
-
-/** returns the the name of the given protocol number */
-IRMP_DLLEXPORT  const char* IRMP_GetProtocolName(uint32_t i_protocol);
+IRMP_DLLEXPORT int irmp_get_result_data(struct irmp_result_data *data);
 
+/**
+ * @brief Resolve the protocol identifer to the protocol's name.
+ *
+ * @param[in] protocol The numerical identifier.
+ *
+ * @returns A pointer to the string literal, or #NULL in case of failure.
+ */
+IRMP_DLLEXPORT const char *irmp_get_protocol_name(uint32_t protocol);
 
 #ifdef __cplusplus
 }
 #endif
 
-#endif // IRMP_SHARED_H
+#endif