irmp/irmp-main-sharedlib.h

   1 /*
   2  * irmp-main-sharedlib.h
   3  *
   4  * Copyright (c) 2009-2019 Frank Meyer - frank(at)fli4l.de
   5  * Copyright (c) 2009-2019 René Staffen - r.staffen(at)gmx.de
   6  * Copyright (c) 2020-2021 Gerhard Sittig <gerhard.sittig@gmx.net>
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  */
  13
  14 #ifndef IRMP_SHAREDLIB_H
  15 #define IRMP_SHAREDLIB_H
  16
  17 #include <stdint.h>
  18 #include <stdlib.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /* Export the public API routines. */
  25 #ifndef IRMP_DLLEXPORT
  26 #  if defined WIN32 && defined _MSC_VER
  27 #    define IRMP_DLLEXPORT __declspec(dllexport)
  28 #  else
  29 #    define IRMP_DLLEXPORT __attribute__((visibility("default")))
  30 #  endif
  31 #endif
  32
  33 /* Part of the library API is optional. */
  34 #define WITH_IRMP_DETECT_BUFFER 0
  35
  36 /**
  37  * @brief State container for a decoder core instance. Opaque to clients.
  38  */
  39 struct irmp_instance;
  40
  41 /**
  42  * @brief Allocate a decoder instance.
  43  *
  44  * @returns Reference to the allocated instance state.
  45  */
  46 IRMP_DLLEXPORT struct irmp_instance *irmp_instance_alloc(void);
  47
  48 /**
  49  * @brief Release a decoder instance.
  50  *
  51  * @param[in] state Reference to the instance's state.
  52  */
  53 IRMP_DLLEXPORT void irmp_instance_free(struct irmp_instance *state);
  54
  55 /**
  56  * @brief Get the client ID of an IRMP decoder core instance.
  57  */
  58 IRMP_DLLEXPORT size_t irmp_instance_id(struct irmp_instance *state);
  59
  60 /**
  61  * @brief Acquire a decoder instance's lock.
  62  *
  63  * @param[in] state Reference to the instance's state.
  64  * @param[in] wait Whether to block until the lock is acquired.
  65  *
  66  * @returns 0 upon success, non-zero upon failure
  67  */
  68 IRMP_DLLEXPORT int irmp_instance_lock(struct irmp_instance *state, int wait);
  69
  70 /**
  71  * @brief Release a decoder instance's lock.
  72  *
  73  * @param[in] state Reference to the instance's state.
  74  *
  75  * @returns 0 upon success, non-zero upon failure
  76  */
  77 IRMP_DLLEXPORT void irmp_instance_unlock(struct irmp_instance *state);
  78
  79 /**
  80  * @brief IR decoder result data at the library's public API.
  81  */
  82 struct irmp_result_data {
  83         uint32_t protocol;      /**!< protocol, e.g. NEC_PROTOCOL */
  84         const char *protocol_name;      /**!< name of the protocol */
  85         uint32_t address;       /**!< address */
  86         uint32_t command;       /**!< command */
  87         uint32_t flags;         /**!< flags currently only repetition (bit 0) */
  88         uint32_t start_sample;  /**!< the sampleindex there the detected command started */
  89         uint32_t end_sample;    /**!< the sampleindex there the detected command ended */
  90 };
  91
  92 #define IRMP_DATA_FLAG_REPETITION       (1 << 0)
  93 #define IRMP_DATA_FLAG_RELEASE          (1 << 1)
  94
  95 /**
  96  * @brief Query the IRMP library's configured sample rate.
  97  *
  98  * The internally used sample rate is a compile time option. Any data
  99  * that is provided at runtime needs to match this rate, or detection
 100  * will fail.
 101  */
 102 IRMP_DLLEXPORT uint32_t irmp_get_sample_rate(void);
 103
 104 /**
 105  * @brief Reset internal decoder state.
 106  *
 107  * This must be called before data processing starts.
 108  */
 109 IRMP_DLLEXPORT void irmp_reset_state(void);
 110
 111 /**
 112  * @brief Feed an individual sample to the detector.
 113  *
 114  * See @ref irmp_get_result_data() for result retrieval when detection
 115  * of an IR frame completes. Make sure @ref irmp_reset_state() was
 116  * called before providing the first sample.
 117  *
 118  * @param[in] sample The pin value to feed to the detector.
 119  *
 120  * @returns Non-zero when an IR frame was detected.
 121  */
 122 IRMP_DLLEXPORT int irmp_add_one_sample(int sample);
 123
 124 #if WITH_IRMP_DETECT_BUFFER
 125 /**
 126  * @brief Process the given buffer until an IR frame is found.
 127  *
 128  * Stops at the first detected IR frame, and returns its data. Subsequent
 129  * calls resume processing at the previously stopped position. Make sure
 130  * @ref irmp_reset_state() was called before the first detect call.
 131  *
 132  * @param[in] buf Pointer to the data buffer.
 133  * @param[in] len Number of samples in the Buffer.
 134  */
 135 IRMP_DLLEXPORT struct irmp_result_data irmp_detect_buffer(const uint8_t *buf, size_t len);
 136 #endif
 137
 138 /**
 139  * @brief Query result data after detection succeeded.
 140  *
 141  * @param[out] data The caller provided result buffer.
 142  *
 143  * @returns Non-zero if data was available, zero otherwise.
 144  */
 145 IRMP_DLLEXPORT int irmp_get_result_data(struct irmp_result_data *data);
 146
 147 /**
 148  * @brief Resolve the protocol identifer to the protocol's name.
 149  *
 150  * @param[in] protocol The numerical identifier.
 151  *
 152  * @returns A pointer to the string literal, or #NULL in case of failure.
 153  */
 154 IRMP_DLLEXPORT const char *irmp_get_protocol_name(uint32_t protocol);
 155
 156 #ifdef __cplusplus
 157 }
 158 #endif
 159
 160 #endif