]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/dialup.tex
Fixed to work with the new wxMacControl system.
[wxWidgets.git] / docs / latex / wx / dialup.tex
... / ...
CommitLineData
1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2%% Name: dialup.tex
3%% Purpose: wxDialUpManager documentation
4%% Author: Vadim Zeitlin
5%% Modified by:
6%% Created: 08.04.00
7%% RCS-ID: $Id$
8%% Copyright: (c) Vadim Zeitlin
9%% License: wxWidgets license
10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12\section{\class{wxDialUpManager}}\label{wxdialupmanager}
13
14This class encapsulates functions dealing with verifying the connection status
15of the workstation (connected to the Internet via a direct connection,
16connected through a modem or not connected at all) and to establish this
17connection if possible/required (i.e. in the case of the modem).
18
19The program may also wish to be notified about the change in the connection
20status (for example, to perform some action when the user connects to the
21network the next time or, on the contrary, to stop receiving data from the net
22when the user hangs up the modem). For this, you need to use one of the event
23macros described below.
24
25This class is different from other wxWidgets classes in that there is at most
26one instance of this class in the program accessed via
27\helpref{wxDialUpManager::Create()}{wxdialupmanagercreate} and you can't
28create the objects of this class directly.
29
30\wxheading{Derived from}
31
32No base class
33
34\wxheading{Include files}
35
36<wx/dialup.h>
37
38\wxheading{Event table macros}
39
40To be notified about the change in the network connection status, use these
41event handler macros to direct input to member functions that take a
42\helpref{wxDialUpEvent}{wxdialupevent} argument.
43
44\twocolwidtha{7cm}
45\begin{twocollist}\itemsep=0pt
46\twocolitem{{\bf EVT\_DIALUP\_CONNECTED(func)}}{A connection with the network was established.}
47\twocolitem{{\bf EVT\_DIALUP\_DISCONNECTED(func)}}{The connection with the network was lost.}
48\end{twocollist}%
49
50\wxheading{See also}
51
52\helpref{dialup sample}{sampledialup}\\
53\helpref{wxDialUpEvent}{wxdialupevent}
54
55\latexignore{\rtfignore{\wxheading{Members}}}
56
57\membersection{wxDialUpManager::Create}\label{wxdialupmanagercreate}
58
59\func{wxDialUpManager*}{Create}{\void}
60
61This function should create and return the object of the platform-specific
62class derived from wxDialUpManager. You should delete the pointer when you are
63done with it.
64
65\membersection{wxDialUpManager::IsOk}\label{wxdialupmanagerisok}
66
67\constfunc{bool}{IsOk}{\void}
68
69Returns {\tt true} if the dialup manager was initialized correctly. If this
70function returns {\tt false}, no other functions will work neither, so it is a
71good idea to call this function and check its result before calling any other
72wxDialUpManager methods
73
74\membersection{wxDialUpManager::\destruct{wxDialUpManager}}\label{wxdialupmanagerdtor}
75
76\func{}{\destruct{wxDialUpManager}}{\void}
77
78Destructor.
79
80\membersection{wxDialUpManager::GetISPNames}\label{wxdialupmanagergetispnames}
81
82\constfunc{size\_t}{GetISPNames}{\param{wxArrayString\& }{names}}
83
84This function is only implemented under Windows.
85
86Fills the array with the names of all possible values for the first
87parameter to \helpref{Dial()}{wxdialupmanagerdial} on this machine and returns
88their number (may be $0$).
89
90\membersection{wxDialUpManager::Dial}\label{wxdialupmanagerdial}
91
92\func{bool}{Dial}{\param{const wxString\& }{nameOfISP = wxEmptyString}, \param{const wxString\& }{username = wxEmptyString}, \param{const wxString\& }{password = wxEmptyString}, \param{bool }{async = true}}
93
94Dial the given ISP, use {\it username} and {\it password} to authenticate.
95
96The parameters are only used under Windows currently, for Unix you should use
97\helpref{SetConnectCommand}{wxdialupmanagersetconnectcommand} to customize this
98functions behaviour.
99
100If no {\it nameOfISP} is given, the function will select the default one
101(proposing the user to choose among all connections defined on this machine)
102and if no username and/or password are given, the function will try to do
103without them, but will ask the user if really needed.
104
105If {\it async} parameter is {\tt false}, the function waits until the end of dialing
106and returns {\tt true} upon successful completion.
107
108If {\it async} is {\tt true}, the function only initiates the connection and
109returns immediately - the result is reported via events (an event is sent
110anyhow, but if dialing failed it will be a DISCONNECTED one).
111
112\membersection{wxDialUpManager::IsDialing}\label{wxdialupmanagerisdialing}
113
114\constfunc{bool}{IsDialing}{\void}
115
116Returns true if (async) dialing is in progress.
117
118\wxheading{See also}
119
120\helpref{Dial}{wxdialupmanagerdial}
121
122\membersection{wxDialUpManager::CancelDialing}\label{wxdialupmanagercanceldialing}
123
124\func{bool}{CancelDialing}{\void}
125
126Cancel dialing the number initiated with \helpref{Dial}{wxdialupmanagerdial}
127with async parameter equal to {\tt true}.
128
129Note that this won't result in DISCONNECTED event being sent.
130
131\wxheading{See also}
132
133\helpref{IsDialing}{wxdialupmanagerisdialing}
134
135\membersection{wxDialUpManager::HangUp}\label{wxdialupmanagerhangup}
136
137\func{bool}{HangUp}{\void}
138
139Hang up the currently active dial up connection.
140
141\membersection{wxDialUpManager::IsAlwaysOnline}\label{wxdialupmanagerisalwaysonline}
142
143\constfunc{bool}{IsAlwaysOnline}{\void}
144
145Returns {\tt true} if the computer has a permanent network connection (i.e. is
146on a LAN) and so there is no need to use Dial() function to go online.
147
148{\bf NB:} this functions tries to guess the result and it is not always
149guaranteed to be correct, so it is better to ask user for
150confirmation or give him a possibility to override it.
151
152\membersection{wxDialUpManager::IsOnline}\label{wxdialupmanagerisonline}
153
154\constfunc{bool}{IsOnline}{\void}
155
156Returns {\tt true} if the computer is connected to the network: under Windows,
157this just means that a RAS connection exists, under Unix we check that
158the "well-known host" (as specified by
159\helpref{SetWellKnownHost}{wxdialupmanagersetwellknownhost}) is reachable.
160
161\membersection{wxDialUpManager::SetOnlineStatus}\label{wxdialupmanagersetonlinestatus}
162
163\func{void}{SetOnlineStatus}{\param{bool }{isOnline = true}}
164
165Sometimes the built-in logic for determining the online status may fail,
166so, in general, the user should be allowed to override it. This function
167allows to forcefully set the online status - whatever our internal
168algorithm may think about it.
169
170\wxheading{See also}
171
172\helpref{IsOnline}{wxdialupmanagerisonline}
173
174\membersection{wxDialUpManager::EnableAutoCheckOnlineStatus}\label{wxdialupmanagerenableautocheckonlinestatus}
175
176\func{bool}{EnableAutoCheckOnlineStatus}{\param{size\_t }{nSeconds = 60}}
177
178Enable automatic checks for the connection status and sending of
179{\tt wxEVT\_DIALUP\_CONNECTED/wxEVT\_DIALUP\_DISCONNECTED} events. The interval
180parameter is only for Unix where we do the check manually and specifies how
181often should we repeat the check (each minute by default). Under Windows, the
182notification about the change of connection status is sent by the system and so
183we don't do any polling and this parameter is ignored.
184
185Returns {\tt false} if couldn't set up automatic check for online status.
186
187\membersection{wxDialUpManager::DisableAutoCheckOnlineStatus}\label{wxdialupmanagerdisableautocheckonlinestatus}
188
189\func{void}{DisableAutoCheckOnlineStatus}{\void}
190
191Disable automatic check for connection status change - notice that the
192{\tt wxEVT\_DIALUP\_XXX} events won't be sent any more neither.
193
194\membersection{wxDialUpManager::SetWellKnownHost}\label{wxdialupmanagersetwellknownhost}
195
196\func{void}{SetWellKnownHost}{\param{const wxString\& }{hostname}, \param{int }{portno = 80}}
197
198This method is for Unix only.
199
200Under Unix, the value of well-known host is used to check whether we're
201connected to the internet. It is unused under Windows, but this function
202is always safe to call. The default value is {\tt www.yahoo.com:80}.
203
204\membersection{wxDialUpManager::SetConnectCommand}\label{wxdialupmanagersetconnectcommand}
205
206\func{}{SetConnectCommand}{\param{const wxString\& }{commandDial = wxT("/usr/bin/pon")}, \param{const wxString\& }{commandHangup = wxT("/usr/bin/poff")}}
207
208This method is for Unix only.
209
210Sets the commands to start up the network and to hang up again.
211
212\wxheading{See also}
213
214\helpref{Dial}{wxdialupmanagerdial}
215