-
Notifications
You must be signed in to change notification settings - Fork 2
/
c_serial.h
549 lines (477 loc) · 17.4 KB
/
c_serial.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
/*
Copyright 2016 rm5248
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
*/
#ifndef C_SERIAL_H
#define C_SERIAL_H
/**
* \addtogroup CSerial
* @{
*/
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
#ifdef _WIN32
#ifdef cserial_EXPORTS
#define CSERIAL_EXPORT __declspec( dllexport )
#else
#define CSERIAL_EXPORT __declspec( dllimport )
#endif /* CSERIAL_LIB */
/* Static libraries don't use dllexport/dllimport */
#ifdef CSERIAL_STATIC
#undef CSERIAL_EXPORT
#define CSERIAL_EXPORT
#endif
#include <windows.h>
typedef HANDLE c_serial_handle_t;
typedef DWORD c_serial_errnum_t;
#else
/* Linux/POSIX zone */
#define CSERIAL_EXPORT
typedef int c_serial_handle_t;
typedef int c_serial_errnum_t;
#endif /* _WIN32 */
/*
* Error code definitions
*/
/** Everything OK */
#define CSERIAL_OK 0
/** Generic error */
#define CSERIAL_ERROR_GENERIC -1
/** The port we tried to open is not actually a serial port */
#define CSERIAL_ERROR_NOT_A_SERIAL_PORT -2
/** The port that we tried to open does not exist */
#define CSERIAL_ERROR_NO_SUCH_SERIAL_PORT -3
/** The parameters to cserial_read were incorrect */
#define CSERIAL_ERROR_INCORRECT_READ_PARAMS -4
/** Unable to create new serial port */
#define CSERIAL_ERROR_CANT_CREATE -5
/** No port defined to open */
#define CSERIAL_ERROR_NO_PORT -6
/** Port already open */
#define CSERIAL_ERROR_ALREADY_OPEN -7
/** invalid c_serial_port_t, e.g. it is NULL */
#define CSERIAL_ERROR_INVALID_PORT -8
/** name of the port to open is too long(6 chars on Windows, 255 on POSIX */
#define CSERIAL_ERROR_NAME_TOO_LONG -9
/** Invalid parameters for flow control. This will be returned if the flow
* control and the RTS handling conflict with each other.
*/
#define CSERIAL_ERROR_INVALID_FLOW -10
/** Returned if the specified RTS control type is not available
*/
#define CSERIAL_RTS_TYPE_NOT_AVAILABLE -11
/**
* Serial line flags
*/
#define CSERIAL_LINE_FLAG_CTS ( 0x01 << 0 )
#define CSERIAL_LINE_FLAG_DSR ( 0x01 << 1 )
#define CSERIAL_LINE_FLAG_DTR ( 0x01 << 2 )
#define CSERIAL_LINE_FLAG_RTS ( 0x01 << 3 )
#define CSERIAL_LINE_FLAG_RI ( 0x01 << 4 )
#define CSERIAL_LINE_FLAG_CD ( 0x01 << 5 )
#define CSERIAL_LINE_FLAG_NONE 0x00
#define CSERIAL_LINE_FLAG_ALL ( CSERIAL_LINE_FLAG_CTS | \
CSERIAL_LINE_FLAG_DSR | \
CSERIAL_LINE_FLAG_DTR | \
CSERIAL_LINE_FLAG_RTS | \
CSERIAL_LINE_FLAG_RI | \
CSERIAL_LINE_FLAG_CD )
/**
* Struct representing the control line state.
*/
struct c_serial_control_lines {
/** CD - Carrier Detect */
int cd;
/** CTS - Clear To Send */
int cts;
/** DSR - Data Set Ready */
int dsr;
/** DTR - Data Terminal Ready */
int dtr;
/** RTS - Request To Send */
int rts;
/** Ring Indicator(is the phone ringing?) */
int ri;
};
typedef struct c_serial_control_lines c_serial_control_lines_t;
/**
* Enum for logging callback.
*/
enum CSerial_Log_Level{
CSERIAL_TRACE,
CSERIAL_DEBUG,
CSERIAL_INFO,
CSERIAL_WARNING,
CSERIAL_ERROR
};
/**
* Enum for baud rate
*/
enum CSerial_Baud_Rate {
/** Not supported by Windows */
CSERIAL_BAUD_0 = 0,
/** Not supported by Windows */
CSERIAL_BAUD_50 = 50,
/** Not supported by Windows */
CSERIAL_BAUD_100 = 100,
CSERIAL_BAUD_110 = 110,
/** Not supported by Windows */
CSERIAL_BAUD_134 = 134,
/** Not supported by Windows */
CSERIAL_BAUD_150 = 150,
/** Not supported by Windows */
CSERIAL_BAUD_200 = 200,
CSERIAL_BAUD_300 = 300,
CSERIAL_BAUD_600 = 600,
CSERIAL_BAUD_1200 = 1200,
/** Not supported by Windows */
CSERIAL_BAUD_1800 = 1800,
CSERIAL_BAUD_2400 = 2400,
CSERIAL_BAUD_4800 = 4800,
CSERIAL_BAUD_9600 = 9600,
CSERIAL_BAUD_19200 = 19200,
CSERIAL_BAUD_38400 = 38400,
CSERIAL_BAUD_115200 = 115200,
CSERIAL_BAUD_921600 = 921600
};
enum CSerial_Data_Bits{
CSERIAL_BITS_5 = 5,
CSERIAL_BITS_6,
CSERIAL_BITS_7,
CSERIAL_BITS_8
};
enum CSerial_Stop_Bits{
CSERIAL_STOP_BITS_1 = 1,
CSERIAL_STOP_BITS_2
};
enum CSerial_Parity{
CSERIAL_PARITY_NONE = 0,
CSERIAL_PARITY_ODD,
CSERIAL_PARITY_EVEN
};
enum CSerial_Flow_Control{
CSERIAL_FLOW_NONE = 0,
CSERIAL_FLOW_HARDWARE,
CSERIAL_FLOW_SOFTWARE
};
enum CSerial_RTS_Handling{
/** Do not handle the RTS line */
CSERIAL_RTS_NONE = 0,
/** Use hardware/driver level RTS handling. */
CSERIAL_RTS_HARDWARE,
/** Use software-level RTS handling. This will cause any calls
* to c_serial_write_data to block
*/
CSERIAL_RTS_SOFTWARE,
/** Use the best available RTS handling.
* CSERIAL_RTS_HARDWARE will be used if it is available
*/
CSERIAL_RTS_BEST_AVAILABLE
};
/*
* Opaque type for interfacing with a serial port.
*/
typedef struct c_serial_port c_serial_port_t;
/**
* Logging function pointer type
*/
typedef void (*c_serial_log_function)( enum CSerial_Log_Level logLevel,
const char* logMessage,
const char* fileName,
int lineNumber,
const char* functionName,
c_serial_port_t* port );
/**
* Cerate a new C Serial object with default settings.
*
* @param port A pointer to the pointer that will be filled in with the
* new data.
* @param errnum A pointer to the native error type if extended error
* information is required
* @return CSERIAL_OK or an error code. If there was an error, the port will
* not be valid.
*/
CSERIAL_EXPORT int c_serial_new( c_serial_port_t** port,
c_serial_errnum_t* errnum );
/**
* Close the serial port(if it is not already closed) and free all resources.
* The pointer will be invalid after this call
*/
CSERIAL_EXPORT void c_serial_free( c_serial_port_t* port );
/**
* Close the port associated with this serial port. The port may be opened
* again by calling c_serial_open()
*/
CSERIAL_EXPORT void c_serial_close( c_serial_port_t* port );
/**
* Open the port on the system.
*/
CSERIAL_EXPORT int c_serial_open( c_serial_port_t* port );
/**
* Open the port on the system, optionally keeping all settings.
* If keepSettings is set to 0, acts the same as c_serial_open
*
* @param port The port to open
* @param keepSettings 1 if current serial port settings should be kept,
* 0 otherwise
*/
CSERIAL_EXPORT int c_serial_open_keep_settings( c_serial_port_t* port,
int keepSettings );
/**
* Returns 1 if the port is open, 0 otherwise
*/
CSERIAL_EXPORT int c_serial_is_open( c_serial_port_t* port );
/**
* Set the name of the port to open.
* The value sent is platform-dependent, e.g. COM1 on Windows and /dev/ttyS1
* on Linux and Linux-like systems.
*
* The port name is copied to internal memory and may be freed after.
*/
CSERIAL_EXPORT int c_serial_set_port_name( c_serial_port_t* port,
const char* port_name );
/**
* Get the port name that this serial port represents, e.g. COM1 on Windows
* and /dev/ttyS1 on Linux and Linux-like systems
*/
CSERIAL_EXPORT const char* c_serial_get_port_name( c_serial_port_t* port );
/**
* Set the baud rate of the serial port
*/
CSERIAL_EXPORT int c_serial_set_baud_rate( c_serial_port_t* port,
enum CSerial_Baud_Rate baud );
/**
* Get the baud rate of the serial port. Note that this function returns
* a cached value if the port is not open, otherwise it reads directly
* from the port and returns the proper value.
*/
CSERIAL_EXPORT enum CSerial_Baud_Rate c_serial_get_baud_rate(
c_serial_port_t* port );
/**
* Set the number of data bits.
*/
CSERIAL_EXPORT int c_serial_set_data_bits( c_serial_port_t* port,
enum CSerial_Data_Bits bits );
/**
* Get the number of data bits
*/
CSERIAL_EXPORT enum CSerial_Data_Bits c_serial_get_data_bits(
c_serial_port_t* port );
/**
* Set the number of stop bits
*/
CSERIAL_EXPORT int c_serial_set_stop_bits( c_serial_port_t* port,
enum CSerial_Stop_Bits bits );
/**
* Get the number of stop bits
*/
CSERIAL_EXPORT enum CSerial_Stop_Bits c_serial_get_stop_btis(
c_serial_port_t* port );
/**
* Set the parity
*/
CSERIAL_EXPORT int c_serial_set_parity( c_serial_port_t* port,
enum CSerial_Parity parity );
/**
* Get the parity.
*/
CSERIAL_EXPORT enum CSerial_Parity c_serial_get_parity(
c_serial_port_t* port );
/**
* Set the flow control
*/
CSERIAL_EXPORT int c_serial_set_flow_control( c_serial_port_t* port,
enum CSerial_Flow_Control contol );
/**
* Get the flow control
*/
CSERIAL_EXPORT enum CSerial_Flow_Control c_serial_get_flow_control(
c_serial_port_t* port );
/**
* Write a block of data to the serial port.
* Acts the same as write() in POSIX systems.
*
* @param port The port to write data out to.
* @param data The data to write out to the port.
* @param length How long(in bytes) the data is. Set to the number of bytes written on return.
* @return status code
*/
CSERIAL_EXPORT int c_serial_write_data( c_serial_port_t* port,
void* data,
int* length );
/**
* Read data from the serial port.
* Acts like read() in POSIX systems, except that it will also return the
* state of the serial lines. This function will block for data before it
* returns. If a mask of serial lines to listen to has been set using
* c_serial_set_serial_line_change_flags, then this function may return
* without having read any data into the data buffer.
*
* If data is NULL and lines is non-NULL, but no change_flags have been set,
* this function returns immediately without having read any data.
*
* @param port The port to read data from
* @param data The buffer to write data to. May be NULL if you are only
* interested in listening for serial line changes.
* @param data_length On entry, how long the data is. On exit, how many bytes
* were read.
* @param lines The state of the serial lines on read of data. If waiting for
* the line state to change, cannot be NULL
* @return CSERIAL_OK on success, error code otherwise
*/
CSERIAL_EXPORT int c_serial_read_data( c_serial_port_t* port,
void* data,
int* data_length, int* bytes_remaining,
c_serial_control_lines_t* lines );
/**
* Get the native handle(int or HANDLE) that is used by this serial port.
*
* Note that on Windows, this will return the actual handle used for
* the ReadFile/WriteFile system calls. To get the HANDLE for the
* Event, use c_serial_get_poll_handle()
*/
CSERIAL_EXPORT c_serial_handle_t c_serial_get_native_handle(
c_serial_port_t* port );
/**
* Get the native handle used for a poll()-like function.
* On POSIX systems, this will return the same as
* c_serial_get_native_handle()
*
* On Windows, this will return a HANDLE to an created with the
* CreateEvent system call, which can then be used to listen for changes
* using a function such as MsgWaitForMultipleObjectsEx or
* WaitForSingleObject.
*/
CSERIAL_EXPORT c_serial_handle_t c_serial_get_poll_handle(
c_serial_port_t* port );
/**
* Set the state of the control lines, optionally returning the current
* state of the lines after setting them.
*
* @param port The port to set the line state for.
* @param lines The line state to set. Note that only DTR and RTS can be set.
* @param return_state If true, modify lines on return with the current state
* of the serial lines.
*/
CSERIAL_EXPORT int c_serial_set_control_line( c_serial_port_t* port,
c_serial_control_lines_t* lines,
int return_state );
/**
* Get the current state of the serial lines
*/
CSERIAL_EXPORT int c_serial_get_control_lines( c_serial_port_t* port,
c_serial_control_lines_t* lines );
/**
* Get the number of bytes currently available
*
* @param port The port to get the number of bytes currently available from
* @param available The number of bytes available
* @return CSERIAL_OK or an error code
*/
CSERIAL_EXPORT int c_serial_get_available( c_serial_port_t* port,
int* available );
/**
* Set the serial lines that will cause a return from c_serial_read
*
* @param port The port to set the line bitmask for
* @param flags Bitwise-OR of any CSERIAL_LINE_FLAG_XXX
*/
CSERIAL_EXPORT int c_serial_set_serial_line_change_flags( c_serial_port_t* port,
int flags );
/**
* Get the serial line flags that will cause a return from c_serial_read
*/
CSERIAL_EXPORT int c_serial_get_serial_line_change_flags(
c_serial_port_t* port );
/**
* Set any user data that should be associated with this serial port
*/
CSERIAL_EXPORT void c_serial_set_user_data( c_serial_port_t* port, void* data );
/**
* Get any user data associated with this serial port
*/
CSERIAL_EXPORT void* c_serial_get_user_data( c_serial_port_t* port );
/**
* Get the text of a C Serial error number
*/
CSERIAL_EXPORT const char* c_serial_get_error_string( int errnum );
/**
* Set the log function for a specific serial port
*/
CSERIAL_EXPORT int c_serial_set_log_function( c_serial_port_t* port,
c_serial_log_function func );
/**
* Set the global log function. This function is used if the log function
* for a specified port has not been set.
*/
CSERIAL_EXPORT int c_serial_set_global_log_function(
c_serial_log_function func );
/**
* A simple implementation of a log function which outputs log information
* to stderr.
*/
CSERIAL_EXPORT void c_serial_stderr_log_function(
enum CSerial_Log_Level logLevel,
const char* logMessage,
const char* fileName,
int lineNumber,
const char* functionName,
c_serial_port_t* port );
/**
* Get the last error number associated with this port. This corresponds
* to errno on Linux-like systems, and GetLastError() on Windows.
*/
CSERIAL_EXPORT c_serial_errnum_t c_serial_get_last_native_errnum(
c_serial_port_t* port );
/**
* Get a list of all serial ports that are on the system.
* This must be freed with c_serial_free_serial_ports_list()
*
* @return An array of char* listing all of the serial ports on the system
* e.g. /dev/ttyS1, /dev/ttyS2 on Linux; COM1,COM2 on Windows. This array is
* NULL-terminated.
*/
CSERIAL_EXPORT const char** c_serial_get_serial_ports_list();
/**
* Free the list of serial ports retrieved with c_serial_get_serial_ports
*/
CSERIAL_EXPORT void c_serial_free_serial_ports_list( const char** port_list );
/**
* Set how RTS should be controlled. This is generally used for RS-485
* converters. Note that this logically separate from the flow control, even
* if they both use RTS. That is, if c_serial_set_flow_control() is set with
* HARDWARE flow control, this will override that setting.
*
* Important note regarding setting the RTS control: If the port is not open,
* this function may return CSERIAL_OK if the setting is valid, and upon
* opening the port CSERIAL_RTS_TYPE_NOT_AVAILABLE may be returned.
*
* @param handling How to handle setting the RTS control. HARDWARE indicates
* that we will attempt to use the OS-level way of setting the RTS line.
* SOFTWARE indicates that we will set the RTS line on the library side.
* NONE turns it off.
*/
CSERIAL_EXPORT int c_serial_set_rts_control( c_serial_port_t* port,
enum CSerial_RTS_Handling handling );
/**
* Get the current handling of the RTS line for RS485 handling
*/
CSERIAL_EXPORT enum CSerial_RTS_Handling c_serial_get_rts_control(
c_serial_port_t* port );
/**
* Flush all data.
*/
CSERIAL_EXPORT int c_serial_flush( c_serial_port_t* port );
#ifdef __cplusplus
} /* end extern "C" */
#endif /* __cplusplus */
/** @} */
#endif /* C_SERIAL_H */