interface/wx/dialup.h

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