A collection of Analog Devices drivers for the mbed platform
Embed:
(wiki syntax)
Show/hide line numbers
libserialport.h
00001 /* libserialport.h. Generated from libserialport.h.in by configure. */ 00002 /* 00003 * This file is part of the libserialport project. 00004 * 00005 * Copyright (C) 2013, 2015 Martin Ling <martin-libserialport@earth.li> 00006 * Copyright (C) 2014 Uwe Hermann <uwe@hermann-uwe.de> 00007 * Copyright (C) 2014 Aurelien Jacobs <aurel@gnuage.org> 00008 * 00009 * This program is free software: you can redistribute it and/or modify 00010 * it under the terms of the GNU Lesser General Public License as 00011 * published by the Free Software Foundation, either version 3 of the 00012 * License, or (at your option) any later version. 00013 * 00014 * This program is distributed in the hope that it will be useful, 00015 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00017 * GNU General Public License for more details. 00018 * 00019 * You should have received a copy of the GNU Lesser General Public License 00020 * along with this program. If not, see <http://www.gnu.org/licenses/>. 00021 */ 00022 00023 /** 00024 * @mainpage libserialport API 00025 * 00026 * Introduction 00027 * ============ 00028 * 00029 * libserialport is a minimal library written in C that is intended to take 00030 * care of the OS-specific details when writing software that uses serial ports. 00031 * 00032 * By writing your serial code to use libserialport, you enable it to work 00033 * transparently on any platform supported by the library. 00034 * 00035 * libserialport is an open source project released under the LGPL3+ license. 00036 * 00037 * The library is maintained by the [sigrok](http://sigrok.org/) project. See 00038 * the [libserialport homepage](http://sigrok.org/wiki/Libserialport) for the 00039 * latest information. 00040 * 00041 * Source code is maintained in git at 00042 * [git://sigrok.org/libserialport](http://sigrok.org/gitweb/?p=libserialport.git). 00043 * 00044 * Bugs are tracked at http://sigrok.org/bugzilla/. 00045 * 00046 * The library was conceived and designed by Martin Ling, is maintained by 00047 * Uwe Hermann, and has received contributions from several other developers. 00048 * See the git history for full credits. 00049 * 00050 * API information 00051 * =============== 00052 * 00053 * The API has been designed from scratch. It does not exactly resemble the 00054 * serial API of any particular operating system. Instead it aims to provide 00055 * a set of functions that can reliably be implemented across all operating 00056 * systems. These form a sufficient basis for higher level behaviour to 00057 * be implemented in a platform independent manner. 00058 * 00059 * If you are porting code written for a particular OS, you may find you need 00060 * to restructure things somewhat, or do without some specialised features. 00061 * For particular notes on porting existing code, see @ref Porting. 00062 * 00063 * The following subsections will help explain the principles of the API. 00064 * 00065 * Headers 00066 * ------- 00067 * 00068 * To use libserialport functions in your code, you should include the 00069 * libserialport.h header, i.e. "#include <libserialport.h>". 00070 * 00071 * Namespace 00072 * --------- 00073 * 00074 * All identifiers defined by the public libserialport headers use the prefix 00075 * sp_ (for functions and data types) or SP_ (for macros and constants). 00076 * 00077 * Functions 00078 * --------- 00079 * 00080 * The functions provided by the library are documented in detail in 00081 * the following sections: 00082 * 00083 * - @ref Enumeration (obtaining a list of serial ports on the system) 00084 * - @ref Ports (opening, closing and getting information about ports) 00085 * - @ref Configuration (baud rate, parity, etc.) 00086 * - @ref Signals (modem control lines, breaks, etc.) 00087 * - @ref Data (reading and writing data, and buffer management) 00088 * - @ref Waiting (waiting for ports to be ready, integrating with event loops) 00089 * - @ref Errors (getting error and debugging information) 00090 * 00091 * Data structures 00092 * --------------- 00093 * 00094 * The library defines three data structures: 00095 * 00096 * - @ref sp_port, which represents a serial port. 00097 * See @ref Enumeration. 00098 * - @ref sp_port_config, which represents a port configuration. 00099 * See @ref Configuration. 00100 * - @ref sp_event_set, which represents a set of events. 00101 * See @ref Waiting. 00102 * 00103 * All these structures are allocated and freed by library functions. It is 00104 * the caller's responsibility to ensure that the correct calls are made to 00105 * free allocated structures after use. 00106 * 00107 * Return codes and error handling 00108 * ------------------------------- 00109 * 00110 * Most functions have return type @ref sp_return and can return only four 00111 * possible error values: 00112 * 00113 * - @ref SP_ERR_ARG means that a function was called with invalid 00114 * arguments. This implies a bug in the caller. The arguments passed would 00115 * be invalid regardless of the underlying OS or serial device involved. 00116 * 00117 * - @ref SP_ERR_FAIL means that the OS reported a failure. The error code or 00118 * message provided by the OS can be obtained by calling sp_last_error_code() 00119 * or sp_last_error_message(). 00120 * 00121 * - @ref SP_ERR_SUPP indicates that there is no support for the requested 00122 * operation in the current OS, driver or device. No error message is 00123 * available from the OS in this case. There is either no way to request 00124 * the operation in the first place, or libserialport does not know how to 00125 * do so in the current version. 00126 * 00127 * - @ref SP_ERR_MEM indicates that a memory allocation failed. 00128 * 00129 * All of these error values are negative. 00130 * 00131 * Calls that succeed return @ref SP_OK, which is equal to zero. Some functions 00132 * declared @ref sp_return can also return a positive value for a successful 00133 * numeric result, e.g. sp_blocking_read() or sp_blocking_write(). 00134 * 00135 * An error message is only available via sp_last_error_message() in the case 00136 * where SP_ERR_FAIL was returned by the previous function call. The error 00137 * message returned is that provided by the OS, using the current language 00138 * settings. It is an error to call sp_last_error_code() or 00139 * sp_last_error_message() except after a previous function call returned 00140 * SP_ERR_FAIL. The library does not define its own error codes or messages 00141 * to accompany other return codes. 00142 * 00143 * Thread safety 00144 * ------------- 00145 * 00146 * Certain combinations of calls can be made concurrently, as follows. 00147 * 00148 * - Calls using different ports may always be made concurrently, i.e. 00149 * it is safe for separate threads to handle their own ports. 00150 * 00151 * - Calls using the same port may be made concurrently when one call 00152 * is a read operation and one call is a write operation, i.e. it is safe 00153 * to use separate "reader" and "writer" threads for the same port. See 00154 * below for which operations meet these definitions. 00155 * 00156 * Read operations: 00157 * 00158 * - sp_blocking_read() 00159 * - sp_blocking_read_next() 00160 * - sp_nonblocking_read() 00161 * - sp_input_waiting() 00162 * - sp_flush() with @ref SP_BUF_INPUT only. 00163 * - sp_wait() with @ref SP_EVENT_RX_READY only. 00164 * 00165 * Write operations: 00166 * 00167 * - sp_blocking_write() 00168 * - sp_nonblocking_write() 00169 * - sp_output_waiting() 00170 * - sp_drain() 00171 * - sp_flush() with @ref SP_BUF_OUTPUT only. 00172 * - sp_wait() with @ref SP_EVENT_TX_READY only. 00173 * 00174 * If two calls, on the same port, do not fit into one of these categories 00175 * each, then they may not be made concurrently. 00176 * 00177 * Debugging 00178 * --------- 00179 * 00180 * The library can output extensive tracing and debugging information. The 00181 * simplest way to use this is to set the environment variable 00182 * LIBSERIALPORT_DEBUG to any value; messages will then be output to the 00183 * standard error stream. 00184 * 00185 * This behaviour is implemented by a default debug message handling 00186 * callback. An alternative callback can be set using sp_set_debug_handler(), 00187 * in order to e.g. redirect the output elsewhere or filter it. 00188 * 00189 * No guarantees are made about the content of the debug output; it is chosen 00190 * to suit the needs of the developers and may change between releases. 00191 * 00192 * @anchor Porting 00193 * Porting 00194 * ------- 00195 * 00196 * The following guidelines may help when porting existing OS-specific code 00197 * to use libserialport. 00198 * 00199 * ### Porting from Unix-like systems ### 00200 * 00201 * There are two main differences to note when porting code written for Unix. 00202 * 00203 * The first is that Unix traditionally provides a wide range of functionality 00204 * for dealing with serial devices at the OS level; this is exposed through the 00205 * termios API and dates to the days when serial terminals were common. If your 00206 * code relies on many of these facilities you will need to adapt it, because 00207 * libserialport provides only a raw binary channel with no special handling. 00208 * 00209 * The second relates to blocking versus non-blocking I/O behaviour. In 00210 * Unix-like systems this is normally specified by setting the O_NONBLOCK 00211 * flag on the file descriptor, affecting the semantics of subsequent read() 00212 * and write() calls. 00213 * 00214 * In libserialport, blocking and nonblocking operations are both available at 00215 * any time. If your existing code ѕets O_NONBLOCK, you should use 00216 * sp_nonblocking_read() and sp_nonblocking_write() to get the same behaviour 00217 * as your existing read() and write() calls. If it does not, you should use 00218 * sp_blocking_read() and sp_blocking_write() instead. You may also find 00219 * sp_blocking_read_next() useful, which reproduces the semantics of a blocking 00220 * read() with VTIME = 0 and VMIN = 1 set in termios. 00221 * 00222 * Finally, you should take care if your program uses custom signal handlers. 00223 * The blocking calls provided by libserialport will restart system calls that 00224 * return with EINTR, so you will need to make your own arrangements if you 00225 * need to interrupt blocking operations when your signal handlers are called. 00226 * This is not an issue if you only use the default handlers. 00227 * 00228 * ### Porting from Windows ### 00229 * 00230 * The main consideration when porting from Windows is that there is no 00231 * direct equivalent for overlapped I/O operations. 00232 * 00233 * If your program does not use overlapped I/O, you can simply use 00234 * sp_blocking_read() and sp_blocking_write() as direct equivalents for 00235 * ReadFile() and WriteFile(). You may also find sp_blocking_read_next() 00236 * useful, which reproduces the special semantics of ReadFile() with 00237 * ReadIntervalTimeout and ReadTotalTimeoutMultiplier set to MAXDWORD 00238 * and 0 < ReadTotalTimeoutConstant < MAXDWORD. 00239 * 00240 * If your program makes use of overlapped I/O to continue work while a serial 00241 * operation is in progress, then you can achieve the same results using 00242 * sp_nonblocking_read() and sp_nonblocking_write(). 00243 * 00244 * Generally, overlapped I/O is combined with either waiting for completion 00245 * once there is no more background work to do (using WaitForSingleObject() or 00246 * WaitForMultipleObjects()), or periodically checking for completion with 00247 * GetOverlappedResult(). If the aim is to start a new operation for further 00248 * data once the previous one has completed, you can instead simply call the 00249 * nonblocking functions again with the next data. If you need to wait for 00250 * completion, use sp_wait() to determine when the port is ready to send or 00251 * receive further data. 00252 */ 00253 00254 #ifndef LIBSERIALPORT_LIBSERIALPORT_H 00255 #define LIBSERIALPORT_LIBSERIALPORT_H 00256 00257 #ifdef __cplusplus 00258 extern "C" { 00259 #endif 00260 00261 #include <stddef.h> 00262 00263 /** Return values. */ 00264 enum sp_return { 00265 /** Operation completed successfully. */ 00266 SP_OK = 0, 00267 /** Invalid arguments were passed to the function. */ 00268 SP_ERR_ARG = -1, 00269 /** A system error occurred while executing the operation. */ 00270 SP_ERR_FAIL = -2, 00271 /** A memory allocation failed while executing the operation. */ 00272 SP_ERR_MEM = -3, 00273 /** The requested operation is not supported by this system or device. */ 00274 SP_ERR_SUPP = -4 00275 }; 00276 00277 /** Port access modes. */ 00278 enum sp_mode { 00279 /** Open port for read access. */ 00280 SP_MODE_READ = 1, 00281 /** Open port for write access. */ 00282 SP_MODE_WRITE = 2, 00283 /** Open port for read and write access. @since 0.1.1 */ 00284 SP_MODE_READ_WRITE = 3 00285 }; 00286 00287 /** Port events. */ 00288 enum sp_event { 00289 /** Data received and ready to read. */ 00290 SP_EVENT_RX_READY = 1, 00291 /** Ready to transmit new data. */ 00292 SP_EVENT_TX_READY = 2, 00293 /** Error occurred. */ 00294 SP_EVENT_ERROR = 4 00295 }; 00296 00297 /** Buffer selection. */ 00298 enum sp_buffer { 00299 /** Input buffer. */ 00300 SP_BUF_INPUT = 1, 00301 /** Output buffer. */ 00302 SP_BUF_OUTPUT = 2, 00303 /** Both buffers. */ 00304 SP_BUF_BOTH = 3 00305 }; 00306 00307 /** Parity settings. */ 00308 enum sp_parity { 00309 /** Special value to indicate setting should be left alone. */ 00310 SP_PARITY_INVALID = -1, 00311 /** No parity. */ 00312 SP_PARITY_NONE = 0, 00313 /** Odd parity. */ 00314 SP_PARITY_ODD = 1, 00315 /** Even parity. */ 00316 SP_PARITY_EVEN = 2, 00317 /** Mark parity. */ 00318 SP_PARITY_MARK = 3, 00319 /** Space parity. */ 00320 SP_PARITY_SPACE = 4 00321 }; 00322 00323 /** RTS pin behaviour. */ 00324 enum sp_rts { 00325 /** Special value to indicate setting should be left alone. */ 00326 SP_RTS_INVALID = -1, 00327 /** RTS off. */ 00328 SP_RTS_OFF = 0, 00329 /** RTS on. */ 00330 SP_RTS_ON = 1, 00331 /** RTS used for flow control. */ 00332 SP_RTS_FLOW_CONTROL = 2 00333 }; 00334 00335 /** CTS pin behaviour. */ 00336 enum sp_cts { 00337 /** Special value to indicate setting should be left alone. */ 00338 SP_CTS_INVALID = -1, 00339 /** CTS ignored. */ 00340 SP_CTS_IGNORE = 0, 00341 /** CTS used for flow control. */ 00342 SP_CTS_FLOW_CONTROL = 1 00343 }; 00344 00345 /** DTR pin behaviour. */ 00346 enum sp_dtr { 00347 /** Special value to indicate setting should be left alone. */ 00348 SP_DTR_INVALID = -1, 00349 /** DTR off. */ 00350 SP_DTR_OFF = 0, 00351 /** DTR on. */ 00352 SP_DTR_ON = 1, 00353 /** DTR used for flow control. */ 00354 SP_DTR_FLOW_CONTROL = 2 00355 }; 00356 00357 /** DSR pin behaviour. */ 00358 enum sp_dsr { 00359 /** Special value to indicate setting should be left alone. */ 00360 SP_DSR_INVALID = -1, 00361 /** DSR ignored. */ 00362 SP_DSR_IGNORE = 0, 00363 /** DSR used for flow control. */ 00364 SP_DSR_FLOW_CONTROL = 1 00365 }; 00366 00367 /** XON/XOFF flow control behaviour. */ 00368 enum sp_xonxoff { 00369 /** Special value to indicate setting should be left alone. */ 00370 SP_XONXOFF_INVALID = -1, 00371 /** XON/XOFF disabled. */ 00372 SP_XONXOFF_DISABLED = 0, 00373 /** XON/XOFF enabled for input only. */ 00374 SP_XONXOFF_IN = 1, 00375 /** XON/XOFF enabled for output only. */ 00376 SP_XONXOFF_OUT = 2, 00377 /** XON/XOFF enabled for input and output. */ 00378 SP_XONXOFF_INOUT = 3 00379 }; 00380 00381 /** Standard flow control combinations. */ 00382 enum sp_flowcontrol { 00383 /** No flow control. */ 00384 SP_FLOWCONTROL_NONE = 0, 00385 /** Software flow control using XON/XOFF characters. */ 00386 SP_FLOWCONTROL_XONXOFF = 1, 00387 /** Hardware flow control using RTS/CTS signals. */ 00388 SP_FLOWCONTROL_RTSCTS = 2, 00389 /** Hardware flow control using DTR/DSR signals. */ 00390 SP_FLOWCONTROL_DTRDSR = 3 00391 }; 00392 00393 /** Input signals. */ 00394 enum sp_signal { 00395 /** Clear to send. */ 00396 SP_SIG_CTS = 1, 00397 /** Data set ready. */ 00398 SP_SIG_DSR = 2, 00399 /** Data carrier detect. */ 00400 SP_SIG_DCD = 4, 00401 /** Ring indicator. */ 00402 SP_SIG_RI = 8 00403 }; 00404 00405 /** 00406 * Transport types. 00407 * 00408 * @since 0.1.1 00409 */ 00410 enum sp_transport { 00411 /** Native platform serial port. @since 0.1.1 */ 00412 SP_TRANSPORT_NATIVE, 00413 /** USB serial port adapter. @since 0.1.1 */ 00414 SP_TRANSPORT_USB, 00415 /** Bluetooth serial port adapter. @since 0.1.1 */ 00416 SP_TRANSPORT_BLUETOOTH 00417 }; 00418 00419 /** 00420 * @struct sp_port 00421 * An opaque structure representing a serial port. 00422 */ 00423 struct sp_port; 00424 00425 /** 00426 * @struct sp_port_config 00427 * An opaque structure representing the configuration for a serial port. 00428 */ 00429 struct sp_port_config; 00430 00431 /** 00432 * @struct sp_event_set 00433 * A set of handles to wait on for events. 00434 */ 00435 struct sp_event_set { 00436 /** Array of OS-specific handles. */ 00437 void *handles; 00438 /** Array of bitmasks indicating which events apply for each handle. */ 00439 enum sp_event *masks; 00440 /** Number of handles. */ 00441 unsigned int count; 00442 }; 00443 00444 /** 00445 * @defgroup Enumeration Port enumeration 00446 * 00447 * Enumerating the serial ports of a system. 00448 * 00449 * @{ 00450 */ 00451 00452 /** 00453 * Obtain a pointer to a new sp_port structure representing the named port. 00454 * 00455 * The user should allocate a variable of type "struct sp_port *" and pass a 00456 * pointer to this to receive the result. 00457 * 00458 * The result should be freed after use by calling sp_free_port(). 00459 * 00460 * @param[in] portname The OS-specific name of a serial port. Must not be NULL. 00461 * @param[out] port_ptr If any error is returned, the variable pointed to by 00462 * port_ptr will be set to NULL. Otherwise, it will be set 00463 * to point to the newly allocated port. Must not be NULL. 00464 * 00465 * @return SP_OK upon success, a negative error code otherwise. 00466 * 00467 * @since 0.1.0 00468 */ 00469 enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_ptr); 00470 00471 /** 00472 * Free a port structure obtained from sp_get_port_by_name() or sp_copy_port(). 00473 * 00474 * @param[in] port Pointer to a port structure. Must not be NULL. 00475 * 00476 * @since 0.1.0 00477 */ 00478 void sp_free_port(struct sp_port *port); 00479 00480 /** 00481 * List the serial ports available on the system. 00482 * 00483 * The result obtained is an array of pointers to sp_port structures, 00484 * terminated by a NULL. The user should allocate a variable of type 00485 * "struct sp_port **" and pass a pointer to this to receive the result. 00486 * 00487 * The result should be freed after use by calling sp_free_port_list(). 00488 * If a port from the list is to be used after freeing the list, it must be 00489 * copied first using sp_copy_port(). 00490 * 00491 * @param[out] list_ptr If any error is returned, the variable pointed to by 00492 * list_ptr will be set to NULL. Otherwise, it will be set 00493 * to point to the newly allocated array. Must not be NULL. 00494 * 00495 * @return SP_OK upon success, a negative error code otherwise. 00496 * 00497 * @since 0.1.0 00498 */ 00499 enum sp_return sp_list_ports(struct sp_port ***list_ptr); 00500 00501 /** 00502 * Make a new copy of an sp_port structure. 00503 * 00504 * The user should allocate a variable of type "struct sp_port *" and pass a 00505 * pointer to this to receive the result. 00506 * 00507 * The copy should be freed after use by calling sp_free_port(). 00508 * 00509 * @param[in] port Pointer to a port structure. Must not be NULL. 00510 * @param[out] copy_ptr If any error is returned, the variable pointed to by 00511 * copy_ptr will be set to NULL. Otherwise, it will be set 00512 * to point to the newly allocated copy. Must not be NULL. 00513 * 00514 * @return SP_OK upon success, a negative error code otherwise. 00515 * 00516 * @since 0.1.0 00517 */ 00518 enum sp_return sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr); 00519 00520 /** 00521 * Free a port list obtained from sp_list_ports(). 00522 * 00523 * This will also free all the sp_port structures referred to from the list; 00524 * any that are to be retained must be copied first using sp_copy_port(). 00525 * 00526 * @param[in] ports Pointer to a list of port structures. Must not be NULL. 00527 * 00528 * @since 0.1.0 00529 */ 00530 void sp_free_port_list(struct sp_port **ports); 00531 00532 /** 00533 * @} 00534 * @defgroup Ports Port handling 00535 * 00536 * Opening, closing and querying ports. 00537 * 00538 * @{ 00539 */ 00540 00541 /** 00542 * Open the specified serial port. 00543 * 00544 * @param[in] port Pointer to a port structure. Must not be NULL. 00545 * @param[in] flags Flags to use when opening the serial port. 00546 * 00547 * @return SP_OK upon success, a negative error code otherwise. 00548 * 00549 * @since 0.1.0 00550 */ 00551 enum sp_return sp_open(struct sp_port *port, enum sp_mode flags); 00552 00553 /** 00554 * Close the specified serial port. 00555 * 00556 * @param[in] port Pointer to a port structure. Must not be NULL. 00557 * 00558 * @return SP_OK upon success, a negative error code otherwise. 00559 * 00560 * @since 0.1.0 00561 */ 00562 enum sp_return sp_close(struct sp_port *port); 00563 00564 /** 00565 * Get the name of a port. 00566 * 00567 * The name returned is whatever is normally used to refer to a port on the 00568 * current operating system; e.g. for Windows it will usually be a "COMn" 00569 * device name, and for Unix it will be a device path beginning with "/dev/". 00570 * 00571 * @param[in] port Pointer to a port structure. Must not be NULL. 00572 * 00573 * @return The port name, or NULL if an invalid port is passed. The name 00574 * string is part of the port structure and may not be used after 00575 * the port structure has been freed. 00576 * 00577 * @since 0.1.0 00578 */ 00579 char *sp_get_port_name(const struct sp_port *port); 00580 00581 /** 00582 * Get a description for a port, to present to end user. 00583 * 00584 * @param[in] port Pointer to a port structure. Must not be NULL. 00585 * 00586 * @return The port description, or NULL if an invalid port is passed. 00587 * The description string is part of the port structure and may not 00588 * be used after the port structure has been freed. 00589 * 00590 * @since 0.1.1 00591 */ 00592 char *sp_get_port_description(const struct sp_port *port); 00593 00594 /** 00595 * Get the transport type used by a port. 00596 * 00597 * @param[in] port Pointer to a port structure. Must not be NULL. 00598 * 00599 * @return The port transport type. 00600 * 00601 * @since 0.1.1 00602 */ 00603 enum sp_transport sp_get_port_transport(const struct sp_port *port); 00604 00605 /** 00606 * Get the USB bus number and address on bus of a USB serial adapter port. 00607 * 00608 * @param[in] port Pointer to a port structure. Must not be NULL. 00609 * @param[out] usb_bus Pointer to a variable to store the USB bus. 00610 * Can be NULL (in that case it will be ignored). 00611 * @param[out] usb_address Pointer to a variable to store the USB address. 00612 * Can be NULL (in that case it will be ignored). 00613 * 00614 * @return SP_OK upon success, a negative error code otherwise. 00615 * 00616 * @since 0.1.1 00617 */ 00618 enum sp_return sp_get_port_usb_bus_address(const struct sp_port *port, 00619 int *usb_bus, int *usb_address); 00620 00621 /** 00622 * Get the USB Vendor ID and Product ID of a USB serial adapter port. 00623 * 00624 * @param[in] port Pointer to a port structure. Must not be NULL. 00625 * @param[out] usb_vid Pointer to a variable to store the USB VID. 00626 * Can be NULL (in that case it will be ignored). 00627 * @param[out] usb_pid Pointer to a variable to store the USB PID. 00628 * Can be NULL (in that case it will be ignored). 00629 * 00630 * @return SP_OK upon success, a negative error code otherwise. 00631 * 00632 * @since 0.1.1 00633 */ 00634 enum sp_return sp_get_port_usb_vid_pid(const struct sp_port *port, int *usb_vid, int *usb_pid); 00635 00636 /** 00637 * Get the USB manufacturer string of a USB serial adapter port. 00638 * 00639 * @param[in] port Pointer to a port structure. Must not be NULL. 00640 * 00641 * @return The port manufacturer string, or NULL if an invalid port is passed. 00642 * The manufacturer string is part of the port structure and may not 00643 * be used after the port structure has been freed. 00644 * 00645 * @since 0.1.1 00646 */ 00647 char *sp_get_port_usb_manufacturer(const struct sp_port *port); 00648 00649 /** 00650 * Get the USB product string of a USB serial adapter port. 00651 * 00652 * @param[in] port Pointer to a port structure. Must not be NULL. 00653 * 00654 * @return The port product string, or NULL if an invalid port is passed. 00655 * The product string is part of the port structure and may not be 00656 * used after the port structure has been freed. 00657 * 00658 * @since 0.1.1 00659 */ 00660 char *sp_get_port_usb_product(const struct sp_port *port); 00661 00662 /** 00663 * Get the USB serial number string of a USB serial adapter port. 00664 * 00665 * @param[in] port Pointer to a port structure. Must not be NULL. 00666 * 00667 * @return The port serial number, or NULL if an invalid port is passed. 00668 * The serial number string is part of the port structure and may 00669 * not be used after the port structure has been freed. 00670 * 00671 * @since 0.1.1 00672 */ 00673 char *sp_get_port_usb_serial(const struct sp_port *port); 00674 00675 /** 00676 * Get the MAC address of a Bluetooth serial adapter port. 00677 * 00678 * @param[in] port Pointer to a port structure. Must not be NULL. 00679 * 00680 * @return The port MAC address, or NULL if an invalid port is passed. 00681 * The MAC address string is part of the port structure and may not 00682 * be used after the port structure has been freed. 00683 * 00684 * @since 0.1.1 00685 */ 00686 char *sp_get_port_bluetooth_address(const struct sp_port *port); 00687 00688 /** 00689 * Get the operating system handle for a port. 00690 * 00691 * The type of the handle depends on the operating system. On Unix based 00692 * systems, the handle is a file descriptor of type "int". On Windows, the 00693 * handle is of type "HANDLE". The user should allocate a variable of the 00694 * appropriate type and pass a pointer to this to receive the result. 00695 * 00696 * To obtain a valid handle, the port must first be opened by calling 00697 * sp_open() using the same port structure. 00698 * 00699 * After the port is closed or the port structure freed, the handle may 00700 * no longer be valid. 00701 * 00702 * @warning This feature is provided so that programs may make use of 00703 * OS-specific functionality where desired. Doing so obviously 00704 * comes at a cost in portability. It also cannot be guaranteed 00705 * that direct usage of the OS handle will not conflict with the 00706 * library's own usage of the port. Be careful. 00707 * 00708 * @param[in] port Pointer to a port structure. Must not be NULL. 00709 * @param[out] result_ptr If any error is returned, the variable pointed to by 00710 * result_ptr will have unknown contents and should not 00711 * be used. Otherwise, it will be set to point to the 00712 * OS handle. Must not be NULL. 00713 * 00714 * @return SP_OK upon success, a negative error code otherwise. 00715 * 00716 * @since 0.1.0 00717 */ 00718 enum sp_return sp_get_port_handle(const struct sp_port *port, void *result_ptr); 00719 00720 /** 00721 * @} 00722 * 00723 * @defgroup Configuration Configuration 00724 * 00725 * Setting and querying serial port parameters. 00726 * @{ 00727 */ 00728 00729 /** 00730 * Allocate a port configuration structure. 00731 * 00732 * The user should allocate a variable of type "struct sp_port_config *" and 00733 * pass a pointer to this to receive the result. The variable will be updated 00734 * to point to the new configuration structure. The structure is opaque and 00735 * must be accessed via the functions provided. 00736 * 00737 * All parameters in the structure will be initialised to special values which 00738 * are ignored by sp_set_config(). 00739 * 00740 * The structure should be freed after use by calling sp_free_config(). 00741 * 00742 * @param[out] config_ptr If any error is returned, the variable pointed to by 00743 * config_ptr will be set to NULL. Otherwise, it will 00744 * be set to point to the allocated config structure. 00745 * Must not be NULL. 00746 * 00747 * @return SP_OK upon success, a negative error code otherwise. 00748 * 00749 * @since 0.1.0 00750 */ 00751 enum sp_return sp_new_config(struct sp_port_config **config_ptr); 00752 00753 /** 00754 * Free a port configuration structure. 00755 * 00756 * @param[in] config Pointer to a configuration structure. Must not be NULL. 00757 * 00758 * @since 0.1.0 00759 */ 00760 void sp_free_config(struct sp_port_config *config); 00761 00762 /** 00763 * Get the current configuration of the specified serial port. 00764 * 00765 * The user should allocate a configuration structure using sp_new_config() 00766 * and pass this as the config parameter. The configuration structure will 00767 * be updated with the port configuration. 00768 * 00769 * Any parameters that are configured with settings not recognised or 00770 * supported by libserialport, will be set to special values that are 00771 * ignored by sp_set_config(). 00772 * 00773 * @param[in] port Pointer to a port structure. Must not be NULL. 00774 * @param[out] config Pointer to a configuration structure that will hold 00775 * the result. Upon errors the contents of the config 00776 * struct will not be changed. Must not be NULL. 00777 * 00778 * @return SP_OK upon success, a negative error code otherwise. 00779 * 00780 * @since 0.1.0 00781 */ 00782 enum sp_return sp_get_config(struct sp_port *port, struct sp_port_config *config); 00783 00784 /** 00785 * Set the configuration for the specified serial port. 00786 * 00787 * For each parameter in the configuration, there is a special value (usually 00788 * -1, but see the documentation for each field). These values will be ignored 00789 * and the corresponding setting left unchanged on the port. 00790 * 00791 * Upon errors, the configuration of the serial port is unknown since 00792 * partial/incomplete config updates may have happened. 00793 * 00794 * @param[in] port Pointer to a port structure. Must not be NULL. 00795 * @param[in] config Pointer to a configuration structure. Must not be NULL. 00796 * 00797 * @return SP_OK upon success, a negative error code otherwise. 00798 * 00799 * @since 0.1.0 00800 */ 00801 enum sp_return sp_set_config(struct sp_port *port, const struct sp_port_config *config); 00802 00803 /** 00804 * Set the baud rate for the specified serial port. 00805 * 00806 * @param[in] port Pointer to a port structure. Must not be NULL. 00807 * @param[in] baudrate Baud rate in bits per second. 00808 * 00809 * @return SP_OK upon success, a negative error code otherwise. 00810 * 00811 * @since 0.1.0 00812 */ 00813 enum sp_return sp_set_baudrate(struct sp_port *port, int baudrate); 00814 00815 /** 00816 * Get the baud rate from a port configuration. 00817 * 00818 * The user should allocate a variable of type int and 00819 * pass a pointer to this to receive the result. 00820 * 00821 * @param[in] config Pointer to a configuration structure. Must not be NULL. 00822 * @param[out] baudrate_ptr Pointer to a variable to store the result. Must not be NULL. 00823 * 00824 * @return SP_OK upon success, a negative error code otherwise. 00825 * 00826 * @since 0.1.0 00827 */ 00828 enum sp_return sp_get_config_baudrate(const struct sp_port_config *config, int *baudrate_ptr); 00829 00830 /** 00831 * Set the baud rate in a port configuration. 00832 * 00833 * @param[in] config Pointer to a configuration structure. Must not be NULL. 00834 * @param[in] baudrate Baud rate in bits per second, or -1 to retain the current setting. 00835 * 00836 * @return SP_OK upon success, a negative error code otherwise. 00837 * 00838 * @since 0.1.0 00839 */ 00840 enum sp_return sp_set_config_baudrate(struct sp_port_config *config, int baudrate); 00841 00842 /** 00843 * Set the data bits for the specified serial port. 00844 * 00845 * @param[in] port Pointer to a port structure. Must not be NULL. 00846 * @param[in] bits Number of data bits. 00847 * 00848 * @return SP_OK upon success, a negative error code otherwise. 00849 * 00850 * @since 0.1.0 00851 */ 00852 enum sp_return sp_set_bits(struct sp_port *port, int bits); 00853 00854 /** 00855 * Get the data bits from a port configuration. 00856 * 00857 * The user should allocate a variable of type int and 00858 * pass a pointer to this to receive the result. 00859 * 00860 * @param[in] config Pointer to a configuration structure. Must not be NULL. 00861 * @param[out] bits_ptr Pointer to a variable to store the result. Must not be NULL. 00862 * 00863 * @return SP_OK upon success, a negative error code otherwise. 00864 * 00865 * @since 0.1.0 00866 */ 00867 enum sp_return sp_get_config_bits(const struct sp_port_config *config, int *bits_ptr); 00868 00869 /** 00870 * Set the data bits in a port configuration. 00871 * 00872 * @param[in] config Pointer to a configuration structure. Must not be NULL. 00873 * @param[in] bits Number of data bits, or -1 to retain the current setting. 00874 * 00875 * @return SP_OK upon success, a negative error code otherwise. 00876 * 00877 * @since 0.1.0 00878 */ 00879 enum sp_return sp_set_config_bits(struct sp_port_config *config, int bits); 00880 00881 /** 00882 * Set the parity setting for the specified serial port. 00883 * 00884 * @param[in] port Pointer to a port structure. Must not be NULL. 00885 * @param[in] parity Parity setting. 00886 * 00887 * @return SP_OK upon success, a negative error code otherwise. 00888 * 00889 * @since 0.1.0 00890 */ 00891 enum sp_return sp_set_parity(struct sp_port *port, enum sp_parity parity); 00892 00893 /** 00894 * Get the parity setting from a port configuration. 00895 * 00896 * The user should allocate a variable of type enum sp_parity and 00897 * pass a pointer to this to receive the result. 00898 * 00899 * @param[in] config Pointer to a configuration structure. Must not be NULL. 00900 * @param[out] parity_ptr Pointer to a variable to store the result. Must not be NULL. 00901 * 00902 * @return SP_OK upon success, a negative error code otherwise. 00903 * 00904 * @since 0.1.0 00905 */ 00906 enum sp_return sp_get_config_parity(const struct sp_port_config *config, enum sp_parity *parity_ptr); 00907 00908 /** 00909 * Set the parity setting in a port configuration. 00910 * 00911 * @param[in] config Pointer to a configuration structure. Must not be NULL. 00912 * @param[in] parity Parity setting, or -1 to retain the current setting. 00913 * 00914 * @return SP_OK upon success, a negative error code otherwise. 00915 * 00916 * @since 0.1.0 00917 */ 00918 enum sp_return sp_set_config_parity(struct sp_port_config *config, enum sp_parity parity); 00919 00920 /** 00921 * Set the stop bits for the specified serial port. 00922 * 00923 * @param[in] port Pointer to a port structure. Must not be NULL. 00924 * @param[in] stopbits Number of stop bits. 00925 * 00926 * @return SP_OK upon success, a negative error code otherwise. 00927 * 00928 * @since 0.1.0 00929 */ 00930 enum sp_return sp_set_stopbits(struct sp_port *port, int stopbits); 00931 00932 /** 00933 * Get the stop bits from a port configuration. 00934 * 00935 * The user should allocate a variable of type int and 00936 * pass a pointer to this to receive the result. 00937 * 00938 * @param[in] config Pointer to a configuration structure. Must not be NULL. 00939 * @param[out] stopbits_ptr Pointer to a variable to store the result. Must not be NULL. 00940 * 00941 * @return SP_OK upon success, a negative error code otherwise. 00942 * 00943 * @since 0.1.0 00944 */ 00945 enum sp_return sp_get_config_stopbits(const struct sp_port_config *config, int *stopbits_ptr); 00946 00947 /** 00948 * Set the stop bits in a port configuration. 00949 * 00950 * @param[in] config Pointer to a configuration structure. Must not be NULL. 00951 * @param[in] stopbits Number of stop bits, or -1 to retain the current setting. 00952 * 00953 * @return SP_OK upon success, a negative error code otherwise. 00954 * 00955 * @since 0.1.0 00956 */ 00957 enum sp_return sp_set_config_stopbits(struct sp_port_config *config, int stopbits); 00958 00959 /** 00960 * Set the RTS pin behaviour for the specified serial port. 00961 * 00962 * @param[in] port Pointer to a port structure. Must not be NULL. 00963 * @param[in] rts RTS pin mode. 00964 * 00965 * @return SP_OK upon success, a negative error code otherwise. 00966 * 00967 * @since 0.1.0 00968 */ 00969 enum sp_return sp_set_rts(struct sp_port *port, enum sp_rts rts); 00970 00971 /** 00972 * Get the RTS pin behaviour from a port configuration. 00973 * 00974 * The user should allocate a variable of type enum sp_rts and 00975 * pass a pointer to this to receive the result. 00976 * 00977 * @param[in] config Pointer to a configuration structure. Must not be NULL. 00978 * @param[out] rts_ptr Pointer to a variable to store the result. Must not be NULL. 00979 * 00980 * @return SP_OK upon success, a negative error code otherwise. 00981 * 00982 * @since 0.1.0 00983 */ 00984 enum sp_return sp_get_config_rts(const struct sp_port_config *config, enum sp_rts *rts_ptr); 00985 00986 /** 00987 * Set the RTS pin behaviour in a port configuration. 00988 * 00989 * @param[in] config Pointer to a configuration structure. Must not be NULL. 00990 * @param[in] rts RTS pin mode, or -1 to retain the current setting. 00991 * 00992 * @return SP_OK upon success, a negative error code otherwise. 00993 * 00994 * @since 0.1.0 00995 */ 00996 enum sp_return sp_set_config_rts(struct sp_port_config *config, enum sp_rts rts); 00997 00998 /** 00999 * Set the CTS pin behaviour for the specified serial port. 01000 * 01001 * @param[in] port Pointer to a port structure. Must not be NULL. 01002 * @param[in] cts CTS pin mode. 01003 * 01004 * @return SP_OK upon success, a negative error code otherwise. 01005 * 01006 * @since 0.1.0 01007 */ 01008 enum sp_return sp_set_cts(struct sp_port *port, enum sp_cts cts); 01009 01010 /** 01011 * Get the CTS pin behaviour from a port configuration. 01012 * 01013 * The user should allocate a variable of type enum sp_cts and 01014 * pass a pointer to this to receive the result. 01015 * 01016 * @param[in] config Pointer to a configuration structure. Must not be NULL. 01017 * @param[out] cts_ptr Pointer to a variable to store the result. Must not be NULL. 01018 * 01019 * @return SP_OK upon success, a negative error code otherwise. 01020 * 01021 * @since 0.1.0 01022 */ 01023 enum sp_return sp_get_config_cts(const struct sp_port_config *config, enum sp_cts *cts_ptr); 01024 01025 /** 01026 * Set the CTS pin behaviour in a port configuration. 01027 * 01028 * @param[in] config Pointer to a configuration structure. Must not be NULL. 01029 * @param[in] cts CTS pin mode, or -1 to retain the current setting. 01030 * 01031 * @return SP_OK upon success, a negative error code otherwise. 01032 * 01033 * @since 0.1.0 01034 */ 01035 enum sp_return sp_set_config_cts(struct sp_port_config *config, enum sp_cts cts); 01036 01037 /** 01038 * Set the DTR pin behaviour for the specified serial port. 01039 * 01040 * @param[in] port Pointer to a port structure. Must not be NULL. 01041 * @param[in] dtr DTR pin mode. 01042 * 01043 * @return SP_OK upon success, a negative error code otherwise. 01044 * 01045 * @since 0.1.0 01046 */ 01047 enum sp_return sp_set_dtr(struct sp_port *port, enum sp_dtr dtr); 01048 01049 /** 01050 * Get the DTR pin behaviour from a port configuration. 01051 * 01052 * The user should allocate a variable of type enum sp_dtr and 01053 * pass a pointer to this to receive the result. 01054 * 01055 * @param[in] config Pointer to a configuration structure. Must not be NULL. 01056 * @param[out] dtr_ptr Pointer to a variable to store the result. Must not be NULL. 01057 * 01058 * @return SP_OK upon success, a negative error code otherwise. 01059 * 01060 * @since 0.1.0 01061 */ 01062 enum sp_return sp_get_config_dtr(const struct sp_port_config *config, enum sp_dtr *dtr_ptr); 01063 01064 /** 01065 * Set the DTR pin behaviour in a port configuration. 01066 * 01067 * @param[in] config Pointer to a configuration structure. Must not be NULL. 01068 * @param[in] dtr DTR pin mode, or -1 to retain the current setting. 01069 * 01070 * @return SP_OK upon success, a negative error code otherwise. 01071 * 01072 * @since 0.1.0 01073 */ 01074 enum sp_return sp_set_config_dtr(struct sp_port_config *config, enum sp_dtr dtr); 01075 01076 /** 01077 * Set the DSR pin behaviour for the specified serial port. 01078 * 01079 * @param[in] port Pointer to a port structure. Must not be NULL. 01080 * @param[in] dsr DSR pin mode. 01081 * 01082 * @return SP_OK upon success, a negative error code otherwise. 01083 * 01084 * @since 0.1.0 01085 */ 01086 enum sp_return sp_set_dsr(struct sp_port *port, enum sp_dsr dsr); 01087 01088 /** 01089 * Get the DSR pin behaviour from a port configuration. 01090 * 01091 * The user should allocate a variable of type enum sp_dsr and 01092 * pass a pointer to this to receive the result. 01093 * 01094 * @param[in] config Pointer to a configuration structure. Must not be NULL. 01095 * @param[out] dsr_ptr Pointer to a variable to store the result. Must not be NULL. 01096 * 01097 * @return SP_OK upon success, a negative error code otherwise. 01098 * 01099 * @since 0.1.0 01100 */ 01101 enum sp_return sp_get_config_dsr(const struct sp_port_config *config, enum sp_dsr *dsr_ptr); 01102 01103 /** 01104 * Set the DSR pin behaviour in a port configuration. 01105 * 01106 * @param[in] config Pointer to a configuration structure. Must not be NULL. 01107 * @param[in] dsr DSR pin mode, or -1 to retain the current setting. 01108 * 01109 * @return SP_OK upon success, a negative error code otherwise. 01110 * 01111 * @since 0.1.0 01112 */ 01113 enum sp_return sp_set_config_dsr(struct sp_port_config *config, enum sp_dsr dsr); 01114 01115 /** 01116 * Set the XON/XOFF configuration for the specified serial port. 01117 * 01118 * @param[in] port Pointer to a port structure. Must not be NULL. 01119 * @param[in] xon_xoff XON/XOFF mode. 01120 * 01121 * @return SP_OK upon success, a negative error code otherwise. 01122 * 01123 * @since 0.1.0 01124 */ 01125 enum sp_return sp_set_xon_xoff(struct sp_port *port, enum sp_xonxoff xon_xoff); 01126 01127 /** 01128 * Get the XON/XOFF configuration from a port configuration. 01129 * 01130 * The user should allocate a variable of type enum sp_xonxoff and 01131 * pass a pointer to this to receive the result. 01132 * 01133 * @param[in] config Pointer to a configuration structure. Must not be NULL. 01134 * @param[out] xon_xoff_ptr Pointer to a variable to store the result. Must not be NULL. 01135 * 01136 * @return SP_OK upon success, a negative error code otherwise. 01137 * 01138 * @since 0.1.0 01139 */ 01140 enum sp_return sp_get_config_xon_xoff(const struct sp_port_config *config, enum sp_xonxoff *xon_xoff_ptr); 01141 01142 /** 01143 * Set the XON/XOFF configuration in a port configuration. 01144 * 01145 * @param[in] config Pointer to a configuration structure. Must not be NULL. 01146 * @param[in] xon_xoff XON/XOFF mode, or -1 to retain the current setting. 01147 * 01148 * @return SP_OK upon success, a negative error code otherwise. 01149 * 01150 * @since 0.1.0 01151 */ 01152 enum sp_return sp_set_config_xon_xoff(struct sp_port_config *config, enum sp_xonxoff xon_xoff); 01153 01154 /** 01155 * Set the flow control type in a port configuration. 01156 * 01157 * This function is a wrapper that sets the RTS, CTS, DTR, DSR and 01158 * XON/XOFF settings as necessary for the specified flow control 01159 * type. For more fine-grained control of these settings, use their 01160 * individual configuration functions. 01161 * 01162 * @param[in] config Pointer to a configuration structure. Must not be NULL. 01163 * @param[in] flowcontrol Flow control setting to use. 01164 * 01165 * @return SP_OK upon success, a negative error code otherwise. 01166 * 01167 * @since 0.1.0 01168 */ 01169 enum sp_return sp_set_config_flowcontrol(struct sp_port_config *config, enum sp_flowcontrol flowcontrol); 01170 01171 /** 01172 * Set the flow control type for the specified serial port. 01173 * 01174 * This function is a wrapper that sets the RTS, CTS, DTR, DSR and 01175 * XON/XOFF settings as necessary for the specified flow control 01176 * type. For more fine-grained control of these settings, use their 01177 * individual configuration functions. 01178 * 01179 * @param[in] port Pointer to a port structure. Must not be NULL. 01180 * @param[in] flowcontrol Flow control setting to use. 01181 * 01182 * @return SP_OK upon success, a negative error code otherwise. 01183 * 01184 * @since 0.1.0 01185 */ 01186 enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flowcontrol); 01187 01188 /** 01189 * @} 01190 * 01191 * @defgroup Data Data handling 01192 * 01193 * Reading, writing, and flushing data. 01194 * 01195 * @{ 01196 */ 01197 01198 /** 01199 * Read bytes from the specified serial port, blocking until complete. 01200 * 01201 * @warning If your program runs on Unix, defines its own signal handlers, and 01202 * needs to abort blocking reads when these are called, then you 01203 * should not use this function. It repeats system calls that return 01204 * with EINTR. To be able to abort a read from a signal handler, you 01205 * should implement your own blocking read using sp_nonblocking_read() 01206 * together with a blocking method that makes sense for your program. 01207 * E.g. you can obtain the file descriptor for an open port using 01208 * sp_get_port_handle() and use this to call select() or pselect(), 01209 * with appropriate arrangements to return if a signal is received. 01210 * 01211 * @param[in] port Pointer to a port structure. Must not be NULL. 01212 * @param[out] buf Buffer in which to store the bytes read. Must not be NULL. 01213 * @param[in] count Requested number of bytes to read. 01214 * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely. 01215 * 01216 * @return The number of bytes read on success, or a negative error code. If 01217 * the number of bytes returned is less than that requested, the 01218 * timeout was reached before the requested number of bytes was 01219 * available. If timeout is zero, the function will always return 01220 * either the requested number of bytes or a negative error code. 01221 * 01222 * @since 0.1.0 01223 */ 01224 enum sp_return sp_blocking_read(struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms); 01225 01226 /** 01227 * Read bytes from the specified serial port, returning as soon as any data is 01228 * available. 01229 * 01230 * @warning If your program runs on Unix, defines its own signal handlers, and 01231 * needs to abort blocking reads when these are called, then you 01232 * should not use this function. It repeats system calls that return 01233 * with EINTR. To be able to abort a read from a signal handler, you 01234 * should implement your own blocking read using sp_nonblocking_read() 01235 * together with a blocking method that makes sense for your program. 01236 * E.g. you can obtain the file descriptor for an open port using 01237 * sp_get_port_handle() and use this to call select() or pselect(), 01238 * with appropriate arrangements to return if a signal is received. 01239 * 01240 * @param[in] port Pointer to a port structure. Must not be NULL. 01241 * @param[out] buf Buffer in which to store the bytes read. Must not be NULL. 01242 * @param[in] count Maximum number of bytes to read. Must not be zero. 01243 * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely. 01244 * 01245 * @return The number of bytes read on success, or a negative error code. If 01246 * the result is zero, the timeout was reached before any bytes were 01247 * available. If timeout_ms is zero, the function will always return 01248 * either at least one byte, or a negative error code. 01249 * 01250 * @since 0.1.1 01251 */ 01252 enum sp_return sp_blocking_read_next(struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms); 01253 01254 /** 01255 * Read bytes from the specified serial port, without blocking. 01256 * 01257 * @param[in] port Pointer to a port structure. Must not be NULL. 01258 * @param[out] buf Buffer in which to store the bytes read. Must not be NULL. 01259 * @param[in] count Maximum number of bytes to read. 01260 * 01261 * @return The number of bytes read on success, or a negative error code. The 01262 * number of bytes returned may be any number from zero to the maximum 01263 * that was requested. 01264 * 01265 * @since 0.1.0 01266 */ 01267 enum sp_return sp_nonblocking_read(struct sp_port *port, void *buf, size_t count); 01268 01269 /** 01270 * Write bytes to the specified serial port, blocking until complete. 01271 * 01272 * Note that this function only ensures that the accepted bytes have been 01273 * written to the OS; they may be held in driver or hardware buffers and not 01274 * yet physically transmitted. To check whether all written bytes have actually 01275 * been transmitted, use the sp_output_waiting() function. To wait until all 01276 * written bytes have actually been transmitted, use the sp_drain() function. 01277 * 01278 * @warning If your program runs on Unix, defines its own signal handlers, and 01279 * needs to abort blocking writes when these are called, then you 01280 * should not use this function. It repeats system calls that return 01281 * with EINTR. To be able to abort a write from a signal handler, you 01282 * should implement your own blocking write using sp_nonblocking_write() 01283 * together with a blocking method that makes sense for your program. 01284 * E.g. you can obtain the file descriptor for an open port using 01285 * sp_get_port_handle() and use this to call select() or pselect(), 01286 * with appropriate arrangements to return if a signal is received. 01287 * 01288 * @param[in] port Pointer to a port structure. Must not be NULL. 01289 * @param[in] buf Buffer containing the bytes to write. Must not be NULL. 01290 * @param[in] count Requested number of bytes to write. 01291 * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely. 01292 * 01293 * @return The number of bytes written on success, or a negative error code. 01294 * If the number of bytes returned is less than that requested, the 01295 * timeout was reached before the requested number of bytes was 01296 * written. If timeout is zero, the function will always return 01297 * either the requested number of bytes or a negative error code. In 01298 * the event of an error there is no way to determine how many bytes 01299 * were sent before the error occurred. 01300 * 01301 * @since 0.1.0 01302 */ 01303 enum sp_return sp_blocking_write(struct sp_port *port, const void *buf, size_t count, unsigned int timeout_ms); 01304 01305 /** 01306 * Write bytes to the specified serial port, without blocking. 01307 * 01308 * Note that this function only ensures that the accepted bytes have been 01309 * written to the OS; they may be held in driver or hardware buffers and not 01310 * yet physically transmitted. To check whether all written bytes have actually 01311 * been transmitted, use the sp_output_waiting() function. To wait until all 01312 * written bytes have actually been transmitted, use the sp_drain() function. 01313 * 01314 * @param[in] port Pointer to a port structure. Must not be NULL. 01315 * @param[in] buf Buffer containing the bytes to write. Must not be NULL. 01316 * @param[in] count Maximum number of bytes to write. 01317 * 01318 * @return The number of bytes written on success, or a negative error code. 01319 * The number of bytes returned may be any number from zero to the 01320 * maximum that was requested. 01321 * 01322 * @since 0.1.0 01323 */ 01324 enum sp_return sp_nonblocking_write(struct sp_port *port, const void *buf, size_t count); 01325 01326 /** 01327 * Gets the number of bytes waiting in the input buffer. 01328 * 01329 * @param[in] port Pointer to a port structure. Must not be NULL. 01330 * 01331 * @return Number of bytes waiting on success, a negative error code otherwise. 01332 * 01333 * @since 0.1.0 01334 */ 01335 enum sp_return sp_input_waiting(struct sp_port *port); 01336 01337 /** 01338 * Gets the number of bytes waiting in the output buffer. 01339 * 01340 * @param[in] port Pointer to a port structure. Must not be NULL. 01341 * 01342 * @return Number of bytes waiting on success, a negative error code otherwise. 01343 * 01344 * @since 0.1.0 01345 */ 01346 enum sp_return sp_output_waiting(struct sp_port *port); 01347 01348 /** 01349 * Flush serial port buffers. Data in the selected buffer(s) is discarded. 01350 * 01351 * @param[in] port Pointer to a port structure. Must not be NULL. 01352 * @param[in] buffers Which buffer(s) to flush. 01353 * 01354 * @return SP_OK upon success, a negative error code otherwise. 01355 * 01356 * @since 0.1.0 01357 */ 01358 enum sp_return sp_flush(struct sp_port *port, enum sp_buffer buffers); 01359 01360 /** 01361 * Wait for buffered data to be transmitted. 01362 * 01363 * @warning If your program runs on Unix, defines its own signal handlers, and 01364 * needs to abort draining the output buffer when when these are 01365 * called, then you should not use this function. It repeats system 01366 * calls that return with EINTR. To be able to abort a drain from a 01367 * signal handler, you would need to implement your own blocking 01368 * drain by polling the result of sp_output_waiting(). 01369 * 01370 * @param[in] port Pointer to a port structure. Must not be NULL. 01371 * 01372 * @return SP_OK upon success, a negative error code otherwise. 01373 * 01374 * @since 0.1.0 01375 */ 01376 enum sp_return sp_drain(struct sp_port *port); 01377 01378 /** 01379 * @} 01380 * 01381 * @defgroup Waiting Waiting 01382 * 01383 * Waiting for events and timeout handling. 01384 * 01385 * @{ 01386 */ 01387 01388 /** 01389 * Allocate storage for a set of events. 01390 * 01391 * The user should allocate a variable of type struct sp_event_set *, 01392 * then pass a pointer to this variable to receive the result. 01393 * 01394 * The result should be freed after use by calling sp_free_event_set(). 01395 * 01396 * @param[out] result_ptr If any error is returned, the variable pointed to by 01397 * result_ptr will be set to NULL. Otherwise, it will 01398 * be set to point to the event set. Must not be NULL. 01399 * 01400 * @return SP_OK upon success, a negative error code otherwise. 01401 * 01402 * @since 0.1.0 01403 */ 01404 enum sp_return sp_new_event_set(struct sp_event_set **result_ptr); 01405 01406 /** 01407 * Add events to a struct sp_event_set for a given port. 01408 * 01409 * The port must first be opened by calling sp_open() using the same port 01410 * structure. 01411 * 01412 * After the port is closed or the port structure freed, the results may 01413 * no longer be valid. 01414 * 01415 * @param[in,out] event_set Event set to update. Must not be NULL. 01416 * @param[in] port Pointer to a port structure. Must not be NULL. 01417 * @param[in] mask Bitmask of events to be waited for. 01418 * 01419 * @return SP_OK upon success, a negative error code otherwise. 01420 * 01421 * @since 0.1.0 01422 */ 01423 enum sp_return sp_add_port_events(struct sp_event_set *event_set, 01424 const struct sp_port *port, enum sp_event mask); 01425 01426 /** 01427 * Wait for any of a set of events to occur. 01428 * 01429 * @param[in] event_set Event set to wait on. Must not be NULL. 01430 * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely. 01431 * 01432 * @return SP_OK upon success, a negative error code otherwise. 01433 * 01434 * @since 0.1.0 01435 */ 01436 enum sp_return sp_wait(struct sp_event_set *event_set, unsigned int timeout_ms); 01437 01438 /** 01439 * Free a structure allocated by sp_new_event_set(). 01440 * 01441 * @param[in] event_set Event set to free. Must not be NULL. 01442 * 01443 * @since 0.1.0 01444 */ 01445 void sp_free_event_set(struct sp_event_set *event_set); 01446 01447 /** 01448 * @} 01449 * 01450 * @defgroup Signals Signals 01451 * 01452 * Port signalling operations. 01453 * 01454 * @{ 01455 */ 01456 01457 /** 01458 * Gets the status of the control signals for the specified port. 01459 * 01460 * The user should allocate a variable of type "enum sp_signal" and pass a 01461 * pointer to this variable to receive the result. The result is a bitmask 01462 * in which individual signals can be checked by bitwise OR with values of 01463 * the sp_signal enum. 01464 * 01465 * @param[in] port Pointer to a port structure. Must not be NULL. 01466 * @param[out] signal_mask Pointer to a variable to receive the result. 01467 * Must not be NULL. 01468 * 01469 * @return SP_OK upon success, a negative error code otherwise. 01470 * 01471 * @since 0.1.0 01472 */ 01473 enum sp_return sp_get_signals(struct sp_port *port, enum sp_signal *signal_mask); 01474 01475 /** 01476 * Put the port transmit line into the break state. 01477 * 01478 * @param[in] port Pointer to a port structure. Must not be NULL. 01479 * 01480 * @return SP_OK upon success, a negative error code otherwise. 01481 * 01482 * @since 0.1.0 01483 */ 01484 enum sp_return sp_start_break(struct sp_port *port); 01485 01486 /** 01487 * Take the port transmit line out of the break state. 01488 * 01489 * @param[in] port Pointer to a port structure. Must not be NULL. 01490 * 01491 * @return SP_OK upon success, a negative error code otherwise. 01492 * 01493 * @since 0.1.0 01494 */ 01495 enum sp_return sp_end_break(struct sp_port *port); 01496 01497 /** 01498 * @} 01499 * 01500 * @defgroup Errors Errors 01501 * 01502 * Obtaining error information. 01503 * 01504 * @{ 01505 */ 01506 01507 /** 01508 * Get the error code for a failed operation. 01509 * 01510 * In order to obtain the correct result, this function should be called 01511 * straight after the failure, before executing any other system operations. 01512 * The result is thread-specific, and only valid when called immediately 01513 * after a previous call returning SP_ERR_FAIL. 01514 * 01515 * @return The system's numeric code for the error that caused the last 01516 * operation to fail. 01517 * 01518 * @since 0.1.0 01519 */ 01520 int sp_last_error_code(void); 01521 01522 /** 01523 * Get the error message for a failed operation. 01524 * 01525 * In order to obtain the correct result, this function should be called 01526 * straight after the failure, before executing other system operations. 01527 * The result is thread-specific, and only valid when called immediately 01528 * after a previous call returning SP_ERR_FAIL. 01529 * 01530 * @return The system's message for the error that caused the last 01531 * operation to fail. This string may be allocated by the function, 01532 * and should be freed after use by calling sp_free_error_message(). 01533 * 01534 * @since 0.1.0 01535 */ 01536 char *sp_last_error_message(void); 01537 01538 /** 01539 * Free an error message returned by sp_last_error_message(). 01540 * 01541 * @param[in] message The error message string to free. Must not be NULL. 01542 * 01543 * @since 0.1.0 01544 */ 01545 void sp_free_error_message(char *message); 01546 01547 /** 01548 * Set the handler function for library debugging messages. 01549 * 01550 * Debugging messages are generated by the library during each operation, 01551 * to help in diagnosing problems. The handler will be called for each 01552 * message. The handler can be set to NULL to ignore all debug messages. 01553 * 01554 * The handler function should accept a format string and variable length 01555 * argument list, in the same manner as e.g. printf(). 01556 * 01557 * The default handler is sp_default_debug_handler(). 01558 * 01559 * @param[in] handler The handler function to use. Can be NULL (in that case 01560 * all debug messages will be ignored). 01561 * 01562 * @since 0.1.0 01563 */ 01564 void sp_set_debug_handler(void (*handler)(const char *format, ...)); 01565 01566 /** 01567 * Default handler function for library debugging messages. 01568 * 01569 * This function prints debug messages to the standard error stream if the 01570 * environment variable LIBSERIALPORT_DEBUG is set. Otherwise, they are 01571 * ignored. 01572 * 01573 * @param[in] format The format string to use. Must not be NULL. 01574 * @param[in] ... The variable length argument list to use. 01575 * 01576 * @since 0.1.0 01577 */ 01578 void sp_default_debug_handler(const char *format, ...); 01579 01580 /** @} */ 01581 01582 /** 01583 * @defgroup Versions Versions 01584 * 01585 * Version number querying functions, definitions, and macros. 01586 * 01587 * This set of API calls returns two different version numbers related 01588 * to libserialport. The "package version" is the release version number of the 01589 * libserialport tarball in the usual "major.minor.micro" format, e.g. "0.1.0". 01590 * 01591 * The "library version" is independent of that; it is the libtool version 01592 * number in the "current:revision:age" format, e.g. "2:0:0". 01593 * See http://www.gnu.org/software/libtool/manual/libtool.html#Libtool-versioning for details. 01594 * 01595 * Both version numbers (and/or individual components of them) can be 01596 * retrieved via the API calls at runtime, and/or they can be checked at 01597 * compile/preprocessor time using the respective macros. 01598 * 01599 * @{ 01600 */ 01601 01602 /* 01603 * Package version macros (can be used for conditional compilation). 01604 */ 01605 01606 /** The libserialport package 'major' version number. */ 01607 #define SP_PACKAGE_VERSION_MAJOR 0 01608 01609 /** The libserialport package 'minor' version number. */ 01610 #define SP_PACKAGE_VERSION_MINOR 1 01611 01612 /** The libserialport package 'micro' version number. */ 01613 #define SP_PACKAGE_VERSION_MICRO 1 01614 01615 /** The libserialport package version ("major.minor.micro") as string. */ 01616 #define SP_PACKAGE_VERSION_STRING "0.1.1" 01617 01618 /* 01619 * Library/libtool version macros (can be used for conditional compilation). 01620 */ 01621 01622 /** The libserialport libtool 'current' version number. */ 01623 #define SP_LIB_VERSION_CURRENT 1 01624 01625 /** The libserialport libtool 'revision' version number. */ 01626 #define SP_LIB_VERSION_REVISION 0 01627 01628 /** The libserialport libtool 'age' version number. */ 01629 #define SP_LIB_VERSION_AGE 1 01630 01631 /** The libserialport libtool version ("current:revision:age") as string. */ 01632 #define SP_LIB_VERSION_STRING "1:0:1" 01633 01634 /** 01635 * Get the major libserialport package version number. 01636 * 01637 * @return The major package version number. 01638 * 01639 * @since 0.1.0 01640 */ 01641 int sp_get_major_package_version(void); 01642 01643 /** 01644 * Get the minor libserialport package version number. 01645 * 01646 * @return The minor package version number. 01647 * 01648 * @since 0.1.0 01649 */ 01650 int sp_get_minor_package_version(void); 01651 01652 /** 01653 * Get the micro libserialport package version number. 01654 * 01655 * @return The micro package version number. 01656 * 01657 * @since 0.1.0 01658 */ 01659 int sp_get_micro_package_version(void); 01660 01661 /** 01662 * Get the libserialport package version number as a string. 01663 * 01664 * @return The package version number string. The returned string is 01665 * static and thus should NOT be free'd by the caller. 01666 * 01667 * @since 0.1.0 01668 */ 01669 const char *sp_get_package_version_string(void); 01670 01671 /** 01672 * Get the "current" part of the libserialport library version number. 01673 * 01674 * @return The "current" library version number. 01675 * 01676 * @since 0.1.0 01677 */ 01678 int sp_get_current_lib_version(void); 01679 01680 /** 01681 * Get the "revision" part of the libserialport library version number. 01682 * 01683 * @return The "revision" library version number. 01684 * 01685 * @since 0.1.0 01686 */ 01687 int sp_get_revision_lib_version(void); 01688 01689 /** 01690 * Get the "age" part of the libserialport library version number. 01691 * 01692 * @return The "age" library version number. 01693 * 01694 * @since 0.1.0 01695 */ 01696 int sp_get_age_lib_version(void); 01697 01698 /** 01699 * Get the libserialport library version number as a string. 01700 * 01701 * @return The library version number string. The returned string is 01702 * static and thus should NOT be free'd by the caller. 01703 * 01704 * @since 0.1.0 01705 */ 01706 const char *sp_get_lib_version_string(void); 01707 01708 /** @} */ 01709 01710 #ifdef __cplusplus 01711 } 01712 #endif 01713 01714 #endif
Generated on Tue Jul 12 2022 17:59:52 by 1.7.2