include/ptlib/serchan.h

   1 /*
   2  * serchan.h
   3  *
   4  * Asynchronous Serial I/O channel class.
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
  25  * All Rights Reserved.
  26  *
  27  * Contributor(s): ______________________________________.
  28  *
  29  * $Log$
  30  * Revision 1.18  2005/11/25 03:43:47  csoutheren
  31  * Fixed function argument comments to be compatible with Doxygen
  32  *
  33  * Revision 1.17  2005/02/20 21:18:30  dereksmithies
  34  * Fix documentation typos.
  35  *
  36  * Revision 1.16  2003/09/17 05:41:59  csoutheren
  37  * Removed recursive includes
  38  *
  39  * Revision 1.15  2003/09/17 01:18:02  csoutheren
  40  * Removed recursive include file system and removed all references
  41  * to deprecated coooperative threading support
  42  *
  43  * Revision 1.14  2002/09/16 01:08:59  robertj
  44  * Added #define so can select if #pragma interface/implementation is used on
  45  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  46  *
  47  * Revision 1.13  2001/05/22 12:49:32  robertj
  48  * Did some seriously wierd rewrite of platform headers to eliminate the
  49  *   stupid GNU compiler warning about braces not matching.
  50  *
  51  * Revision 1.12  1999/03/09 02:59:50  robertj
  52  * Changed comments to doc++ compatible documentation.
  53  *
  54  * Revision 1.11  1999/02/16 08:11:10  robertj
  55  * MSVC 6.0 compatibility changes.
  56  *
  57  * Revision 1.10  1998/09/23 06:21:21  robertj
  58  * Added open source copyright license.
  59  *
  60  * Revision 1.9  1995/07/31 12:15:46  robertj
  61  * Removed PContainer from PChannel ancestor.
  62  *
  63  * Revision 1.8  1995/06/17 11:13:18  robertj
  64  * Documentation update.
  65  *
  66  * Revision 1.7  1995/03/14 12:42:33  robertj
  67  * Updated documentation to use HTML codes.
  68  *
  69  * Revision 1.6  1995/01/14  06:19:37  robertj
  70  * Documentation
  71  *
  72  * Revision 1.5  1994/08/23  11:32:52  robertj
  73  * Oops
  74  *
  75  * Revision 1.4  1994/08/22  00:46:48  robertj
  76  * Added pragma fro GNU C++ compiler.
  77  *
  78  * Revision 1.3  1994/07/17  10:46:06  robertj
  79  * Moved data to PChannel class.
  80  *
  81  * Revision 1.2  1994/06/25  11:55:15  robertj
  82  * Unix version synchronisation.
  83  *
  84  * Revision 1.1  1994/04/20  12:17:44  robertj
  85  * Initial revision
  86  *
  87  */
  88
  89 #ifndef _PSERIALCHANNEL
  90 #define _PSERIALCHANNEL
  91
  92 #ifdef P_USE_PRAGMA
  93 #pragma interface
  94 #endif
  95
  96
  97 class PConfig;
  98
  99
 100 ///////////////////////////////////////////////////////////////////////////////
 101 // Serial Channel
 102
 103 /**This class defines an I/O channel that communicates via a serial port. This
 104    is usually an RS-232 port.
 105  */
 106 class PSerialChannel : public PChannel
 107 {
 108   PCLASSINFO(PSerialChannel, PChannel);
 109
 110   public:
 111   /**@name Construction */
 112   //@{
 113     /// Create a new serial channel object, but do not open it.
 114     PSerialChannel();
 115
 116     /// Configuration of serial port parity options.
 117     enum Parity {
 118       /// Use the default parity, ie do not change it.
 119       DefaultParity,
 120       /// Set the port for no parity bit.
 121       NoParity,
 122       /// Set the port to generate parity and make it even.
 123       EvenParity,
 124       /// Set the port to generate parity and make it odd.
 125       OddParity,
 126       /// Set the port parity bit to mark only.
 127       MarkParity,
 128       /// Set the port parity bit to space only.
 129       SpaceParity
 130     };
 131
 132     /// Configuration of serial port flow control options.
 133     enum FlowControl {
 134       /// Use the default flow control, ie do not change it.
 135       DefaultFlowControl,
 136       /// Set the port for no flow control.
 137       NoFlowControl,
 138       /// Set the port for software or XON/XOFF flow control.
 139       XonXoff,
 140       /// Set the port for hardware or RTS/CTS flow control.
 141       RtsCts
 142     };
 143
 144     /**Create a serial channal.
 145        The channel is opened it on the specified port and with the specified
 146        attributes.
 147      */
 148     PSerialChannel(
 149       /**The name of the serial port to connect to. This is a platform
 150          dependent string and woiuld rarely be a literal. The static function
 151          #GetPortNames()# can be used to find the platforms serial ports.
 152        */
 153       const PString & port,
 154       /**Serial port speed or baud rate. The actual values possible here are
 155          platform dependent, but the standard value of 300, 1200, 2400, 4800,
 156          9600, 19200, 38400 always be legal.
 157        */
 158       DWORD speed = 0,
 159       /**Number of data bits for serial port. The actual values possible here
 160          are platform dependent, but 7 and 8 should always be legal.
 161        */
 162       BYTE data = 0,
 163       /**Parity for serial port. The actual values possible here are platform
 164          dependent, but #NoParity#, #OddParity# and
 165          #EvenParity# should always be legal.
 166        */
 167       Parity parity = DefaultParity,
 168       /**Number of stop bits for serial port. The actual values possible here
 169          are platform dependent, but 1 and 2 should always be legal.
 170        */
 171       BYTE stop = 0,
 172       /**Flow control for data from the remote system into this conputer.*/
 173       FlowControl inputFlow = DefaultFlowControl,
 174       /**Flow control for data from this conputer out to remote system. */
 175       FlowControl outputFlow = DefaultFlowControl
 176     );
 177
 178     /**Create a serial channal.
 179        The channel is opened using attributes obtained from standard variables
 180        in the configuration file. Note that it assumed that the correct
 181        configuration file section is already set.
 182      */
 183     PSerialChannel(
 184       PConfig & cfg  ///< Configuration file to read serial port attributes from.
 185     );
 186
 187     /// Close the serial channel on destruction.
 188     ~PSerialChannel();
 189   //@}
 190
 191
 192   /**@name Open functions */
 193   //@{
 194     /**Open a serial channal.
 195        The channel is opened it on the specified port and with the specified
 196        attributes.
 197      */
 198     virtual BOOL Open(
 199       /**The name of the serial port to connect to. This is a platform
 200          dependent string and woiuld rarely be a literal. The static function
 201          #GetPortNames()# can be used to find the platforms serial ports.
 202        */
 203       const PString & port,
 204       /**Serial port speed or baud rate. The actual values possible here are
 205          platform dependent, but the standard value of 300, 1200, 2400, 4800,
 206          9600, 19200, 38400 always be legal.
 207        */
 208       DWORD speed = 0,
 209       /**Number of data bits for serial port. The actual values possible here
 210          are platform dependent, but 7 and 8 should always be legal.
 211        */
 212       BYTE data = 0,
 213       /**Parity for serial port. The actual values possible here are platform
 214          dependent, but #NoParity#, #OddParity# and
 215          #EvenParity# should always be legal.
 216        */
 217       Parity parity = DefaultParity,
 218       /**Number of stop bits for serial port. The actual values possible here
 219          are platform dependent, but 1 and 2 should always be legal.
 220        */
 221       BYTE stop = 0,
 222       /**Flow control for data from the remote system into this conputer.*/
 223       FlowControl inputFlow = DefaultFlowControl,
 224       /**Flow control for data from this conputer out to remote system. */
 225       FlowControl outputFlow = DefaultFlowControl
 226     );
 227
 228     /**Open a serial channal.
 229        The channel is opened using attributes obtained from standard variables
 230        in the configuration file. Note that it assumed that the correct
 231        configuration file section is already set.
 232      */
 233     virtual BOOL Open(
 234       PConfig & cfg  ///< Configuration file to read serial port attributes from.
 235     );
 236
 237     /**Get a list of the available serial ports. This returns a set of
 238        platform dependent strings which describe the serial ports of the
 239        computer. For example under unix it may be "ttyS0", under MS-DOS or
 240        NT it would be "COM1" and for the Macintosh it could be "Modem".
 241
 242        @return
 243        list of strings for possible serial ports.
 244      */
 245     static PStringList GetPortNames();
 246   //@}
 247
 248
 249   /**@name Configuration functions */
 250   //@{
 251     /**Set the speed (baud rate) of the serial channel.
 252
 253        @return
 254        TRUE if the change was successfully made.
 255      */
 256     BOOL SetSpeed(
 257       DWORD speed   ///< New speed for serial channel.
 258     );
 259
 260     /**Get the speed (baud rate) of the serial channel.
 261
 262        @return
 263        current setting.
 264      */
 265     DWORD GetSpeed() const;
 266
 267     /**Set the data bits (5, 6, 7 or 8) of the serial port.
 268
 269        @return
 270        TRUE if the change was successfully made.
 271      */
 272     BOOL SetDataBits(
 273       BYTE data   ///< New number of data bits for serial channel.
 274     );
 275
 276     /**Get the data bits (5, 6, 7 or 8) of the serial port.
 277
 278        @return
 279        current setting.
 280      */
 281     BYTE GetDataBits() const;
 282
 283     /**Set the parity of the serial port.
 284
 285        @return
 286        TRUE if the change was successfully made.
 287      */
 288     BOOL SetParity(
 289       Parity parity   ///< New parity option for serial channel.
 290     );
 291
 292     /**Get the parity of the serial port.
 293
 294        @return
 295        current setting.
 296      */
 297     Parity GetParity() const;
 298
 299     /**Set the stop bits (1 or 2) of the serial port.
 300
 301        @return
 302        TRUE if the change was successfully made.
 303      */
 304     BOOL SetStopBits(
 305       BYTE stop   ///< New number of stop bits for serial channel.
 306     );
 307
 308     /**Get the stop bits (1 or 2) of the serial port.
 309
 310        @return
 311        current setting.
 312      */
 313     BYTE GetStopBits() const;
 314
 315     /**Set the flow control (handshaking) protocol of the input to the serial
 316        port.
 317
 318        @return
 319        TRUE if the change was successfully made.
 320      */
 321     BOOL SetInputFlowControl(
 322       FlowControl flowControl   ///< New flow control for serial channel input.
 323     );
 324
 325     /**Get the flow control (handshaking) protocol of the input to the serial
 326        port.
 327
 328        @return
 329        current setting.
 330      */
 331     FlowControl GetInputFlowControl() const;
 332
 333     /**Set the flow control (handshaking) protocol of the output to the serial
 334        port.
 335
 336        @return
 337        TRUE if the change was successfully made.
 338      */
 339     BOOL SetOutputFlowControl(
 340       FlowControl flowControl   ///< New flow control for serial channel output.
 341     );
 342
 343     /**Get the flow control (handshaking) protocol of the output from the
 344        serial port.
 345
 346        @return
 347        current setting.
 348      */
 349     FlowControl GetOutputFlowControl() const;
 350
 351     /**Save the current port settings into the configuration file. Note that
 352        it assumed that the correct configuration file section is already set.
 353      */
 354     virtual void SaveSettings(
 355       PConfig & cfg   ///< Configuration file to save setting into.
 356     );
 357   //@}
 358
 359
 360   /**@name Status functions */
 361   //@{
 362     /** Set the Data Terminal Ready signal of the serial port. */
 363     void SetDTR(
 364       BOOL state = TRUE   ///< New state of the DTR signal.
 365     );
 366
 367     /**Clear the Data Terminal Ready signal of the serial port. This is
 368        equivalent to #SetDTR(FALSE)#.
 369      */
 370     void ClearDTR();
 371
 372     /**Set the Request To Send signal of the serial port. */
 373     void SetRTS(
 374       BOOL state = TRUE   ///< New state of the RTS signal.
 375     );
 376
 377     /**Clear the Request To Send signal of the serial port. This is equivalent
 378        to #SetRTS(FALSE)#.
 379      */
 380     void ClearRTS();
 381
 382     /** Set the break condition of the serial port. */
 383     void SetBreak(
 384       BOOL state = TRUE   ///< New state of the serial port break condition.
 385     );
 386
 387     /**Clear the break condition of the serial port. This is equivalent to
 388        #SetBreak(FALSE)#.
 389      */
 390     void ClearBreak();
 391
 392     /**Get the Clear To Send signal of the serial port.
 393
 394        @return
 395        TRUE if the CTS signal is asserted.
 396      */
 397     BOOL GetCTS();
 398
 399     /**Get the Data Set Ready signal of the serial port.
 400
 401        @return
 402        TRUE if the DSR signal is asserted.
 403      */
 404     BOOL GetDSR();
 405
 406     /**Get the Data Carrier Detect signal of the serial port.
 407
 408        @return
 409        TRUE if the DCD signal is asserted.
 410      */
 411     BOOL GetDCD();
 412
 413     /**Get the Ring Indicator signal of the serial port.
 414
 415        @return
 416        TRUE if the RI signal is asserted.
 417      */
 418     BOOL GetRing();
 419   //@}
 420
 421
 422   private:
 423     void Construct();
 424     // Platform dependent construct of the serial channel.
 425
 426
 427 // Include platform dependent part of class
 428 #ifdef _WIN32
 429 #include "msos/ptlib/serchan.h"
 430 #else
 431 #include "unix/ptlib/serchan.h"
 432 #endif
 433 };
 434
 435 #endif
 436
 437 // End Of File ///////////////////////////////////////////////////////////////