| 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 | |
| 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 | 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 extrenal |
| 211 | process (i.e. does it result from our own attempt to establish the |
| 212 | connection)? |
| 213 | */ |
| 214 | bool IsOwnEvent() const; |
| 215 | }; |
| 216 | |