PortableSerialLib
v0.4
a portable serial port lib
|
00001 /*********************************************************************************************//** 00002 * @file PortableSerialLib.h 00003 * 00004 * 00005 * @author Copyright (c) 2012 René Staffen r.staffen@gmx.de 00006 * @version $Id: PortableSerialLib.h 17 2012-03-10 22:36:04Z Vlad $ 00007 * 00008 * @copyright This program is free software; you can redistribute it 00009 * and/or modify it under the terms of the GNU General Public 00010 * License as published by the Free Software Foundation; 00011 * either version 2 of the License, or (at your option) any 00012 * later version. 00013 * For a full text of the license look at the enclosed gpl2.txt 00014 * or at http://www.gnu.org/licenses/gpl-2.0.html 00015 * 00016 * @details 00017 * 00018 * 00019 *//*********************************************************************************************/ 00020 00021 #ifndef _PortableSerialLib_h__3322127 00022 #define _PortableSerialLib_h__3322127 00023 00024 00025 #include <inttypes.h> 00026 00027 #ifdef __cplusplus 00028 extern "C" { 00029 #endif 00030 00031 /** 00032 * if 0 only a short name is reported by PSerLib_getAvailablePorts 00033 * function (without the device path) 00034 * 00035 * @todo consider make argument PSerLib_getAvailablePorts 00036 */ 00037 #define PSL_REPORT_FULL_DEVICE_NAME 0 00038 00039 /** Handle that represents a serial port object */ 00040 typedef struct PSerLibHandleInternal_t * PSerLibHandle_t; 00041 00042 /** Indicates a bad Handle */ 00043 #define PSL_NOPORT_HANDLE ((PSerLibHandle_t)(0)) 00044 00045 /** 00046 * predefined baud rate constants \see PSerLib_setParams 00047 * some may not supported by different platforms 00048 */ 00049 typedef enum PSL_Baudrates_e{ 00050 PSL_BR_50 =0, 00051 PSL_BR_75 , 00052 PSL_BR_110 , 00053 PSL_BR_134 , 00054 PSL_BR_150 , 00055 PSL_BR_200 , 00056 PSL_BR_300 , 00057 PSL_BR_600 , 00058 PSL_BR_1200 , 00059 PSL_BR_1800 , 00060 PSL_BR_2400 , 00061 PSL_BR_4800 , 00062 PSL_BR_9600 , 00063 PSL_BR_14400 , 00064 PSL_BR_19200 , 00065 PSL_BR_28800 , 00066 PSL_BR_38400 , 00067 PSL_BR_56000 , 00068 PSL_BR_57600 , 00069 PSL_BR_115200 , 00070 PSL_BR_128000 , 00071 PSL_BR_230400 , 00072 PSL_BR_256000 , 00073 PSL_BR_460800 , 00074 PSL_BR_500000 , 00075 PSL_BR_576000 , 00076 PSL_BR_921600 , 00077 PSL_BR_1000000, 00078 PSL_BR_1152000, 00079 PSL_BR_1500000, 00080 PSL_BR_2000000, 00081 PSL_BR_2500000, 00082 PSL_BR_3000000, 00083 PSL_BR_3500000, 00084 PSL_BR_4000000, 00085 PSL_BR_CONSTANTS_COUNT 00086 }PSL_Baudrates_e; 00087 00088 /** 00089 * Constants for configuring number of data bits per transmitted character. 00090 * \see PSerLib_setParams 00091 */ 00092 typedef enum PSL_NumDataBits_e{ 00093 PSL_DB_5 = 0, 00094 PSL_DB_6, 00095 PSL_DB_7, 00096 PSL_DB_8, 00097 PSL_DB_CONSTANTS_COUNT 00098 }PSL_NumDataBits_e; 00099 00100 /** Constants for parity settings \see PSerLib_setParams */ 00101 typedef enum PSL_Parity_e{ 00102 PSL_P_none = 0, 00103 PSL_P_odd, 00104 PSL_P_even, 00105 PSL_P_mark, 00106 PSL_P_space, 00107 PSL_P_CONSTANTS_COUNT, 00108 }PSL_Parity_e; 00109 00110 /** 00111 * Constants for configuring number of stop bits per transmitted character. 00112 * \see PSerLib_setParams 00113 */ 00114 typedef enum PSL_StopBits_e{ 00115 PSL_SB_1 = 0, 00116 PSL_SB_1p5, 00117 PSL_SB_2, 00118 PSL_SB_CONSTANTS_COUNT, 00119 }PSL_StopBits_e; 00120 00121 /** 00122 * Constants for configuring flow control. 00123 * \see PSerLib_setParams 00124 */ 00125 typedef enum PSL_FlowControl_e{ 00126 PSL_FC_none = 0, 00127 PSL_FC_rts_cts, 00128 PSL_FC_xon_xoff, 00129 PSL_FC_rts_cts__xon_xoff, 00130 PSL_FC_CONSTANTS_COUNT, 00131 }PSL_FlowControl_e; 00132 00133 00134 /** 00135 * Error codes that may be returned by the functions. 00136 * \see PSerLib_getErrorMessage 00137 */ 00138 typedef enum PSL_ErrorCodes_e{ 00139 PSL_ERROR_none = 0, 00140 PSL_ERROR_couldNotOpen, 00141 PSL_ERROR_invalidHandle, 00142 PSL_ERROR_unsupportedBitrate, 00143 PSL_ERROR_unsupportedConfig, 00144 PSL_ERROR_configurePort, 00145 PSL_ERROR_notYetImplemented, 00146 PSL_ERROR_bufferToSmall, 00147 00148 PSL_ERROR_writeDataFailed, 00149 PSL_ERROR_readDataFailed, 00150 00151 00152 PSL_ERROR_START_WIN_SPECIFIC = 1000, 00153 PSL_ERROR_couldNotOpenRegistryKey = PSL_ERROR_START_WIN_SPECIFIC, 00154 PSL_ERROR_couldNotIterateRegistryValues, 00155 PSL_ERROR_creatingDCBA, 00156 PSL_ERROR_setComState, 00157 00158 PSL_ERROR_START_LINUX_SPECIFIC = 2000, 00159 PSL_ERROR_couldNotReadProcTtyFile = PSL_ERROR_START_LINUX_SPECIFIC, 00160 PSL_ERROR_couldParseProcTtyFile, 00161 PSL_ERROR_couldNotReadSysClassTty, 00162 00163 00164 PSL_ERROR_CODES_COUNT 00165 }PSL_ErrorCodes_e; 00166 00167 00168 /** 00169 * @brief translates an error code in something printable 00170 * @param i_errorCode the error code to translate 00171 * @returns pointer to a null-terminated string that gives a short 00172 * description of the error 00173 * @ingroup PortUtility 00174 */ 00175 const char* PSerLib_getErrorMessage(PSL_ErrorCodes_e i_errorCode); 00176 00177 00178 /** 00179 * @brief returns a list with device names of available serial ports 00180 * 00181 * @param o_names buffer for output\n 00182 * Each device name is quit a \\0 character. 00183 * An empty name indicates the end of the list.\n 00184 * Look at details - section for an example how to use the output. 00185 * @param i_maxlen length of buffer 00186 * @param o_numPortsFound pointer to variable that receives the number of ports found 00187 * 00188 * @returns PSL_ERROR_none if successful else another error code 00189 * 00190 * @details Fiddeling out devices may be done in following fashion: 00191 \code{.c} 00192 char buff[1000]; 00193 char* iterator = buff; 00194 int n; 00195 PSerLib_getAvailablePorts(buff, sizeof(buff), &n); 00196 printf("found %i devices:\n", n); 00197 for( ;*iterator; iterator+=strlen(iterator)+1 ) 00198 { 00199 printf("%s\n",iterator); 00200 } 00201 \endcode 00202 * @ingroup PortUtility 00203 */ 00204 PSL_ErrorCodes_e PSerLib_getAvailablePorts(char* o_names, int i_maxlen, int* o_numPortsFound); 00205 00206 00207 /** 00208 * tries to open the specified serial port 00209 * @param i_portName name of the port to open\n 00210 * These names are indeed some kind of platform specific - sorry. 00211 * But you may get a list of possible ports from \see PSerLib_getAvailablePorts. 00212 * @param o_handle pointer to a handle variable that receives the handle to the opened 00213 * port on success or PSL_NOPORT_HANDLE if opening failed 00214 * 00215 * @returns PSL_ERROR_none if successful else another error code 00216 * @ingroup PortHandling 00217 */ 00218 PSL_ErrorCodes_e PSerLib_open(const char* i_portName, PSerLibHandle_t* o_handle); 00219 00220 00221 /** 00222 * @brief closes and deinitializes the port 00223 * 00224 * @param io_portH pointer to port handle to close. 00225 * The handle will be invalidated. 00226 * @returns PSL_ERROR_none if successful else another error code 00227 * @ingroup PortHandling 00228 */ 00229 PSL_ErrorCodes_e PSerLib_close(PSerLibHandle_t* io_portH); 00230 00231 00232 00233 /** 00234 * @brief sets the port to the given configuration 00235 * @attention currently not all baud rates are supported on 00236 * linux (have to figure out how to set custom baud 00237 * rates that are not defined in termios) 00238 * 00239 * @todo support all enumerated and custom baud rates 00240 * 00241 * @param io_port handle of port to be configured 00242 * @param i_baudrate baudrate if argument is less than PSL_BR_CONSTANTS_COUNT 00243 * it is interpreted as one of the enumerated constants. 00244 * If it is larger it is interpreted as baudrate. 00245 * @param i_bits number of data bits 00246 * @param i_parity parity 00247 * @param i_stopbits number of stopbits 00248 * @param i_flowControl flow control to use 00249 * 00250 * @returns PSL_ERROR_none if successful else another error code 00251 * @ingroup PortHandling 00252 */ 00253 PSL_ErrorCodes_e PSerLib_setParams(PSerLibHandle_t io_port, 00254 PSL_Baudrates_e i_baudrate, 00255 PSL_NumDataBits_e i_bits, 00256 PSL_Parity_e i_parity, 00257 PSL_StopBits_e i_stopbits, 00258 PSL_FlowControl_e i_flowControl 00259 ); 00260 00261 /** 00262 * @todo specify 00263 * @ingroup PortHandling 00264 */ 00265 PSL_ErrorCodes_e PSerLib_setTimeOuts(PSerLibHandle_t io_port); 00266 00267 00268 /** 00269 * @brief outputs the given character to the port 00270 * 00271 * @param io_port handle of port to write to 00272 * @param c character to send 00273 * 00274 * @returns PSL_ERROR_none if successful else another error code 00275 * @ingroup PortWrite 00276 */ 00277 PSL_ErrorCodes_e PSerLib_putc(PSerLibHandle_t io_port, char c); 00278 00279 00280 /** 00281 * @brief outputs the given string to the port 00282 * 00283 * @param io_port handle of port to write to 00284 * @param i_str null terminated string 00285 * 00286 * @returns PSL_ERROR_none if successful else another error code 00287 * @ingroup PortWrite 00288 */ 00289 PSL_ErrorCodes_e PSerLib_puts(PSerLibHandle_t io_port, const char* i_str); 00290 00291 00292 /** 00293 * @brief outputs the given data to the port 00294 * 00295 * @param io_port handle of port to write to 00296 * @param i_data pointer to data to output 00297 * @param i_dataLen number of bytes to read from data pointer 00298 * @param o_bytesWritten number of bytes actual written 00299 * (May differ because of time out or error)\n 00300 * Can be NULL if not required. 00301 * 00302 * @remark Sending/receiving of binary data may be incompatible with 00303 * connections that base on XON/XOFF flow control 00304 * because XON/XOFF are special bytes. 00305 * If you use XON/XOFF flow control then ensure that these 00306 * bytes cannot appear in i_data else your communication may 00307 * screw up. 00308 * 00309 * @returns PSL_ERROR_none if successful else another error code 00310 * @ingroup PortWrite 00311 */ 00312 PSL_ErrorCodes_e PSerLib_writeBinaryData( PSerLibHandle_t io_port, 00313 const uint8_t* i_data, 00314 int i_dataLen, 00315 int* o_bytesWritten); 00316 00317 00318 00319 /** 00320 * @brief reads data from the port 00321 * 00322 * @param io_port handle of port to read from 00323 * @param o_string pointer to buffer where the data should be stored. 00324 * @param i_bufferLength number of bytes the buffer can take. 00325 * Remember that the buffer also have to take the end 00326 * character and terminating \\0 character 00327 * @param i_endLineChars \\0 terminated string, that contains characters 00328 * that indicates line end. 00329 * The line end character will also be copied into 00330 * output buffer. 00331 * 00332 * @returns PSL_ERROR_none if successful else another error code 00333 * @ingroup PortRead 00334 */ 00335 PSL_ErrorCodes_e PSerLib_readLine( PSerLibHandle_t io_port, 00336 char* o_string, 00337 int i_bufferLength, 00338 const char* i_endLineChars); 00339 00340 00341 /** 00342 * @brief reads data from the port 00343 * 00344 * @param io_port handle of port to read from 00345 * @param o_data pointer to buffer where the data should be stored. 00346 * Ensure that the buffer can take at least i_dataToRead 00347 * bytes. 00348 * @param i_dataToRead number of bytes to read 00349 * @param o_bytesRead number of bytes actual read 00350 * (May differ because of time out or error)\n 00351 * Can be NULL if not required. 00352 * 00353 * @remark see remarks of PSerLib_writeBinaryData 00354 * 00355 * @returns PSL_ERROR_none if successful else another error code 00356 * @ingroup PortRead 00357 */ 00358 PSL_ErrorCodes_e PSerLib_readBinaryData( PSerLibHandle_t io_port, 00359 uint8_t* o_data, 00360 int i_dataToRead, 00361 int* o_bytesRead); 00362 00363 00364 00365 #ifdef __cplusplus 00366 } 00367 #endif 00368 00369 #endif /* _PortableSerialLib_h__3322127 */