X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;f=libserialport.h.in;h=c8defbed5c363bcf9c7e0245e475e9aeaa58906c;hb=ec4b55ae25c368e30a5db6ab6cb33bb6abeca46c;hp=1dd4715f289ef740fb9fc76625d3cae809e1a5ef;hpb=ad036cc8efcdcae5d2b8727996108c38c4915d2b;p=libserialport.git

diff --git a/libserialport.h.in b/libserialport.h.in
index 1dd4715..c8defbe 100644
--- a/libserialport.h.in
+++ b/libserialport.h.in
@@ -415,7 +415,7 @@ char *sp_get_port_name(const struct sp_port *port);
  *
  * @since 0.1.1
  */
-char *sp_get_port_description(struct sp_port *port);
+char *sp_get_port_description(const struct sp_port *port);
 
 /**
  * Get the transport type used by a port.
@@ -432,8 +432,10 @@ enum sp_transport sp_get_port_transport(const struct sp_port *port);
  * Get the USB bus number and address on bus of a USB serial adapter port.
  *
  * @param[in] port Pointer to a port structure. Must not be NULL.
- * @param[out] usb_bus Pointer to a variable to store the USB bus. Must not be NULL.
- * @param[out] usb_address Pointer to a variable to store the USB address. Must not be NULL.
+ * @param[out] usb_bus Pointer to a variable to store the USB bus.
+ *                     Can be NULL (in that case it will be ignored).
+ * @param[out] usb_address Pointer to a variable to store the USB address.
+ *                         Can be NULL (in that case it will be ignored).
  *
  * @return SP_OK upon success, a negative error code otherwise.
  *
@@ -446,8 +448,10 @@ enum sp_return sp_get_port_usb_bus_address(const struct sp_port *port,
  * Get the USB Vendor ID and Product ID of a USB serial adapter port.
  *
  * @param[in] port Pointer to a port structure. Must not be NULL.
- * @param[out] usb_vid Pointer to a variable to store the USB VID. Must not be NULL.
- * @param[out] usb_pid Pointer to a variable to store the USB PID. Must not be NULL.
+ * @param[out] usb_vid Pointer to a variable to store the USB VID.
+ *                     Can be NULL (in that case it will be ignored).
+ * @param[out] usb_pid Pointer to a variable to store the USB PID.
+ *                     Can be NULL (in that case it will be ignored).
  *
  * @return SP_OK upon success, a negative error code otherwise.
  *
@@ -529,8 +533,9 @@ char *sp_get_port_bluetooth_address(const struct sp_port *port);
  *
  * @param[in] port Pointer to a port structure. Must not be NULL.
  * @param[out] result_ptr If any error is returned, the variable pointed to by
- *                        result_ptr will be set to NULL. Otherwise, it will
- *                        be set to point to the OS handle. Must not be NULL.
+ *                        result_ptr will have unknown contents and should not
+ *                        be used. Otherwise, it will be set to point to the
+ *                        OS handle. Must not be NULL.
  *
  * @return SP_OK upon success, a negative error code otherwise.
  *
@@ -550,17 +555,19 @@ enum sp_return sp_get_port_handle(const struct sp_port *port, void *result_ptr);
 /**
  * Allocate a port configuration structure.
  *
- * The user should allocate a variable of type "struct sp_config *" and pass a
- * pointer to this to receive the result. The variable will be updated to
- * point to the new configuration structure. The structure is opaque and must
- * be accessed via the functions provided.
+ * The user should allocate a variable of type "struct sp_port_config *" and
+ * pass a pointer to this to receive the result. The variable will be updated
+ * to point to the new configuration structure. The structure is opaque and
+ * must be accessed via the functions provided.
  *
  * All parameters in the structure will be initialised to special values which
  * are ignored by sp_set_config().
  *
  * The structure should be freed after use by calling sp_free_config().
  *
- * @param[out] config_ptr Pointer to a variable to receive the result.
+ * @param[out] config_ptr If any error is returned, the variable pointed to by
+ *                        config_ptr will be set to NULL. Otherwise, it will
+ *                        be set to point to the allocated config structure.
  *                        Must not be NULL.
  *
  * @return SP_OK upon success, a negative error code otherwise.
@@ -591,7 +598,8 @@ void sp_free_config(struct sp_port_config *config);
  *
  * @param[in] port Pointer to a port structure. Must not be NULL.
  * @param[out] config Pointer to a configuration structure that will hold
- *                    the result. Must not be NULL.
+ *                    the result. Upon errors the contents of the config
+ *                    struct will not be changed. Must not be NULL.
  *
  * @return SP_OK upon success, a negative error code otherwise.
  *
@@ -606,6 +614,9 @@ enum sp_return sp_get_config(struct sp_port *port, struct sp_port_config *config
  * -1, but see the documentation for each field). These values will be ignored
  * and the corresponding setting left unchanged on the port.
  *
+ * Upon errors, the configuration of the serial port is unknown since
+ * partial/incomplete config updates may have happened.
+ *
  * @param[in] port Pointer to a port structure. Must not be NULL.
  * @param[in] config Pointer to a configuration structure. Must not be NULL.
  *
@@ -1026,7 +1037,7 @@ enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flow
  * @param[in] port Pointer to a port structure. Must not be NULL.
  * @param[out] buf Buffer in which to store the bytes read. Must not be NULL.
  * @param[in] count Requested number of bytes to read.
- * @param[in] timeout Timeout in milliseconds, or zero to wait indefinitely.
+ * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely.
  *
  * @return The number of bytes read on success, or a negative error code. If
  *         the number of bytes returned is less than that requested, the
@@ -1036,7 +1047,35 @@ enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flow
  *
  * @since 0.1.0
  */
