include/wx/dialup.h

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