include/wx/net.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/net.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$
   8 // Copyright:   (c) Vadim Zeitlin
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_NET_H
  13 #define _WX_NET_H
  14
  15 #if wxUSE_DIALUP_MANAGER
  16
  17 // ----------------------------------------------------------------------------
  18 // A class which groups functions dealing with connecting to the network from a
  19 // workstation using dial-up access to the net. There is at most one instance
  20 // of this class in the program accessed via GetDialUpManager().
  21 // ----------------------------------------------------------------------------
  22
  23 /* TODO
  24  *
  25  * 1. more configurability for Unix: i.e. how to initiate the connection, how
  26  *    to check for online status, &c.
  27  * 2. add a "long Dial(long connectionId = -1)" function which asks the user
  28  *    about which connection to dial (this may be done using native dialogs
  29  *    under NT, need generic dialogs for all others) and returns the identifier
  30  *    of the selected connection (it's opaque to the application) - it may be
  31  *    reused later to dial the same connection later (or use strings instead of
  32  *    longs may be?)
  33  * 3. add an async version of dialing functions which notify the caller about
  34  *    the progress (or may be even start another thread to monitor it)
  35  * 4. the static creation/accessor functions are not MT-safe - but is this
  36  *    really crucial? I think we may suppose they're always called from the
  37  *    main thread?
  38  */
  39
  40 class WXDLLEXPORT wxDialUpManager
  41 {
  42 public:
  43     // get the pointer to the global wxDialUpManager object
  44     static wxDialUpManager *Get()
  45     {
  46         if ( !ms_dialUpManager )
  47         {
  48             ms_dialUpManager = Create();
  49         }
  50
  51         return ms_dialUpManager;
  52     }
  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     // the simplest way to initiate a dial up: this function dials the given
  67     // ISP (exact meaning of the parameter depends on the platform), returns
  68     // TRUE on success or FALSE on failure and logs the appropriate error
  69     // message in the latter case.
  70     virtual bool Dial(const wxString& nameOfISP,
  71                       const wxString& username,
  72                       const wxString& password) = 0;
  73
  74     // hang up the currently active dial up connection
  75     virtual bool HangUp() = 0;
  76
  77     // online status
  78     // -------------
  79
  80     // returns TRUE if the computer is connected to the network: under Windows,
  81     // this just means that a RAS connection exists, under Unix we check that
  82     // the "well-known host" (as specified by SetWellKnownHost) is reachable
  83     virtual bool IsOnline() = 0;
  84
  85     // sometimes the built-in logic for determining the online status may fail,
  86     // so, in general, the user should be allowed to override it. This function
  87     // allows to forcefully set the online status - whatever our internal
  88     // algorithm may think about it.
  89     virtual void SetOnlineStatus(bool isOnline = TRUE) = 0;
  90
  91     // set misc wxDialUpManager options
  92     // --------------------------------
  93
  94     // enable automatical checks for the connection status and sending of
  95     // wxEVT_DIALUP_CONNECTED/wxEVT_DIALUP_DISCONNECTED events. The interval
  96     // parameter is only for Unix where we do the check manually: under
  97     // Windows, the notification about the change of connection status is
  98     // instantenous.
  99     //
 100     // Returns FALSE if couldn't set up automatic check for online status.
 101     virtual bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60) = 0;
 102
 103     // disable automatic check for connection status change - notice that the
 104     // wxEVT_DIALUP_XXX events won't be sent any more neither.
 105     virtual void DisableAutoCheckOnlineStatus() = 0;
 106
 107     // under Unix, the value of well-known host is used to check whether we're
 108     // connected to the internet. It's unused under Windows, but this function
 109     // is always safe to call. The default value is www.yahoo.com.
 110     virtual void SetWellKnownHost(const wxString& hostname) = 0;
 111
 112 private:
 113     friend class WXDLLEXPORT wxApp;
 114
 115     // only for wxApp usage: clean up.
 116     static void Delete()
 117     {
 118         if ( ms_dialUpManager )
 119         {
 120             delete ms_dialUpManager;
 121             ms_dialUpManager = (wxDialUpManager *)NULL;
 122         }
 123     }
 124
 125     // this function should create and return the object of the
 126     // platform-specific class derived from wxDialUpManager. It's implemented
 127     // in the platform-specific source files.
 128     static wxDialUpManager *Create();
 129
 130     // the unique instance of this class
 131     static wxDialUpManager *ms_dialUpManager;
 132 };
 133
 134 // ----------------------------------------------------------------------------
 135 // DIALUP events processing
 136 // ----------------------------------------------------------------------------
 137
 138 // the event class for the dialup events
 139 class WXDLLEXPORT wxDialUpEvent : public wxEvent
 140 {
 141 public:
 142     wxDialUpEvent(bool isConnected) : wxEvent(isConnected)
 143     {
 144         SetEventType(isConnected ? wxEVT_DIALUP_CONNECTED
 145                                  : wxEVT_DIALUP_DISCONNECTED);
 146     }
 147
 148     // is this a CONNECTED or DISCONNECTED event?
 149     bool IsConnectedEvent() const { return m_id != 0; }
 150 };
 151
 152 // the type of dialup event handler function
 153 typedef void (wxObject::*wxDialUpEventFunction)(wxDialUpEvent&);
 154
 155 // macros to catch dialup events
 156 #define EVT_DIALUP_CONNECTED(func) { wxEVT_DIALUP_CONNECTED, -1, -1, (wxObjectEventFunction) (wxEventFunction) (wxDialUpEventFunction) & func, NULL},
 157 #define EVT_DIALUP_DISCONNECTED(func) { wxEVT_DIALUP_DISCONNECTED, -1, -1, (wxObjectEventFunction) (wxEventFunction) (wxDialUpEventFunction) & func, NULL},
 158
 159 #endif // wxUSE_DIALUP_MANAGER
 160
 161 #endif // _WX_NET_H