* - @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.
*
* 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
#include <windows.h>
#endif
-/* Package version macros (e.g. for conditional compilation). */
-#define SP_PACKAGE_VERSION_MAJOR @SP_PACKAGE_VERSION_MAJOR@
-#define SP_PACKAGE_VERSION_MINOR @SP_PACKAGE_VERSION_MINOR@
-#define SP_PACKAGE_VERSION_MICRO @SP_PACKAGE_VERSION_MICRO@
-#define SP_PACKAGE_VERSION_STRING "@SP_PACKAGE_VERSION@"
-
-/* Library/libtool version macros (e.g. for conditional compilation). */
-#define SP_LIB_VERSION_CURRENT @SP_LIB_VERSION_CURRENT@
-#define SP_LIB_VERSION_REVISION @SP_LIB_VERSION_REVISION@
-#define SP_LIB_VERSION_AGE @SP_LIB_VERSION_AGE@
-#define SP_LIB_VERSION_STRING "@SP_LIB_VERSION@"
-
/** Return values. */
enum sp_return {
/** Operation completed successfully. */
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. */
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
@{
/**
* 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(),
* 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(),
/**
* 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 event_set 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
/** @} */
+/**
+ * @defgroup Versions Version number querying functions, definitions, and macros
+ *
+ * This set of API calls returns two different version numbers related
+ * to libserialport. The "package version" is the release version number of the
+ * libserialport tarball in the usual "major.minor.micro" format, e.g. "0.1.0".
+ *
+ * The "library version" is independent of that; it is the libtool version
+ * number in the "current:revision:age" format, e.g. "2:0:0".
+ * See http://www.gnu.org/software/libtool/manual/libtool.html#Libtool-versioning for details.
+ *
+ * Both version numbers (and/or individual components of them) can be
+ * retrieved via the API calls at runtime, and/or they can be checked at
+ * compile/preprocessor time using the respective macros.
+ *
+ * @{
+ */
+
+/*
+ * Package version macros (can be used for conditional compilation).
+ */
+
+/** The libserialport package 'major' version number. */
+#define SP_PACKAGE_VERSION_MAJOR @SP_PACKAGE_VERSION_MAJOR@
+
+/** The libserialport package 'minor' version number. */
+#define SP_PACKAGE_VERSION_MINOR @SP_PACKAGE_VERSION_MINOR@
+
+/** The libserialport package 'micro' version number. */
+#define SP_PACKAGE_VERSION_MICRO @SP_PACKAGE_VERSION_MICRO@
+
+/** The libserialport package version ("major.minor.micro") as string. */
+#define SP_PACKAGE_VERSION_STRING "@SP_PACKAGE_VERSION@"
+
+/*
+ * Library/libtool version macros (can be used for conditional compilation).
+ */
+
+/** The libserialport libtool 'current' version number. */
+#define SP_LIB_VERSION_CURRENT @SP_LIB_VERSION_CURRENT@
+
+/** The libserialport libtool 'revision' version number. */
+#define SP_LIB_VERSION_REVISION @SP_LIB_VERSION_REVISION@
+
+/** The libserialport libtool 'age' version number. */
+#define SP_LIB_VERSION_AGE @SP_LIB_VERSION_AGE@
+
+/** The libserialport libtool version ("current:revision:age") as string. */
+#define SP_LIB_VERSION_STRING "@SP_LIB_VERSION@"
+
+/**
+ * Get the major libserialport package version number.
+ *
+ * @return The major package version number.
+ *
+ * @since 0.1.0
+ */
+int sp_get_major_package_version(void);
+
+/**
+ * Get the minor libserialport package version number.
+ *
+ * @return The minor package version number.
+ *
+ * @since 0.1.0
+ */
+int sp_get_minor_package_version(void);
+
+/**
+ * Get the micro libserialport package version number.
+ *
+ * @return The micro package version number.
+ *
+ * @since 0.1.0
+ */
+int sp_get_micro_package_version(void);
+
+/**
+ * Get the libserialport package version number as a string.
+ *
+ * @return The package version number string. The returned string is
+ * static and thus should NOT be free'd by the caller.
+ *
+ * @since 0.1.0
+ */
+const char *sp_get_package_version_string(void);
+
+/**
+ * Get the "current" part of the libserialport library version number.
+ *
+ * @return The "current" library version number.
+ *
+ * @since 0.1.0
+ */
+int sp_get_current_lib_version(void);
+
+/**
+ * Get the "revision" part of the libserialport library version number.
+ *
+ * @return The "revision" library version number.
+ *
+ * @since 0.1.0
+ */
+int sp_get_revision_lib_version(void);
+
+/**
+ * Get the "age" part of the libserialport library version number.
+ *
+ * @return The "age" library version number.
+ *
+ * @since 0.1.0
+ */
+int sp_get_age_lib_version(void);
+
+/**
+ * Get the libserialport library version number as a string.
+ *
+ * @return The library version number string. The returned string is
+ * static and thus should NOT be free'd by the caller.
+ *
+ * @since 0.1.0
+ */
+const char *sp_get_lib_version_string(void);
+
+/** @} */
+
#ifdef __cplusplus
}
#endif
projects / libserialport.git / blobdiff