/////////////////////////////////////////////////////////////////////////////
// Name: dialup.h
-// Purpose: documentation for wxDialUpManager class
+// Purpose: interface of wxDialUpManager
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/**
@class wxDialUpManager
@wxheader{dialup.h}
-
- 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).
-
+
+ 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
- wxDialUpManager::Create and you can't
- create the objects of this class directly.
-
+ 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 Create() and
+ you can't create the objects of this class directly.
+
+ @beginEventTable{wxDialUpEvent}
+ @event{EVT_DIALUP_CONNECTED(func)}
+ A connection with the network was established.
+ @event{EVT_DIALUP_DISCONNECTED(func)}
+ The connection with the network was lost.
+ @endEventTable
+
@library{wxcore}
@category{net}
-
- @seealso
- @ref overview_sampledialup "dialup sample", wxDialUpEvent
+
+ @see @ref page_samples_dialup, wxDialUpEvent
*/
-class wxDialUpManager
+class wxDialUpManager
{
public:
/**
~wxDialUpManager();
/**
- Cancel dialing the number initiated with Dial()
- with async parameter equal to @true.
-
- Note that this won't result in DISCONNECTED event being sent.
-
- @sa IsDialing()
+ Cancel dialing the number initiated with Dial() with async parameter
+ equal to @true.
+
+ @note This won't result in a DISCONNECTED event being sent.
+
+ @see IsDialing()
*/
bool CancelDialing();
/**
- 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.
+ 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.
*/
wxDialUpManager* Create();
/**
- Dial the given ISP, use @e username and @e password to authenticate.
-
- The parameters are only used under Windows currently, for Unix you should use
- SetConnectCommand() to customize this
- functions behaviour.
-
- If no @e 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 @e async parameter is @false, the function waits until the end of dialing
- and returns @true upon successful completion.
-
- If @e async is @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).
+ Dial the given ISP, use @a username and @a password to authenticate.
+
+ The parameters are only used under Windows currently, for Unix you
+ should use SetConnectCommand() to customize this functions behaviour.
+
+ If no @a 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 @a async parameter is @false, the function waits until the end of
+ dialing and returns @true upon successful completion.
+
+ If @a async is @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).
*/
bool Dial(const wxString& nameOfISP = wxEmptyString,
const wxString& username = wxEmptyString,
const wxString& password = wxEmptyString,
- bool async = @true);
+ bool async = true);
/**
Disable automatic check for connection status change - notice that the
void DisableAutoCheckOnlineStatus();
/**
- Enable automatic checks for the connection status and sending of
- @c 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 @false if couldn't set up automatic check for online status.
+ Enable automatic checks for the connection status and sending of
+ 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 @false if couldn't set up automatic check for online status.
*/
bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60);
/**
This function is only implemented under Windows.
-
+
Fills the array with the names of all possible values for the first
- parameter to Dial() on this machine and returns
- their number (may be 0).
+ parameter to Dial() on this machine and returns their number (may be
+ 0).
*/
- size_t GetISPNames(wxArrayString& names);
+ size_t GetISPNames(wxArrayString& names) const;
/**
Hang up the currently active dial up connection.
bool HangUp();
/**
- Returns @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.
-
- @b 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.
+ Returns @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.
+
+ @note This function 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.
*/
- bool IsAlwaysOnline();
+ bool IsAlwaysOnline() const;
/**
Returns @true if (async) dialing is in progress.
-
- @sa Dial()
+
+ @see Dial()
*/
- bool IsDialing();
+ bool IsDialing() const;
/**
Returns @true if the dialup manager was initialized correctly. If this
- function returns @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
+ function returns @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.
*/
-#define bool IsOk() /* implementation is private */
+ bool IsOk() const;
/**
- Returns @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
- wxDialUpManager::SetWellKnownHost) is reachable.
+ Returns @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 SetWellKnownHost())
+ is reachable.
*/
- bool IsOnline();
+ bool IsOnline() const;
/**
- , @b const wxString&@e commandHangup = wxT("/usr/bin/poff"))
-
This method is for Unix only.
-
+
Sets the commands to start up the network and to hang up again.
*/
- void SetConnectCommand();
+ void SetConnectCommand(const wxString& commandDial = "/usr/bin/pon",
+ const wxString& commandHangup = "/usr/bin/poff") const;
/**
- 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.
-
- @sa IsOnline()
+ 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.
+
+ @see IsOnline()
*/
- void SetOnlineStatus(bool isOnline = @true);
+ void SetOnlineStatus(bool isOnline = true);
/**
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 @c www.yahoo.com:80.
+ connected to the internet. It is unused under Windows, but this
+ function is always safe to call. The default value is
+ @c "www.yahoo.com:80".
*/
void SetWellKnownHost(const wxString& hostname, int portno = 80);
};
+
/**
@class wxDialUpEvent
@wxheader{dialup.h}
-
- This is the event class for the dialup events sent by
- wxDialUpManager.
-
+
+ This is the event class for the dialup events sent by wxDialUpManager.
+
@library{wxcore}
@category{events}
*/
wxDialUpEvent(bool isConnected, bool isOwnEvent);
/**
- Is this a @c CONNECTED or @c DISCONNECTED event? In other words, does it
- notify about transition from offline to online state or vice versa?
+ Is this a @c CONNECTED or @c DISCONNECTED event? In other words, does
+ it notify about transition from offline to online state or vice versa?
*/
- bool IsConnectedEvent();
+ bool IsConnectedEvent() const;
/**
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)?
*/
- bool IsOwnEvent();
+ bool IsOwnEvent() const;
};
+
projects / wxWidgets.git / blobdiff