]> git.saurik.com Git - wxWidgets.git/blame_incremental - include/wx/dialup.h
build fixes
[wxWidgets.git] / include / wx / dialup.h
... / ...
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: wx/dialup.h
3// Purpose: Network related wxWidgets classes and functions
4// Author: Vadim Zeitlin
5// Modified by:
6// Created: 07.07.99
7// RCS-ID: $Id$
8// Copyright: (c) Vadim Zeitlin
9// Licence: wxWindows licence
10/////////////////////////////////////////////////////////////////////////////
11
12#ifndef _WX_DIALUP_H
13#define _WX_DIALUP_H
14
15#if wxUSE_DIALUP_MANAGER
16
17#include "wx/event.h"
18
19// ----------------------------------------------------------------------------
20// misc
21// ----------------------------------------------------------------------------
22
23class WXDLLIMPEXP_FWD_BASE wxArrayString;
24
25#define WXDIALUP_MANAGER_DEFAULT_BEACONHOST wxT("www.yahoo.com")
26
27// ----------------------------------------------------------------------------
28// A class which groups functions dealing with connecting to the network from a
29// workstation using dial-up access to the net. There is at most one instance
30// of this class in the program accessed via GetDialUpManager().
31// ----------------------------------------------------------------------------
32
33/* TODO
34 *
35 * 1. more configurability for Unix: i.e. how to initiate the connection, how
36 * to check for online status, &c.
37 * 2. a function to enumerate all connections (ISPs) and show a dialog in
38 * Dial() allowing to choose between them if no ISP given
39 * 3. add an async version of dialing functions which notify the caller about
40 * the progress (or may be even start another thread to monitor it)
41 * 4. the static creation/accessor functions are not MT-safe - but is this
42 * really crucial? I think we may suppose they're always called from the
43 * main thread?
44 */
45
46class WXDLLEXPORT wxDialUpManager
47{
48public:
49 // this function should create and return the object of the
50 // platform-specific class derived from wxDialUpManager. It's implemented
51 // in the platform-specific source files.
52 static wxDialUpManager *Create();
53
54 // could the dialup manager be initialized correctly? If this function
55 // returns false, no other functions will work neither, so it's a good idea
56 // to call this function and check its result before calling any other
57 // wxDialUpManager methods
58 virtual bool IsOk() const = 0;
59
60 // virtual dtor for any base class
61 virtual ~wxDialUpManager() { }
62
63 // operations
64 // ----------
65
66 // fills the array with the names of all possible values for the first
67 // parameter to Dial() on this machine and returns their number (may be 0)
68 virtual size_t GetISPNames(wxArrayString& names) const = 0;
69
70 // dial the given ISP, use username and password to authentificate
71 //
72 // if no nameOfISP is given, the function will select the default one
73 //
74 // if no username/password are given, the function will try to do without
75 // them, but will ask the user if really needed
76 //
77 // if async parameter is false, the function waits until the end of dialing
78 // and returns true upon successful completion.
79 // if async is true, the function only initiates the connection and returns
80 // immediately - the result is reported via events (an event is sent
81 // anyhow, but if dialing failed it will be a DISCONNECTED one)
82 virtual bool Dial(const wxString& nameOfISP = wxEmptyString,
83 const wxString& username = wxEmptyString,
84 const wxString& password = wxEmptyString,
85 bool async = true) = 0;
86
87 // returns true if (async) dialing is in progress
88 virtual bool IsDialing() const = 0;
89
90 // cancel dialing the number initiated with Dial(async = true)
91 // NB: this won't result in DISCONNECTED event being sent
92 virtual bool CancelDialing() = 0;
93
94 // hang up the currently active dial up connection
95 virtual bool HangUp() = 0;
96
97 // online status
98 // -------------
99
100 // returns true if the computer has a permanent network connection (i.e. is
101 // on a LAN) and so there is no need to use Dial() function to go online
102 //
103 // NB: this functions tries to guess the result and it is not always
104 // guaranteed to be correct, so it's better to ask user for
105 // confirmation or give him a possibility to override it
106 virtual bool IsAlwaysOnline() const = 0;
107
108 // returns true if the computer is connected to the network: under Windows,
109 // this just means that a RAS connection exists, under Unix we check that
110 // the "well-known host" (as specified by SetWellKnownHost) is reachable
111 virtual bool IsOnline() const = 0;
112
113 // sometimes the built-in logic for determining the online status may fail,
114 // so, in general, the user should be allowed to override it. This function
115 // allows to forcefully set the online status - whatever our internal
116 // algorithm may think about it.
117 virtual void SetOnlineStatus(bool isOnline = true) = 0;
118
119 // set misc wxDialUpManager options
120 // --------------------------------
121
122 // enable automatical checks for the connection status and sending of
123 // wxEVT_DIALUP_CONNECTED/wxEVT_DIALUP_DISCONNECTED events. The interval
124 // parameter is only for Unix where we do the check manually: under
125 // Windows, the notification about the change of connection status is
126 // instantenous.
127 //
128 // Returns false if couldn't set up automatic check for online status.
129 virtual bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60) = 0;
130
131 // disable automatic check for connection status change - notice that the
132 // wxEVT_DIALUP_XXX events won't be sent any more neither.
133 virtual void DisableAutoCheckOnlineStatus() = 0;
134
135 // additional Unix-only configuration
136 // ----------------------------------
137
138 // under Unix, the value of well-known host is used to check whether we're
139 // connected to the internet. It's unused under Windows, but this function
140 // is always safe to call. The default value is www.yahoo.com.
141 virtual void SetWellKnownHost(const wxString& hostname,
142 int portno = 80) = 0;
143
144 // Sets the commands to start up the network and to hang up again. Used by
145 // the Unix implementations only.
146 virtual void
147 SetConnectCommand(const wxString& commandDial = wxT("/usr/bin/pon"),
148 const wxString& commandHangup = wxT("/usr/bin/poff")) = 0;
149};
150
151// ----------------------------------------------------------------------------
152// wxDialUpManager events
153// ----------------------------------------------------------------------------
154
155BEGIN_DECLARE_EVENT_TYPES()
156 DECLARE_EVENT_TYPE(wxEVT_DIALUP_CONNECTED, 450)
157 DECLARE_EVENT_TYPE(wxEVT_DIALUP_DISCONNECTED, 451)
158END_DECLARE_EVENT_TYPES()
159
160// the event class for the dialup events
161class WXDLLEXPORT wxDialUpEvent : public wxEvent
162{
163public:
164 wxDialUpEvent(bool isConnected, bool isOwnEvent) : wxEvent(isOwnEvent)
165 {
166 SetEventType(isConnected ? wxEVT_DIALUP_CONNECTED
167 : wxEVT_DIALUP_DISCONNECTED);
168 }
169
170 // is this a CONNECTED or DISCONNECTED event?
171 bool IsConnectedEvent() const
172 { return GetEventType() == wxEVT_DIALUP_CONNECTED; }
173
174 // does this event come from wxDialUpManager::Dial() or from some extrenal
175 // process (i.e. does it result from our own attempt to establish the
176 // connection)?
177 bool IsOwnEvent() const { return m_id != 0; }
178
179 // implement the base class pure virtual
180 virtual wxEvent *Clone() const { return new wxDialUpEvent(*this); }
181
182private:
183 DECLARE_NO_ASSIGN_CLASS(wxDialUpEvent)
184};
185
186// the type of dialup event handler function
187typedef void (wxEvtHandler::*wxDialUpEventFunction)(wxDialUpEvent&);
188
189#define wxDialUpEventHandler(func) \
190 (wxObjectEventFunction)(wxEventFunction)wxStaticCastEvent(wxDialUpEventFunction, &func)
191
192// macros to catch dialup events
193#define EVT_DIALUP_CONNECTED(func) \
194 wx__DECLARE_EVT0(wxEVT_DIALUP_CONNECTED, wxDialUpEventHandler(func))
195#define EVT_DIALUP_DISCONNECTED(func) \
196 wx__DECLARE_EVT0(wxEVT_DIALUP_DISCONNECTED, wxDialUpEventHandler(func))
197
198
199#endif // wxUSE_DIALUP_MANAGER
200
201#endif // _WX_DIALUP_H