include/wx/gsocket.h

   1 /* -------------------------------------------------------------------------
   2  * Project: GSocket (Generic Socket)
   3  * Name:    gsocket.h
   4  * Purpose: GSocket include file (system independent)
   5  * CVSID:   $Id$
   6  * -------------------------------------------------------------------------
   7  */
   8 #ifndef __GSOCKET_H
   9 #define __GSOCKET_H
  10
  11 #ifndef __GSOCKET_STANDALONE__
  12 #include "wx/setup.h"
  13 #endif
  14
  15 #if wxUSE_SOCKETS || defined(__GSOCKET_STANDALONE__)
  16
  17 #include <stddef.h>
  18 #include <sys/types.h>
  19
  20 #if !defined(__cplusplus)
  21 typedef unsigned int bool;
  22 #endif
  23
  24 #ifndef TRUE
  25 #define TRUE 1
  26 #endif
  27
  28 #ifndef FALSE
  29 #define FALSE 0
  30 #endif
  31
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 typedef struct _GSocket GSocket;
  38 typedef struct _GAddress GAddress;
  39
  40 typedef enum {
  41   GSOCK_NOFAMILY = 0,
  42   GSOCK_INET,
  43   GSOCK_INET6,
  44   GSOCK_UNIX
  45 } GAddressType;
  46
  47 typedef enum {
  48   GSOCK_STREAMED,
  49   GSOCK_UNSTREAMED
  50 } GSocketStream;
  51
  52 typedef enum {
  53   GSOCK_NOERROR = 0,
  54   GSOCK_INVOP,
  55   GSOCK_IOERR,
  56   GSOCK_INVADDR,
  57   GSOCK_INVSOCK,
  58   GSOCK_NOHOST,
  59   GSOCK_INVPORT,
  60   GSOCK_WOULDBLOCK,
  61   GSOCK_TIMEDOUT,
  62   GSOCK_MEMERR
  63 } GSocketError;
  64
  65 typedef enum {
  66   GSOCK_INPUT  = 0,
  67   GSOCK_OUTPUT = 1,
  68   GSOCK_CONNECTION = 2,
  69   GSOCK_LOST = 3,
  70   GSOCK_MAX_EVENT = 4
  71 } GSocketEvent;
  72
  73 enum {
  74   GSOCK_INPUT_FLAG = 1 << GSOCK_INPUT,
  75   GSOCK_OUTPUT_FLAG = 1 << GSOCK_OUTPUT,
  76   GSOCK_CONNECTION_FLAG = 1 << GSOCK_CONNECTION,
  77   GSOCK_LOST_FLAG = 1 << GSOCK_LOST
  78 };
  79
  80 typedef int GSocketEventFlags;
  81
  82 typedef void (*GSocketCallback)(GSocket *socket, GSocketEvent event,
  83                                 char *cdata);
  84
  85
  86 /* Global initializers */
  87
  88 /* GSocket_Init() must be called at the beginning */
  89 bool GSocket_Init();
  90 /* GSocket_Cleanup() must be called at the ending */
  91 void GSocket_Cleanup();
  92
  93 /* Constructors / Destructors */
  94
  95 GSocket *GSocket_new();
  96 void GSocket_destroy(GSocket *socket);
  97
  98 /* This will disable all further IO calls to this socket */
  99 void GSocket_Shutdown(GSocket *socket);
 100
 101 /* Address handling */
 102
 103 GSocketError GSocket_SetLocal(GSocket *socket, GAddress *address);
 104 GSocketError GSocket_SetPeer(GSocket *socket, GAddress *address);
 105 GAddress *GSocket_GetLocal(GSocket *socket);
 106 GAddress *GSocket_GetPeer(GSocket *socket);
 107
 108 /* Non-oriented connections handlers */
 109
 110 GSocketError GSocket_SetNonOriented(GSocket *socket);
 111
 112 /* Server specific parts */
 113
 114 /* GSocket_SetServer:
 115  *  Sets up the socket as a server. It uses the "Local" field of GSocket.
 116  *  "Local" must be set by GSocket_SetLocal() before GSocket_SetServer()
 117  *  is called. Possible error codes are: GSOCK_INVSOCK if socket has not
 118  *  been initialized, GSOCK_INVADDR if the local address has not been
 119  *  defined and GSOCK_IOERR for other internal errors.
 120  */
 121 GSocketError GSocket_SetServer(GSocket *socket);
 122
 123 /* GSocket_WaitConnection:
 124  *  Waits for an incoming client connection.
 125  */
 126 GSocket *GSocket_WaitConnection(GSocket *socket);
 127
 128 /* Client specific parts */
 129
 130 /* GSocket_Connect:
 131  *  Establishes a client connection to a server using the "Peer"
 132  *  field of GSocket. "Peer" must be set by GSocket_SetPeer() before
 133  *  GSocket_Connect() is called. Possible error codes are GSOCK_INVSOCK,
 134  *  GSOCK_INVADDR, GSOCK_TIMEDOUT, GSOCK_WOULDBLOCK and GSOCK_IOERR.
 135  *  If a socket is nonblocking and Connect() returns GSOCK_WOULDBLOCK,
 136  *  the connection request can be completed later. Use GSocket_Select()
 137  *  to check it, or wait for a GSOCK_CONNECTION event.
 138  */
 139 GSocketError GSocket_Connect(GSocket *socket, GSocketStream stream);
 140
 141 /* Generic IO */
 142
 143 /* Like recv(), send(), ... */
 144
 145 /* NOTE: In case we read from a non-oriented connection, the incoming
 146  * (outgoing) connection address is stored in the "Local" ("Peer")
 147  * field.
 148  */
 149 int GSocket_Read(GSocket *socket, char *buffer, int size);
 150 int GSocket_Write(GSocket *socket, const char *buffer,
 151                   int size);
 152
 153 /* GSocket_Select:
 154  *  Polls the socket to determine its status. This function will
 155  *  check for the events specified in the 'flags' parameter, and
 156  *  it will return a mask indicating which operations can be
 157  *  performed. This function won't block, regardless of the
 158  *  mode (blocking|nonblocking) of the socket.
 159  */
 160 GSocketEventFlags GSocket_Select(GSocket *socket, GSocketEventFlags flags);
 161
 162 /* Flags/Parameters */
 163
 164 /* GSocket_SetTimeout:
 165  *  Sets the timeout for blocking calls. Time is
 166  *  expressed in milliseconds.
 167  */
 168 void GSocket_SetTimeout(GSocket *socket, unsigned long millisec);
 169
 170 /* GSocket_SetNonBlocking:
 171  *  Sets the socket to non-blocking mode. This is useful if
 172  *  we don't want to wait.
 173  */
 174 void GSocket_SetNonBlocking(GSocket *socket, bool non_block);
 175
 176 /* GSocket_GetError:
 177  *  Returns the last error occured for this socket.
 178  */
 179 GSocketError GSocket_GetError(GSocket *socket);
 180
 181 /* Callbacks */
 182
 183 /* Only one callback is possible for each event (INPUT, OUTPUT, CONNECTION
 184  * and LOST). The callbacks are called in the following situations:
 185  *
 186  * INPUT: There is at least one byte in the input buffer
 187  * OUTPUT: The system is sure that the next write call will not block
 188  * CONNECTION: Two cases are possible:
 189  *           Client socket -> the connection is established
 190  *           Server socket -> a client requests a connection
 191  * LOST: The connection is lost
 192  *
 193  * An event is generated only once and its state is reseted when the
 194  * relative IO call is requested.
 195  * For example: INPUT -> GSocket_Read()
 196  *              CONNECTION -> GSocket_Accept()
 197  */
 198
 199 /* GSocket_SetCallback:
 200  *  Enables the callbacks specified by 'flags'. Note that 'flags'
 201  *  may be a combination of flags OR'ed toghether, so the same
 202  *  callback function can be made to accept different events.
 203  *  The callback function must have the following prototype:
 204  *
 205  *  void function(GSocket *socket, GSocketEvent event, char *cdata)
 206  */
 207 void GSocket_SetCallback(GSocket *socket, GSocketEventFlags flags,
 208                          GSocketCallback fallback, char *cdata);
 209
 210 /* GSocket_UnsetCallback:
 211  *  Disables all callbacks specified by 'flags', which may be a
 212  *  combination of flags OR'ed toghether.
 213  */
 214 void GSocket_UnsetCallback(GSocket *socket, GSocketEventFlags flags);
 215
 216 /* GAddress */
 217
 218 GAddress *GAddress_new();
 219 GAddress *GAddress_copy(GAddress *address);
 220 void GAddress_destroy(GAddress *address);
 221
 222 void GAddress_SetFamily(GAddress *address, GAddressType type);
 223 GAddressType GAddress_GetFamily(GAddress *address);
 224
 225 /* The use of any of the next functions will set the address family to
 226  * the specific one. For example if you use GAddress_INET_SetHostName,
 227  * address family will be implicitly set to AF_INET.
 228  */
 229
 230 GSocketError GAddress_INET_SetHostName(GAddress *address, const char *hostname);
 231 GSocketError GAddress_INET_SetHostAddress(GAddress *address,
 232                                           unsigned long hostaddr);
 233 GSocketError GAddress_INET_SetPortName(GAddress *address, const char *port,
 234                                        const char *protocol);
 235 GSocketError GAddress_INET_SetPort(GAddress *address, unsigned short port);
 236
 237 GSocketError GAddress_INET_GetHostName(GAddress *address, char *hostname,
 238                                        size_t sbuf);
 239 unsigned long GAddress_INET_GetHostAddress(GAddress *address);
 240 unsigned short GAddress_INET_GetPort(GAddress *address);
 241
 242 /* TODO: Define specific parts (INET6, UNIX) */
 243
 244 GSocketError GAddress_UNIX_SetPath(GAddress *address, const char *path);
 245 GSocketError GAddress_UNIX_GetPath(GAddress *address, char *path, size_t sbuf);
 246
 247 #ifdef __cplusplus
 248 };
 249 #endif /* __cplusplus */
 250
 251
 252 #endif    /* wxUSE_SOCKETS || defined(__GSOCKET_STANDALONE__) */
 253
 254 #endif    /* __GSOCKET_H */