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