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 #include <sys/types.h>
  12
  13 #if !defined(__cplusplus)
  14
  15 typedef int bool;
  16
  17 #endif
  18
  19 #ifndef TRUE
  20 #define TRUE 1
  21 #endif
  22
  23 #ifndef FALSE
  24 #define FALSE 0
  25 #endif
  26
  27 typedef struct _GSocket GSocket;
  28 typedef struct _GAddress GAddress;
  29
  30 typedef enum {
  31   GSOCK_NOFAMILY = 0,
  32   GSOCK_INET,
  33   GSOCK_INET6,
  34   GSOCK_UNIX
  35 } GAddressType;
  36
  37 typedef enum {
  38   GSOCK_STREAMED,
  39   GSOCK_UNSTREAMED
  40 } GSocketStream;
  41
  42 typedef enum {
  43   GSOCK_NOERROR = 0,
  44   GSOCK_INVOP,
  45   GSOCK_IOERR,
  46   GSOCK_INVADDR,
  47   GSOCK_INVSOCK,
  48   GSOCK_NOHOST,
  49   GSOCK_INVPORT
  50 } GSocketError;
  51
  52 typedef enum {
  53   GSOCK_INPUT  = 0,
  54   GSOCK_OUTPUT = 1,
  55   GSOCK_CONNECTION = 2,
  56   GSOCK_LOST = 3,
  57   GSOCK_MAX_EVENT = 4
  58 } GSocketEvent;
  59
  60 enum {
  61   GSOCK_INPUT_FLAG = 1 << GSOCK_INPUT,
  62   GSOCK_OUTPUT_FLAG = 1 << GSOCK_OUTPUT,
  63   GSOCK_CONNECTION_FLAG = 1 << GSOCK_CONNECTION,
  64   GSOCK_LOST_FLAG = 1 << GSOCK_LOST
  65 };
  66
  67 typedef int GSocketEventFlags;
  68
  69 typedef void (*GSocketCallback)(GSocket *socket, GSocketEvent event,
  70                                 char *cdata);
  71
  72 #ifdef __cplusplus
  73 extern "C" {
  74 #endif
  75
  76 /* Global initialisers */
  77
  78 /* GSocket_Init() must be called at the beginning */
  79 bool GSocket_Init();
  80 /* GSocket_Cleanup() must be called at the ending */
  81 void GSocket_Cleanup();
  82
  83 /* Constructors / Destructors */
  84
  85 GSocket *GSocket_new();
  86 void GSocket_destroy(GSocket *socket);
  87
  88 /* This will disable all IO calls to this socket but errors are still available */
  89 void GSocket_Shutdown(GSocket *socket);
  90
  91 /* Address handling */
  92
  93 GSocketError GSocket_SetLocal(GSocket *socket, GAddress *address);
  94 GSocketError GSocket_SetPeer(GSocket *socket, GAddress *address);
  95 GAddress *GSocket_GetLocal(GSocket *socket);
  96 GAddress *GSocket_GetPeer(GSocket *socket);
  97
  98 /* Non-oriented connections handlers */
  99
 100 GSocketError GSocket_SetNonOriented(GSocket *socket);
 101
 102 /* Server specific parts */
 103
 104 /*
 105   GSocket_SetServer() setups the socket as a server. It uses the "Local" field
 106   of GSocket. "Local" must be set by GSocket_SetLocal() before
 107   GSocket_SetServer() is called. In the other case, it returns GSOCK_INVADDR.
 108 */
 109 GSocketError GSocket_SetServer(GSocket *socket);
 110
 111 /*
 112   GSocket_WaitConnection() waits for an incoming client connection.
 113 */
 114 GSocket *GSocket_WaitConnection(GSocket *socket);
 115
 116 /* Client specific parts */
 117
 118 /*
 119   GSocket_Connect() establishes a client connection to a server using the "Peer"
 120   field of GSocket. "Peer" must be set by GSocket_SetPeer() before
 121   GSocket_Connect() is called. In the other case, it returns GSOCK_INVADDR.
 122 */
 123 GSocketError GSocket_Connect(GSocket *socket, GSocketStream stream);
 124
 125 /* Generic IO */
 126
 127 /* Like recv(), send(), ... */
 128 /*
 129    NOTE: In case we read from a non-oriented connection, the incoming (outgoing)
 130    connection address is stored in the "Local" ("Peer") field.
 131 */
 132 int GSocket_Read(GSocket *socket, char *buffer, int size);
 133 int GSocket_Write(GSocket *socket, const char *buffer,
 134                   int size);
 135 bool GSocket_DataAvailable(GSocket *socket);
 136
 137 /* Flags/Parameters */
 138
 139 /*
 140   GSocket_SetTimeout() sets the timeout for reading and writing IO call. Time
 141   is expressed in milliseconds.
 142  */
 143 void GSocket_SetTimeout(GSocket *socket, unsigned long millisec);
 144
 145 /*
 146   GSocket_SetBlocking() puts the socket in non-blocking mode. This is useful
 147   if we don't want to wait.
 148 */
 149 void GSocket_SetNonBlocking(GSocket *socket, bool non_block);
 150
 151 /*
 152   GSocket_GetError() returns the last error occured on the socket stream.
 153 */
 154
 155 GSocketError GSocket_GetError(GSocket *socket);
 156
 157 /* Callbacks */
 158
 159 /*
 160    Only one fallback is possible for each event (INPUT, OUTPUT, CONNECTION, LOST)
 161    INPUT: The function is called when there is at least a byte in the
 162           input buffer
 163    OUTPUT: The function is called when the system is sure the next write call
 164            will not block
 165    CONNECTION: Two cases is possible:
 166              Client socket -> the connection is established
 167              Server socket -> a client request a connection
 168    LOST: the connection is lost
 169
 170    SetCallback accepts a combination of these flags so a same callback can
 171    receive different events.
 172
 173    An event is generated only once and its state is reseted when the relative
 174    IO call is requested.
 175    For example: INPUT -> GSocket_Read()
 176                 CONNECTION -> GSocket_Accept()
 177 */
 178 void GSocket_SetCallback(GSocket *socket, GSocketEventFlags event,
 179                          GSocketCallback fallback, char *cdata);
 180
 181 /*
 182   UnsetCallback will disables all fallbacks specified by "event".
 183   NOTE: event may be a combination of flags
 184 */
 185 void GSocket_UnsetCallback(GSocket *socket, GSocketEventFlags event);
 186
 187 /* GAddress */
 188
 189 GAddress *GAddress_new();
 190 GAddress *GAddress_copy(GAddress *address);
 191 void GAddress_destroy(GAddress *address);
 192
 193 void GAddress_SetFamily(GAddress *address, GAddressType type);
 194 GAddressType GAddress_GetFamily(GAddress *address);
 195
 196 /*
 197    The use of any of the next functions will set the address family to the adapted
 198    one. For example if you use GAddress_INET_SetHostName, address family will be AF_INET
 199    implicitely
 200 */
 201
 202 GSocketError GAddress_INET_SetHostName(GAddress *address, const char *hostname);
 203 GSocketError GAddress_INET_SetHostAddress(GAddress *address,
 204                                           unsigned long hostaddr);
 205 GSocketError GAddress_INET_SetPortName(GAddress *address, const char *port,
 206                                        const char *protocol);
 207 GSocketError GAddress_INET_SetPort(GAddress *address, unsigned short port);
 208
 209 GSocketError GAddress_INET_GetHostName(GAddress *address, char *hostname,
 210                                        size_t sbuf);
 211 unsigned long GAddress_INET_GetHostAddress(GAddress *address);
 212 unsigned short GAddress_INET_GetPort(GAddress *address);
 213
 214 /* TODO: Define specific parts (INET6, UNIX) */
 215
 216 GSocketError GAddress_UNIX_SetPath(GAddress *address, const char *path);
 217 GSocketError GAddress_UNIX_GetPath(GAddress *address, char *path, size_t sbuf);
 218
 219 /*
 220  * System specific functions
 221  */
 222
 223 /* On systems needing an event id */
 224 void GSocket_SetEventID(GSocket *socket, unsigned long evt_id);
 225
 226 /* On systems which don't have background refresh */
 227 void GSocket_DoEvent(unsigned long evt_id);
 228
 229 #ifdef __cplusplus
 230 };
 231 #endif
 232
 233 #endif
 234  /* __GSOCKET_H */