-enum sp_return sp_blocking_read(struct sp_port *port, void *buf, size_t count, unsigned int timeout);
+enum sp_return sp_blocking_read(struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms);
+
+/**
+ * Read bytes from the specified serial port, returning as soon as any data is
+ * available.
+ *
+ * @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(),
+ *          with appropriate arrangements to return if a signal is received.
+ *
+ * @param[in] port Pointer to a port structure. Must not be NULL.
+ * @param[out] buf Buffer in which to store the bytes read. Must not be NULL.
+ * @param[in] count Maximum number of bytes to read. Must not be zero.
+ * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely.
+ *
+ * @return The number of bytes read on success, or a negative error code. If
+ *         the result is zero, the timeout was reached before any bytes were
+ *         available. If timeout_ms is zero, the function will always return
+ *         either at least one byte, or a negative error code.
+ *
+ * @since 0.1.1
+ */
+enum sp_return sp_blocking_read_next(struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms);
 
 /**
  * Read bytes from the specified serial port, without blocking.
@@ -1075,7 +1114,7 @@ enum sp_return sp_nonblocking_read(struct sp_port *port, void *buf, size_t count
  * @param[in] port Pointer to a port structure. Must not be NULL.
  * @param[in] buf Buffer containing the bytes to write. Must not be NULL.
  * @param[in] count Requested number of bytes to write.
- * @param[in] timeout Timeout in milliseconds, or zero to wait indefinitely.
+ * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely.
  *
  * @return The number of bytes written on success, or a negative error code.
  *         If the number of bytes returned is less than that requested, the
@@ -1087,7 +1126,7 @@ enum sp_return sp_nonblocking_read(struct sp_port *port, void *buf, size_t count
  *
  * @since 0.1.0
  */
-enum sp_return sp_blocking_write(struct sp_port *port, const void *buf, size_t count, unsigned int timeout);
+enum sp_return sp_blocking_write(struct sp_port *port, const void *buf, size_t count, unsigned int timeout_ms);
 
 /**
  * Write bytes to the specified serial port, without blocking.
@@ -1214,13 +1253,13 @@ enum sp_return sp_add_port_events(struct sp_event_set *event_set,
  * Wait for any of a set of events to occur.
  *
  * @param[in] event_set Event set to wait on. Must not be NULL.
- * @param[in] timeout Timeout in milliseconds, or zero to wait indefinitely.
+ * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely.
  *
  * @return SP_OK upon success, a negative error code otherwise.
  *
  * @since 0.1.0
  */
-enum sp_return sp_wait(struct sp_event_set *event_set, unsigned int timeout);
+enum sp_return sp_wait(struct sp_event_set *event_set, unsigned int timeout_ms);
 
 /**
  * Free a structure allocated by sp_new_event_set().
@@ -1296,6 +1335,8 @@ enum sp_return sp_end_break(struct sp_port *port);
  *
  * In order to obtain the correct result, this function should be called
  * straight after the failure, before executing any other system operations.
+ * The result is thread-specific, and only valid when called immediately
+ * after a previous call returning SP_ERR_FAIL.
  *
  * @return The system's numeric code for the error that caused the last
  *         operation to fail.
@@ -1309,6 +1350,8 @@ int sp_last_error_code(void);
  *
  * In order to obtain the correct result, this function should be called
  * straight after the failure, before executing other system operations.
+ * The result is thread-specific, and only valid when called immediately
+ * after a previous call returning SP_ERR_FAIL.
  *
  * @return The system's message for the error that caused the last
  *         operation to fail. This string may be allocated by the function,