include/ptlib/remconn.h

   1 /*
   2  * remconn.h
   3  *
   4  * Remote networking connection 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  2003/09/17 05:41:59  csoutheren
  34  * Removed recursive includes
  35  *
  36  * Revision 1.16  2003/09/17 01:18:02  csoutheren
  37  * Removed recursive include file system and removed all references
  38  * to deprecated coooperative threading support
  39  *
  40  * Revision 1.15  2002/09/16 01:08:59  robertj
  41  * Added #define so can select if #pragma interface/implementation is used on
  42  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  43  *
  44  * Revision 1.14  2001/05/22 12:49:32  robertj
  45  * Did some seriously wierd rewrite of platform headers to eliminate the
  46  *   stupid GNU compiler warning about braces not matching.
  47  *
  48  * Revision 1.13  1999/03/09 02:59:50  robertj
  49  * Changed comments to doc++ compatible documentation.
  50  *
  51  * Revision 1.12  1999/02/16 08:11:10  robertj
  52  * MSVC 6.0 compatibility changes.
  53  *
  54  * Revision 1.11  1998/09/23 06:21:17  robertj
  55  * Added open source copyright license.
  56  *
  57  * Revision 1.10  1998/07/24 06:58:27  robertj
  58  * Added ability to get IP number of RAS connection.
  59  *
  60  * Revision 1.9  1998/02/03 06:28:46  robertj
  61  * Added more error codes.
  62  *
  63  * Revision 1.8  1998/01/26 00:34:51  robertj
  64  * Added parameter to PRemoteConnection to open only if already connected.
  65  * Added function to PRemoteConnection to get at OS error code.
  66  *
  67  * Revision 1.7  1997/04/01 06:00:05  robertj
  68  * Added Remove Configuration.
  69  *
  70  * Revision 1.6  1997/01/12 04:15:11  robertj
  71  * Added ability to add/change new connections.
  72  *
  73  * Revision 1.5  1996/11/04 03:40:43  robertj
  74  * Added more debugging for remote drop outs.
  75  *
  76  * Revision 1.4  1996/08/11 07:03:45  robertj
  77  * Changed remote connection to late bind DLL.
  78  *
  79  * Revision 1.3  1996/04/23 11:33:04  robertj
  80  * Added username and password.
  81  *
  82  * Revision 1.2  1996/03/02 03:09:48  robertj
  83  * Added function to get all possible remote access connection names.
  84  *
  85  * Revision 1.1  1995/12/10 13:04:46  robertj
  86  * Initial revision
  87  *
  88  */
  89
  90 #ifndef _PREMOTECONNECTION
  91 #define _PREMOTECONNECTION
  92
  93 #ifdef P_USE_PRAGMA
  94 #pragma interface
  95 #endif
  96
  97 #include <ptlib/pipechan.h>
  98
  99 #ifdef _WIN32
 100 #include <ras.h>
 101 #include <raserror.h>
 102 #endif
 103
 104 /** Remote Access Connection class.
 105 */
 106 class PRemoteConnection : public PObject
 107 {
 108   PCLASSINFO(PRemoteConnection, PObject);
 109
 110   public:
 111   /**@name Construction */
 112   //@{
 113     /// Create a new remote connection.
 114     PRemoteConnection();
 115
 116     /**Create a new remote connection.
 117        This will initiate the connection using the specified settings.
 118      */
 119     PRemoteConnection(
 120       const PString & name  ///< Name of RAS configuration.
 121     );
 122
 123     /// Disconnect remote connection.
 124     ~PRemoteConnection();
 125   //@}
 126
 127   /**@name Overrides from class PObject */
 128   //@{
 129     /** Compare two connections.
 130       @return EqualTo of same RAS connectionconfiguration.
 131      */
 132     virtual Comparison Compare(
 133       const PObject & obj     ///< Another connection instance.
 134     ) const;
 135
 136     /** Get has value for the connection
 137         @return Hash value of the connection name string.
 138       */
 139     virtual PINDEX HashFunction() const;
 140   //@}
 141
 142   /**@name Dial/Hangup functions */
 143   //@{
 144     /** Open the remote connection.
 145      */
 146     BOOL Open(
 147       BOOL existing = FALSE  ///< Flag for open only if already connected.
 148     );
 149
 150     /** Open the remote connection.
 151      */
 152     BOOL Open(
 153       const PString & name,   ///< RAS name of of connection to open.
 154       BOOL existing = FALSE   ///< Flag for open only if already connected.
 155     );
 156
 157     /** Open the remote connection.
 158      */
 159     BOOL Open(
 160       const PString & name,     ///< RAS name of of connection to open.
 161       const PString & username, ///< Username for remote log in.
 162       const PString & password, ///< password for remote log in.
 163       BOOL existing = FALSE     ///< Flag for open only if already connected.
 164     );
 165
 166     /** Close the remote connection.
 167         This will hang up/dosconnect the connection, net access will no longer
 168         be available to this site.
 169       */
 170     void Close();
 171   //@}
 172
 173   /**@name Error/Status functions */
 174   //@{
 175     /// Status codes for remote connection.
 176     enum Status {
 177       /// Connection has not been made and no attempt is being made.
 178       Idle,
 179       /// Connection is completed and active.
 180       Connected,
 181       /// Connection is in progress.
 182       InProgress,
 183       /// Connection failed due to the line being busy.
 184       LineBusy,
 185       /// Connection failed due to the line havin no dial tone.
 186       NoDialTone,
 187       /// Connection failed due to the remote not answering.
 188       NoAnswer,
 189       /// Connection failed due to the port being in use.
 190       PortInUse,
 191       /// Connection failed due to the RAS setting name/number being incorrect.
 192       NoNameOrNumber,
 193       /// Connection failed due to insufficient privilege.
 194       AccessDenied,
 195       /// Connection failed due to a hardware failure.
 196       HardwareFailure,
 197       /// Connection failed due to a general failure.
 198       GeneralFailure,
 199       /// Connection was lost after successful establishment.
 200       ConnectionLost,
 201       /// The Remote Access Operating System support is not installed.
 202       NotInstalled,
 203       NumStatuses
 204     };
 205
 206     /**Get the current status of the RAS connection.
 207
 208        @return
 209        Status code.
 210      */
 211     Status GetStatus() const;
 212
 213     /**Get the error code for the last operation.
 214
 215        @return
 216        Operating system error code.
 217      */
 218     DWORD GetErrorCode() const { return osError; }
 219   //@}
 220
 221   /**@name Information functions */
 222   //@{
 223     /**Get the name of the RAS connection.
 224
 225        @return
 226        String for IP address, or empty string if none.
 227      */
 228     const PString & GetName() const { return remoteName; }
 229
 230     /**Get the IP address in dotted decimal form for the RAS connection.
 231
 232        @return
 233        String for IP address, or empty string if none.
 234      */
 235     PString GetAddress();
 236
 237     /**Get an array of names for all of the available remote connections on
 238        this system.
 239
 240        @return
 241        Array of strings for remote connection names.
 242      */
 243     static PStringArray GetAvailableNames();
 244   //@}
 245
 246   /**@name Configuration functions */
 247   //@{
 248     /// Structure for a RAS configuration.
 249     struct Configuration {
 250       /// Device name for connection eg /dev/modem
 251       PString device;
 252       /// Telephone number to call to make the connection.
 253       PString phoneNumber;
 254       /// IP address of local machine after connection is made.
 255       PString ipAddress;
 256       /// DNS host on remote site.
 257       PString dnsAddress;
 258       /// Script name for doing remote log in.
 259       PString script;
 260       /// Sub-entry number when Multi-link PPP is used.
 261       PINDEX  subEntries;
 262       /// Always establish maximum bandwidth when Multi-link PPP is used.
 263       BOOL    dialAllSubEntries;
 264     };
 265
 266     /**Get the configuration of the specified remote access connection.
 267
 268        @return
 269        #Connected# if the configuration information was obtained,
 270        #NoNameOrNumber# if the particular RAS name does not exist,
 271        #NotInstalled# if there is no RAS support in the operating system,
 272        #GeneralFailure# on any other error.
 273      */
 274     Status GetConfiguration(
 275       Configuration & config  ///< Configuration of remote connection
 276     );
 277
 278     /**Get the configuration of the specified remote access connection.
 279
 280        @return
 281        #Connected# if the configuration information was obtained,
 282        #NoNameOrNumber# if the particular RAS name does not exist,
 283        #NotInstalled# if there is no RAS support in the operating system,
 284        #GeneralFailure# on any other error.
 285      */
 286     static Status GetConfiguration(
 287       const PString & name,   ///< Remote connection name to get configuration
 288       Configuration & config  ///< Configuration of remote connection
 289     );
 290
 291     /**Set the configuration of the specified remote access connection.
 292
 293        @return
 294        #Connected# if the configuration information was set,
 295        #NoNameOrNumber# if the particular RAS name does not exist,
 296        #NotInstalled# if there is no RAS support in the operating system,
 297        #GeneralFailure# on any other error.
 298      */
 299     Status SetConfiguration(
 300       const Configuration & config,  ///< Configuration of remote connection
 301       BOOL create = FALSE            ///< Flag to create connection if not present
 302     );
 303
 304     /**Set the configuration of the specified remote access connection.
 305
 306        @return
 307        #Connected# if the configuration information was set,
 308        #NoNameOrNumber# if the particular RAS name does not exist,
 309        #NotInstalled# if there is no RAS support in the operating system,
 310        #GeneralFailure# on any other error.
 311      */
 312     static Status SetConfiguration(
 313       const PString & name,          ///< Remote connection name to configure
 314       const Configuration & config,  ///< Configuration of remote connection
 315       BOOL create = FALSE            ///< Flag to create connection if not present
 316     );
 317
 318     /**Remove the specified remote access connection.
 319
 320        @return
 321        #Connected# if the configuration information was removed,
 322        #NoNameOrNumber# if the particular RAS name does not exist,
 323        #NotInstalled# if there is no RAS support in the operating system,
 324        #GeneralFailure# on any other error.
 325      */
 326     static Status RemoveConfiguration(
 327       const PString & name          ///< Remote connection name to configure
 328     );
 329   //@}
 330
 331   protected:
 332     PString remoteName;
 333     PString userName;
 334     PString password;
 335     DWORD osError;
 336
 337   private:
 338     PRemoteConnection(const PRemoteConnection &) { }
 339     void operator=(const PRemoteConnection &) { }
 340     void Construct();
 341
 342
 343 // Include platform dependent part of class
 344 #ifdef _WIN32
 345 #include "msos/ptlib/remconn.h"
 346 #else
 347 #include "unix/ptlib/remconn.h"
 348 #endif
 349 };
 350
 351 #endif
 352
 353 // End Of File ///////////////////////////////////////////////////////////////