include/wx/private/socket.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/private/socket.h
   3 // Purpose:     wxSocketImpl nd related declarations
   4 // Authors:     Guilhem Lavaux, Vadim Zeitlin
   5 // Created:     April 1997
   6 // RCS-ID:      $Id: socket.h 56994 2008-11-28 12:47:07Z VZ $
   7 // Copyright:   (c) 1997 Guilhem Lavaux
   8 //              (c) 2008 Vadim Zeitlin
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 /*
  13     Brief overview of different socket classes:
  14
  15     - wxSocketBase is the public class representing a socket ("Base" here
  16       refers to the fact that wxSocketClient and wxSocketServer are derived
  17       from it and predates the convention of using "Base" for common base
  18       classes for platform-specific classes in wxWidgets) with implementation
  19       common to all platforms and forwarding methods whose implementation
  20       differs between platforms to wxSocketImpl which it contains.
  21
  22     - wxSocketImpl is actually just an abstract base class having only code
  23       common to all platforms, the concrete implementation classes derive from
  24       it and are created by wxSocketImpl::Create().
  25
  26     - Some socket operations have different implementations in console-mode and
  27       GUI applications. wxSocketManager class exists to abstract this in such
  28       way that console applications (using wxBase) don't depend on wxNet. An
  29       object of this class is made available via wxApp and GUI applications set
  30       up a different kind of global socket manager from console ones.
  31
  32       TODO: it looks like wxSocketManager could be eliminated by providing
  33             methods for registering/unregistering sockets directly in
  34             wxEventLoop.
  35  */
  36
  37 #ifndef _WX_PRIVATE_SOCKET_H_
  38 #define _WX_PRIVATE_SOCKET_H_
  39
  40 #include "wx/defs.h"
  41
  42 #if wxUSE_SOCKETS
  43
  44 #include "wx/socket.h"
  45
  46 #include <stddef.h>
  47
  48 /*
  49    Including sys/types.h under Cygwin results in the warnings about "fd_set
  50    having been defined in sys/types.h" when winsock.h is included later and
  51    doesn't seem to be necessary anyhow. It's not needed under Mac neither.
  52  */
  53 #if !defined(__WXMAC__) && !defined(__CYGWIN__) && !defined(__WXWINCE__)
  54 #include <sys/types.h>
  55 #endif
  56
  57 #ifdef __WXWINCE__
  58 #include <stdlib.h>
  59 #endif
  60
  61 // include the header defining timeval: under Windows this struct is used only
  62 // with sockets so we need to include winsock.h which we do via windows.h
  63 #ifdef __WXMSW__
  64     #include "wx/msw/wrapwin.h"
  65 #else
  66     #include <sys/time.h>   // for timeval
  67 #endif
  68
  69 // these definitions are for MSW when we don't use configure, otherwise these
  70 // symbols are defined by configure
  71 #ifndef WX_SOCKLEN_T
  72     #define WX_SOCKLEN_T int
  73 #endif
  74
  75 #ifndef SOCKOPTLEN_T
  76     #define SOCKOPTLEN_T int
  77 #endif
  78
  79 // define some symbols which winsock.h defines but traditional BSD headers
  80 // don't
  81 #ifndef SOCKET
  82     #define SOCKET int
  83 #endif
  84
  85 #ifndef INVALID_SOCKET
  86     #define INVALID_SOCKET (-1)
  87 #endif
  88
  89 #ifndef SOCKET_ERROR
  90     #define SOCKET_ERROR (-1)
  91 #endif
  92
  93 #if wxUSE_IPV6
  94     typedef struct sockaddr_storage wxSockAddr;
  95 #else
  96     typedef struct sockaddr wxSockAddr;
  97 #endif
  98
  99 enum GAddressType
 100 {
 101     wxSOCKET_NOFAMILY = 0,
 102     wxSOCKET_INET,
 103     wxSOCKET_INET6,
 104     wxSOCKET_UNIX
 105 };
 106
 107 typedef int wxSocketEventFlags;
 108
 109 struct GAddress;
 110 class wxSocketImpl;
 111
 112 /*
 113    Class providing hooks abstracting the differences between console and GUI
 114    applications for socket code.
 115
 116    We also have different implementations of this class for different platforms
 117    allowing us to keep more things in the common code but the main reason for
 118    its existence is that we want the same socket code work differently
 119    depending on whether it's used from a console or a GUI program. This is
 120    achieved by implementing the virtual methods of this class differently in
 121    the objects returned by wxConsoleAppTraits::GetSocketManager() and the same
 122    method in wxGUIAppTraits.
 123  */
 124 class wxSocketManager
 125 {
 126 public:
 127     // set the manager to use, we don't take ownership of it
 128     //
 129     // this should be called before creating the first wxSocket object,
 130     // otherwise the manager returned by wxAppTraits::GetSocketManager() will
 131     // be used
 132     static void Set(wxSocketManager *manager);
 133
 134     // return the manager to use
 135     //
 136     // this initializes the manager at first use
 137     static wxSocketManager *Get()
 138     {
 139         if ( !ms_manager )
 140             Init();
 141
 142         return ms_manager;
 143     }
 144
 145     // called before the first wxSocket is created and should do the
 146     // initializations needed in order to use the network
 147     //
 148     // return true if initialized successfully; if this returns false sockets
 149     // can't be used at all
 150     virtual bool OnInit() = 0;
 151
 152     // undo the initializations of OnInit()
 153     virtual void OnExit() = 0;
 154
 155
 156     // these functions enable or disable monitoring of the given socket for the
 157     // specified events inside the currently running event loop (but notice
 158     // that both BSD and Winsock implementations actually use socket->m_server
 159     // value to determine what exactly should be monitored so it needs to be
 160     // set before calling these functions)
 161     virtual void Install_Callback(wxSocketImpl *socket,
 162                                   wxSocketNotify event = wxSOCKET_MAX_EVENT) = 0;
 163     virtual void Uninstall_Callback(wxSocketImpl *socket,
 164                                     wxSocketNotify event = wxSOCKET_MAX_EVENT) = 0;
 165
 166     virtual ~wxSocketManager() { }
 167
 168 private:
 169     // get the manager to use if we don't have it yet
 170     static void Init();
 171
 172     static wxSocketManager *ms_manager;
 173 };
 174
 175 /*
 176     Base class for all socket implementations providing functionality common to
 177     BSD and Winsock sockets.
 178
 179     Objects of this class are not created directly but only via its static
 180     Create() method which is implemented in port-specific code.
 181  */
 182 class wxSocketImpl
 183 {
 184 public:
 185     // static factory function: creates the low-level socket associated with
 186     // the given wxSocket (and inherits its attributes such as timeout)
 187     static wxSocketImpl *Create(wxSocketBase& wxsocket);
 188
 189     virtual ~wxSocketImpl();
 190
 191     // set various socket properties: all of those can only be called before
 192     // creating the socket
 193     void SetTimeout(unsigned long millisec);
 194     void SetNonBlocking(bool non_blocking) { m_non_blocking = non_blocking; }
 195     void SetReusable() { m_reusable = true; }
 196     void SetBroadcast() { m_broadcast = true; }
 197     void DontDoBind() { m_dobind = false; }
 198     void SetInitialSocketBuffers(int recv, int send)
 199     {
 200         m_initialRecvBufferSize = recv;
 201         m_initialSendBufferSize = send;
 202     }
 203
 204     wxSocketError SetLocal(GAddress *address);
 205     wxSocketError SetPeer(GAddress *address);
 206
 207     // accessors
 208     // ---------
 209
 210     GAddress *GetLocal();
 211     GAddress *GetPeer();
 212
 213     wxSocketError GetError() const { return m_error; }
 214     bool IsOk() const { return m_error == wxSOCKET_NOERROR; }
 215
 216
 217     // creating/closing the socket
 218     // --------------------------
 219
 220     // notice that SetLocal() must be called before creating the socket using
 221     // any of the functions below
 222     //
 223     // all of Create() functions return wxSOCKET_NOERROR if the operation
 224     // completed successfully or one of:
 225     //  wxSOCKET_INVSOCK - the socket is in use.
 226     //  wxSOCKET_INVADDR - the local (server) or peer (client) address has not
 227     //                     been set.
 228     //  wxSOCKET_IOERR   - any other error.
 229
 230     // create a socket listening on the local address specified by SetLocal()
 231     // (notice that DontDoBind() is ignored by this function)
 232     wxSocketError CreateServer();
 233
 234     // create a socket connected to the peer address specified by SetPeer()
 235     // (notice that DontDoBind() is ignored by this function)
 236     //
 237     // this function may return wxSOCKET_WOULDBLOCK in addition to the return
 238     // values listed above
 239     wxSocketError CreateClient();
 240
 241     // create (and bind unless DontDoBind() had been called) an UDP socket
 242     // associated with the given local address
 243     wxSocketError CreateUDP();
 244
 245     // may be called whether the socket was created or not, calls DoClose() if
 246     // it was indeed created
 247     void Close();
 248
 249     virtual void Shutdown();
 250
 251
 252     // IO operations
 253     // -------------
 254
 255     virtual int Read(char *buffer, int size) = 0;
 256     virtual int Write(const char *buffer, int size) = 0;
 257
 258     wxSocketEventFlags Select(wxSocketEventFlags flags);
 259
 260     virtual wxSocketImpl *WaitConnection(wxSocketBase& wxsocket) = 0;
 261
 262
 263     // notifications
 264     // -------------
 265
 266     // notify m_wxsocket about the given socket event by calling its (inaptly
 267     // named) OnRequest() method
 268     void NotifyOnStateChange(wxSocketNotify event);
 269
 270     // FIXME: this one probably isn't needed here at all
 271     virtual void Notify(bool WXUNUSED(notify)) { }
 272
 273     // TODO: make these fields protected and provide accessors for those of
 274     //       them that wxSocketBase really needs
 275 //protected:
 276     SOCKET m_fd;
 277
 278     int m_initialRecvBufferSize;
 279     int m_initialSendBufferSize;
 280
 281     GAddress *m_local;
 282     GAddress *m_peer;
 283     wxSocketError m_error;
 284
 285     bool m_non_blocking;
 286     bool m_server;
 287     bool m_stream;
 288     bool m_establishing;
 289     bool m_reusable;
 290     bool m_broadcast;
 291     bool m_dobind;
 292
 293     struct timeval m_timeout;
 294
 295     wxSocketEventFlags m_detected;
 296
 297 protected:
 298     wxSocketImpl(wxSocketBase& wxsocket);
 299
 300 private:
 301     // handle the given connect() return value (which may be 0 or EWOULDBLOCK
 302     // or something else)
 303     virtual wxSocketError DoHandleConnect(int ret) = 0;
 304
 305     // called by Close() if we have a valid m_fd
 306     virtual void DoClose() = 0;
 307
 308     // put this socket into non-blocking mode and enable monitoring this socket
 309     // as part of the event loop
 310     virtual void UnblockAndRegisterWithEventLoop() = 0;
 311
 312     // check that the socket wasn't created yet and that the given address
 313     // (either m_local or m_peer depending on the socket kind) is valid and
 314     // set m_error and return false if this is not the case
 315     bool PreCreateCheck(GAddress *addr);
 316
 317     // set the given socket option: this just wraps setsockopt(SOL_SOCKET)
 318     int SetSocketOption(int optname, int optval)
 319     {
 320         // although modern Unix systems use "const void *" for the 4th
 321         // parameter here, old systems and Winsock still use "const char *"
 322         return setsockopt(m_fd, SOL_SOCKET, optname,
 323                           reinterpret_cast<const char *>(&optval),
 324                           sizeof(optval));
 325     }
 326
 327     // set the given socket option to true value: this is an even simpler
 328     // wrapper for setsockopt(SOL_SOCKET) for boolean options
 329     int EnableSocketOption(int optname)
 330     {
 331         return SetSocketOption(optname, 1);
 332     }
 333
 334     // apply the options to the (just created) socket and register it with the
 335     // event loop by calling UnblockAndRegisterWithEventLoop()
 336     void PostCreation();
 337
 338     // update local address after binding/connecting
 339     wxSocketError UpdateLocalAddress();
 340
 341
 342     // set in ctor and never changed except that it's reset to NULL when the
 343     // socket is shut down
 344     wxSocketBase *m_wxsocket;
 345
 346     DECLARE_NO_COPY_CLASS(wxSocketImpl)
 347 };
 348
 349 #if defined(__WXMSW__)
 350     #include "wx/msw/gsockmsw.h"
 351 #else
 352     #include "wx/unix/private/sockunix.h"
 353 #endif
 354
 355
 356 /* GAddress */
 357
 358 // TODO: make GAddress a real class instead of this mix of C and C++
 359
 360 // Represents a socket endpoint, i.e. -- in spite of its name -- not an address
 361 // but an (address, port) pair
 362 struct GAddress
 363 {
 364     struct sockaddr *m_addr;
 365     size_t m_len;
 366
 367     GAddressType m_family;
 368     int m_realfamily;
 369
 370     wxSocketError m_error;
 371 };
 372
 373 GAddress *GAddress_new();
 374 GAddress *GAddress_copy(GAddress *address);
 375 void GAddress_destroy(GAddress *address);
 376
 377 void GAddress_SetFamily(GAddress *address, GAddressType type);
 378 GAddressType GAddress_GetFamily(GAddress *address);
 379
 380 /* The use of any of the next functions will set the address family to
 381  * the specific one. For example if you use GAddress_INET_SetHostName,
 382  * address family will be implicitly set to AF_INET.
 383  */
 384
 385 wxSocketError GAddress_INET_SetHostName(GAddress *address, const char *hostname);
 386 wxSocketError GAddress_INET_SetBroadcastAddress(GAddress *address);
 387 wxSocketError GAddress_INET_SetAnyAddress(GAddress *address);
 388 wxSocketError GAddress_INET_SetHostAddress(GAddress *address,
 389                                           unsigned long hostaddr);
 390 wxSocketError GAddress_INET_SetPortName(GAddress *address, const char *port,
 391                                        const char *protocol);
 392 wxSocketError GAddress_INET_SetPort(GAddress *address, unsigned short port);
 393
 394 wxSocketError GAddress_INET_GetHostName(GAddress *address, char *hostname,
 395                                        size_t sbuf);
 396 unsigned long GAddress_INET_GetHostAddress(GAddress *address);
 397 unsigned short GAddress_INET_GetPort(GAddress *address);
 398
 399 wxSocketError _GAddress_translate_from(GAddress *address,
 400                                       struct sockaddr *addr, int len);
 401 wxSocketError _GAddress_translate_to  (GAddress *address,
 402                                       struct sockaddr **addr, int *len);
 403 wxSocketError _GAddress_Init_INET(GAddress *address);
 404
 405 #if wxUSE_IPV6
 406
 407 wxSocketError GAddress_INET6_SetHostName(GAddress *address, const char *hostname);
 408 wxSocketError GAddress_INET6_SetAnyAddress(GAddress *address);
 409 wxSocketError GAddress_INET6_SetHostAddress(GAddress *address,
 410                                           struct in6_addr hostaddr);
 411 wxSocketError GAddress_INET6_SetPortName(GAddress *address, const char *port,
 412                                        const char *protocol);
 413 wxSocketError GAddress_INET6_SetPort(GAddress *address, unsigned short port);
 414
 415 wxSocketError GAddress_INET6_GetHostName(GAddress *address, char *hostname,
 416                                        size_t sbuf);
 417 wxSocketError GAddress_INET6_GetHostAddress(GAddress *address,struct in6_addr *hostaddr);
 418 unsigned short GAddress_INET6_GetPort(GAddress *address);
 419
 420 #endif // wxUSE_IPV6
 421
 422 // these functions are available under all platforms but only implemented under
 423 // Unix ones, elsewhere they just return wxSOCKET_INVADDR
 424 wxSocketError _GAddress_Init_UNIX(GAddress *address);
 425 wxSocketError GAddress_UNIX_SetPath(GAddress *address, const char *path);
 426 wxSocketError GAddress_UNIX_GetPath(GAddress *address, char *path, size_t sbuf);
 427
 428 #endif /* wxUSE_SOCKETS */
 429
 430 #endif /* _WX_PRIVATE_SOCKET_H_ */