include/wx/gsocket.h

   1 /* -------------------------------------------------------------------------
   2  * Project: GSocket (Generic Socket)
   3  * Name:    gsocket.h
   4  * Author:  Guilhem Lavaux
   5  *          Guillermo Rodriguez Garcia <guille@iies.es> (maintainer)
   6  * Purpose: GSocket include file (system independent)
   7  * CVSID:   $Id$
   8  * -------------------------------------------------------------------------
   9  */
  10
  11 #ifndef __GSOCKET_H
  12 #define __GSOCKET_H
  13
  14 #ifndef __GSOCKET_STANDALONE__
  15 #include "wx/setup.h"
  16 #endif
  17
  18 #if wxUSE_SOCKETS || defined(__GSOCKET_STANDALONE__)
  19
  20 #include <stddef.h>
  21 #include <sys/types.h>
  22
  23 #if !defined(__cplusplus)
  24 typedef unsigned int bool;
  25 #endif
  26
  27 #ifndef TRUE
  28 #define TRUE 1
  29 #endif
  30
  31 #ifndef FALSE
  32 #define FALSE 0
  33 #endif
  34
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 typedef struct _GSocket GSocket;
  41 typedef struct _GAddress GAddress;
  42
  43 typedef enum {
  44   GSOCK_NOFAMILY = 0,
  45   GSOCK_INET,
  46   GSOCK_INET6,
  47   GSOCK_UNIX
  48 } GAddressType;
  49
  50 typedef enum {
  51   GSOCK_STREAMED,
  52   GSOCK_UNSTREAMED
  53 } GSocketStream;
  54
  55 typedef enum {
  56   GSOCK_NOERROR = 0,
  57   GSOCK_INVOP,
  58   GSOCK_IOERR,
  59   GSOCK_INVADDR,
  60   GSOCK_INVSOCK,
  61   GSOCK_NOHOST,
  62   GSOCK_INVPORT,
  63   GSOCK_WOULDBLOCK,
  64   GSOCK_TIMEDOUT,
  65   GSOCK_MEMERR
  66 } GSocketError;
  67
  68 /* See below for an explanation on how events work.
  69  */
  70 typedef enum {
  71   GSOCK_INPUT  = 0,
  72   GSOCK_OUTPUT = 1,
  73   GSOCK_CONNECTION = 2,
  74   GSOCK_LOST = 3,
  75   GSOCK_MAX_EVENT = 4
  76 } GSocketEvent;
  77
  78 enum {
  79   GSOCK_INPUT_FLAG = 1 << GSOCK_INPUT,
  80   GSOCK_OUTPUT_FLAG = 1 << GSOCK_OUTPUT,
  81   GSOCK_CONNECTION_FLAG = 1 << GSOCK_CONNECTION,
  82   GSOCK_LOST_FLAG = 1 << GSOCK_LOST
  83 };
  84
  85 typedef int GSocketEventFlags;
  86
  87 typedef void (*GSocketCallback)(GSocket *socket, GSocketEvent event,
  88                                 char *cdata);
  89
  90
  91 /* Global initializers */
  92
  93 /* GSocket_Init() must be called at the beginning */
  94 bool GSocket_Init(void);
  95
  96 /* GSocket_Cleanup() must be called at the end */
  97 void GSocket_Cleanup(void);
  98
  99
 100 /* Constructors / Destructors */
 101
 102 GSocket *GSocket_new(void);
 103 void GSocket_destroy(GSocket *socket);
 104
 105
 106
 107 /* GSocket_Shutdown:
 108  *  Disallow further read/write operations on this socket, close
 109  *  the fd and disable all callbacks.
 110  */
 111 void GSocket_Shutdown(GSocket *socket);
 112
 113 /* Address handling */
 114
 115 /* GSocket_SetLocal:
 116  * GSocket_GetLocal:
 117  * GSocket_SetPeer:
 118  * GSocket_GetPeer:
 119  *  Set or get the local or peer address for this socket. The 'set'
 120  *  functions return GSOCK_NOERROR on success, an error code otherwise.
 121  *  The 'get' functions return a pointer to a GAddress object on success,
 122  *  or NULL otherwise, in which case they set the error code of the
 123  *  corresponding GSocket.
 124  *
 125  *  Error codes:
 126  *    GSOCK_INVSOCK - the socket is not valid.
 127  *    GSOCK_INVADDR - the address is not valid.
 128  */
 129 GSocketError GSocket_SetLocal(GSocket *socket, GAddress *address);
 130 GSocketError GSocket_SetPeer(GSocket *socket, GAddress *address);
 131 GAddress *GSocket_GetLocal(GSocket *socket);
 132 GAddress *GSocket_GetPeer(GSocket *socket);
 133
 134 /* Server specific parts */
 135
 136 /* GSocket_SetServer:
 137  *  Sets up this socket as a server. The local address must have been
 138  *  set with GSocket_SetLocal() before GSocket_SetServer() is called.
 139  *  Returns GSOCK_NOERROR on success, one of the following otherwise:
 140  *
 141  *  Error codes:
 142  *    GSOCK_INVSOCK - the socket is in use.
 143  *    GSOCK_INVADDR - the local address has not been set.
 144  *    GSOCK_IOERR   - low-level error.
 145  */
 146 GSocketError GSocket_SetServer(GSocket *socket);
 147
 148 /* GSocket_WaitConnection:
 149  *  Waits for an incoming client connection. Returns a pointer to
 150  *  a GSocket object, or NULL if there was an error, in which case
 151  *  the last error field will be updated for the calling GSocket.
 152  *
 153  *  Error codes (set in the calling GSocket)
 154  *    GSOCK_INVSOCK    - the socket is not valid or not a server.
 155  *    GSOCK_TIMEDOUT   - timeout, no incoming connections.
 156  *    GSOCK_WOULDBLOCK - the call would block and the socket is nonblocking.
 157  *    GSOCK_MEMERR     - couldn't allocate memory.
 158  *    GSOCK_IOERR      - low-level error.
 159  */
 160 GSocket *GSocket_WaitConnection(GSocket *socket);
 161
 162
 163 /* Client specific parts */
 164
 165 /* GSocket_Connect:
 166  *  For stream (connection oriented) sockets, GSocket_Connect() tries
 167  *  to establish a client connection to a server using the peer address
 168  *  as established with GSocket_SetPeer(). Returns GSOCK_NOERROR if the
 169  *  connection has been succesfully established, or one of the error
 170  *  codes listed below. Note that for nonblocking sockets, a return
 171  *  value of GSOCK_WOULDBLOCK doesn't mean a failure. The connection
 172  *  request can be completed later; you should use GSocket_Select()
 173  *  to poll for GSOCK_CONNECTION | GSOCK_LOST, or wait for the
 174  *  corresponding asynchronous events.
 175  *
 176  *  For datagram (non connection oriented) sockets, GSocket_Connect()
 177  *  just sets the peer address established with GSocket_SetPeer() as
 178  *  default destination.
 179  *
 180  *  Error codes:
 181  *    GSOCK_INVSOCK    - the socket is in use or not valid.
 182  *    GSOCK_INVADDR    - the peer address has not been established.
 183  *    GSOCK_TIMEDOUT   - timeout, the connection failed.
 184  *    GSOCK_WOULDBLOCK - connection in progress (nonblocking sockets only)
 185  *    GSOCK_MEMERR     - couldn't allocate memory.
 186  *    GSOCK_IOERR      - low-level error.
 187  */
 188 GSocketError GSocket_Connect(GSocket *socket, GSocketStream stream);
 189
 190
 191 /* Datagram sockets */
 192
 193 /* GSocket_SetNonOriented:
 194  *  Sets up this socket as a non-connection oriented (datagram) socket.
 195  *  Before using this function, the local address must have been set
 196  *  with GSocket_SetLocal(), or the call will fail. Returns GSOCK_NOERROR
 197  *  on success, or one of the following otherwise.
 198  *
 199  *  Error codes:
 200  *    GSOCK_INVSOCK - the socket is in use.
 201  *    GSOCK_INVADDR - the local address has not been set.
 202  *    GSOCK_IOERR   - low-level error.
 203  */
 204 GSocketError GSocket_SetNonOriented(GSocket *socket);
 205
 206
 207 /* Generic IO */
 208
 209 /* Like recv(), send(), ... */
 210
 211 /* For datagram sockets, the incoming / outgoing addresses
 212  * are stored as / read from the 'peer' address field.
 213  */
 214 int GSocket_Read(GSocket *socket, char *buffer, int size);
 215 int GSocket_Write(GSocket *socket, const char *buffer,
 216                   int size);
 217
 218 /* GSocket_Select:
 219  *  Polls the socket to determine its status. This function will
 220  *  check for the events specified in the 'flags' parameter, and
 221  *  it will return a mask indicating which operations can be
 222  *  performed. This function won't block, regardless of the
 223  *  mode (blocking | nonblocking) of the socket.
 224  */
 225 GSocketEventFlags GSocket_Select(GSocket *socket, GSocketEventFlags flags);
 226
 227
 228 /* Attributes */
 229
 230 /* GSocket_SetNonBlocking:
 231  *  Sets the socket to non-blocking mode. All IO calls will return
 232  *  immediately.
 233  */
 234 void GSocket_SetNonBlocking(GSocket *socket, bool non_block);
 235
 236 /* GSocket_SetTimeout:
 237  *  Sets the timeout for blocking calls. Time is expressed in
 238  *  milliseconds.
 239  */
 240 void GSocket_SetTimeout(GSocket *socket, unsigned long millisec);
 241
 242 /* GSocket_GetError:
 243  *  Returns the last error occured for this socket. Note that successful
 244  *  operations do not clear this back to GSOCK_NOERROR, so use it only
 245  *  after an error.
 246  */
 247 GSocketError GSocket_GetError(GSocket *socket);
 248
 249
 250 /* Callbacks */
 251
 252 /* GSOCK_INPUT:
 253  *   There is data to be read in the input buffer. If, after a read
 254  *   operation, there is still data available, the callback function will
 255  *   be called again.
 256  * GSOCK_OUTPUT:
 257  *   The socket is available for writing. That is, the next write call
 258  *   won't block. This event is generated only once, when the connection is
 259  *   first established, and then only if a call failed with GSOCK_WOULDBLOCK,
 260  *   when the output buffer empties again. This means that the app should
 261  *   assume that it can write since the first OUTPUT event, and no more
 262  *   OUTPUT events will be generated unless an error occurs.
 263  * GSOCK_CONNECTION:
 264  *   Connection succesfully established, for client sockets, or incoming
 265  *   client connection, for server sockets. Wait for this event (also watch
 266  *   out for GSOCK_LOST) after you issue a nonblocking GSocket_Connect() call.
 267  * GSOCK_LOST:
 268  *   The connection is lost (or a connection request failed); this could
 269  *   be due to a failure, or due to the peer closing it gracefully.
 270  */
 271
 272 /* GSocket_SetCallback:
 273  *  Enables the callbacks specified by 'flags'. Note that 'flags'
 274  *  may be a combination of flags OR'ed toghether, so the same
 275  *  callback function can be made to accept different events.
 276  *  The callback function must have the following prototype:
 277  *
 278  *  void function(GSocket *socket, GSocketEvent event, char *cdata)
 279  */
 280 void GSocket_SetCallback(GSocket *socket, GSocketEventFlags flags,
 281                          GSocketCallback fallback, char *cdata);
 282
 283 /* GSocket_UnsetCallback:
 284  *  Disables all callbacks specified by 'flags', which may be a
 285  *  combination of flags OR'ed toghether.
 286  */
 287 void GSocket_UnsetCallback(GSocket *socket, GSocketEventFlags flags);
 288
 289
 290 /* GAddress */
 291
 292 GAddress *GAddress_new(void);
 293 GAddress *GAddress_copy(GAddress *address);
 294 void GAddress_destroy(GAddress *address);
 295
 296 void GAddress_SetFamily(GAddress *address, GAddressType type);
 297 GAddressType GAddress_GetFamily(GAddress *address);
 298
 299 /* The use of any of the next functions will set the address family to
 300  * the specific one. For example if you use GAddress_INET_SetHostName,
 301  * address family will be implicitly set to AF_INET.
 302  */
 303
 304 GSocketError GAddress_INET_SetHostName(GAddress *address, const char *hostname);
 305 GSocketError GAddress_INET_SetAnyAddress(GAddress *address);
 306 GSocketError GAddress_INET_SetHostAddress(GAddress *address,
 307                                           unsigned long hostaddr);
 308 GSocketError GAddress_INET_SetPortName(GAddress *address, const char *port,
 309                                        const char *protocol);
 310 GSocketError GAddress_INET_SetPort(GAddress *address, unsigned short port);
 311
 312 GSocketError GAddress_INET_GetHostName(GAddress *address, char *hostname,
 313                                        size_t sbuf);
 314 unsigned long GAddress_INET_GetHostAddress(GAddress *address);
 315 unsigned short GAddress_INET_GetPort(GAddress *address);
 316
 317 /* TODO: Define specific parts (INET6, UNIX) */
 318
 319 GSocketError GAddress_UNIX_SetPath(GAddress *address, const char *path);
 320 GSocketError GAddress_UNIX_GetPath(GAddress *address, char *path, size_t sbuf);
 321
 322 #ifdef __cplusplus
 323 };
 324 #endif /* __cplusplus */
 325
 326
 327 #endif    /* wxUSE_SOCKETS || defined(__GSOCKET_STANDALONE__) */
 328
 329 #endif    /* __GSOCKET_H */