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