*/
/**
- *
* @mainpage libserialport API
*
* Introduction
* port. These structures are always allocated and freed by the library, using
* the functions in the @ref Enumeration "Enumeration" section.
*
- * All functions can return only three possible error values. @ref SP_ERR_ARG
- * indicates the function was called with invalid arguments. @ref SP_ERR_FAIL
- * indicates that the OS reported a failure. @ref SP_ERR_MEM indicates that a
- * memory allocation failed. All of these error values are negative.
+ * All functions can return only four possible error values:
*
- * When @ref SP_ERR_FAIL is returned, an error code or string description of
- * the error can be obtained by calling sp_last_error_code() or
- * sp_last_error_message(). The error code or message is that provided by the
- * OS; libserialport does not define any error codes or messages of its own.
+ * - @ref SP_ERR_ARG means that a function was called with invalid
+ * arguments. This implies a bug in the caller. The arguments passed would
+ * be invalid regardless of the underlying OS or serial device involved.
+ *
+ * - @ref SP_ERR_FAIL means that the OS reported a failure. The error code or
+ * message provided by the OS can be obtained by calling sp_last_error_code()
+ * or sp_last_error_message().
+ *
+ * - @ref SP_ERR_SUPP indicates that there is no support for the requested
+ * operation in the current OS, driver or device. No error message is
+ * available from the OS in this case. There is either no way to request
+ * the operation in the first place, or libserialport does not know how to
+ * do so in the current version.
+ *
+ * - @ref SP_ERR_MEM indicates that a memory allocation failed.
+ *
+ * All of these error values are negative.
*
* Function calls that succeed return @ref SP_OK, which is equal to zero,
* or where otherwise documented a positive value.
*/
-#ifndef LIBSERIALPORT_H
-#define LIBSERIALPORT_H
+#ifndef LIBSERIALPORT_LIBSERIALPORT_H
+#define LIBSERIALPORT_LIBSERIALPORT_H
#ifdef __cplusplus
extern "C" {
/* 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). */
SP_ERR_FAIL = -2,
/** A memory allocation failed while executing the operation. */
SP_ERR_MEM = -3,
+ /** The requested operation is not supported by this system or device. */
+ SP_ERR_SUPP = -4,
};
/** Port access modes. */
/**
* Wait for buffered data to be transmitted.
*
+ * @param port Pointer to port structure.
+ *
* @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
* if an invalid port is passed.
*/
/**
* Put the port transmit line into the break state.
*
+ * @param port Pointer to port structure.
+ *
* @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
* if an invalid port is passed.
*/
/**
* Take the port transmit line out of the break state.
*
+ * @param port Pointer to port structure.
+ *
* @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
* if an invalid port is passed.
*/
}
#endif
-#endif /* LIBSERIALPORT_H */
+#endif