interface/dialup.h

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