wxDialUpManager docs

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_2_BRANCH@7092 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/category.tex

@@ -188,6 +188,7 @@ An event object contains information about a specific event. Event handlers
 \twocolitem{\helpref{wxCalculateLayoutEvent}{wxcalculatelayoutevent}}{Used to calculate window layout}
 \twocolitem{\helpref{wxCloseEvent}{wxcloseevent}}{A close window or end session event}
 \twocolitem{\helpref{wxCommandEvent}{wxcommandevent}}{An event from a variety of standard controls}
+\twocolitem{\helpref{wxDialUpEvent}{wxdialupevent}}{Event send by \helpref{wxDialUpManager}}{wxdialupmanager}
 \twocolitem{\helpref{wxDropFilesEvent}{wxdropfilesevent}}{A drop files event}
 \twocolitem{\helpref{wxEraseEvent}{wxeraseevent}}{An erase background event}
 \twocolitem{\helpref{wxEvent}{wxevent}}{The event base class}
@@ -299,6 +300,7 @@ classes, functions and macros.
 wxWindows provides its own classes for socket based networking.
 
 \begin{twocollist}\itemsep=0pt
+\twocolitem{\helpref{wxDialUpManager}{wxdialupmanager}}{Provides functions to check the status of network connection and to establish one}
 \twocolitem{\helpref{wxIPV4address}{wxipv4address}}{Represents an Internet address}
 \twocolitem{\helpref{wxSocketBase}{wxsocketbase}}{Represents a socket base object}
 \twocolitem{\helpref{wxSocketClient}{wxsocketclient}}{Represents a socket client}

docs/latex/wx/classes.tex

@@ -60,6 +60,8 @@
 \input ddeservr.tex
 \input debugcxt.tex
 \input dialog.tex
+\input dialevt.tex
+\input dialup.tex
 \input dir.tex
 \input dirdlg.tex
 \input dllload.tex

docs/latex/wx/dialevt.tex

@@ -0,0 +1,48 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        dialevt.tex
+%% Purpose:     wxDialUpEvent documentation
+%% Author:      Vadim Zeitlin
+%% Modified by:
+%% Created:     08.04.00
+%% RCS-ID:      $Id$
+%% Copyright:   (c) Vadim Zeitlin
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\class{wxDialUpEvent}}\label{wxdialupevent}
+
+This is the event class for the dialup events sent by 
+\helpref{wxDialUpManager}{wxdialupmanager}.
+
+\wxheading{Derived from}
+
+\helpref{wxEvent}{wxevent}\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/dialup.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxDialUpEvent::wxDialUpEvent}\label{wxdialupeventwxdialupevent}
+
+\func{}{wxDialUpEvent}{\param{bool }{isConnected}, \param{bool }{isOwnEvent}}
+
+Constructor is only used by \helpref{wxDialUpManager}{wxdialupmanager}.
+
+\membersection{wxDialUpEvent::IsConnectedEvent}\label{wxdialupeventisconnectedevent}
+
+\constfunc{bool}{IsConnectedEvent}{\void}
+
+Is this a {\tt CONNECTED} or {\tt DISCONNECTED} event? In other words, does it
+notify about transition from offline to online state or vice versa?
+
+\membersection{wxDialUpEvent::IsOwnEvent}\label{wxdialupeventisownevent}
+
+\constfunc{bool}{IsOwnEvent}{\void}
+
+Does this event come from wxDialUpManager::Dial() or from some extrenal
+process (i.e. does it result from our own attempt to establish the
+connection)?
+

docs/latex/wx/dialup.tex

@@ -0,0 +1,214 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% 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 veryfying 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 wxWindows classes in that there is at most
+one instance of this class in the program accessed via 
+\helpref{GetDialUpManager()}{wxdialupmanagergetdialupmanager} 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's 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 authentificate.
+
+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's 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 automatical 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's 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}

docs/latex/wx/tsamples.tex

@@ -121,6 +121,19 @@ system.
 This sample shows how to use the common dialogs available from wxWindows. These
 dialogs are described in details in the \helpref{Common dialogs overview}{commondialogsoverview}.
 
+\subsection{Dialup sample}\label{sampledialup}
+
+This sample shows \helpref{wxDialUpManager}{wxdialupmanagerwxdialupmanager}
+class. It displays in the status bar the information gathered through itsi
+nterface: in particular, the current connection status (online or offline) and
+whether the connection is permanent (in which case a string `LAN' appears in
+the thrid status bar field - but note that you may have be on a LAN not
+connected to the Internet, in which case you will not see this) or not.
+
+Using the menu entries, you may also dial or hang up the line if you have a
+modem attached and (this only makes sense for Windows) list the available
+connections.
+
 \subsection{Dynamic sample}\label{sampledynamic}
 
 This sample is a very small sample that demonstrates the use of the