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