]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/dialup.h
Try out - instead of @li, more backslash escaping
[wxWidgets.git] / interface / dialup.h
... / ...
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 @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*/
34class wxDialUpManager
35{
36public:
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*/
178class wxDialUpEvent : public wxEvent
179{
180public:
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