X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;f=libserialport.h.in;h=9c6842ab7f079f1ed769269e0f259b21326f34f6;hb=0188a545c75b1012054efef41b8fb465ca90a37a;hp=1dd4715f289ef740fb9fc76625d3cae809e1a5ef;hpb=ad036cc8efcdcae5d2b8727996108c38c4915d2b;p=libserialport.git diff --git a/libserialport.h.in b/libserialport.h.in index 1dd4715..9c6842a 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,7 @@ 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, without blocking. @@ -1075,7 +1086,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 +1098,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 +1225,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().