X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;f=README;h=7666a5c144fe199d862410cfe4f6696d4d2eba68;hb=7f450f46bda085943df503d9d74ed1c8f9d42e7f;hp=2a1e653659f999c85eb6a7745013f4c919dd6eab;hpb=f92f1f0c20ca6ec520d43702ec5f51ca245d7ec9;p=libserialport.git diff --git a/README b/README index 2a1e653..7666a5c 100644 --- a/README +++ b/README @@ -11,6 +11,7 @@ transparently on any platform supported by the library. The operations that are supported are: - Port enumeration (obtaining a list of serial ports on the system). +- Obtaining port metadata (USB device information, Bluetooth address, etc). - Opening and closing ports. - Setting port parameters (baud rate, parity, etc). - Reading, writing and flushing data. @@ -25,26 +26,16 @@ The library should build and work on any Windows or Unix-based system. If it does not, please submit a bug. Enumeration is currently only implemented on Windows, Mac OS X and Linux. On -other systems enumeration will return no results, but ports can still be opened -by name and then used. +other systems enumeration is not supported, but ports can still be opened by +name and then used. If you know how to enumerate available ports on another OS, please submit a bug with this information, or better still a patch implementing it. -Future -====== - -Future versions will add additional API calls for obtaining metadata about a -port, e.g. for USB devices the USB VID and PID of the underlying device. - Dependencies ============ -On Linux, libudev is required. On other systems no other libraries are required. - -The libudev dependency could be eliminated in favour of direct sysfs queries at -the cost of some brevity. This is not currently a priority but if you feel like -doing this feel free to submit a patch. +No other libraries are required. Building ======== @@ -58,192 +49,4 @@ Run "./autogen.sh" to generate the build system, "./configure" to setup, then API === -The API is simple, and designed to be a minimal wrapper around the serial port -support in each OS. - -Most functions take a pointer to a struct sp_port, which represents a serial -port. These structures are always allocated and freed by the library, using the -functions in the 'Enumeration' section below. - -All functions can return only three possible error values. SP_ERR_ARG indicates -the function was called with invalid arguments. SP_ERR_FAIL indicates that the -OS reported a failure. SP_ERR_MEM indicates that a memory allocation failed. -All of these error values are negative. - -When 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. - -Function calls that succeed return SP_OK, which is equal to zero, or where -otherwise documented a positive value. - -The available functions are as follows: - -Enumeration ------------ - -int sp_get_port_by_name(const char *portname, struct sp_port **port_ptr); - - 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 - to this to receive the result. - - The result should be freed after use by calling sp_free_port(). - - Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation - failure, or SP_ERR_ARG if an invalid pointer is passed. If any error - 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. - -void sp_free_port(struct sp_port *port); - - Frees a port structure obtained from sp_get_port_by_name(). - -int sp_list_ports(struct sp_port ***list_ptr); - - Lists the serial ports available on the system. The result obtained is an - array of pointers to sp_port structures, terminated by a NULL. The user should - allocate a variable of type "struct sp_port **" and pass a pointer to this to - receive the result. - - The result should be freed after use by calling sp_free_port_list(). If a port - from the list is to be used after freeing the list, it must be copied first - using sp_copy_port(). - - Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation - failure, or SP_ERR_ARG if an invalid pointer is passed. If any error - 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_copy_port(const struct sp_port *port, struct sp_port **copy_ptr); - - Makes a new copy of a sp_port structure. The user should allocate a variable - of type "struct sp_port *" and pass a pointer to this to receive the result. - - The copy should be freed after use by calling sp_free_port(). - - Returns: SP_OK on success, SP_ERR_MEM on allocation failure, or SP_ERR_ARG - if an invalid port or pointer is passed. If any error is returned, - the variable pointed to by copy_ptr will be set to NULL. Otherwise, - it will be set to point to the newly allocated copy. - -void sp_free_port_list(struct sp_port **list); - - Frees a port list obtained from sp_list_ports(). This will also free all - the sp_port structures referred to from the list; any that are to be retained - must be copied first using sp_copy_port(). - -Opening and closing ports -------------------------- - -int sp_open(struct sp_port *port, int flags); - - Opens the specified serial port. - - Parameters: - - port: Pointer to port structure. - flags: Flags to use when opening the serial port. Possible - flags are: SP_MODE_RDWR, SP_MODE_RDONLY, and SP_MODE_NONBLOCK. - - Returns: 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_close(struct sp_port *port); - - Closes the specified serial port. - - Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG - if an invalid port is passed. - -Setting port parameters ------------------------ - -int sp_set_params(struct sp_port *port, int baudrate, - int bits, int parity, int stopbits, - int flowcontrol, int rts, int dtr); - - Sets serial parameters for the specified serial port. - - Parameters: - - port: Pointer to port structure. - baudrate: Baud rate to set. - bits: Number of data bits to use. - parity: Parity setting to use - (SP_PARITY_NONE, SP_PARITY_EVEN or SP_PARITY_ODD) - stopbits: Number of stop bits to use (1 or 2). - flowcontrol: Flow control setting to use - (SP_FLOW_NONE, SP_FLOW_HARDWARE or SP_FLOW_SOFTWARE) - - Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG - for invalid arguments. - -Reading, writing and flushing data ----------------------------------- - -int sp_read(struct sp_port *port, const void *buf, size_t count) - - Reads bytes from the specified serial port. Note that this function may - return after reading less than the specified number of bytes; it is the - user's responsibility to iterate as necessary in this case. - - Parameters: - - port: Pointer to port structure. - buf: Buffer in which to store the bytes read. - count: Maximum number of bytes to read. - - Returns: The number of bytes read, 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) - - Write bytes to the specified serial port. Note that this function may - return after writing less than the specified number of bytes; it is the - user's responsibility to iterate as necessary in this case. - - Parameters: - - port: Pointer to port structure. - buf: Buffer containing the bytes to write. - count: Maximum number of bytes to write. - - Returns: The number of bytes written, SP_ERR_FAIL on failure, - or SP_ERR_ARG for invalid arguments. - -int sp_flush(struct sp_port *port); - - Flushes serial port buffers. - - Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG - if an invalid port is passed. - -Error handling --------------- - -int sp_last_error_code(); - - Gets the error code for a failed operation. - - In order to obtain the correct result, this function should be called - straight after the failure, before executing any other system operations. - - Returns: The system's numeric code for the error that caused the last - operation to fail. - -char *sp_last_error_message(); - - Gets the error message for failed operation. - - In order to obtain the correct result, this function should be called - straight after the failure, before executing other system operations. - - Returns: The system's message for the error that caused the last - operation to fail. This string may be allocated by the function, - and should be freed after use by calling sp_free_error_message. - -void sp_free_error_message(char *message); - - Frees the error message returned by sp_last_error_message(). +Doxygen API documentation is included.