[wxWidgets.git] / docs / latex / wx / dialup.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        dialup.tex
%% Purpose:     wxDialUpManager documentation
%% Author:      Vadim Zeitlin
%% Modified by:
%% Created:     08.04.00
%% RCS-ID:      $Id$
%% Copyright:   (c) Vadim Zeitlin
%% License:     wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{\class{wxDialUpManager}}\label{wxdialupmanager}

This class encapsulates functions dealing with verifying the connection status
of the workstation (connected to the Internet via a direct connection,
connected through a modem or not connected at all) and to establish this
connection if possible/required (i.e. in the case of the modem).

The program may also wish to be notified about the change in the connection
status (for example, to perform some action when the user connects to the
network the next time or, on the contrary, to stop receiving data from the net
when the user hangs up the modem). For this, you need to use one of the event
macros described below.

This class is different from other wxWidgets classes in that there is at most
one instance of this class in the program accessed via 
\helpref{wxDialUpManager::Create()}{wxdialupmanagercreate} and you can't
create the objects of this class directly.

\wxheading{Derived from}

No base class

\wxheading{Include files}

<wx/dialup.h>

\wxheading{Library}

\helpref{wxCore}{librarieslist}

\wxheading{Event table macros}

To be notified about the change in the network connection status, use these
event handler macros to direct input to member functions that take a 
\helpref{wxDialUpEvent}{wxdialupevent} argument.

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf EVT\_DIALUP\_CONNECTED(func)}}{A connection with the network was established.}
\twocolitem{{\bf EVT\_DIALUP\_DISCONNECTED(func)}}{The connection with the network was lost.}
\end{twocollist}%

\wxheading{See also}

\helpref{dialup sample}{sampledialup}\\
\helpref{wxDialUpEvent}{wxdialupevent}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxDialUpManager::Create}\label{wxdialupmanagercreate}

\func{wxDialUpManager*}{Create}{\void}

This function should create and return the object of the platform-specific
class derived from wxDialUpManager. You should delete the pointer when you are
done with it.

\membersection{wxDialUpManager::IsOk}\label{wxdialupmanagerisok}

\constfunc{bool}{IsOk}{\void}

Returns {\tt true} if the dialup manager was initialized correctly. If this
function returns {\tt false}, no other functions will work neither, so it is a
good idea to call this function and check its result before calling any other
wxDialUpManager methods

\membersection{wxDialUpManager::\destruct{wxDialUpManager}}\label{wxdialupmanagerdtor}

\func{}{\destruct{wxDialUpManager}}{\void}

Destructor.

\membersection{wxDialUpManager::GetISPNames}\label{wxdialupmanagergetispnames}

\constfunc{size\_t}{GetISPNames}{\param{wxArrayString\& }{names}}

This function is only implemented under Windows.

Fills the array with the names of all possible values for the first
parameter to \helpref{Dial()}{wxdialupmanagerdial} on this machine and returns
their number (may be $0$).

\membersection{wxDialUpManager::Dial}\label{wxdialupmanagerdial}

\func{bool}{Dial}{\param{const wxString\& }{nameOfISP = wxEmptyString}, \param{const wxString\& }{username = wxEmptyString}, \param{const wxString\& }{password = wxEmptyString}, \param{bool }{async = true}}

Dial the given ISP, use {\it username} and {\it password} to authenticate.

The parameters are only used under Windows currently, for Unix you should use 
\helpref{SetConnectCommand}{wxdialupmanagersetconnectcommand} to customize this
functions behaviour.

If no {\it nameOfISP} is given, the function will select the default one
(proposing the user to choose among all connections defined on this machine)
and if no username and/or password are given, the function will try to do
without them, but will ask the user if really needed.

If {\it async} parameter is {\tt false}, the function waits until the end of dialing
and returns {\tt true} upon successful completion.

If {\it async} is {\tt true}, the function only initiates the connection and
returns immediately - the result is reported via events (an event is sent
anyhow, but if dialing failed it will be a DISCONNECTED one).

\membersection{wxDialUpManager::IsDialing}\label{wxdialupmanagerisdialing}

