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