]> git.saurik.com Git - wxWidgets.git/blob - include/wx/gsocket.h
Added simplistic makefile/project files for wxWinCE.
[wxWidgets.git] / 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
17 /* kludge for GTK.. gsockgtk.c craps out miserably if we include
18 defs.h ... no idea how other files get away with it.. */
19
20 #if !defined( __WXMSW__ ) && !defined( WXDLLEXPORT )
21 #define WXDLLEXPORT
22 #endif
23
24 #endif
25
26 #if wxUSE_SOCKETS || defined(__GSOCKET_STANDALONE__)
27
28 #include <stddef.h>
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__)
36 #include <sys/types.h>
37 #endif
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43 typedef struct _GSocket GSocket;
44 typedef struct _GAddress GAddress;
45
46 typedef enum {
47 GSOCK_NOFAMILY = 0,
48 GSOCK_INET,
49 GSOCK_INET6,
50 GSOCK_UNIX
51 } GAddressType;
52
53 typedef enum {
54 GSOCK_STREAMED,
55 GSOCK_UNSTREAMED
56 } GSocketStream;
57
58 typedef enum {
59 GSOCK_NOERROR = 0,
60 GSOCK_INVOP,
61 GSOCK_IOERR,
62 GSOCK_INVADDR,
63 GSOCK_INVSOCK,
64 GSOCK_NOHOST,
65 GSOCK_INVPORT,
66 GSOCK_WOULDBLOCK,
67 GSOCK_TIMEDOUT,
68 GSOCK_MEMERR
69 } GSocketError;
70
71 /* See below for an explanation on how events work.
72 */
73 typedef 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
81 enum {
82 GSOCK_INPUT_FLAG = 1 << GSOCK_INPUT,
83 GSOCK_OUTPUT_FLAG = 1 << GSOCK_OUTPUT,
84 GSOCK_CONNECTION_FLAG = 1 << GSOCK_CONNECTION,
85 GSOCK_LOST_FLAG = 1 << GSOCK_LOST
86 };
87
88 typedef int GSocketEventFlags;
89
90 typedef void (*GSocketCallback)(GSocket *socket, GSocketEvent event,
91 char *cdata);
92
93
94 /* Global initializers */
95
96 /* GSocket_Init() must be called at the beginning */
97 int GSocket_Init(void);
98
99 /* GSocket_Cleanup() must be called at the end */
100 void GSocket_Cleanup(void);
101
102
103 /* Constructors / Destructors */
104
105 GSocket *GSocket_new(void);
106 void GSocket_destroy(GSocket *socket);
107
108
109
110 /* GSocket_Shutdown:
111 * Disallow further read/write operations on this socket, close
112 * the fd and disable all callbacks.
113 */
114 void GSocket_Shutdown(GSocket *socket);
115
116 /* Address handling */
117
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 */
132 GSocketError GSocket_SetLocal(GSocket *socket, GAddress *address);
133 GSocketError GSocket_SetPeer(GSocket *socket, GAddress *address);
134 GAddress *GSocket_GetLocal(GSocket *socket);
135 GAddress *GSocket_GetPeer(GSocket *socket);
136
137 /* Server specific parts */
138
139 /* GSocket_SetServer:
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:
143 *
144 * Error codes:
145 * GSOCK_INVSOCK - the socket is in use.
146 * GSOCK_INVADDR - the local address has not been set.
147 * GSOCK_IOERR - low-level error.
148 */
149 GSocketError GSocket_SetServer(GSocket *socket);
150
151 /* GSocket_WaitConnection:
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.
161 * GSOCK_IOERR - low-level error.
162 */
163 GSocket *GSocket_WaitConnection(GSocket *socket);
164
165
166 /* Client specific parts */
167
168 /* GSocket_Connect:
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.
189 * GSOCK_IOERR - low-level error.
190 */
191 GSocketError GSocket_Connect(GSocket *socket, GSocketStream stream);
192
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.
205 * GSOCK_IOERR - low-level error.
206 */
207 GSocketError GSocket_SetNonOriented(GSocket *socket);
208
209
210 /* Generic IO */
211
212 /* Like recv(), send(), ... */
213
214 /* For datagram sockets, the incoming / outgoing addresses
215 * are stored as / read from the 'peer' address field.
216 */
217 int GSocket_Read(GSocket *socket, char *buffer, int size);
218 int GSocket_Write(GSocket *socket, const char *buffer,
219 int size);
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
226 * mode (blocking | nonblocking) of the socket.
227 */
228 GSocketEventFlags GSocket_Select(GSocket *socket, GSocketEventFlags flags);
229
230
231 /* Attributes */
232
233 /* GSocket_SetNonBlocking:
234 * Sets the socket to non-blocking mode. All IO calls will return
235 * immediately.
236 */
237 void GSocket_SetNonBlocking(GSocket *socket, int non_block);
238
239 /* GSocket_SetTimeout:
240 * Sets the timeout for blocking calls. Time is expressed in
241 * milliseconds.
242 */
243 void GSocket_SetTimeout(GSocket *socket, unsigned long millisec);
244
245 /* GSocket_GetError:
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.
249 */
250 GSocketError WXDLLEXPORT GSocket_GetError(GSocket *socket);
251
252
253 /* Callbacks */
254
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:
260 * The socket is available for writing. That is, the next write call
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.
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 */
283 void GSocket_SetCallback(GSocket *socket, GSocketEventFlags flags,
284 GSocketCallback fallback, char *cdata);
285
286 /* GSocket_UnsetCallback:
287 * Disables all callbacks specified by 'flags', which may be a
288 * combination of flags OR'ed toghether.
289 */
290 void GSocket_UnsetCallback(GSocket *socket, GSocketEventFlags flags);
291
292
293 /* GAddress */
294
295 GAddress *GAddress_new(void);
296 GAddress *GAddress_copy(GAddress *address);
297 void GAddress_destroy(GAddress *address);
298
299 void GAddress_SetFamily(GAddress *address, GAddressType type);
300 GAddressType GAddress_GetFamily(GAddress *address);
301
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 */
306
307 GSocketError GAddress_INET_SetHostName(GAddress *address, const char *hostname);
308 GSocketError GAddress_INET_SetAnyAddress(GAddress *address);
309 GSocketError GAddress_INET_SetHostAddress(GAddress *address,
310 unsigned long hostaddr);
311 GSocketError GAddress_INET_SetPortName(GAddress *address, const char *port,
312 const char *protocol);
313 GSocketError GAddress_INET_SetPort(GAddress *address, unsigned short port);
314
315 GSocketError GAddress_INET_GetHostName(GAddress *address, char *hostname,
316 size_t sbuf);
317 unsigned long GAddress_INET_GetHostAddress(GAddress *address);
318 unsigned short GAddress_INET_GetPort(GAddress *address);
319
320 /* TODO: Define specific parts (INET6, UNIX) */
321
322 GSocketError GAddress_UNIX_SetPath(GAddress *address, const char *path);
323 GSocketError GAddress_UNIX_GetPath(GAddress *address, char *path, size_t sbuf);
324
325 #ifdef __cplusplus
326 }
327 #endif /* __cplusplus */
328
329
330 #endif /* wxUSE_SOCKETS || defined(__GSOCKET_STANDALONE__) */
331
332 #endif /* __GSOCKET_H */