\constfunc{bool}{IsDialing}{\void}

Returns true if (async) dialing is in progress.

\wxheading{See also}

\helpref{Dial}{wxdialupmanagerdial}

\membersection{wxDialUpManager::CancelDialing}\label{wxdialupmanagercanceldialing}

\func{bool}{CancelDialing}{\void}

Cancel dialing the number initiated with \helpref{Dial}{wxdialupmanagerdial} 
with async parameter equal to {\tt true}.

Note that this won't result in DISCONNECTED event being sent.

\wxheading{See also}

\helpref{IsDialing}{wxdialupmanagerisdialing}

\membersection{wxDialUpManager::HangUp}\label{wxdialupmanagerhangup}

\func{bool}{HangUp}{\void}

Hang up the currently active dial up connection.

\membersection{wxDialUpManager::IsAlwaysOnline}\label{wxdialupmanagerisalwaysonline}

\constfunc{bool}{IsAlwaysOnline}{\void}

Returns {\tt true} if the computer has a permanent network connection (i.e. is
on a LAN) and so there is no need to use Dial() function to go online.

{\bf NB:} this functions tries to guess the result and it is not always
guaranteed to be correct, so it is better to ask user for
confirmation or give him a possibility to override it.

\membersection{wxDialUpManager::IsOnline}\label{wxdialupmanagerisonline}

\constfunc{bool}{IsOnline}{\void}

Returns {\tt true} if the computer is connected to the network: under Windows,
this just means that a RAS connection exists, under Unix we check that
the "well-known host" (as specified by 
\helpref{SetWellKnownHost}{wxdialupmanagersetwellknownhost}) is reachable.

\membersection{wxDialUpManager::SetOnlineStatus}\label{wxdialupmanagersetonlinestatus}

\func{void}{SetOnlineStatus}{\param{bool }{isOnline = true}}

Sometimes the built-in logic for determining the online status may fail,
so, in general, the user should be allowed to override it. This function
allows to forcefully set the online status - whatever our internal
algorithm may think about it.

\wxheading{See also}

\helpref{IsOnline}{wxdialupmanagerisonline}

\membersection{wxDialUpManager::EnableAutoCheckOnlineStatus}\label{wxdialupmanagerenableautocheckonlinestatus}

\func{bool}{EnableAutoCheckOnlineStatus}{\param{size\_t }{nSeconds = 60}}

Enable automatic checks for the connection status and sending of 
{\tt wxEVT\_DIALUP\_CONNECTED/wxEVT\_DIALUP\_DISCONNECTED} events. The interval
parameter is only for Unix where we do the check manually and specifies how
often should we repeat the check (each minute by default). Under Windows, the
notification about the change of connection status is sent by the system and so
we don't do any polling and this parameter is ignored.

Returns {\tt false} if couldn't set up automatic check for online status.

\membersection{wxDialUpManager::DisableAutoCheckOnlineStatus}\label{wxdialupmanagerdisableautocheckonlinestatus}

\func{void}{DisableAutoCheckOnlineStatus}{\void}

Disable automatic check for connection status change - notice that the
{\tt wxEVT\_DIALUP\_XXX} events won't be sent any more neither.

\membersection{wxDialUpManager::SetWellKnownHost}\label{wxdialupmanagersetwellknownhost}

\func{void}{SetWellKnownHost}{\param{const wxString\& }{hostname}, \param{int }{portno = 80}}

This method is for Unix only.

Under Unix, the value of well-known host is used to check whether we're
connected to the internet. It is unused under Windows, but this function
is always safe to call. The default value is {\tt www.yahoo.com:80}.

\membersection{wxDialUpManager::SetConnectCommand}\label{wxdialupmanagersetconnectcommand}

\func{void}{SetConnectCommand}{\param{const wxString\& }{commandDial = wxT("/usr/bin/pon")}, \param{const wxString\& }{commandHangup = wxT("/usr/bin/poff")}}

This method is for Unix only.

Sets the commands to start up the network and to hang up again.

\wxheading{See also}

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