PortableSerialLib  v0.2
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 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 */