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: dialup.tex 32309 2005-02-22 15:09:56Z ABX $ 8%% Copyright: (c) Vadim Zeitlin 9%% License: wxWindows 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{void}{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 216