interface/dialup.h

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