[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:     wxWidgets 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{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{}{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
fc2171bd	9	%% License: wxWidgets 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
	38	\wxheading{Event table macros}
	39
	40	To be notified about the change in the network connection status, use these
	41	event 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
	61	This function should create and return the object of the platform-specific
	62	class derived from wxDialUpManager. You should delete the pointer when you are
	63	done with it.
	64
	65	\membersection{wxDialUpManager::IsOk}\label{wxdialupmanagerisok}
	66
	67	\constfunc{bool}{IsOk}{\void}
	68
cc81d32f VS	69	Returns {\tt true} if the dialup manager was initialized correctly. If this
cc81d32f VS	70	function returns {\tt false}, no other functions will work neither, so it is a
f6bcfd97 BP	71	good idea to call this function and check its result before calling any other
	72	wxDialUpManager methods
	73
	74	\membersection{wxDialUpManager::\destruct{wxDialUpManager}}\label{wxdialupmanagerdtor}
	75
	76	\func{}{\destruct{wxDialUpManager}}{\void}
	77
	78	Destructor.
	79
	80	\membersection{wxDialUpManager::GetISPNames}\label{wxdialupmanagergetispnames}
	81
	82	\constfunc{size\_t}{GetISPNames}{\param{wxArrayString\& }{names}}
	83
	84	This function is only implemented under Windows.
	85
	86	Fills the array with the names of all possible values for the first
	87	parameter to \helpref{Dial()}{wxdialupmanagerdial} on this machine and returns
	88	their number (may be $0$).
	89
	90	\membersection{wxDialUpManager::Dial}\label{wxdialupmanagerdial}
	91
cc81d32f	92	\func{bool}{Dial}{\param{const wxString\& }{nameOfISP = wxEmptyString}, \param{const wxString\& }{username = wxEmptyString}, \param{const wxString\& }{password = wxEmptyString}, \param{bool }{async = true}}
f6bcfd97	93
2edb0bde	94	Dial the given ISP, use {\it username} and {\it password} to authenticate.
f6bcfd97 BP	95
	96	The parameters are only used under Windows currently, for Unix you should use
	97	\helpref{SetConnectCommand}{wxdialupmanagersetconnectcommand} to customize this
	98	functions behaviour.
	99
	100	If 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)
	102	and if no username and/or password are given, the function will try to do
	103	without them, but will ask the user if really needed.
	104
cc81d32f VS	105	If {\it async} parameter is {\tt false}, the function waits until the end of dialing
cc81d32f VS	106	and returns {\tt true} upon successful completion.
f6bcfd97	107
cc81d32f	108	If {\it async} is {\tt true}, the function only initiates the connection and
f6bcfd97 BP	109	returns immediately - the result is reported via events (an event is sent
	110	anyhow, but if dialing failed it will be a DISCONNECTED one).
	111
	112	\membersection{wxDialUpManager::IsDialing}\label{wxdialupmanagerisdialing}
	113
	114	\constfunc{bool}{IsDialing}{\void}
	115
cc81d32f	116	Returns true if (async) dialing is in progress.
f6bcfd97 BP	117
	118	\wxheading{See also}
	119
	120	\helpref{Dial}{wxdialupmanagerdial}
	121
	122	\membersection{wxDialUpManager::CancelDialing}\label{wxdialupmanagercanceldialing}
	123
	124	\func{bool}{CancelDialing}{\void}
	125
	126	Cancel dialing the number initiated with \helpref{Dial}{wxdialupmanagerdial}
cc81d32f	127	with async parameter equal to {\tt true}.
f6bcfd97 BP	128
	129	Note 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
	139	Hang up the currently active dial up connection.
	140
	141	\membersection{wxDialUpManager::IsAlwaysOnline}\label{wxdialupmanagerisalwaysonline}
	142
	143	\constfunc{bool}{IsAlwaysOnline}{\void}
	144
cc81d32f	145	Returns {\tt true} if the computer has a permanent network connection (i.e. is
f6bcfd97 BP	146	on 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
	149	guaranteed to be correct, so it is better to ask user for
	150	confirmation or give him a possibility to override it.
	151
	152	\membersection{wxDialUpManager::IsOnline}\label{wxdialupmanagerisonline}
	153
	154	\constfunc{bool}{IsOnline}{\void}
	155
cc81d32f	156	Returns {\tt true} if the computer is connected to the network: under Windows,
f6bcfd97 BP	157	this just means that a RAS connection exists, under Unix we check that
	158	the "well-known host" (as specified by
	159	\helpref{SetWellKnownHost}{wxdialupmanagersetwellknownhost}) is reachable.
	160
	161	\membersection{wxDialUpManager::SetOnlineStatus}\label{wxdialupmanagersetonlinestatus}
	162
cc81d32f	163	\func{void}{SetOnlineStatus}{\param{bool }{isOnline = true}}
f6bcfd97 BP	164
	165	Sometimes the built-in logic for determining the online status may fail,
	166	so, in general, the user should be allowed to override it. This function
	167	allows to forcefully set the online status - whatever our internal
	168	algorithm 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
2edb0bde	178	Enable automatic checks for the connection status and sending of
f6bcfd97 BP	179	{\tt wxEVT\_DIALUP\_CONNECTED/wxEVT\_DIALUP\_DISCONNECTED} events. The interval
	180	parameter is only for Unix where we do the check manually and specifies how
	181	often should we repeat the check (each minute by default). Under Windows, the
	182	notification about the change of connection status is sent by the system and so
	183	we don't do any polling and this parameter is ignored.
	184
cc81d32f	185	Returns {\tt false} if couldn't set up automatic check for online status.
f6bcfd97 BP	186
	187	\membersection{wxDialUpManager::DisableAutoCheckOnlineStatus}\label{wxdialupmanagerdisableautocheckonlinestatus}
	188
	189	\func{void}{DisableAutoCheckOnlineStatus}{\void}
	190
	191	Disable 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
	198	This method is for Unix only.
	199
	200	Under Unix, the value of well-known host is used to check whether we're
	201	connected to the internet. It is unused under Windows, but this function
	202	is 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
	208	This method is for Unix only.
	209
	210	Sets the commands to start up the network and to hang up again.
	211
	212	\wxheading{See also}
	213
	214	\helpref{Dial}{wxdialupmanagerdial}
	215