1 //
2 // Copyright 2015 Ettus Research LLC
3 // Copyright 2018 Ettus Research, a National Instruments Company
4 //
5 // SPDX-License-Identifier: GPL-3.0-or-later
6 //
7 
8 #pragma once
9 
10 #include <uhd/config.h>
11 #include <uhd/error.h>
12 
13 #ifdef __cplusplus
14 #include <uhd/types/sensors.hpp>
15 #include <string>
16 
17 struct uhd_sensor_value_t {
18     // No default constructor, so we need a pointer
19     uhd::sensor_value_t* sensor_value_cpp;
20     std::string last_error;
21 };
22 extern "C" {
23 #else
24 struct uhd_sensor_value_t;
25 #endif
26 
27 //! C-level interface for a UHD sensor
28 /*!
29  * See uhd::sensor_value_t for more details.
30  *
31  * NOTE: Using a handle before calling a make function will result in undefined behavior.
32  */
33 typedef struct uhd_sensor_value_t* uhd_sensor_value_handle;
34 
35 //! Sensor value types
36 typedef enum {
37     UHD_SENSOR_VALUE_BOOLEAN = 98,
38     UHD_SENSOR_VALUE_INTEGER = 105,
39     UHD_SENSOR_VALUE_REALNUM = 114,
40     UHD_SENSOR_VALUE_STRING  = 115
41 } uhd_sensor_value_data_type_t;
42 
43 //! Make an empty UHD sensor value.
44 /*!
45  * The purpose of this call is to populate the handle with a valid sensor value
46  * object. Querying this object will always yield 'false'. Typically, this
47  * sensor value object will never be used, but it will allow the handle object
48  * to be used with sensor functions later on.
49  *
50  * \param h the sensor handle in which to place sensor
51  * \returns UHD error code
52  */
53 UHD_API uhd_error uhd_sensor_value_make(
54     uhd_sensor_value_handle* h
55 );
56 
57 //! Make a UHD sensor from a boolean.
58 /*!
59  * \param h the sensor handle in which to place sensor
60  * \param name sensor name
61  * \param value sensor value
62  * \param utrue string representing "true"
63  * \param ufalse string representing "false"
64  * \returns UHD error code
65  */
66 UHD_API uhd_error uhd_sensor_value_make_from_bool(
67     uhd_sensor_value_handle* h,
68     const char* name,
69     bool value,
70     const char* utrue,
71     const char* ufalse
72 );
73 
74 //! Make a UHD sensor from an integer.
75 /*!
76  * \param h the sensor value in which to place sensor
77  * \param name sensor name
78  * \param value sensor value
79  * \param unit sensor unit
80  * \param formatter printf-style format string for value string
81  * \returns UHD error code
82  */
83 UHD_API uhd_error uhd_sensor_value_make_from_int(
84     uhd_sensor_value_handle* h,
85     const char* name,
86     int value,
87     const char* unit,
88     const char* formatter
89 );
90 
91 //! Make a UHD sensor from a real number.
92 /*!
93  * \param h the sensor value in which to place sensor
94  * \param name sensor name
95  * \param value sensor value
96  * \param unit sensor unit
97  * \param formatter printf-style format string for value string
98  * \returns UHD error code
99  */
100 UHD_API uhd_error uhd_sensor_value_make_from_realnum(
101     uhd_sensor_value_handle* h,
102     const char* name,
103     double value,
104     const char* unit,
105     const char* formatter
106 );
107 
108 //! Make a UHD sensor from a string.
109 /*!
110  * \param h the sensor value in which to place sensor
111  * \param name sensor name
112  * \param value sensor value
113  * \param unit sensor unit
114  * \returns UHD error code
115  */
116 UHD_API uhd_error uhd_sensor_value_make_from_string(
117     uhd_sensor_value_handle* h,
118     const char* name,
119     const char* value,
120     const char* unit
121 );
122 
123 //! Free the given sensor handle.
124 /*!
125  * Attempting to use the handle after calling this handle will
126  * result in a segmentation fault.
127  */
128 UHD_API uhd_error uhd_sensor_value_free(
129     uhd_sensor_value_handle* h
130 );
131 
132 //! Get the sensor's value as a boolean.
133 UHD_API uhd_error uhd_sensor_value_to_bool(
134     uhd_sensor_value_handle h,
135     bool *value_out
136 );
137 
138 //! Get the sensor's value as an integer.
139 UHD_API uhd_error uhd_sensor_value_to_int(
140     uhd_sensor_value_handle h,
141     int *value_out
142 );
143 
144 //! Get the sensor's value as a real number.
145 UHD_API uhd_error uhd_sensor_value_to_realnum(
146     uhd_sensor_value_handle h,
147     double *value_out
148 );
149 
150 //! Get the sensor's name.
151 /*!
152  * NOTE: This function will overwrite any string in the given
153  * buffer before inserting the sensor name.
154  *
155  * \param h sensor handle
156  * \param name_out string buffer in which to place name
157  * \param strbuffer_len buffer length
158  */
159 UHD_API uhd_error uhd_sensor_value_name(
160     uhd_sensor_value_handle h,
161     char* name_out,
162     size_t strbuffer_len
163 );
164 
165 //! Get the sensor's value.
166 /*!
167  * NOTE: This function will overwrite any string in the given
168  * buffer before inserting the sensor value.
169  *
170  * \param h sensor handle
171  * \param value_out string buffer in which to place value
172  * \param strbuffer_len buffer length
173  */
174 UHD_API uhd_error uhd_sensor_value_value(
175     uhd_sensor_value_handle h,
176     char* value_out,
177     size_t strbuffer_len
178 );
179 
180 //! Get the sensor's unit.
181 /*!
182  * NOTE: This function will overwrite any string in the given
183  * buffer before inserting the sensor unit.
184  *
185  * \param h sensor handle
186  * \param unit_out string buffer in which to place unit
187  * \param strbuffer_len buffer length
188  */
189 UHD_API uhd_error uhd_sensor_value_unit(
190     uhd_sensor_value_handle h,
191     char* unit_out,
192     size_t strbuffer_len
193 );
194 
195 UHD_API uhd_error uhd_sensor_value_data_type(
196     uhd_sensor_value_handle h,
197     uhd_sensor_value_data_type_t *data_type_out
198 );
199 
200 //! Get a pretty-print representation of the given sensor.
201 /*!
202  * NOTE: This function will overwrite any string in the given
203  * buffer before inserting the string.
204  *
205  * \param h sensor handle
206  * \param pp_string_out string buffer in which to place pp_string
207  * \param strbuffer_len buffer length
208  */
209 UHD_API uhd_error uhd_sensor_value_to_pp_string(
210     uhd_sensor_value_handle h,
211     char* pp_string_out,
212     size_t strbuffer_len
213 );
214 
215 //! Get the last error logged by the sensor handle.
216 /*!
217  * NOTE: This function will overwrite any string in the given
218  * buffer before inserting the error string.
219  *
220  * \param h sensor handle
221  * \param error_out string buffer in which to place error
222  * \param strbuffer_len buffer length
223  */
224 UHD_API uhd_error uhd_sensor_value_last_error(
225     uhd_sensor_value_handle h,
226     char* error_out,
227     size_t strbuffer_len
228 );
229 
230 #ifdef __cplusplus
231 }
232 #endif
233