don't place NULL pointers in the GDK window array in GTKGetWindow()
[wxWidgets.git] / interface / wx / dialup.h
0 / 216 (  0%)
CommitLineData
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*/
40class wxDialUpManager
41{
42public:
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*/
195class wxDialUpEvent : public wxEvent
196{
197public:
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