From a9a3ea615fd12b567cb67e5320ec7da7333aeeb1 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sat, 8 Apr 2000 20:44:46 +0000 Subject: [PATCH] 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 | 2 + docs/latex/wx/classes.tex | 2 + docs/latex/wx/dialevt.tex | 48 +++++++++ docs/latex/wx/dialup.tex | 214 +++++++++++++++++++++++++++++++++++++ docs/latex/wx/tsamples.tex | 13 +++ 5 files changed, 279 insertions(+) create mode 100644 docs/latex/wx/dialevt.tex create mode 100644 docs/latex/wx/dialup.tex diff --git a/docs/latex/wx/category.tex b/docs/latex/wx/category.tex index c2a59f66d6..a77a5244ae 100644 --- a/docs/latex/wx/category.tex +++ b/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} diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex index 34d7868d31..f985e23929 100644 --- a/docs/latex/wx/classes.tex +++ b/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 diff --git a/docs/latex/wx/dialevt.tex b/docs/latex/wx/dialevt.tex new file mode 100644 index 0000000000..b434db72f5 --- /dev/null +++ b/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} + + + +\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)? + diff --git a/docs/latex/wx/dialup.tex b/docs/latex/wx/dialup.tex new file mode 100644 index 0000000000..f00cce8466 --- /dev/null +++ b/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} + + + +\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} diff --git a/docs/latex/wx/tsamples.tex b/docs/latex/wx/tsamples.tex index 80e9cba490..0e70ae4e44 100644 --- a/docs/latex/wx/tsamples.tex +++ b/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