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