X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=irmp%2Firmp-main-sharedlib.h;h=67e79973446d757abd3d7cc9c7d600521496b05d;hb=7cfa9f7aa2426c617990f3ecfcabed8765aff46c;hp=27f8addb2fa4fe55a1061074c9c6ad5f68bbb138;hpb=53eb681dd5611931b6af949a8c50c22fc65661ac;p=libsigrokdecode.git diff --git a/irmp/irmp-main-sharedlib.h b/irmp/irmp-main-sharedlib.h index 27f8add..67e7997 100644 --- a/irmp/irmp-main-sharedlib.h +++ b/irmp/irmp-main-sharedlib.h @@ -1,91 +1,160 @@ -/*--------------------------------------------------------------------------------------------------------------------------------------------------- - * 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 + * Copyright (c) 2020-2021 Gerhard Sittig * * This program is free software; you can redistribute it and/or modify * 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 +#include #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 State container for a decoder core instance. Opaque to clients. + */ +struct irmp_instance; + +/** + * @brief Allocate a decoder instance. + * + * @returns Reference to the allocated instance state. + */ +IRMP_DLLEXPORT struct irmp_instance *irmp_instance_alloc(void); + +/** + * @brief Release a decoder instance. + * + * @param[in] state Reference to the instance's state. */ -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; +IRMP_DLLEXPORT void irmp_instance_free(struct irmp_instance *state); +/** + * @brief Get the client ID of an IRMP decoder core instance. + */ +IRMP_DLLEXPORT size_t irmp_instance_id(struct irmp_instance *state); /** - * 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 Acquire a decoder instance's lock. + * + * @param[in] state Reference to the instance's state. + * @param[in] wait Whether to block until the lock is acquired. + * + * @returns 0 upon success, non-zero upon failure */ -IRMP_DLLEXPORT uint32_t IRMP_GetSampleRate(void); +IRMP_DLLEXPORT int irmp_instance_lock(struct irmp_instance *state, int wait); /** - * Resets the internal state of the detector - * This has to be called before start processing data. + * @brief Release a decoder instance's lock. + * + * @param[in] state Reference to the instance's state. + * + * @returns 0 upon success, non-zero upon failure */ -IRMP_DLLEXPORT void IRMP_Reset(void); +IRMP_DLLEXPORT void irmp_instance_unlock(struct irmp_instance *state); /** - * 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 IR decoder result data at the library's public API. */ -IRMP_DLLEXPORT uint32_t IRMP_AddSample(const uint8_t i_sample); +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) +#define IRMP_DATA_FLAG_RELEASE (1 << 1) +/** + * @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_get_sample_rate(void); /** - * 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 Reset internal decoder state. + * + * This must be called before data processing starts. */ -IRMP_DLLEXPORT IRMP_DataExt IRMP_Detect(const uint8_t* i_buff, uint32_t i_len); +IRMP_DLLEXPORT void irmp_reset_state(void); +/** + * @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 int irmp_add_one_sample(int sample); +#if WITH_IRMP_DETECT_BUFFER /** - * If a valid IR frame was detected the provided output structure is filled - * \returns 1 if data was available, 0 else + * @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 uint32_t IRMP_GetData(IRMP_DataExt* o_data); +IRMP_DLLEXPORT struct irmp_result_data irmp_detect_buffer(const uint8_t *buf, size_t len); +#endif -/** returns the the name of the given protocol number */ -IRMP_DLLEXPORT const char* IRMP_GetProtocolName(uint32_t i_protocol); +/** + * @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 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