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