X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=libserialport.h.in;h=67df3d7b9db6e00947909235849021d08184e588;hb=39acdc47db65e64e43d52bea2e425751a96f9780;hp=8fd548e18cbaa4dbde6c2e310810bceb01ab58ea;hpb=deef6e528cabe1858c2c3c5fa45f789f3d701366;p=libserialport.git diff --git a/libserialport.h.in b/libserialport.h.in index 8fd548e..67df3d7 100644 --- a/libserialport.h.in +++ b/libserialport.h.in @@ -1,7 +1,9 @@ /* * This file is part of the libserialport project. * - * Copyright (C) 2013 Martin Ling + * Copyright (C) 2013, 2015 Martin Ling + * Copyright (C) 2014 Uwe Hermann + * Copyright (C) 2014 Aurelien Jacobs * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as @@ -57,9 +59,48 @@ * to restructure things somewhat, or do without some specialised features. * For particular notes on porting existing code, see @ref Porting. * - * The following subsections will help explain the principles of the API. - * To jump directly into the detailed function documentation, see the - * categorised function lists. + * Examples + * -------- + * + * Some simple example programs using libserialport are included in the + * @c examples directory in the source package: + * + * - @ref list_ports.c - Getting a list of ports present on the system. + * - @ref port_info.c - Getting information on a particular serial port. + * + * These examples are linked with the API documentation. Each function + * in the API reference includes links to where it is used in an example + * program, and each appearance of a function in the examples links + * to that function's entry in the API reference. + * + * Headers + * ------- + * + * To use libserialport functions in your code, you should include the + * libserialport.h header, i.e. + * @code + * #include + * @endcode + * + * Namespace + * --------- + * + * All identifiers defined by the public libserialport headers use the prefix + * @c sp_ (for functions and data types) or @c SP_ (for macros and constants). + * + * Functions + * --------- + * + * The functions provided by the library are documented in detail in + * the following sections: + * + * - @ref Enumeration (obtaining a list of serial ports on the system) + * - @ref Ports (opening, closing and getting information about ports) + * - @ref Configuration (baud rate, parity, etc.) + * - @ref Signals (modem control lines, breaks, etc.) + * - @ref Data (reading and writing data, and buffer management) + * - @ref Waiting (waiting for ports to be ready, integrating with event loops) + * - @ref Errors (getting error and debugging information) * * Data structures * --------------- @@ -106,12 +147,12 @@ * numeric result, e.g. sp_blocking_read() or sp_blocking_write(). * * An error message is only available via sp_last_error_message() in the case - * where SP_ERR_FAIL was returned by the previous function call. The error + * where @ref SP_ERR_FAIL was returned by the previous function call. The error * message returned is that provided by the OS, using the current language * settings. It is an error to call sp_last_error_code() or * sp_last_error_message() except after a previous function call returned - * SP_ERR_FAIL. The library does not define its own error codes or messages - * to accompany other return codes. + * @ref SP_ERR_FAIL. The library does not define its own error codes or + * messages to accompany other return codes. * * Thread safety * ------------- @@ -152,7 +193,7 @@ * * The library can output extensive tracing and debugging information. The * simplest way to use this is to set the environment variable - * LIBSERIALPORT_DEBUG to any value; messages will then be output to the + * @c LIBSERIALPORT_DEBUG to any value; messages will then be output to the * standard error stream. * * This behaviour is implemented by a default debug message handling @@ -177,24 +218,24 @@ * for dealing with serial devices at the OS level; this is exposed through the * termios API and dates to the days when serial terminals were common. If your * code relies on many of these facilities you will need to adapt it, because - * libserialport provides only a raw 8-bit channel with no special handling. + * libserialport provides only a raw binary channel with no special handling. * * The second relates to blocking versus non-blocking I/O behaviour. In - * Unix-like systems this is normally specified by setting the O_NONBLOCK - * flag on the file descriptor, affecting the semantics of subsequent read() - * and write() calls. + * Unix-like systems this is normally specified by setting the @c O_NONBLOCK + * flag on the file descriptor, affecting the semantics of subsequent @c read() + * and @c write() calls. * * In libserialport, blocking and nonblocking operations are both available at - * any time. If your existing code ѕets O_NONBLOCK, you should use + * any time. If your existing code ѕets @c O_NONBLOCK, you should use * sp_nonblocking_read() and sp_nonblocking_write() to get the same behaviour - * as your existing read() and write() calls. If it does not, you should use - * sp_blocking_read() and sp_blocking_write() instead. You may also find + * as your existing @c read() and @c write() calls. If it does not, you should + * use sp_blocking_read() and sp_blocking_write() instead. You may also find * sp_blocking_read_next() useful, which reproduces the semantics of a blocking - * read() with VTIME = 0 and VMIN = 1 set in termios. + * read() with @c VTIME=0 and @c VMIN=1 set in termios. * * Finally, you should take care if your program uses custom signal handlers. * The blocking calls provided by libserialport will restart system calls that - * return with EINTR, so you will need to make your own arrangements if you + * return with @c EINTR, so you will need to make your own arrangements if you * need to interrupt blocking operations when your signal handlers are called. * This is not an issue if you only use the default handlers. * @@ -205,23 +246,23 @@ * * If your program does not use overlapped I/O, you can simply use * sp_blocking_read() and sp_blocking_write() as direct equivalents for - * ReadFile() and WriteFile(). You may also find sp_blocking_read_next() - * useful, which reproduces the special semantics of ReadFile() with - * ReadIntervalTimeout and ReadTotalTimeoutMultiplier set to MAXDWORD - * and 0 < ReadTotalTimeoutConstant < MAXDWORD. + * @c ReadFile() and @c WriteFile(). You may also find sp_blocking_read_next() + * useful, which reproduces the special semantics of @c ReadFile() with + * @c ReadIntervalTimeout and @c ReadTotalTimeoutMultiplier set to @c MAXDWORD + * and @c ReadTotalTimeoutConstant set to between @c 1 and @c MAXDWORD-1 . * * If your program makes use of overlapped I/O to continue work while a serial * operation is in progress, then you can achieve the same results using * sp_nonblocking_read() and sp_nonblocking_write(). * * Generally, overlapped I/O is combined with either waiting for completion - * once there is no more background work to do (using WaitForSingleObject() or - * WaitForMultipleObjects()), or periodically checking for completion with - * GetOverlappedResult(). If the aim is to start a new operation for further - * data once the previous one has completed, you can instead simply call the - * nonblocking functions again with the next data. If you need to wait for - * completion, use sp_wait() to determine when the port is ready to send or - * receive further data. + * once there is no more background work to do (using @c WaitForSingleObject() + * or @c WaitForMultipleObjects()), or periodically checking for completion + * with @c GetOverlappedResult(). If the aim is to start a new operation for + * further data once the previous one has completed, you can instead simply + * call the nonblocking functions again with the next data. If you need to + * wait for completion, use sp_wait() to determine when the port is ready to + * send or receive further data. */ #ifndef LIBSERIALPORT_LIBSERIALPORT_H @@ -419,6 +460,8 @@ struct sp_event_set { * * Enumerating the serial ports of a system. * + * See @ref list_ports.c for a working example of port enumeration. + * * @{ */ @@ -508,6 +551,8 @@ void sp_free_port_list(struct sp_port **ports); * * Opening, closing and querying ports. * + * See @ref port_info.c for a working example of getting port information. + * * @{ */ @@ -1577,32 +1622,32 @@ void sp_default_debug_handler(const char *format, ...); */ /** The libserialport package 'major' version number. */ -#define SP_PACKAGE_VERSION_MAJOR @SP_PACKAGE_VERSION_MAJOR@ +#undef SP_PACKAGE_VERSION_MAJOR /** The libserialport package 'minor' version number. */ -#define SP_PACKAGE_VERSION_MINOR @SP_PACKAGE_VERSION_MINOR@ +#undef SP_PACKAGE_VERSION_MINOR /** The libserialport package 'micro' version number. */ -#define SP_PACKAGE_VERSION_MICRO @SP_PACKAGE_VERSION_MICRO@ +#undef SP_PACKAGE_VERSION_MICRO /** The libserialport package version ("major.minor.micro") as string. */ -#define SP_PACKAGE_VERSION_STRING "@SP_PACKAGE_VERSION@" +#undef SP_PACKAGE_VERSION_STRING /* * Library/libtool version macros (can be used for conditional compilation). */ /** The libserialport libtool 'current' version number. */ -#define SP_LIB_VERSION_CURRENT @SP_LIB_VERSION_CURRENT@ +#undef SP_LIB_VERSION_CURRENT /** The libserialport libtool 'revision' version number. */ -#define SP_LIB_VERSION_REVISION @SP_LIB_VERSION_REVISION@ +#undef SP_LIB_VERSION_REVISION /** The libserialport libtool 'age' version number. */ -#define SP_LIB_VERSION_AGE @SP_LIB_VERSION_AGE@ +#undef SP_LIB_VERSION_AGE /** The libserialport libtool version ("current:revision:age") as string. */ -#define SP_LIB_VERSION_STRING "@SP_LIB_VERSION@" +#undef SP_LIB_VERSION_STRING /** * Get the major libserialport package version number. @@ -1680,6 +1725,11 @@ const char *sp_get_lib_version_string(void); /** @} */ +/** + * @example list_ports.c Getting a list of ports present on the system. + * @example port_info.c Getting information on a particular serial port. +*/ + #ifdef __cplusplus } #endif