interface/wx/dialup.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dialup.h
   3 // Purpose:     interface of wxDialUpManager
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxDialUpManager
  10
  11     This class encapsulates functions dealing with verifying the connection
  12     status of the workstation (connected to the Internet via a direct
  13     connection, connected through a modem or not connected at all) and to
  14     establish this connection if possible/required (i.e. in the case of the
  15     modem).
  16
  17     The program may also wish to be notified about the change in the connection
  18     status (for example, to perform some action when the user connects to the
  19     network the next time or, on the contrary, to stop receiving data from the
  20     net when the user hangs up the modem). For this, you need to use one of the
  21     event macros described below.
  22
  23     This class is different from other wxWidgets classes in that there is at
  24     most one instance of this class in the program accessed via Create() and
  25     you can't create the objects of this class directly.
  26
  27     @beginEventEmissionTable{wxDialUpEvent}
  28     @event{EVT_DIALUP_CONNECTED(func)}
  29         A connection with the network was established.
  30     @event{EVT_DIALUP_DISCONNECTED(func)}
  31         The connection with the network was lost.
  32     @endEventTable
  33
  34     @library{wxcore}
  35     @category{net}
  36
  37     @see @ref page_samples_dialup, wxDialUpEvent
  38 */
  39 class wxDialUpManager
  40 {
  41 public:
  42     /**
  43         Destructor.
  44     */
  45     virtual ~wxDialUpManager();
  46
  47     /**
  48         Cancel dialing the number initiated with Dial() with async parameter
  49         equal to @true.
  50
  51         @note This won't result in a DISCONNECTED event being sent.
  52
  53         @see IsDialing()
  54     */
  55     virtual bool CancelDialing() = 0;
  56
  57     /**
  58         This function should create and return the object of the
  59         platform-specific class derived from wxDialUpManager. You should delete
  60         the pointer when you are done with it.
  61     */
  62     static wxDialUpManager* Create();
  63
  64     /**
  65         Dial the given ISP, use @a username and @a password to authenticate.
  66
  67         The parameters are only used under Windows currently, for Unix you
  68         should use SetConnectCommand() to customize this functions behaviour.
  69
  70         If no @a nameOfISP is given, the function will select the default one
  71         (proposing the user to choose among all connections defined on this
  72         machine) and if no username and/or password are given, the function
  73         will try to do without them, but will ask the user if really needed.
  74
  75         If @a async parameter is @false, the function waits until the end of
  76         dialing and returns @true upon successful completion.
  77
  78         If @a async is @true, the function only initiates the connection and
  79         returns immediately - the result is reported via events (an event is
  80         sent anyhow, but if dialing failed it will be a DISCONNECTED one).
  81     */
  82     virtual bool Dial(const wxString& nameOfISP = wxEmptyString,
  83                       const wxString& username = wxEmptyString,
  84                       const wxString& password = wxEmptyString,
  85                       bool async = true) = 0;
  86
  87     /**
  88         Disable automatic check for connection status change - notice that the
  89         @c wxEVT_DIALUP_XXX events won't be sent any more neither.
  90     */
  91     virtual void DisableAutoCheckOnlineStatus() = 0;
  92
  93     /**
  94         Enable automatic checks for the connection status and sending of
  95         @c wxEVT_DIALUP_CONNECTED/wxEVT_DIALUP_DISCONNECTED events. The interval
  96         parameter is only for Unix where we do the check manually and specifies
  97         how often should we repeat the check (each minute by default). Under
  98         Windows, the notification about the change of connection status is sent
  99         by the system and so we don't do any polling and this parameter is
 100         ignored.
 101
 102         @return @false if couldn't set up automatic check for online status.
 103     */
 104     virtual bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60) = 0;
 105
 106     /**
 107         This function is only implemented under Windows.
 108
 109         Fills the array with the names of all possible values for the first
 110         parameter to Dial() on this machine and returns their number (may be
 111         0).
 112     */
 113     virtual size_t GetISPNames(wxArrayString& names) const = 0;
 114
 115     /**
 116         Hang up the currently active dial up connection.
 117     */
 118     virtual bool HangUp() = 0;
 119
 120     /**
 121         Returns @true if the computer has a permanent network connection (i.e.\
 122         is on a LAN) and so there is no need to use Dial() function to go
 123         online.
 124
 125         @note This function tries to guess the result and it is not always
 126               guaranteed to be correct, so it is better to ask user for
 127               confirmation or give him a possibility to override it.
 128     */
 129     virtual bool IsAlwaysOnline() const = 0;
 130
 131     /**
 132         Returns @true if (async) dialing is in progress.
 133
 134         @see Dial()
 135     */
 136     virtual bool IsDialing() const = 0;
 137
 138     /**
 139         Returns @true if the dialup manager was initialized correctly. If this
 140         function returns @false, no other functions will work neither, so it is
 141         a good idea to call this function and check its result before calling
 142         any other wxDialUpManager methods.
 143     */
 144     virtual bool IsOk() const = 0;
 145
 146     /**
 147         Returns @true if the computer is connected to the network: under
 148         Windows, this just means that a RAS connection exists, under Unix we
 149         check that the "well-known host" (as specified by SetWellKnownHost())
 150         is reachable.
 151     */
 152     virtual bool IsOnline() const = 0;
 153
 154     /**
 155         This method is for Unix only.
 156
 157         Sets the commands to start up the network and to hang up again.
 158     */
 159     virtual void SetConnectCommand(const wxString& commandDial = "/usr/bin/pon",
 160                                    const wxString& commandHangup = "/usr/bin/poff") = 0;
 161
 162     /**
 163         Sometimes the built-in logic for determining the online status may
 164         fail, so, in general, the user should be allowed to override it. This
 165         function allows to forcefully set the online status - whatever our
 166         internal algorithm may think about it.
 167
 168         @see IsOnline()
 169     */
 170     virtual void SetOnlineStatus(bool isOnline = true) = 0;
 171
 172     /**
 173         This method is for Unix only.
 174
 175         Under Unix, the value of well-known host is used to check whether we're
 176         connected to the internet. It is unused under Windows, but this
 177         function is always safe to call. The default value is
 178         @c "www.yahoo.com:80".
 179     */
 180     virtual void SetWellKnownHost(const wxString& hostname,
 181                                   int portno = 80) = 0;
 182 };
 183
 184
 185
 186 /**
 187     @class wxDialUpEvent
 188
 189     This is the event class for the dialup events sent by wxDialUpManager.
 190
 191     @library{wxcore}
 192     @category{events}
 193 */
 194 class wxDialUpEvent : public wxEvent
 195 {
 196 public:
 197     /**
 198         Constructor is only used by wxDialUpManager.
 199     */
 200     wxDialUpEvent(bool isConnected, bool isOwnEvent);
 201
 202     /**
 203         Is this a @c CONNECTED or @c DISCONNECTED event? In other words, does
 204         it notify about transition from offline to online state or vice versa?
 205     */
 206     bool IsConnectedEvent() const;
 207
 208     /**
 209         Does this event come from wxDialUpManager::Dial() or from some external
 210         process (i.e. does it result from our own attempt to establish the
 211         connection)?
 212     */
 213     bool IsOwnEvent() const;
 214 };
 215