include/wx/socket.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        socket.h
   3 // Purpose:     Socket handling classes
   4 // Authors:     Guilhem Lavaux, Guillermo Rodriguez Garcia
   5 // Modified by:
   6 // Created:     April 1997
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Guilhem Lavaux
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_SOCKET_H_
  13 #define _WX_SOCKET_H_
  14
  15 #include "wx/defs.h"
  16
  17 #if wxUSE_SOCKETS
  18
  19 // ---------------------------------------------------------------------------
  20 // wxSocket headers
  21 // ---------------------------------------------------------------------------
  22
  23 #include "wx/event.h"
  24 #include "wx/sckaddr.h"
  25 #include "wx/list.h"
  26
  27 class wxSocketImpl;
  28
  29 // ------------------------------------------------------------------------
  30 // Types and constants
  31 // ------------------------------------------------------------------------
  32
  33 // Types of different socket notifications or events.
  34 //
  35 // NB: the values here should be consecutive and start with 0 as they are
  36 //     used to construct the wxSOCKET_XXX_FLAG bit mask values below
  37 enum wxSocketNotify
  38 {
  39     wxSOCKET_INPUT,
  40     wxSOCKET_OUTPUT,
  41     wxSOCKET_CONNECTION,
  42     wxSOCKET_LOST
  43 };
  44
  45 enum
  46 {
  47     wxSOCKET_INPUT_FLAG = 1 << wxSOCKET_INPUT,
  48     wxSOCKET_OUTPUT_FLAG = 1 << wxSOCKET_OUTPUT,
  49     wxSOCKET_CONNECTION_FLAG = 1 << wxSOCKET_CONNECTION,
  50     wxSOCKET_LOST_FLAG = 1 << wxSOCKET_LOST
  51 };
  52
  53 // this is a combination of the bit masks defined above
  54 typedef int wxSocketEventFlags;
  55
  56 enum wxSocketError
  57 {
  58     wxSOCKET_NOERROR = 0,
  59     wxSOCKET_INVOP,
  60     wxSOCKET_IOERR,
  61     wxSOCKET_INVADDR,
  62     wxSOCKET_INVSOCK,
  63     wxSOCKET_NOHOST,
  64     wxSOCKET_INVPORT,
  65     wxSOCKET_WOULDBLOCK,
  66     wxSOCKET_TIMEDOUT,
  67     wxSOCKET_MEMERR,
  68     wxSOCKET_OPTERR
  69 };
  70
  71 // socket options/flags bit masks
  72 enum
  73 {
  74     wxSOCKET_NONE = 0,
  75     wxSOCKET_NOWAIT = 1,
  76     wxSOCKET_WAITALL = 2,
  77     wxSOCKET_BLOCK = 4,
  78     wxSOCKET_REUSEADDR = 8,
  79     wxSOCKET_BROADCAST = 16,
  80     wxSOCKET_NOBIND = 32
  81 };
  82
  83 typedef int wxSocketFlags;
  84
  85 // socket kind values (badly defined, don't use)
  86 enum wxSocketType
  87 {
  88     wxSOCKET_UNINIT,
  89     wxSOCKET_CLIENT,
  90     wxSOCKET_SERVER,
  91     wxSOCKET_BASE,
  92     wxSOCKET_DATAGRAM
  93 };
  94
  95
  96
  97 // --------------------------------------------------------------------------
  98 // wxSocketBase
  99 // --------------------------------------------------------------------------
 100
 101 class WXDLLIMPEXP_NET wxSocketBase : public wxObject
 102 {
 103 public:
 104
 105   // Public interface
 106   // ----------------
 107
 108   // ctors and dtors
 109   wxSocketBase();
 110   wxSocketBase(wxSocketFlags flags, wxSocketType type);
 111   virtual ~wxSocketBase();
 112   void Init();
 113   bool Destroy();
 114
 115   // state
 116   bool Ok() const { return IsOk(); }
 117   bool IsOk() const { return m_impl != NULL; }
 118   bool Error() const { return LastError() != wxSOCKET_NOERROR; }
 119   bool IsClosed() const { return m_closed; }
 120   bool IsConnected() const { return m_connected; }
 121   bool IsData() { return WaitForRead(0, 0); }
 122   bool IsDisconnected() const { return !IsConnected(); }
 123   wxUint32 LastCount() const { return m_lcount; }
 124   wxSocketError LastError() const;
 125   void SaveState();
 126   void RestoreState();
 127
 128   // addresses
 129   virtual bool GetLocal(wxSockAddress& addr_man) const;
 130   virtual bool GetPeer(wxSockAddress& addr_man) const;
 131   virtual bool SetLocal(const wxIPV4address& local);
 132
 133   // base IO
 134   virtual bool  Close();
 135   void ShutdownOutput();
 136   wxSocketBase& Discard();
 137   wxSocketBase& Peek(void* buffer, wxUint32 nbytes);
 138   wxSocketBase& Read(void* buffer, wxUint32 nbytes);
 139   wxSocketBase& ReadMsg(void *buffer, wxUint32 nbytes);
 140   wxSocketBase& Unread(const void *buffer, wxUint32 nbytes);
 141   wxSocketBase& Write(const void *buffer, wxUint32 nbytes);
 142   wxSocketBase& WriteMsg(const void *buffer, wxUint32 nbytes);
 143
 144   // all Wait() functions wait until their condition is satisfied or the
 145   // timeout expires; if seconds == -1 (default) then m_timeout value is used
 146   //
 147   // it is also possible to call InterruptWait() to cancel any current Wait()
 148
 149   // wait for anything at all to happen with this socket
 150   bool Wait(long seconds = -1, long milliseconds = 0);
 151
 152   // wait until we can read from or write to the socket without blocking
 153   // (notice that this does not mean that the operation will succeed but only
 154   // that it will return immediately)
 155   bool WaitForRead(long seconds = -1, long milliseconds = 0);
 156   bool WaitForWrite(long seconds = -1, long milliseconds = 0);
 157
 158   // wait until the connection is terminated
 159   bool WaitForLost(long seconds = -1, long milliseconds = 0);
 160
 161   void InterruptWait() { m_interrupt = true; }
 162
 163
 164   wxSocketFlags GetFlags() const { return m_flags; }
 165   void SetFlags(wxSocketFlags flags);
 166   void SetTimeout(long seconds);
 167   long GetTimeout() const { return m_timeout; }
 168
 169   bool GetOption(int level, int optname, void *optval, int *optlen);
 170   bool SetOption(int level, int optname, const void *optval, int optlen);
 171   wxUint32 GetLastIOSize() const { return m_lcount; }
 172
 173   // event handling
 174   void *GetClientData() const { return m_clientData; }
 175   void SetClientData(void *data) { m_clientData = data; }
 176   void SetEventHandler(wxEvtHandler& handler, int id = wxID_ANY);
 177   void SetNotify(wxSocketEventFlags flags);
 178   void Notify(bool notify);
 179
 180   // initialize/shutdown the sockets (usually called automatically)
 181   static bool IsInitialized();
 182   static bool Initialize();
 183   static void Shutdown();
 184
 185
 186   // Implementation from now on
 187   // --------------------------
 188
 189   // do not use, should be private (called from wxSocketImpl only)
 190   void OnRequest(wxSocketNotify notify);
 191
 192   // do not use, not documented nor supported
 193   bool IsNoWait() const { return ((m_flags & wxSOCKET_NOWAIT) != 0); }
 194   wxSocketType GetType() const { return m_type; }
 195
 196 private:
 197   friend class wxSocketClient;
 198   friend class wxSocketServer;
 199   friend class wxDatagramSocket;
 200
 201   // low level IO
 202   wxUint32 DoRead(void* buffer, wxUint32 nbytes);
 203   wxUint32 DoWrite(const void *buffer, wxUint32 nbytes);
 204
 205   // wait until the given flags are set for this socket or the given timeout
 206   // (or m_timeout) expires
 207   //
 208   // notice that wxSOCKET_LOST_FLAG is always taken into account but the return
 209   // value depends on whether it is included in flags or not: if it is, and the
 210   // connection is indeed lost, true is returned, but if it isn't then the
 211   // function returns false in this case
 212   //
 213   // false is always returned if we returned because of the timeout expiration
 214   bool DoWait(long timeout, wxSocketEventFlags flags);
 215
 216   // a helper calling DoWait() using the same convention as the public
 217   // WaitForXXX() functions use, i.e. use our timeout if seconds == -1 or the
 218   // specified timeout otherwise
 219   bool DoWait(long seconds, long milliseconds, wxSocketEventFlags flags);
 220
 221   // another helper calling DoWait() using our m_timeout
 222   bool DoWaitWithTimeout(wxSocketEventFlags flags)
 223   {
 224       return DoWait(m_timeout*1000, flags);
 225   }
 226
 227   // pushback buffer
 228   void     Pushback(const void *buffer, wxUint32 size);
 229   wxUint32 GetPushback(void *buffer, wxUint32 size, bool peek);
 230
 231   // store the given error as the LastError()
 232   void SetError(wxSocketError error);
 233
 234 private:
 235   // socket
 236   wxSocketImpl *m_impl;             // port-specific implementation
 237   wxSocketType  m_type;             // wxSocket type
 238
 239   // state
 240   wxSocketFlags m_flags;            // wxSocket flags
 241   bool          m_connected;        // connected?
 242   bool          m_establishing;     // establishing connection?
 243   bool          m_reading;          // busy reading?
 244   bool          m_writing;          // busy writing?
 245   bool          m_closed;           // was the other end closed?
 246   wxUint32      m_lcount;           // last IO transaction size
 247   unsigned long m_timeout;          // IO timeout value in seconds
 248   wxList        m_states;           // stack of states
 249   bool          m_interrupt;        // interrupt ongoing wait operations?
 250   bool          m_beingDeleted;     // marked for delayed deletion?
 251   wxIPV4address m_localAddress;     // bind to local address?
 252
 253   // pushback buffer
 254   void         *m_unread;           // pushback buffer
 255   wxUint32      m_unrd_size;        // pushback buffer size
 256   wxUint32      m_unrd_cur;         // pushback pointer (index into buffer)
 257
 258   // events
 259   int           m_id;               // socket id
 260   wxEvtHandler *m_handler;          // event handler
 261   void         *m_clientData;       // client data for events
 262   bool          m_notify;           // notify events to users?
 263   wxSocketEventFlags  m_eventmask;  // which events to notify?
 264   wxSocketEventFlags  m_eventsgot;  // collects events received in OnRequest()
 265
 266   // the initialization count, GSocket is initialized if > 0
 267   static size_t m_countInit;
 268
 269   DECLARE_NO_COPY_CLASS(wxSocketBase)
 270   DECLARE_CLASS(wxSocketBase)
 271 };
 272
 273
 274 // --------------------------------------------------------------------------
 275 // wxSocketServer
 276 // --------------------------------------------------------------------------
 277
 278 class WXDLLIMPEXP_NET wxSocketServer : public wxSocketBase
 279 {
 280   DECLARE_CLASS(wxSocketServer)
 281
 282 public:
 283   wxSocketServer(const wxSockAddress& addr, wxSocketFlags flags = wxSOCKET_NONE);
 284
 285   wxSocketBase* Accept(bool wait = true);
 286   bool AcceptWith(wxSocketBase& socket, bool wait = true);
 287
 288   bool WaitForAccept(long seconds = -1, long milliseconds = 0);
 289
 290   DECLARE_NO_COPY_CLASS(wxSocketServer)
 291 };
 292
 293
 294 // --------------------------------------------------------------------------
 295 // wxSocketClient
 296 // --------------------------------------------------------------------------
 297
 298 class WXDLLIMPEXP_NET wxSocketClient : public wxSocketBase
 299 {
 300   DECLARE_CLASS(wxSocketClient)
 301
 302 public:
 303   wxSocketClient(wxSocketFlags flags = wxSOCKET_NONE);
 304   virtual ~wxSocketClient();
 305
 306   virtual bool Connect(const wxSockAddress& addr, bool wait = true);
 307   bool Connect(const wxSockAddress& addr, const wxSockAddress& local,
 308                bool wait = true);
 309
 310   bool WaitOnConnect(long seconds = -1, long milliseconds = 0);
 311
 312   // Sets initial socket buffer sizes using the SO_SNDBUF and SO_RCVBUF options
 313   // before calling connect (either one can be -1 to leave it unchanged)
 314   void SetInitialSocketBuffers(int recv, int send)
 315   {
 316       m_initialRecvBufferSize = recv;
 317       m_initialSendBufferSize = send;
 318   }
 319
 320 private:
 321   virtual bool DoConnect(const wxSockAddress& addr,
 322                          const wxSockAddress* local,
 323                          bool wait = true);
 324
 325   // buffer sizes, -1 if unset and defaults should be used
 326   int m_initialRecvBufferSize;
 327   int m_initialSendBufferSize;
 328
 329   DECLARE_NO_COPY_CLASS(wxSocketClient)
 330 };
 331
 332
 333 // --------------------------------------------------------------------------
 334 // wxDatagramSocket
 335 // --------------------------------------------------------------------------
 336
 337 // WARNING: still in alpha stage
 338
 339 class WXDLLIMPEXP_NET wxDatagramSocket : public wxSocketBase
 340 {
 341   DECLARE_CLASS(wxDatagramSocket)
 342
 343 public:
 344   wxDatagramSocket(const wxSockAddress& addr, wxSocketFlags flags = wxSOCKET_NONE);
 345
 346   wxDatagramSocket& RecvFrom( wxSockAddress& addr,
 347                               void* buf,
 348                               wxUint32 nBytes );
 349   wxDatagramSocket& SendTo( const wxSockAddress& addr,
 350                             const void* buf,
 351                             wxUint32 nBytes );
 352
 353 /* TODO:
 354   bool Connect(wxSockAddress& addr);
 355 */
 356   DECLARE_NO_COPY_CLASS(wxDatagramSocket)
 357 };
 358
 359
 360 // --------------------------------------------------------------------------
 361 // wxSocketEvent
 362 // --------------------------------------------------------------------------
 363
 364 class WXDLLIMPEXP_NET wxSocketEvent : public wxEvent
 365 {
 366 public:
 367   wxSocketEvent(int id = 0)
 368       : wxEvent(id, wxEVT_SOCKET)
 369       {
 370       }
 371
 372   wxSocketNotify  GetSocketEvent() const { return m_event; }
 373   wxSocketBase   *GetSocket() const      { return (wxSocketBase *) GetEventObject(); }
 374   void           *GetClientData() const  { return m_clientData; }
 375
 376   virtual wxEvent *Clone() const { return new wxSocketEvent(*this); }
 377
 378 public:
 379   wxSocketNotify  m_event;
 380   void           *m_clientData;
 381
 382   DECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxSocketEvent)
 383 };
 384
 385
 386 typedef void (wxEvtHandler::*wxSocketEventFunction)(wxSocketEvent&);
 387
 388 #define wxSocketEventHandler(func) \
 389     (wxObjectEventFunction)(wxEventFunction)wxStaticCastEvent(wxSocketEventFunction, &func)
 390
 391 #define EVT_SOCKET(id, func) \
 392     wx__DECLARE_EVT1(wxEVT_SOCKET, id, wxSocketEventHandler(func))
 393
 394 #endif // wxUSE_SOCKETS
 395
 396 #endif // _WX_SOCKET_H_
 397