libsigrokdecode  unreleased development snapshot
sigrok protocol decoding library
irmp-main-sharedlib.h
Go to the documentation of this file.
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  */
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  */
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  */
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
IRMP_DLLEXPORT void irmp_instance_unlock(struct irmp_instance *state)
Release a decoder instance&#39;s lock.
uint32_t command
!< address
IR decoder result data at the library&#39;s public API.
#define IRMP_DLLEXPORT
uint32_t flags
!< command
uint32_t address
!< name of the protocol
uint32_t start_sample
!< flags currently only repetition (bit 0)
IRMP_DLLEXPORT int irmp_add_one_sample(int sample)
Feed an individual sample to the detector.
IRMP_DLLEXPORT uint32_t irmp_get_sample_rate(void)
Query the IRMP library&#39;s configured sample rate.
uint32_t end_sample
!< the sampleindex there the detected command started
IRMP_DLLEXPORT struct irmp_instance * irmp_instance_alloc(void)
Allocate a decoder instance.
IRMP_DLLEXPORT int irmp_get_result_data(struct irmp_result_data *data)
Query result data after detection succeeded.
IRMP_DLLEXPORT void irmp_reset_state(void)
Reset internal decoder state.
const char * protocol_name
!< protocol, e.g.
IRMP_DLLEXPORT void irmp_instance_free(struct irmp_instance *state)
Release a decoder instance.
IRMP_DLLEXPORT size_t irmp_instance_id(struct irmp_instance *state)
Get the client ID of an IRMP decoder core instance.
IRMP_DLLEXPORT const char * irmp_get_protocol_name(uint32_t protocol)
Resolve the protocol identifer to the protocol&#39;s name.
IRMP_DLLEXPORT int irmp_instance_lock(struct irmp_instance *state, int wait)
Acquire a decoder instance&#39;s lock.