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