include/wx/dialup.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/dialup.h
   3 // Purpose:     Network related wxWindows classes and functions
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     07.07.99
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Vadim Zeitlin
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_NET_H
  13 #define _WX_NET_H
  14
  15 #ifdef __GNUG__
  16     #pragma interface "dialup.h"
  17 #endif
  18
  19 #if wxUSE_DIALUP_MANAGER
  20
  21 // ----------------------------------------------------------------------------
  22 // constants
  23 // ----------------------------------------------------------------------------
  24
  25 extern const wxChar *wxEmptyString;
  26
  27 #define WXDIALUP_MANAGER_DEFAULT_BEACONHOST  T("www.yahoo.com")
  28
  29 // ----------------------------------------------------------------------------
  30 // A class which groups functions dealing with connecting to the network from a
  31 // workstation using dial-up access to the net. There is at most one instance
  32 // of this class in the program accessed via GetDialUpManager().
  33 // ----------------------------------------------------------------------------
  34
  35 /* TODO
  36  *
  37  * 1. more configurability for Unix: i.e. how to initiate the connection, how
  38  *    to check for online status, &c.
  39  * 2. a function to enumerate all connections (ISPs) and show a dialog in
  40  *    Dial() allowing to choose between them if no ISP given
  41  * 3. add an async version of dialing functions which notify the caller about
  42  *    the progress (or may be even start another thread to monitor it)
  43  * 4. the static creation/accessor functions are not MT-safe - but is this
  44  *    really crucial? I think we may suppose they're always called from the
  45  *    main thread?
  46  */
  47
  48 class WXDLLEXPORT wxDialUpManager
  49 {
  50 public:
  51     // this function should create and return the object of the
  52     // platform-specific class derived from wxDialUpManager. It's implemented
  53     // in the platform-specific source files.
  54     static wxDialUpManager *Create();
  55
  56     // could the dialup manager be initialized correctly? If this function
  57     // returns FALSE, no other functions will work neither, so it's a good idea
  58     // to call this function and check its result before calling any other
  59     // wxDialUpManager methods
  60     virtual bool IsOk() const = 0;
  61
  62     // virtual dtor for any base class
  63     virtual ~wxDialUpManager() { }
  64
  65     // operations
  66     // ----------
  67
  68     // dial the given ISP, use username and password to authentificate
  69     //
  70     // if async parameter is FALSE, the function waits until the end of dialing
  71     // and returns TRUE upon successful completion.
  72     // if async is TRUE, the function only initiates the connection and returns
  73     // immediately - the result is reported via events (an event is sent
  74     // anyhow, but if dialing failed it will be a DISCONNECTED one)
  75     virtual bool Dial(const wxString& nameOfISP = wxEmptyString,
  76                       const wxString& username = wxEmptyString,
  77                       const wxString& password = wxEmptyString,
  78                       bool async = TRUE) = 0;
  79
  80     // returns TRUE if (async) dialing is in progress
  81     virtual bool IsDialing() const = 0;
  82
  83     // cancel dialing the number initiated with Dial(async = TRUE)
  84     // NB: this won't result in DISCONNECTED event being sent
  85     virtual bool CancelDialing() = 0;
  86
  87     // hang up the currently active dial up connection
  88     virtual bool HangUp() = 0;
  89
  90     // online status
  91     // -------------
  92
  93     // returns TRUE if the computer is connected to the network: under Windows,
  94     // this just means that a RAS connection exists, under Unix we check that
  95     // the "well-known host" (as specified by SetWellKnownHost) is reachable
  96     virtual bool IsOnline() const = 0;
  97
  98     // sometimes the built-in logic for determining the online status may fail,
  99     // so, in general, the user should be allowed to override it. This function
 100     // allows to forcefully set the online status - whatever our internal
 101     // algorithm may think about it.
 102     virtual void SetOnlineStatus(bool isOnline = TRUE) = 0;
 103
 104     // set misc wxDialUpManager options
 105     // --------------------------------
 106
 107     // enable automatical checks for the connection status and sending of
 108     // wxEVT_DIALUP_CONNECTED/wxEVT_DIALUP_DISCONNECTED events. The interval
 109     // parameter is only for Unix where we do the check manually: under
 110     // Windows, the notification about the change of connection status is
 111     // instantenous.
 112     //
 113     // Returns FALSE if couldn't set up automatic check for online status.
 114     virtual bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60) = 0;
 115
 116     // disable automatic check for connection status change - notice that the
 117     // wxEVT_DIALUP_XXX events won't be sent any more neither.
 118     virtual void DisableAutoCheckOnlineStatus() = 0;
 119
 120     // additional Unix-only configuration
 121     // ----------------------------------
 122
 123     // under Unix, the value of well-known host is used to check whether we're
 124     // connected to the internet. It's unused under Windows, but this function
 125     // is always safe to call. The default value is www.yahoo.com.
 126     virtual void SetWellKnownHost(const wxString& hostname,
 127                                   int portno = 80) = 0;
 128
 129     // Sets the commands to start up the network and to hang up again. Used by
 130     // the Unix implementations only.
 131     virtual void
 132     SetConnectCommand(const wxString& commandDial = T("/usr/bin/pon"),
 133                       const wxString& commandHangup = T("/usr/bin/poff")) = 0;
 134 };
 135
 136 // ----------------------------------------------------------------------------
 137 // DIALUP events processing
 138 // ----------------------------------------------------------------------------
 139
 140 // the event class for the dialup events
 141 class WXDLLEXPORT wxDialUpEvent : public wxEvent
 142 {
 143 public:
 144     wxDialUpEvent(bool isConnected, bool isOwnEvent) : wxEvent(isOwnEvent)
 145     {
 146         SetEventType(isConnected ? wxEVT_DIALUP_CONNECTED
 147                                  : wxEVT_DIALUP_DISCONNECTED);
 148     }
 149
 150     // is this a CONNECTED or DISCONNECTED event?
 151     bool IsConnectedEvent() const
 152         { return GetEventType() == wxEVT_DIALUP_CONNECTED; }
 153
 154     // does this event come from wxDialUpManager::Dial() or from some extrenal
 155     // process (i.e. does it result from our own attempt to establish the
 156     // connection)?
 157     bool IsOwnEvent() const { return m_id != 0; }
 158 };
 159
 160 // the type of dialup event handler function
 161 typedef void (wxObject::*wxDialUpEventFunction)(wxDialUpEvent&);
 162
 163 // macros to catch dialup events
 164 #define EVT_DIALUP_CONNECTED(func) { wxEVT_DIALUP_CONNECTED, -1, -1, (wxObjectEventFunction) (wxEventFunction) (wxDialUpEventFunction) & func, NULL},
 165 #define EVT_DIALUP_DISCONNECTED(func) { wxEVT_DIALUP_DISCONNECTED, -1, -1, (wxObjectEventFunction) (wxEventFunction) (wxDialUpEventFunction) & func, NULL},
 166
 167 #endif // wxUSE_DIALUP_MANAGER
 168
 169 #endif // _WX_NET_H