X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=libserialport.h.in;h=01c20af414b28baed977b360a656428ed7b9156d;hb=104f093dba21da6e88b3c6d3349c489a5ac51be8;hp=9eb7662461e727b1f65df885596d65fa0f365b44;hpb=859874648ee98385a9d8be76182157a40eca69c0;p=libserialport.git diff --git a/libserialport.h.in b/libserialport.h.in index 9eb7662..01c20af 100644 --- a/libserialport.h.in +++ b/libserialport.h.in @@ -36,6 +36,7 @@ * - @ref Configuration (baud rate, parity, etc.) * - @ref Signals (modem control lines, breaks, etc.) * - @ref Data + * - @ref Waiting * - @ref Errors * * libserialport is an open source project released under the LGPL3+ license. @@ -73,7 +74,7 @@ * * Calls that succeed return @ref SP_OK, which is equal to zero. Some functions * declared @ref sp_return can also return a positive value for a successful - * numeric result, e.g. sp_read() and sp_write(). + * numeric result, e.g. sp_blocking_read() or sp_blocking_write(). */ #ifndef LIBSERIALPORT_LIBSERIALPORT_H @@ -122,6 +123,16 @@ enum sp_mode { SP_MODE_WRITE = 2, }; +/** Port events. */ +enum sp_event { + /* Data received and ready to read. */ + SP_EVENT_RX_READY = 1, + /* Ready to transmit new data. */ + SP_EVENT_TX_READY = 2, + /* Error occured. */ + SP_EVENT_ERROR = 4, +}; + /** Buffer selection. */ enum sp_buffer { /** Input buffer. */ @@ -230,12 +241,31 @@ enum sp_signal { SP_SIG_RI = 8, }; -/** A serial port. */ +/** + * @struct sp_port + * An opaque structure representing a serial port. + */ struct sp_port; -/** Configuration for a serial port. */ +/** + * @struct sp_port_config + * An opaque structure representing the configuration for a serial port. + */ struct sp_port_config; +/** + * @struct sp_event_set + * A set of handles to wait on for events. + */ +struct sp_event_set { + /** Array of OS-specific handles. */ + void *handles; + /** Array of bitmasks indicating which events apply for each handle. */ + enum sp_event *masks; + /** Number of handles. */ + unsigned int count; +}; + /** @defgroup Enumeration Port enumeration @{ @@ -758,11 +788,11 @@ enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flow /** * Read bytes from the specified serial port, blocking until complete. * - * @warning If your program runs on Unix and makes use of signal handlers, - * note that this function will repeat blocking system calls that - * are interrupted by a signal and return with EINTR. If your program - * needs to abort blocking reads when a signal is handled, you will - * need to implement your own loop using sp_nonblocking_read() + * @warning If your program runs on Unix, defines its own signal handlers, and + * needs to abort blocking reads when these are called, then you + * should not use this function. It repeats system calls that return + * with EINTR. To be able to abort a read from a signal handler, you + * should implement your own blocking read using sp_nonblocking_read() * together with a blocking method that makes sense for your program. * E.g. you can obtain the file descriptor for an open port using * sp_get_port_handle() and use this to call select() or pselect(), @@ -803,11 +833,11 @@ enum sp_return sp_nonblocking_read(struct sp_port *port, void *buf, size_t count * been transmitted, use the sp_output_waiting() function. To wait until all * written bytes have actually been transmitted, use the sp_drain() function. * - * @warning If your program runs on Unix and makes use of signal handlers, - * note that this function will repeat blocking system calls that - * are interrupted by a signal and return with EINTR. If your program - * needs to abort blocking reads when a signal is handled, you will - * need to implement your own loop using sp_nonblocking_read() + * @warning If your program runs on Unix, defines its own signal handlers, and + * needs to abort blocking writes when these are called, then you + * should not use this function. It repeats system calls that return + * with EINTR. To be able to abort a write from a signal handler, you + * should implement your own blocking write using sp_nonblocking_write() * together with a blocking method that makes sense for your program. * E.g. you can obtain the file descriptor for an open port using * sp_get_port_handle() and use this to call select() or pselect(), @@ -878,12 +908,70 @@ enum sp_return sp_flush(struct sp_port *port, enum sp_buffer buffers); /** * Wait for buffered data to be transmitted. * + * @warning If your program runs on Unix, defines its own signal handlers, and + * needs to abort draining the output buffer when when these are + * called, then you should not use this function. It repeats system + * calls that return with EINTR. To be able to abort a drain from a + * signal handler, you would need to implement your own blocking + * drain by polling the result of sp_output_waiting(). + * * @param port Pointer to port structure. * * @return SP_OK upon success, a negative error code otherwise. */ enum sp_return sp_drain(struct sp_port *port); +/** + * @} + * @defgroup Waiting Waiting for events + * @{ + */ + +/** + * Allocate storage for a set of events. + * + * The user should allocate a variable of type struct sp_event_set *, + * then pass a pointer to this variable to receive the result. + * + * The result should be freed after use by calling sp_free_event_set(). + * + * @return SP_OK upon success, a negative error code otherwise. + */ +enum sp_return sp_new_event_set(struct sp_event_set **result_ptr); + +/** + * Add events to a struct sp_event_set for a given port. + * + * The port must first be opened by calling sp_open() using the same port + * structure. + * + * After the port is closed or the port structure freed, the results may + * no longer be valid. + * + * @param event_set Event set to update. + * @param port Pointer to port structure. + * @param mask Bitmask of events to be waited for. + * + * @return SP_OK upon success, a negative error code otherwise. + */ +enum sp_return sp_add_port_events(struct sp_event_set *event_set, + const struct sp_port *port, enum sp_event mask); + +/** + * Wait for any of a set of events to occur. + * + * @param handles Event set to wait on. + * @param timeout Timeout in milliseconds, or zero to wait indefinitely. + * + * @return SP_OK upon success, a negative error code otherwise. + */ +enum sp_return sp_wait(struct sp_event_set *event_set, unsigned int timeout); + +/** + * Free a structure allocated by sp_new_event_set(). + */ +void sp_free_event_set(struct sp_event_set *event_set); + /** * @} * @defgroup Signals Port signalling operations