PortableSerialLib  v0.4
a portable serial port lib
PortableSerialLib.h
Go to the documentation of this file.
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 */