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