From: Martin Ling Date: Tue, 19 Nov 2013 02:36:22 +0000 (+0000) Subject: Use named enums instead of ints for clearer documentation. X-Git-Tag: libserialport-0.1.0~103 X-Git-Url: https://sigrok.org/gitweb/?p=libserialport.git;a=commitdiff_plain;h=eb6ed20f5193475fe0535920e9631137d61aa8b7 Use named enums instead of ints for clearer documentation. --- diff --git a/libserialport.h.in b/libserialport.h.in index 93939a6..a6ca558 100644 --- a/libserialport.h.in +++ b/libserialport.h.in @@ -87,45 +87,8 @@ extern "C" { #define SP_LIB_VERSION_AGE @SP_LIB_VERSION_AGE@ #define SP_LIB_VERSION_STRING "@SP_LIB_VERSION@" -/** A serial port. */ -struct sp_port { - /** Name used to open the port */ - char *name; -/** \cond 0 */ - /* OS-specific port handle */ -#ifdef _WIN32 - HANDLE hdl; -#else - int fd; -#endif -/** \endcond */ -}; - -/** Configuration for a serial port. */ -struct sp_port_config { - /** Baud rate in bits per second. */ - int baudrate; - /** Number of data bits to use. Valid values are 5 to 8. */ - int bits; - /** Parity setting to use. */ - int parity; - /** Number of stop bits to use (1 or 2). */ - int stopbits; - /** RTS pin mode. */ - int rts; - /** CTS pin mode. */ - int cts; - /** DTR pin mode. */ - int dtr; - /** DSR pin mode. */ - int dsr; - /** XON/XOFF flow control mode. */ - int xon_xoff; -}; - - /** Return values. */ -enum { +enum sp_return { /** Operation completed successfully. */ SP_OK = 0, /** Invalid arguments were passed to the function. */ @@ -137,7 +100,7 @@ enum { }; /** Port access modes. */ -enum { +enum sp_mode { /** Open port for read/write access. */ SP_MODE_RDWR = 1, /** Open port for read access only. */ @@ -147,7 +110,8 @@ enum { }; /** Parity settings. */ -enum { +enum sp_parity { + SP_PARITY_INVALID = -1, /** No parity. */ SP_PARITY_NONE = 0, /** Even parity. */ @@ -157,7 +121,8 @@ enum { }; /** RTS pin behaviour. */ -enum { +enum sp_rts { + SP_RTS_INVALID = -1, /** RTS off. */ SP_RTS_OFF = 0, /** RTS on. */ @@ -167,7 +132,8 @@ enum { }; /** CTS pin behaviour. */ -enum { +enum sp_cts { + SP_CTS_INVALID = -1, /** CTS ignored. */ SP_CTS_IGNORE = 0, /** CTS used for flow control. */ @@ -175,7 +141,8 @@ enum { }; /** DTR pin behaviour. */ -enum { +enum sp_dtr { + SP_DTR_INVALID = -1, /** DTR off. */ SP_DTR_OFF = 0, /** DTR on. */ @@ -185,7 +152,8 @@ enum { }; /** DSR pin behaviour. */ -enum { +enum sp_dsr { + SP_DSR_INVALID = -1, /** DSR ignored. */ SP_DSR_IGNORE = 0, /** DSR used for flow control. */ @@ -193,7 +161,8 @@ enum { }; /** XON/XOFF flow control behaviour. */ -enum { +enum sp_xonxoff { + SP_XONXOFF_INVALID = -1, /** XON/XOFF disabled. */ SP_XONXOFF_DISABLED = 0, /** XON/XOFF enabled for input only. */ @@ -205,7 +174,7 @@ enum { }; /** Standard flow control combinations. */ -enum { +enum sp_flowcontrol { /** No flow control. */ SP_FLOWCONTROL_NONE = 0, /** Software flow control using XON/XOFF characters. */ @@ -216,6 +185,42 @@ enum { SP_FLOWCONTROL_DTRDSR = 3 }; +/** A serial port. */ +struct sp_port { + /** Name used to open the port */ + char *name; +/** \cond 0 */ + /* OS-specific port handle */ +#ifdef _WIN32 + HANDLE hdl; +#else + int fd; +#endif +/** \endcond */ +}; + +/** Configuration for a serial port. */ +struct sp_port_config { + /** Baud rate in bits per second. */ + int baudrate; + /** Number of data bits to use. Valid values are 5 to 8. */ + int bits; + /** Parity setting to use. */ + enum sp_parity parity; + /** Number of stop bits to use (1 or 2). */ + int stopbits; + /** RTS pin mode. */ + enum sp_rts rts; + /** CTS pin mode. */ + enum sp_cts cts; + /** DTR pin mode. */ + enum sp_dtr dtr; + /** DSR pin mode. */ + enum sp_dsr dsr; + /** XON/XOFF flow control mode. */ + enum sp_xonxoff xon_xoff; +}; + /** Obtains a pointer to a new sp_port structure representing the named port. The user should allocate a variable of type "struct sp_port *" and pass a pointer @@ -228,7 +233,7 @@ enum { is returned, the variable pointed to by port_ptr will be set to NULL. Otherwise, it will be set to point to the newly allocated port. */ -int sp_get_port_by_name(const char *portname, struct sp_port **port_ptr); +enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_ptr); /** Frees a port structure obtained from sp_get_port_by_name() or sp_copy_port(). @@ -250,7 +255,7 @@ void sp_free_port(struct sp_port *port); is returned, the variable pointed to by list_ptr will be set to NULL. Otherwise, it will be set to point to the newly allocated array. */ -int sp_list_ports(struct sp_port ***list_ptr); +enum sp_return sp_list_ports(struct sp_port ***list_ptr); /** Makes a new copy of a sp_port structure. The user should allocate a variable @@ -263,7 +268,7 @@ int sp_list_ports(struct sp_port ***list_ptr); the variable pointed to by copy_ptr will be set to NULL. Otherwise, it will be set to point to the newly allocated copy. */ -int sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr); +enum sp_return sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr); /** Frees a port list obtained from sp_list_ports(). This will also free all @@ -276,14 +281,12 @@ void sp_free_port_list(struct sp_port **ports); Opens the specified serial port. @param port Pointer to port structure. - @param flags Flags to use when opening the serial port. Possible - flags are: SP_MODE_RDWR, SP_MODE_RDONLY, and - SP_MODE_NONBLOCK. + @param flags Flags to use when opening the serial port. @return SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation failure, or SP_ERR_ARG if an invalid port is passed. */ -int sp_open(struct sp_port *port, int flags); +enum sp_return sp_open(struct sp_port *port, enum sp_mode flags); /** Closes the specified serial port. @@ -291,7 +294,7 @@ int sp_open(struct sp_port *port, int flags); @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG if an invalid port is passed. */ -int sp_close(struct sp_port *port); +enum sp_return sp_close(struct sp_port *port); /** Reads bytes from the specified serial port. Note that this function may @@ -305,7 +308,7 @@ int sp_close(struct sp_port *port); @return The number of bytes read, SP_ERR_FAIL on failure, or SP_ERR_ARG for invalid arguments. */ -int sp_read(struct sp_port *port, void *buf, size_t count); +enum sp_return sp_read(struct sp_port *port, void *buf, size_t count); /** Write bytes to the specified serial port. Note that this function may @@ -319,7 +322,7 @@ int sp_read(struct sp_port *port, void *buf, size_t count); @return The number of bytes written, SP_ERR_FAIL on failure, or SP_ERR_ARG for invalid arguments. */ -int sp_write(struct sp_port *port, const void *buf, size_t count); +enum sp_return sp_write(struct sp_port *port, const void *buf, size_t count); /** Flushes serial port buffers. @@ -327,7 +330,7 @@ int sp_write(struct sp_port *port, const void *buf, size_t count); @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG if an invalid port is passed. */ -int sp_flush(struct sp_port *port); +enum sp_return sp_flush(struct sp_port *port); /** Gets current configuration of the specified serial port. @@ -339,7 +342,7 @@ int sp_flush(struct sp_port *port); @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG for invalid arguments. */ -int sp_get_config(struct sp_port *port, struct sp_port_config *config); +enum sp_return sp_get_config(struct sp_port *port, struct sp_port_config *config); /** Sets all parameters for the specified serial port. @@ -353,7 +356,7 @@ int sp_get_config(struct sp_port *port, struct sp_port_config *config); @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG for invalid arguments. */ -int sp_set_config(struct sp_port *port, const struct sp_port_config *config); +enum sp_return sp_set_config(struct sp_port *port, const struct sp_port_config *config); /** Sets the baud rate for the specified serial port. @@ -364,7 +367,7 @@ int sp_set_config(struct sp_port *port, const struct sp_port_config *config); @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG for invalid arguments. */ -int sp_set_baudrate(struct sp_port *port, int baudrate); +enum sp_return sp_set_baudrate(struct sp_port *port, int baudrate); /** Sets the number of data bits for the specified serial port. @@ -375,19 +378,18 @@ int sp_set_baudrate(struct sp_port *port, int baudrate); @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG for invalid arguments. */ -int sp_set_bits(struct sp_port *port, int bits); +enum sp_return sp_set_bits(struct sp_port *port, int bits); /** Sets the parity for the specified serial port. @param port Pointer to port structure. @param parity Parity setting to use. - (SP_PARITY_NONE, SP_PARITY_EVEN or SP_PARITY_ODD) @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG for invalid arguments. */ -int sp_set_parity(struct sp_port *port, int parity); +enum sp_return sp_set_parity(struct sp_port *port, enum sp_parity parity); /** Sets the number of stop bits for the specified port. @@ -398,7 +400,7 @@ int sp_set_parity(struct sp_port *port, int parity); @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG for invalid arguments. */ -int sp_set_stopbits(struct sp_port *port, int stopbits); +enum sp_return sp_set_stopbits(struct sp_port *port, int stopbits); /** Sets the flow control type for the specified serial port. @@ -409,78 +411,67 @@ int sp_set_stopbits(struct sp_port *port, int stopbits); individual configuration functions or the sp_set_config() function. @param port Pointer to port structure. - @param flowcontrol Flow control setting to use. Valid settings are: - - SP_FLOWCONTROL_NONE: No flow control. - SP_FLOWCONTROL_XONXOFF: Software flow control using XON/XOFF characters. - SP_FLOWCONTROL_RTSCTS: Hardware flow control using RTS/CTS signals. - SP_FLOWCONTROL_DTRDSR: Hardware flow control using DTR/DSR signals. + @param flowcontrol Flow control setting to use. @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG for invalid arguments. */ -int sp_set_flowcontrol(struct sp_port *port, int flowcontrol); +enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flowcontrol); /** Sets the RTS pin behaviour for the specified port. @param port Pointer to port structure. @param rts RTS pin mode. - (SP_RTS_ON, SP_RTS_OFF or SP_RTS_FLOW_CONTROL) @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG for invalid arguments. */ -int sp_set_rts(struct sp_port *port, int rts); +enum sp_return sp_set_rts(struct sp_port *port, enum sp_rts rts); /** Sets the CTS pin behaviour for the specified port. @param port Pointer to port structure. @param cts CTS pin mode. - (SP_CTS_IGNORE or SP_CTS_FLOW_CONTROL) @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG for invalid arguments. */ -int sp_set_cts(struct sp_port *port, int cts); +enum sp_return sp_set_cts(struct sp_port *port, enum sp_cts cts); /** Sets the DTR pin behaviour for the specified port. @param port Pointer to port structure. @param dtr DTR pin mode. - (SP_DTR_ON, SP_DTR_OFF or SP_DTR_FLOW_CONTROL) @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG for invalid arguments. */ -int sp_set_dtr(struct sp_port *port, int dtr); +enum sp_return sp_set_dtr(struct sp_port *port, enum sp_dtr dtr); /** Sets the RTS pin behaviour for the specified port. @param port Pointer to port structure. @param dsr DSR pin mode. - (SP_DSR_IGNORE or SP_DSR_FLOW_CONTROL) @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG for invalid arguments. */ -int sp_set_dsr(struct sp_port *port, int dsr); +enum sp_return sp_set_dsr(struct sp_port *port, enum sp_dsr dsr); /** Configures XON/XOFF flow control for the specified port. @param port Pointer to port structure. @param xon_xoff XON/XOFF flow control mode. - (SP_XONXOFF_DISABLED, SP_XONXOFF_IN, - SP_XONXOFF_OUT or SP_XONXOFF_INOUT) @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG for invalid arguments. */ -int sp_set_xon_xoff(struct sp_port *port, int xon_xoff); +enum sp_return sp_set_xon_xoff(struct sp_port *port, enum sp_xonxoff xon_xoff); /** Gets the error code for a failed operation. diff --git a/serialport.c b/serialport.c index 7066091..7796fce 100644 --- a/serialport.c +++ b/serialport.c @@ -92,12 +92,14 @@ const struct std_baudrate std_baudrates[] = { #define NUM_STD_BAUDRATES ARRAY_SIZE(std_baudrates) /* Helper functions. */ -static int validate_port(struct sp_port *port); +static enum sp_return validate_port(struct sp_port *port); static struct sp_port **list_append(struct sp_port **list, const char *portname); -static int get_config(struct sp_port *port, struct port_data *data, struct sp_port_config *config); -static int set_config(struct sp_port *port, struct port_data *data, const struct sp_port_config *config); +static enum sp_return get_config(struct sp_port *port, struct port_data *data, + struct sp_port_config *config); +static enum sp_return set_config(struct sp_port *port, struct port_data *data, + const struct sp_port_config *config); -int sp_get_port_by_name(const char *portname, struct sp_port **port_ptr) +enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_ptr) { struct sp_port *port; int len; @@ -134,7 +136,7 @@ int sp_get_port_by_name(const char *portname, struct sp_port **port_ptr) return SP_OK; } -int sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr) +enum sp_return sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr) { if (!copy_ptr) return SP_ERR_ARG; @@ -177,7 +179,7 @@ fail: return NULL; } -int sp_list_ports(struct sp_port ***list_ptr) +enum sp_return sp_list_ports(struct sp_port ***list_ptr) { struct sp_port **list; int ret = SP_OK; @@ -397,7 +399,7 @@ void sp_free_port_list(struct sp_port **list) free(list); } -static int validate_port(struct sp_port *port) +static enum sp_return validate_port(struct sp_port *port) { if (port == NULL) return 0; @@ -413,7 +415,7 @@ static int validate_port(struct sp_port *port) #define CHECK_PORT() do { if (!validate_port(port)) return SP_ERR_ARG; } while (0) -int sp_open(struct sp_port *port, int flags) +enum sp_return sp_open(struct sp_port *port, enum sp_mode flags) { if (!port) return SP_ERR_ARG; @@ -491,7 +493,7 @@ int sp_open(struct sp_port *port, int flags) return SP_OK; } -int sp_close(struct sp_port *port) +enum sp_return sp_close(struct sp_port *port) { CHECK_PORT(); @@ -510,7 +512,7 @@ int sp_close(struct sp_port *port) return SP_OK; } -int sp_flush(struct sp_port *port) +enum sp_return sp_flush(struct sp_port *port) { CHECK_PORT(); @@ -526,7 +528,7 @@ int sp_flush(struct sp_port *port) return SP_OK; } -int sp_write(struct sp_port *port, const void *buf, size_t count) +enum sp_return sp_write(struct sp_port *port, const void *buf, size_t count) { CHECK_PORT(); @@ -551,7 +553,7 @@ int sp_write(struct sp_port *port, const void *buf, size_t count) #endif } -int sp_read(struct sp_port *port, void *buf, size_t count) +enum sp_return sp_read(struct sp_port *port, void *buf, size_t count) { CHECK_PORT(); @@ -575,7 +577,8 @@ int sp_read(struct sp_port *port, void *buf, size_t count) #endif } -static int get_config(struct sp_port *port, struct port_data *data, struct sp_port_config *config) +static enum sp_return get_config(struct sp_port *port, struct port_data *data, + struct sp_port_config *config) { unsigned int i; @@ -726,7 +729,8 @@ static int get_config(struct sp_port *port, struct port_data *data, struct sp_po return SP_OK; } -static int set_config(struct sp_port *port, struct port_data *data, const struct sp_port_config *config) +static enum sp_return set_config(struct sp_port *port, struct port_data *data, + const struct sp_port_config *config) { unsigned int i; @@ -1005,7 +1009,7 @@ static int set_config(struct sp_port *port, struct port_data *data, const struct #define TRY(x) do { int ret = x; if (ret != SP_OK) return ret; } while (0) -int sp_set_config(struct sp_port *port, const struct sp_port_config *config) +enum sp_return sp_set_config(struct sp_port *port, const struct sp_port_config *config) { struct port_data data; struct sp_port_config prev_config; @@ -1021,7 +1025,7 @@ int sp_set_config(struct sp_port *port, const struct sp_port_config *config) return SP_OK; } -#define CREATE_SETTER(x) int sp_set_##x(struct sp_port *port, int x) { \ +#define CREATE_SETTER(x, type) int sp_set_##x(struct sp_port *port, type x) { \ struct port_data data; \ struct sp_port_config config; \ CHECK_PORT(); \ @@ -1031,17 +1035,17 @@ int sp_set_config(struct sp_port *port, const struct sp_port_config *config) return SP_OK; \ } -CREATE_SETTER(baudrate) -CREATE_SETTER(bits) -CREATE_SETTER(parity) -CREATE_SETTER(stopbits) -CREATE_SETTER(rts) -CREATE_SETTER(cts) -CREATE_SETTER(dtr) -CREATE_SETTER(dsr) -CREATE_SETTER(xon_xoff) - -int sp_set_flowcontrol(struct sp_port *port, int flowcontrol) +CREATE_SETTER(baudrate, int) +CREATE_SETTER(bits, int) +CREATE_SETTER(parity, enum sp_parity) +CREATE_SETTER(stopbits, int) +CREATE_SETTER(rts, enum sp_rts) +CREATE_SETTER(cts, enum sp_cts) +CREATE_SETTER(dtr, enum sp_dtr) +CREATE_SETTER(dsr, enum sp_dsr) +CREATE_SETTER(xon_xoff, enum sp_xonxoff) + +enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flowcontrol) { struct port_data data; struct sp_port_config config;