* 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.
*
* 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.
*
*
* @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.
*
/**
* 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.
*
* @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.
*
* -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.
*
* @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
*
* @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, without blocking.
* @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
*
* @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.
* 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().