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 #define WXDIALUP_MANAGER_DEFAULT_BEACONHOST  "www.yahoo.com"
  41
  42 class WXDLLEXPORT wxDialUpManager
  43 {
  44 public:
  45     // this function should create and return the object of the
  46     // platform-specific class derived from wxDialUpManager. It's implemented
  47     // in the platform-specific source files.
  48     static wxDialUpManager *Create();
  49
  50     // could the dialup manager be initialized correctly? If this function
  51     // returns FALSE, no other functions will work neither, so it's a good idea
  52     // to call this function and check its result before calling any other
  53     // wxDialUpManager methods
  54     virtual bool IsOk() const = 0;
  55
  56     // virtual dtor for any base class
  57     virtual ~wxDialUpManager() { }
  58
  59     // operations
  60     // ----------
  61
  62     // the simplest way to initiate a dial up: this function dials the given
  63     // ISP (exact meaning of the parameter depends on the platform), returns
  64     // TRUE on success or FALSE on failure and logs the appropriate error
  65     // message in the latter case.
  66     virtual bool Dial(const wxString& nameOfISP = "",
  67                       const wxString& username = "",
  68                       const wxString& password = "") = 0;
  69
  70     // hang up the currently active dial up connection
  71     virtual bool HangUp() = 0;
  72
  73     // online status
  74     // -------------
  75
  76     // returns TRUE if the computer is connected to the network: under Windows,
  77     // this just means that a RAS connection exists, under Unix we check that
  78     // the "well-known host" (as specified by SetWellKnownHost) is reachable
  79     virtual bool IsOnline() const = 0;
  80
  81     // sometimes the built-in logic for determining the online status may fail,
  82     // so, in general, the user should be allowed to override it. This function
  83     // allows to forcefully set the online status - whatever our internal
  84     // algorithm may think about it.
  85     virtual void SetOnlineStatus(bool isOnline = TRUE) = 0;
  86
  87     // set misc wxDialUpManager options
  88     // --------------------------------
  89
  90     // enable automatical checks for the connection status and sending of
  91     // wxEVT_DIALUP_CONNECTED/wxEVT_DIALUP_DISCONNECTED events. The interval
  92     // parameter is only for Unix where we do the check manually: under
  93     // Windows, the notification about the change of connection status is
  94     // instantenous.
  95     //
  96     // Returns FALSE if couldn't set up automatic check for online status.
  97     virtual bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60) = 0;
  98
  99     // disable automatic check for connection status change - notice that the
 100     // wxEVT_DIALUP_XXX events won't be sent any more neither.
 101     virtual void DisableAutoCheckOnlineStatus() = 0;
 102
 103     // under Unix, the value of well-known host is used to check whether we're
 104     // connected to the internet. It's unused under Windows, but this function
 105     // is always safe to call. The default value is www.yahoo.com.
 106     virtual void SetWellKnownHost(const wxString& hostname,
 107                                   int portno = 80) = 0;
 108     /** Sets the commands to start up the network and to hang up
 109         again. Used by the Unix implementations only.
 110     */
 111     virtual void SetConnectCommand(const wxString &command = "/usr/bin/pon",
 112                                    const wxString &hupcmd = "/usr/bin/poff")
 113       { }
 114 };
 115
 116 // ----------------------------------------------------------------------------
 117 // DIALUP events processing
 118 // ----------------------------------------------------------------------------
 119
 120 // the event class for the dialup events
 121 class WXDLLEXPORT wxDialUpEvent : public wxEvent
 122 {
 123 public:
 124     wxDialUpEvent(bool isConnected) : wxEvent(isConnected)
 125     {
 126         SetEventType(isConnected ? wxEVT_DIALUP_CONNECTED
 127                                  : wxEVT_DIALUP_DISCONNECTED);
 128     }
 129
 130     // is this a CONNECTED or DISCONNECTED event?
 131     bool IsConnectedEvent() const { return m_id != 0; }
 132 };
 133
 134 // the type of dialup event handler function
 135 typedef void (wxObject::*wxDialUpEventFunction)(wxDialUpEvent&);
 136
 137 // macros to catch dialup events
 138 #define EVT_DIALUP_CONNECTED(func) { wxEVT_DIALUP_CONNECTED, -1, -1, (wxObjectEventFunction) (wxEventFunction) (wxDialUpEventFunction) & func, NULL},
 139 #define EVT_DIALUP_DISCONNECTED(func) { wxEVT_DIALUP_DISCONNECTED, -1, -1, (wxObjectEventFunction) (wxEventFunction) (wxDialUpEventFunction) & func, NULL},
 140
 141 #endif // wxUSE_DIALUP_MANAGER
 142
 143 #endif // _WX_NET_H