docs/latex/wx/dialup.tex

   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:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxDialUpManager}}\label{wxdialupmanager}
  13
  14 This class encapsulates functions dealing with verifying the connection status
  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
  25 This class is different from other wxWidgets classes in that there is at most
  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{Library}
  39
  40 \helpref{wxCore}{librarieslist}
  41
  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
  73 Returns {\tt true} if the dialup manager was initialized correctly. If this
  74 function returns {\tt false}, no other functions will work neither, so it is a
  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
  96 \func{bool}{Dial}{\param{const wxString\& }{nameOfISP = wxEmptyString}, \param{const wxString\& }{username = wxEmptyString}, \param{const wxString\& }{password = wxEmptyString}, \param{bool }{async = true}}
  97
  98 Dial the given ISP, use {\it username} and {\it password} to authenticate.
  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
 109 If {\it async} parameter is {\tt false}, the function waits until the end of dialing
 110 and returns {\tt true} upon successful completion.
 111
 112 If {\it async} is {\tt true}, the function only initiates the connection and
 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
 120 Returns true if (async) dialing is in progress.
 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}
 131 with async parameter equal to {\tt true}.
 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
 149 Returns {\tt true} if the computer has a permanent network connection (i.e. is
 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
 160 Returns {\tt true} if the computer is connected to the network: under Windows,
 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
 167 \func{void}{SetOnlineStatus}{\param{bool }{isOnline = true}}
 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
 182 Enable automatic checks for the connection status and sending of
 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
 189 Returns {\tt false} if couldn't set up automatic check for online status.
 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
 210 \func{void}{SetConnectCommand}{\param{const wxString\& }{commandDial = wxT("/usr/bin/pon")}, \param{const wxString\& }{commandHangup = wxT("/usr/bin/poff")}}
 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