]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/socket.tex
typo fix.
[wxWidgets.git] / docs / latex / wx / socket.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %% Name: socket.tex
3 %% Purpose: wxSocket docs
4 %% Author: Guillermo Rodriguez Garcia <guille@iies.es>
5 %% Modified by:
6 %% Created: 1999
7 %% RCS-ID: $Id$
8 %% Copyright: (c) wxWindows team
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12 \section{\class{wxSocketBase}}\label{wxsocketbase}
13
14 wxSocketBase is the base class for all socket-related objects, and it
15 defines all basic IO functionality.
16
17 \wxheading{Derived from}
18
19 \helpref{wxObject}{wxobject}
20
21 \wxheading{Include files}
22
23 <wx/socket.h>
24
25 \wxheading{wxSocket errors}
26
27 \twocolwidtha{7cm}
28 \begin{twocollist}\itemsep=0pt
29 \twocolitem{{\bf wxSOCKET\_NOERROR}}{No error happened.}
30 \twocolitem{{\bf wxSOCKET\_INVOP}}{Invalid operation.}
31 \twocolitem{{\bf wxSOCKET\_IOERR}}{Input/Output error.}
32 \twocolitem{{\bf wxSOCKET\_INVADDR}}{Invalid address passed to wxSocket.}
33 \twocolitem{{\bf wxSOCKET\_INVSOCK}}{Invalid socket (uninitialized).}
34 \twocolitem{{\bf wxSOCKET\_NOHOST}}{No corresponding host.}
35 \twocolitem{{\bf wxSOCKET\_INVPORT}}{Invalid port.}
36 \twocolitem{{\bf wxSOCKET\_WOULDBLOCK}}{The socket is non-blocking and the operation would block.}
37 \twocolitem{{\bf wxSOCKET\_TIMEDOUT}}{The timeout for this operation expired.}
38 \twocolitem{{\bf wxSOCKET\_MEMERR}}{Memory exhausted.}
39 \end{twocollist}
40
41 \wxheading{wxSocket events}
42
43 \twocolwidtha{7cm}
44 \begin{twocollist}\itemsep=0pt
45 \twocolitem{{\bf wxSOCKET\_INPUT}}{There is data available for reading.}
46 \twocolitem{{\bf wxSOCKET\_OUTPUT}}{The socket is ready to be written to.}
47 \twocolitem{{\bf wxSOCKET\_CONNECTION}}{Incoming connection request (server), or successful connection establishment (client).}
48 \twocolitem{{\bf wxSOCKET\_LOST}}{The connection has been closed.}
49 \end{twocollist}
50
51 A brief note on how to use these events:
52
53 The {\bf wxSOCKET\_INPUT} event will be issued whenever there is data
54 available for reading. This will be the case if the input queue was
55 empty and new data arrives, or if the application has read some data
56 yet there is still more data available. This means that the application
57 does not need to read all available data in response to a
58 {\bf wxSOCKET\_INPUT} event, as more events will be produced as
59 necessary.
60
61 The {\bf wxSOCKET\_OUTPUT} event is issued when a socket is first
62 connected with \helpref{Connect}{wxsocketclientconnect} or accepted
63 with \helpref{Accept}{wxsocketserveraccept}. After that, new
64 events will be generated only after an output operation fails
65 with {\bf wxSOCKET\_WOULDBLOCK} and buffer space becomes available
66 again. This means that the application should assume that it
67 can write data to the socket until an {\bf wxSOCKET\_WOULDBLOCK}
68 error occurs; after this, whenever the socket becomes writable
69 again the application will be notified with another
70 {\bf wxSOCKET\_OUTPUT} event.
71
72 The {\bf wxSOCKET\_CONNECTION} event is issued when a delayed connection
73 request completes succesfully (client) or when a new connection arrives
74 at the incoming queue (server).
75
76 The {\bf wxSOCKET\_LOST} event is issued when a close indication is
77 received for the socket. This means that the connection broke down or
78 that it was closed by the peer. Also, this event will be issued if
79 a connection request fails.
80
81 \wxheading{Event handling}
82
83 To process events coming from a socket object, use the following event
84 handler macro to direct events to member functions that take
85 a \helpref{wxSocketEvent}{wxsocketevent} argument.
86
87 \twocolwidtha{7cm}%
88 \begin{twocollist}\itemsep=0pt
89 \twocolitem{{\bf EVT\_SOCKET(id, func)}}{Process a wxEVT\_SOCKET event.}
90 \end{twocollist}
91
92 \wxheading{See also}
93
94 \helpref{wxSocketEvent}{wxsocketevent},
95 \helpref{wxSocketClient}{wxsocketclient},
96 \helpref{wxSocketServer}{wxsocketserver},
97 \helpref{Sockets sample}{samplesockets}
98
99 % ---------------------------------------------------------------------------
100 % Function groups
101 % ---------------------------------------------------------------------------
102
103 \latexignore{\rtfignore{\wxheading{Function groups}}}
104
105 \membersection{Construction and destruction}
106
107 \helpref{wxSocketBase}{wxsocketbaseconstruct}\\
108 \helpref{\destruct{wxSocketBase}}{wxsocketbasedestruct}\\
109 \helpref{Destroy}{wxsocketbasedestroy}
110
111 \membersection{Socket state}
112
113 Functions to retrieve current state and miscellaneous info.
114
115 \helpref{Error}{wxsocketbaseerror}\\
116 \helpref{GetLocal}{wxsocketbasegetlocal}\\
117 \helpref{GetPeer}{wxsocketbasegetpeer}
118 \helpref{IsConnected}{wxsocketbaseisconnected}\\
119 \helpref{IsData}{wxsocketbaseisdata}\\
120 \helpref{IsDisconnected}{wxsocketbaseisdisconnected}\\
121 \helpref{LastCount}{wxsocketbaselastcount}\\
122 \helpref{LastError}{wxsocketbaselasterror}\\
123 \helpref{Ok}{wxsocketbaseok}\\
124 \helpref{SaveState}{wxsocketbasesavestate}\\
125 \helpref{RestoreState}{wxsocketbaserestorestate}
126
127 \membersection{Basic IO}
128
129 Functions that perform basic IO functionality.
130
131 \helpref{Close}{wxsocketbaseclose}\\
132 \helpref{Discard}{wxsocketbasediscard}\\
133 \helpref{Peek}{wxsocketbasepeek}\\
134 \helpref{Read}{wxsocketbaseread}\\
135 \helpref{ReadMsg}{wxsocketbasereadmsg}\\
136 \helpref{Unread}{wxsocketbaseunread}\\
137 \helpref{Write}{wxsocketbasewrite}\\
138 \helpref{WriteMsg}{wxsocketbasewritemsg}
139
140 Functions that perform a timed wait on a certain IO condition.
141
142 \helpref{InterruptWait}{wxsocketbaseinterruptwait}\\
143 \helpref{Wait}{wxsocketbasewait}\\
144 \helpref{WaitForLost}{wxsocketbasewaitforlost}\\
145 \helpref{WaitForRead}{wxsocketbasewaitforread}\\
146 \helpref{WaitForWrite}{wxsocketbasewaitforwrite}\\
147
148 and also:
149
150 \helpref{wxSocketServer::WaitForAccept}{wxsocketserverwaitforaccept}\\
151 \helpref{wxSocketClient::WaitOnConnect}{wxsocketclientwaitonconnect}
152
153 Functions that allow applications to customize socket IO as needed.
154
155 \helpref{GetFlags}{wxsocketbasegetflags}\\
156 \helpref{SetFlags}{wxsocketbasesetflags}\\
157 \helpref{SetTimeout}{wxsocketbasesettimeout}
158
159 \membersection{Handling socket events}
160
161 Functions that allow applications to receive socket events.
162
163 \helpref{Notify}{wxsocketbasenotify}\\
164 \helpref{SetNotify}{wxsocketbasesetnotify}\\
165 \helpref{GetClientData}{wxsocketbasegetclientdata}\\
166 \helpref{SetClientData}{wxsocketbasesetclientdata}\\
167 \helpref{SetEventHandler}{wxsocketbaseseteventhandler}
168
169 Callback functions are also available, but they are provided for backwards
170 compatibility only. Their use is strongly discouraged in favour of events,
171 and should be considered deprecated. Callbacks may be unsupported in future
172 releases of wxWindows.
173
174 \helpref{Callback}{wxsocketbasecallback}\\
175 \helpref{CallbackData}{wxsocketbasecallbackdata}
176
177
178 % ---------------------------------------------------------------------------
179 % Members here
180 % ---------------------------------------------------------------------------
181
182 \helponly{\insertatlevel{2}{
183
184 \wxheading{Members}
185
186 }}
187
188 \membersection{wxSocketBase::wxSocketBase}\label{wxsocketbaseconstruct}
189
190 \func{}{wxSocketBase}{\void}
191
192 Default constructor. Don't use it directly; instead, use
193 \helpref{wxSocketClient}{wxsocketclient} to construct a socket client, or
194 \helpref{wxSocketServer}{wxsocketserver} to construct a socket server.
195
196 \membersection{wxSocketBase::\destruct{wxSocketBase}}\label{wxsocketbasedestruct}
197
198 \func{}{\destruct{wxSocketBase}}{\void}
199
200 Destructor. Do not destroy a socket using the delete operator directly;
201 use \helpref{Destroy}{wxsocketbasedestroy} instead. Also, do not create
202 socket objects in the stack.
203
204 %
205 % Callback
206 %
207 \membersection{wxSocketBase::Callback}\label{wxsocketbasecallback}
208
209 \func{wxSocketBase::wxSockCbk}{Callback}{\param{wxSocketBase::wxSockCbk}{ callback}}
210
211 You can setup a callback function to be called when an event occurs.
212 The function will be called only for those events for which notification
213 has been enabled with \helpref{Notify}{wxsocketbasenotify} and
214 \helpref{SetNotify}{wxsocketbasesetnotify}. The prototype of the
215 callback must be as follows:
216
217 \begin{verbatim}
218 void SocketCallback(wxSocketBase& sock, wxSocketNotify evt, char *cdata);
219 \end{verbatim}
220
221 The first parameter is a reference to the socket object in which the
222 event occurred. The second parameter tells you which event occurred.
223 (See \helpref{wxSocket events}{wxsocketbase}). The third parameter
224 is the user data you specified using \helpref{CallbackData}{wxsocketbasecallbackdata}.
225
226 \wxheading{Return value}
227
228 A pointer to the previous callback.
229
230 \wxheading{Remark/Warning}
231
232 Note that callbacks are now deprecated and unsupported, and they remain
233 for backwards compatibility only. Use events instead.
234
235 \wxheading{See also}
236
237 \helpref{wxSocketBase::CallbackData}{wxsocketbasecallbackdata},
238 \helpref{wxSocketBase::SetNotify}{wxsocketbasesetnotify},
239 \helpref{wxSocketBase::Notify}{wxsocketbasenotify}
240
241 %
242 % CallbackData
243 %
244 \membersection{wxSocketBase::CallbackData}\label{wxsocketbasecallbackdata}
245
246 \func{char *}{CallbackData}{\param{char *}{cdata}}
247
248 This function sets the the user data which will be passed to a
249 callback function set via \helpref{Callback}{wxsocketbasecallback}.
250
251 \wxheading{Return value}
252
253 A pointer to the previous user data.
254
255 \wxheading{Remark/Warning}
256
257 Note that callbacks are now deprecated and unsupported, and they remain
258 for backwards compatibility only. Use events instead.
259
260 \wxheading{See also}
261
262 \helpref{wxSocketBase::Callback}{wxsocketbasecallback},
263 \helpref{wxSocketBase::SetNotify}{wxsocketbasesetnotify},
264 \helpref{wxSocketBase::Notify}{wxsocketbasenotify}
265
266 %
267 % Close
268 %
269 \membersection{wxSocketBase::Close}\label{wxsocketbaseclose}
270
271 \func{void}{Close}{\void}
272
273 This function shuts down the socket, disabling further transmission and
274 reception of data; it also disables events for the socket and frees the
275 associated system resources. Upon socket destruction, Close is automatically
276 called, so in most cases you won't need to do it yourself, unless you
277 explicitly want to shut down the socket, typically to notify the peer
278 that you are closing the connection.
279
280 \wxheading{Remark/Warning}
281
282 Although Close immediately disables events for the socket, it is possible
283 that event messages may be waiting in the application's event queue. The
284 application must therefore be prepared to handle socket event messages
285 even after calling Close.
286
287 %
288 % Destroy
289 %
290 \membersection{wxSocketBase::Destroy}\label{wxsocketbasedestroy}
291
292 \func{bool}{Destroy}{\void}
293
294 Destroys the socket safely. Use this function instead of the delete operator,
295 since otherwise socket events could reach the application even after the
296 socket has been destroyed. To prevent this problem, this function appends
297 the wxSocket to a list of object to be deleted on idle time, after all
298 events have been processed. For the same reason, you should avoid creating
299 socket objects in the stack.
300
301 Destroy calls \helpref{Close}{wxsocketbaseclose} automatically.
302
303 \wxheading{Return value}
304
305 Always TRUE.
306
307 %
308 % Discard
309 %
310 \membersection{wxSocketBase::Discard}\label{wxsocketbasediscard}
311
312 \func{wxSocketBase\&}{Discard}{\void}
313
314 This function simply deletes all bytes in the incoming queue. This function
315 always returns immediately and its operation is not affected by IO flags.
316
317 Use \helpref{LastCount}{wxsocketbaselastcount} to verify the number of bytes actually discarded.
318
319 If you use \helpref{Error}{wxsocketbaseerror}, it will always return FALSE.
320
321 %
322 % Error
323 %
324 \membersection{wxSocketBase::Error}\label{wxsocketbaseerror}
325
326 \constfunc{bool}{Error}{\void}
327
328 Returns TRUE if an error occurred in the last IO operation.
329
330 Use this function to check for an error condition after one of the
331 following calls: Discard, Peek, Read, ReadMsg, Unread, Write, WriteMsg.
332
333 %
334 % GetClientData
335 %
336 \membersection{wxSocketBase::GetClientData}\label{wxsocketbasegetclientdata}
337
338 \constfunc{void *}{GetClientData}{\void}
339
340 Returns a pointer of the client data for this socket, as set with
341 \helpref{SetClientData}{wxsocketbasesetclientdata}
342
343 %
344 % GetLocal
345 %
346 \membersection{wxSocketBase::GetLocal}\label{wxsocketbasegetlocal}
347
348 \constfunc{bool}{GetLocal}{\param{wxSockAddress\& }{addr}}
349
350 This function returns the local address field of the socket. The local
351 address field contains the complete local address of the socket (local
352 address, local port, ...).
353
354 \wxheading{Return value}
355
356 TRUE if no error happened, FALSE otherwise.
357
358 %
359 % GetFlags
360 %
361 \membersection{wxSocketBase::GetFlags}\label{wxsocketbasegetflags}
362
363 \constfunc{wxSocketFlags}{GetFlags}{\void}
364
365 Returns current IO flags, as set with \helpref{SetFlags}{wxsocketbasesetflags}
366
367 %
368 % GetPeer
369 %
370 \membersection{wxSocketBase::GetPeer}\label{wxsocketbasegetpeer}
371
372 \constfunc{bool}{GetPeer}{\param{wxSockAddress\& }{addr}}
373
374 This function returns the peer address field of the socket. The peer
375 address field contains the complete peer host address of the socket
376 (address, port, ...).
377
378 \wxheading{Return value}
379
380 TRUE if no error happened, FALSE otherwise.
381
382 %
383 % InterruptWait
384 %
385 \membersection{wxSocketBase::InterruptWait}\label{wxsocketbaseinterruptwait}
386
387 \func{void}{InterruptWait}{\void}
388
389 Use this function to interrupt any wait operation currently in progress.
390 Note that this is not intended as a regular way to interrupt a Wait call,
391 but only as an escape mechanism for exceptional situations where it is
392 absolutely necessary to use it, for example to abort an operation due to
393 some exception or abnormal problem. InterruptWait is automatically called
394 when you \helpref{Close}{wxsocketbaseclose} a socket (and thus also upon
395 socket destruction), so you don't need to use it in these cases.
396
397 \helpref{wxSocketBase::Wait}{wxsocketbasewait},
398 \helpref{wxSocketServer::WaitForAccept}{wxsocketserverwaitforaccept},
399 \helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost},
400 \helpref{wxSocketBase::WaitForRead}{wxsocketbasewaitforread},
401 \helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite},
402 \helpref{wxSocketClient::WaitOnConnect}{wxsocketclientwaitonconnect}
403
404 %
405 % IsConnected
406 %
407 \membersection{wxSocketBase::IsConnected}\label{wxsocketbaseisconnected}
408
409 \constfunc{bool}{IsConnected}{\void}
410
411 Returns TRUE if the socket is connected.
412
413 %
414 % IsData
415 %
416 \membersection{wxSocketBase::IsData}\label{wxsocketbaseisdata}
417
418 \constfunc{bool}{IsData}{\void}
419
420 This function waits until the socket is readable. This might mean that
421 queued data is available for reading or, for streamed sockets, that
422 the connection has been closed, so that a read operation will complete
423 immediately without blocking (unless the {\bf wxSOCKET\_WAITALL} flag
424 is set, in which case the operation might still block).
425
426 \membersection{wxSocketBase::IsDisconnected}\label{wxsocketbaseisdisconnected}
427
428 %
429 % IsDisconnected
430 %
431 \constfunc{bool}{IsDisconnected}{\void}
432
433 Returns TRUE if the socket is not connected.
434
435 \membersection{wxSocketBase::LastCount}\label{wxsocketbaselastcount}
436
437 %
438 % LastCount
439 %
440 \constfunc{wxUint32}{LastCount}{\void}
441
442 Returns the number of bytes read or written by the last IO call.
443
444 Use this function to get the number of bytes actually transferred
445 after using one of the following IO calls: Discard, Peek, Read,
446 ReadMsg, Unread, Write, WriteMsg.
447
448 %
449 % LastError
450 %
451 \membersection{wxSocketBase::LastError}\label{wxsocketbaselasterror}
452
453 \constfunc{wxSocketError}{LastError}{\void}
454
455 Returns the last wxSocket error. See \helpref{wxSocket errors}{wxsocketbase}.
456
457 Please note that this function merely returns the last error code,
458 but it should not be used to determine if an error has occurred (this
459 is because successful operations do not change the LastError value).
460 Use \helpref{Error}{wxsocketbaseerror} first, in order to determine
461 if the last IO call failed. If this returns TRUE, use LastError
462 to discover the cause of the error.
463
464 %
465 % Notify
466 %
467 \membersection{wxSocketBase::Notify}\label{wxsocketbasenotify}
468
469 \func{void}{Notify}{\param{bool}{ notify}}
470
471 According to the {\it notify} value, this function enables
472 or disables socket events. If {\it notify} is TRUE, the events
473 configured with \helpref{SetNotify}{wxsocketbasesetnotify} will
474 be sent to the application. If {\it notify} is FALSE; no events
475 will be sent.
476
477 %
478 % Ok
479 %
480 \membersection{wxSocketBase::Ok}\label{wxsocketbaseok}
481
482 \constfunc{bool}{Ok}{\void}
483
484 Returns TRUE if the socket is initialized and ready and FALSE in other
485 cases.
486
487 \wxheading{Remark/Warning}
488
489 For \helpref{wxSocketClient}{wxsocketclient}, Ok won't return TRUE unless
490 the client is connected to a server.
491
492 For \helpref{wxSocketServer}{wxsocketserver}, Ok will return TRUE if the
493 server could bind to the specified address and is already listening for
494 new connections.
495
496 Ok does not check for IO errors;
497 use \helpref{Error}{wxsocketbaseerror} instead for that purpose.
498
499 %
500 % RestoreState
501 %
502 \membersection{wxSocketBase::RestoreState}\label{wxsocketbaserestorestate}
503
504 \func{void}{RestoreState}{\void}
505
506 This function restores the previous state of the socket, as saved
507 with \helpref{SaveState}{wxsocketbasesavestate}
508
509 Calls to SaveState and RestoreState can be nested.
510
511 \wxheading{See also}
512
513 \helpref{wxSocketBase::SaveState}{wxsocketbasesavestate}
514
515 %
516 % SaveState
517 %
518 \membersection{wxSocketBase::SaveState}\label{wxsocketbasesavestate}
519
520 \func{void}{SaveState}{\void}
521
522 This function saves the current state of the socket in a stack. Socket
523 state includes flags, as set with \helpref{SetFlags}{wxsocketbasesetflags},
524 event mask, as set with \helpref{SetNotify}{wxsocketbasesetnotify} and
525 \helpref{Notify}{wxsocketbasenotify}, user data, as set with
526 \helpref{SetClientData}{wxsocketbasesetclientdata}, and asynchronous
527 callback settings, as set with \helpref{Callback}{wxsocketbasecallback}
528 and \helpref{CallbackData}{wxsocketbasecallbackdata}.
529
530 Calls to SaveState and RestoreState can be nested.
531
532 \wxheading{See also}
533
534 \helpref{wxSocketBase::RestoreState}{wxsocketbaserestorestate}
535
536 %
537 % SetClientData
538 %
539 \membersection{wxSocketBase::SetClientData}\label{wxsocketbasesetclientdata}
540
541 \func{void}{SetClientData}{\param{void *}{data}}
542
543 Sets user-supplied client data for this socket. All socket events will
544 contain a pointer to this data, which can be retrieved with
545 the \helpref{wxSocketEvent::GetClientData}{wxsocketeventgetclientdata} function.
546
547 %
548 % SetEventHandler
549 %
550 \membersection{wxSocketBase::SetEventHandler}\label{wxsocketbaseseteventhandler}
551
552 \func{void}{SetEventHandler}{\param{wxEvtHandler\&}{ handler}, \param{int}{ id = -1}}
553
554 Sets an event handler to be called when a socket event occurs. The
555 handler will be called for those events for which notification is
556 enabled with \helpref{SetNotify}{wxsocketbasesetnotify} and
557 \helpref{Notify}{wxsocketbasenotify}.
558
559 \wxheading{Parameters}
560
561 \docparam{handler}{Specifies the event handler you want to use.}
562
563 \docparam{id}{The id of socket event.}
564
565 \wxheading{See also}
566
567 \helpref{wxSocketBase::SetNotify}{wxsocketbasesetnotify},
568 \helpref{wxSocketBase::Notify}{wxsocketbasenotify},
569 \helpref{wxSocketEvent}{wxsocketevent},
570 \helpref{wxEvtHandler}{wxevthandler}
571
572 %
573 % SetFlags
574 %
575 \membersection{wxSocketBase::SetFlags}\label{wxsocketbasesetflags}
576
577 \func{void}{SetFlags}{\param{wxSocketFlags}{ flags}}
578
579 Use SetFlags to customize IO operation for this socket.
580 The {\it flags} parameter may be a combination of flags ORed toghether.
581 The following flags can be used:
582
583 \twocolwidtha{7cm}
584 \begin{twocollist}\itemsep=0pt
585 \twocolitem{{\bf wxSOCKET\_NONE}}{Normal functionality.}
586 \twocolitem{{\bf wxSOCKET\_NOWAIT}}{Read/write as much data as possible and return immediately.}
587 \twocolitem{{\bf wxSOCKET\_WAITALL}}{Wait for all required data to be read/written unless an error occurs.}
588 \twocolitem{{\bf wxSOCKET\_BLOCK}}{Block the GUI (do not yield) while reading/writing data.}
589 \end{twocollist}
590
591 A brief overview on how to use these flags follows.
592
593 If no flag is specified (this is the same as {\bf wxSOCKET\_NONE}),
594 IO calls will return after some data has been read or written, even
595 when the transfer might not be complete. This is the same as issuing
596 exactly one blocking low-level call to recv() or send(). Note
597 that {\it blocking} here refers to when the function returns, not
598 to whether the GUI blocks during this time.
599
600 If {\bf wxSOCKET\_NOWAIT} is specified, IO calls will return immediately.
601 Read operations will retrieve only available data. Write operations will
602 write as much data as possible, depending on how much space is available
603 in the output buffer. This is the same as issuing exactly one nonblocking
604 low-level call to recv() or send(). Note that {\it nonblocking} here
605 refers to when the function returns, not to whether the GUI blocks during
606 this time.
607
608 If {\bf wxSOCKET\_WAITALL} is specified, IO calls won't return until ALL
609 the data has been read or written (or until an error occurs), blocking if
610 necessary, and issuing several low level calls if necessary. This is the
611 same as having a loop which makes as many blocking low-level calls to
612 recv() or send() as needed so as to transfer all the data. Note
613 that {\it blocking} here refers to when the function returns, not
614 to whether the GUI blocks during this time.
615
616 The {\bf wxSOCKET\_BLOCK} flag controls whether the GUI blocks during
617 IO operations. If this flag is specified, the socket will not yield
618 during IO calls, so the GUI will remain blocked until the operation
619 completes. If it is not used, then the application must take extra
620 care to avoid unwanted reentrance.
621
622 So:
623
624 {\bf wxSOCKET\_NONE} will try to read at least SOME data, no matter how much.
625
626 {\bf wxSOCKET\_NOWAIT} will always return immediately, even if it cannot
627 read or write ANY data.
628
629 {\bf wxSOCKET\_WAITALL} will only return when it has read or written ALL
630 the data.
631
632 {\bf wxSOCKET\_BLOCK} has nothing to do with the previous flags and
633 it controls whether the GUI blocks.
634
635 %
636 % SetNotify
637 %
638 \membersection{wxSocketBase::SetNotify}\label{wxsocketbasesetnotify}
639
640 \func{void}{SetNotify}{\param{wxSocketEventFlags}{ flags}}
641
642 SetNotify specifies which socket events are to be sent to the event handler.
643 The {\it flags} parameter may be combination of flags ORed toghether. The
644 following flags can be used:
645
646 \twocolwidtha{7cm}
647 \begin{twocollist}\itemsep=0pt
648 \twocolitem{{\bf wxSOCKET\_INPUT\_FLAG}}{to receive wxSOCKET\_INPUT}
649 \twocolitem{{\bf wxSOCKET\_OUTPUT\_FLAG}}{to receive wxSOCKET\_OUTPUT}
650 \twocolitem{{\bf wxSOCKET\_CONNECTION\_FLAG}}{to receive wxSOCKET\_CONNECTION}
651 \twocolitem{{\bf wxSOCKET\_LOST\_FLAG}}{to receive wxSOCKET\_LOST}
652 \end{twocollist}
653
654 For example:
655
656 \begin{verbatim}
657 sock.SetNotify(wxSOCKET_INPUT_FLAG | wxSOCKET_LOST_FLAG);
658 sock.Notify(TRUE);
659 \end{verbatim}
660
661 In this example, the user will be notified about incoming socket data and
662 whenever the connection is closed.
663
664 For more information on socket events see \helpref{wxSocket events}{wxsocketbase}.
665
666 %
667 % SetTimeout
668 %
669 \membersection{wxSocketBase::SetTimeout}\label{wxsocketbasesettimeout}
670
671 \func{void}{SetTimeout}{\param{int }{seconds}}
672
673 This function sets the default socket timeout in seconds. This timeout
674 applies to all IO calls, and also to the \helpref{Wait}{wxsocketbasewait} family
675 of functions if you don't specify a wait interval. Initially, the default
676 timeout is 10 minutes.
677
678 %
679 % Peek
680 %
681 \membersection{wxSocketBase::Peek}\label{wxsocketbasepeek}
682
683 \func{wxSocketBase\&}{Peek}{\param{void *}{ buffer}, \param{wxUint32}{ nbytes}}
684
685 This function peeks a buffer of {\it nbytes} bytes from the socket.
686 Peeking a buffer doesn't delete it from the socket input queue.
687
688 Use \helpref{LastCount}{wxsocketbaselastcount} to verify the number of bytes actually peeked.
689
690 Use \helpref{Error}{wxsocketbaseerror} to determine if the operation succeeded.
691
692 \wxheading{Parameters}
693
694 \docparam{buffer}{Buffer where to put peeked data.}
695
696 \docparam{nbytes}{Number of bytes.}
697
698 \wxheading{Return value}
699
700 Returns a reference to the current object.
701
702 \wxheading{Remark/Warning}
703
704 The exact behaviour of wxSocketBase::Peek depends on the combination
705 of flags being used. For a detailed explanation, see \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags}
706
707 \wxheading{See also}
708
709 \helpref{wxSocketBase::Error}{wxsocketbaseerror},
710 \helpref{wxSocketBase::LastError}{wxsocketbaselasterror},
711 \helpref{wxSocketBase::LastCount}{wxsocketbaselastcount},
712 \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags}
713
714 %
715 % Read
716 %
717 \membersection{wxSocketBase::Read}\label{wxsocketbaseread}
718
719 \func{wxSocketBase\&}{Read}{\param{void *}{ buffer}, \param{wxUint32}{ nbytes}}
720
721 This function reads a buffer of {\it nbytes} bytes from the socket.
722
723 Use \helpref{LastCount}{wxsocketbaselastcount} to verify the number of bytes actually read.
724
725 Use \helpref{Error}{wxsocketbaseerror} to determine if the operation succeeded.
726
727 \wxheading{Parameters}
728
729 \docparam{buffer}{Buffer where to put read data.}
730
731 \docparam{nbytes}{Number of bytes.}
732
733 \wxheading{Return value}
734
735 Returns a reference to the current object.
736
737 \wxheading{Remark/Warning}
738
739 The exact behaviour of wxSocketBase::Read depends on the combination
740 of flags being used. For a detailed explanation, see \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags}.
741
742 \wxheading{See also}
743
744 \helpref{wxSocketBase::Error}{wxsocketbaseerror},
745 \helpref{wxSocketBase::LastError}{wxsocketbaselasterror},
746 \helpref{wxSocketBase::LastCount}{wxsocketbaselastcount},
747 \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags}
748
749 %
750 % ReadMsg
751 %
752 \membersection{wxSocketBase::ReadMsg}\label{wxsocketbasereadmsg}
753
754 \func{wxSocketBase\&}{ReadMsg}{\param{void *}{ buffer}, \param{wxUint32}{ nbytes}}
755
756 This function reads a buffer sent by \helpref{WriteMsg}{wxsocketbasewritemsg}
757 on a socket. If the buffer passed to the function isn't big enough, the
758 remaining bytes will be discarded. This function always waits for the
759 buffer to be entirely filled, unless an error occurs.
760
761 Use \helpref{LastCount}{wxsocketbaselastcount} to verify the number of bytes actually read.
762
763 Use \helpref{Error}{wxsocketbaseerror} to determine if the operation succeeded.
764
765 \wxheading{Parameters}
766
767 \docparam{buffer}{Buffer where to put read data.}
768
769 \docparam{nbytes}{Size of the buffer.}
770
771 \wxheading{Return value}
772
773 Returns a reference to the current object.
774
775 \wxheading{Remark/Warning}
776
777 wxSocketBase::ReadMsg will behave as if the {\bf wxSOCKET\_WAITALL} flag
778 was always set and it will always ignore the {\bf wxSOCKET\_NOWAIT} flag.
779 The exact behaviour of ReadMsg depends on the {\bf wxSOCKET\_BLOCK} flag.
780 For a detailed explanation, see \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags}.
781
782 \wxheading{See also}
783
784 \helpref{wxSocketBase::Error}{wxsocketbaseerror},
785 \helpref{wxSocketBase::LastError}{wxsocketbaselasterror},
786 \helpref{wxSocketBase::LastCount}{wxsocketbaselastcount},
787 \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags},
788 \helpref{wxSocketBase::WriteMsg}{wxsocketbasewritemsg}
789
790 %
791 % Unread
792 %
793 \membersection{wxSocketBase::Unread}\label{wxsocketbaseunread}
794
795 \func{wxSocketBase\&}{Unread}{\param{const void *}{ buffer}, \param{wxUint32}{ nbytes}}
796
797 This function unreads a buffer. That is, the data in the buffer is put back
798 in the incoming queue. This function is not affected by wxSocket flags.
799
800 If you use \helpref{LastCount}{wxsocketbaselastcount}, it will always return {\it nbytes}.
801
802 If you use \helpref{Error}{wxsocketbaseerror}, it will always return FALSE.
803
804 \wxheading{Parameters}
805
806 \docparam{buffer}{Buffer to be unread.}
807
808 \docparam{nbytes}{Number of bytes.}
809
810 \wxheading{Return value}
811
812 Returns a reference to the current object.
813
814 \wxheading{See also}
815
816 \helpref{wxSocketBase::Error}{wxsocketbaseerror},
817 \helpref{wxSocketBase::LastCount}{wxsocketbaselastcount},
818 \helpref{wxSocketBase::LastError}{wxsocketbaselasterror}
819
820 %
821 % Wait
822 %
823 \membersection{wxSocketBase::Wait}\label{wxsocketbasewait}
824
825 \func{bool}{Wait}{\param{long}{ seconds = -1}, \param{long}{ millisecond = 0}}
826
827 This function waits until any of the following conditions is TRUE:
828
829 \begin{itemize}
830 \item The socket becomes readable.
831 \item The socket becomes writable.
832 \item An ongoing connection request has completed (\helpref{wxSocketClient}{wxsocketclient} only)
833 \item An incoming connection request has arrived (\helpref{wxSocketServer}{wxsocketserver} only)
834 \item The connection has been closed.
835 \end{itemize}
836
837 Note that it is recommended to use the individual Wait functions
838 to wait for the required condition, instead of this one.
839
840 \wxheading{Parameters}
841
842 \docparam{seconds}{Number of seconds to wait.
843 If -1, it will wait for the default timeout,
844 as set with \helpref{SetTimeout}{wxsocketbasesettimeout}.}
845
846 \docparam{millisecond}{Number of milliseconds to wait.}
847
848 \wxheading{Return value}
849
850 Returns TRUE when any of the above conditions is satisfied,
851 FALSE if the timeout was reached.
852
853 \wxheading{See also}
854
855 \helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
856 \helpref{wxSocketServer::WaitForAccept}{wxsocketserverwaitforaccept},
857 \helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost},
858 \helpref{wxSocketBase::WaitForRead}{wxsocketbasewaitforread},
859 \helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite},
860 \helpref{wxSocketClient::WaitOnConnect}{wxsocketclientwaitonconnect}
861
862 %
863 % WaitForLost
864 %
865 \membersection{wxSocketBase::WaitForLost}\label{wxsocketbasewaitforlost}
866
867 \func{bool}{Wait}{\param{long}{ seconds = -1}, \param{long}{ millisecond = 0}}
868
869 This function waits until the connection is lost. This may happen if
870 the peer gracefully closes the connection or if the connection breaks.
871
872 \wxheading{Parameters}
873
874 \docparam{seconds}{Number of seconds to wait.
875 If -1, it will wait for the default timeout,
876 as set with \helpref{SetTimeout}{wxsocketbasesettimeout}.}
877
878 \docparam{millisecond}{Number of milliseconds to wait.}
879
880 \wxheading{Return value}
881
882 Returns TRUE if the connection was lost, FALSE if the timeout was reached.
883
884 \wxheading{See also}
885
886 \helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
887 \helpref{wxSocketBase::Wait}{wxsocketbasewait}
888
889 %
890 % WaitForRead
891 %
892 \membersection{wxSocketBase::WaitForRead}\label{wxsocketbasewaitforread}
893
894 \func{bool}{WaitForRead}{\param{long}{ seconds = -1}, \param{long}{ millisecond = 0}}
895
896 This function waits until the socket is readable. This might mean that
897 queued data is available for reading or, for streamed sockets, that
898 the connection has been closed, so that a read operation will complete
899 immediately without blocking (unless the {\bf wxSOCKET\_WAITALL} flag
900 is set, in which case the operation might still block).
901
902 \wxheading{Parameters}
903
904 \docparam{seconds}{Number of seconds to wait.
905 If -1, it will wait for the default timeout,
906 as set with \helpref{SetTimeout}{wxsocketbasesettimeout}.}
907
908 \docparam{millisecond}{Number of milliseconds to wait.}
909
910 \wxheading{Return value}
911
912 Returns TRUE if the socket becomes readable, FALSE on timeout.
913
914 \wxheading{See also}
915
916 \helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
917 \helpref{wxSocketBase::Wait}{wxsocketbasewait}
918
919 %
920 % WaitForWrite
921 %
922 \membersection{wxSocketBase::WaitForWrite}\label{wxsocketbasewaitforwrite}
923
924 \func{bool}{WaitForWrite}{\param{long}{ seconds = -1}, \param{long}{ millisecond = 0}}
925
926 This function waits until the socket becomes writable. This might mean that
927 the socket is ready to send new data, or for streamed sockets, that the
928 connection has been closed, so that a write operation is guaranteed to
929 complete immediately (unless the {\bf wxSOCKET\_WAITALL} flag is set,
930 in which case the operation might still block).
931
932 \wxheading{Parameters}
933
934 \docparam{seconds}{Number of seconds to wait.
935 If -1, it will wait for the default timeout,
936 as set with \helpref{SetTimeout}{wxsocketbasesettimeout}.}
937
938 \docparam{millisecond}{Number of milliseconds to wait.}
939
940 \wxheading{Return value}
941
942 Returns TRUE if the socket becomes writable, FALSE on timeout.
943
944 \wxheading{See also}
945
946 \helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
947 \helpref{wxSocketBase::Wait}{wxsocketbasewait}
948
949 %
950 % Write
951 %
952 \membersection{wxSocketBase::Write}\label{wxsocketbasewrite}
953
954 \func{wxSocketBase\&}{Write}{\param{const void *}{ buffer}, \param{wxUint32}{ nbytes}}
955
956 This function writes a buffer of {\it nbytes} bytes to the socket.
957
958 Use \helpref{LastCount}{wxsocketbaselastcount} to verify the number of bytes actually written.
959
960 Use \helpref{Error}{wxsocketbaseerror} to determine if the operation succeeded.
961
962 \wxheading{Parameters}
963
964 \docparam{buffer}{Buffer with the data to be sent.}
965
966 \docparam{nbytes}{Number of bytes.}
967
968 \wxheading{Return value}
969
970 Returns a reference to the current object.
971
972 \wxheading{Remark/Warning}
973
974 The exact behaviour of wxSocketBase::Write depends on the combination
975 of flags being used. For a detailed explanation, see \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags}.
976
977 \wxheading{See also}
978
979 \helpref{wxSocketBase::Error}{wxsocketbaseerror},
980 \helpref{wxSocketBase::LastError}{wxsocketbaselasterror},
981 \helpref{wxSocketBase::LastCount}{wxsocketbaselastcount},
982 \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags}
983
984 %
985 % WriteMsg
986 %
987 \membersection{wxSocketBase::WriteMsg}\label{wxsocketbasewritemsg}
988
989 \func{wxSocketBase\&}{WriteMsg}{\param{const void *}{ buffer}, \param{wxUint32}{ nbytes}}
990
991 This function writes a buffer of {\it nbytes} bytes from the socket, but it
992 writes a short header before so that \helpref{ReadMsg}{wxsocketbasereadmsg}
993 knows how much data should it actually read. So, a buffer sent with WriteMsg
994 {\bf must} be read with ReadMsg. This function always waits for the entire
995 buffer to be sent, unless an error occurs.
996
997 Use \helpref{LastCount}{wxsocketbaselastcount} to verify the number of bytes actually written.
998
999 Use \helpref{Error}{wxsocketbaseerror} to determine if the operation succeeded.
1000
1001 \wxheading{Parameters}
1002
1003 \docparam{buffer}{Buffer with the data to be sent.}
1004
1005 \docparam{nbytes}{Number of bytes to send.}
1006
1007 \wxheading{Return value}
1008
1009 Returns a reference to the current object.
1010
1011 \wxheading{Remark/Warning}
1012
1013 wxSocketBase::WriteMsg will behave as if the {\bf wxSOCKET\_WAITALL} flag
1014 was always set and it will always ignore the {\bf wxSOCKET\_NOWAIT} flag.
1015 The exact behaviour of WriteMsg depends on the {\bf wxSOCKET\_BLOCK} flag.
1016 For a detailed explanation, see \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags}.
1017
1018 \wxheading{See also}
1019
1020 \helpref{wxSocketBase::Error}{wxsocketbaseerror},
1021 \helpref{wxSocketBase::LastError}{wxsocketbaselasterror},
1022 \helpref{wxSocketBase::LastCount}{wxsocketbaselastcount},
1023 \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags},
1024 \helpref{wxSocketBase::ReadMsg}{wxsocketbasereadmsg}
1025
1026
1027 % ---------------------------------------------------------------------------
1028 % CLASS wxSocketClient
1029 % ---------------------------------------------------------------------------
1030
1031 \section{\class{wxSocketClient}}\label{wxsocketclient}
1032
1033 \wxheading{Derived from}
1034
1035 \helpref{wxSocketBase}{wxsocketbase}
1036
1037 \wxheading{Include files}
1038
1039 <wx/socket.h>
1040
1041 \latexignore{\rtfignore{\wxheading{Members}}}
1042
1043 % ---------------------------------------------------------------------------
1044 % Members
1045 % ---------------------------------------------------------------------------
1046 %
1047 % wxSocketClient
1048 %
1049 \membersection{wxSocketClient::wxSocketClient}
1050
1051 \func{}{wxSocketClient}{\param{wxSocketFlags}{ flags = wxSOCKET_NONE}}
1052
1053 Constructor.
1054
1055 \wxheading{Parameters}
1056
1057 \docparam{flags}{Socket flags (See \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags})}
1058
1059 %
1060 % ~wxSocketClient
1061 %
1062 \membersection{wxSocketClient::\destruct{wxSocketClient}}
1063
1064 \func{}{\destruct{wxSocketClient}}{\void}
1065
1066 Destructor. Please see \helpref{wxSocketBase::Destroy}{wxsocketbasedestroy}.
1067
1068 %
1069 % Connect
1070 %
1071 \membersection{wxSocketClient::Connect}\label{wxsocketclientconnect}
1072
1073 \func{bool}{Connect}{\param{wxSockAddress\&}{ address}, \param{bool}{ wait = TRUE}}
1074
1075 Connects to a server using the specified address.
1076
1077 If {\it wait} is TRUE, Connect will wait until the connection
1078 completes. {\bf Warning:} This will block the GUI.
1079
1080 If {\it wait} is FALSE, Connect will try to establish the connection and
1081 return immediately, without blocking the GUI. When used this way, even if
1082 Connect returns FALSE, the connection request can be completed later.
1083 To detect this, use \helpref{WaitOnConnect}{wxsocketclientwaitonconnect},
1084 or catch {\bf wxSOCKET\_CONNECTION} events (for successful establishment)
1085 and {\bf wxSOCKET\_LOST} events (for connection failure).
1086
1087 \wxheading{Parameters}
1088
1089 \docparam{address}{Address of the server.}
1090
1091 \docparam{wait}{If TRUE, waits for the connection to complete.}
1092
1093 \wxheading{Return value}
1094
1095 Returns TRUE if the connection is established and no error occurs.
1096
1097 If {\it wait} was TRUE, and Connect returns FALSE, an error occurred
1098 and the connection failed.
1099
1100 If {\it wait} was FALSE, and Connect returns FALSE, you should still
1101 be prepared to handle the completion of this connection request, either
1102 with \helpref{WaitOnConnect}{wxsocketclientwaitonconnect} or by
1103 watching {\bf wxSOCKET\_CONNECTION} and {\bf wxSOCKET\_LOST} events.
1104
1105 \wxheading{See also}
1106
1107 \helpref{wxSocketClient::WaitOnConnect}{wxsocketclientwaitonconnect},
1108 \helpref{wxSocketBase::SetNotify}{wxsocketbasesetnotify},
1109 \helpref{wxSocketBase::Notify}{wxsocketbasenotify}
1110
1111 %
1112 % WaitOnConnect
1113 %
1114 \membersection{wxSocketClient::WaitOnConnect}\label{wxsocketclientwaitonconnect}
1115
1116 \func{bool}{WaitOnConnect}{\param{long}{ seconds = -1}, \param{long}{ milliseconds = 0}}
1117
1118 Wait until a connection request completes, or until the specified timeout
1119 elapses. Use this function after issuing a call
1120 to \helpref{Connect}{wxsocketclientconnect} with {\it wait} set to FALSE.
1121
1122 \wxheading{Parameters}
1123
1124 \docparam{seconds}{Number of seconds to wait.
1125 If -1, it will wait for the default timeout,
1126 as set with \helpref{SetTimeout}{wxsocketbasesettimeout}.}
1127
1128 \docparam{millisecond}{Number of milliseconds to wait.}
1129
1130 \wxheading{Return value}
1131
1132 WaitOnConnect returns TRUE if the connection request completes. This
1133 does not necessarily mean that the connection was succesfully established;
1134 it might also happen that the connection was refused by the peer. Use
1135 \helpref{IsConnected}{wxsocketbaseisconnected} to distinguish between
1136 these two situations.
1137
1138 If the timeout elapses, WaitOnConnect returns FALSE.
1139
1140 These semantics allow code like this:
1141
1142 \begin{verbatim}
1143 // Issue the connection request
1144 client->Connect(addr, FALSE);
1145
1146 // Wait until the request completes or until we decide to give up
1147 bool waitmore = TRUE;
1148 while ( !client->WaitOnConnect(seconds, millis) && waitmore )
1149 {
1150 // possibly give some feedback to the user,
1151 // and update waitmore as needed.
1152 }
1153 bool success = client->IsConnected();
1154 \end{verbatim}
1155
1156 \wxheading{See also}
1157
1158 \helpref{wxSocketClient::Connect}{wxsocketclientconnect},
1159 \helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
1160 \helpref{wxSocketBase::IsConnected}{wxsocketbaseisconnected}
1161
1162 % ---------------------------------------------------------------------------
1163 % CLASS: wxSocketEvent
1164 % ---------------------------------------------------------------------------
1165 \section{\class{wxSocketEvent}}\label{wxsocketevent}
1166
1167 This event class contains information about socket events.
1168
1169 \wxheading{Derived from}
1170
1171 \helpref{wxEvent}{wxevent}
1172
1173 \wxheading{Include files}
1174
1175 <wx/socket.h>
1176
1177 \wxheading{Event table macros}
1178
1179 To process a socket event, use these event handler macros to direct input
1180 to member functions that take a wxSocketEvent argument.
1181
1182 \twocolwidtha{7cm}
1183 \begin{twocollist}\itemsep=0pt
1184 \twocolitem{{\bf EVT\_SOCKET(id, func)}}{Process a socket event, supplying the member function.}
1185 \end{twocollist}
1186
1187 \wxheading{See also}
1188
1189 \helpref{wxSocketBase}{wxsocketbase},
1190 \helpref{wxSocketClient}{wxsocketclient},
1191 \helpref{wxSocketServer}{wxsocketserver}
1192
1193 \latexignore{\rtfignore{\wxheading{Members}}}
1194
1195 \membersection{wxSocketEvent::wxSocketEvent}
1196
1197 \func{}{wxSocketEvent}{\param{int}{ id = 0}}
1198
1199 Constructor.
1200
1201 \membersection{wxSocketEvent::GetClientData}\label{wxsocketeventgetclientdata}
1202
1203 \func{void *}{GetClientData}{\void}
1204
1205 Gets the client data of the socket which generated this event, as
1206 set with \helpref{wxSocketBase::SetClientData}{wxsocketbasesetclientdata}.
1207
1208 \membersection{wxSocketEvent::GetSocket}\label{wxsocketeventgetsocket}
1209
1210 \constfunc{wxSocketBase *}{GetSocket}{\void}
1211
1212 Returns the socket object to which this event refers to. This makes
1213 it possible to use the same event handler for different sockets.
1214
1215 \membersection{wxSocketEvent::GetSocketEvent}\label{wxsocketeventgetsocketevent}
1216
1217 \constfunc{wxSocketNotify}{GetSocketEvent}{\void}
1218
1219 Returns the socket event type.
1220
1221 % ---------------------------------------------------------------------------
1222 % CLASS: wxSocketServer
1223 % ---------------------------------------------------------------------------
1224 \section{\class{wxSocketServer}}\label{wxsocketserver}
1225
1226 \wxheading{Derived from}
1227
1228 \helpref{wxSocketBase}{wxsocketbase}
1229
1230 \wxheading{Include files}
1231
1232 <wx/socket.h>
1233
1234 % ---------------------------------------------------------------------------
1235 % Members
1236 % ---------------------------------------------------------------------------
1237 \latexignore{\rtfignore{\wxheading{Members}}}
1238
1239 %
1240 % wxSocketServer
1241 %
1242 \membersection{wxSocketServer::wxSocketServer}\label{wxsocketserverconstr}
1243
1244 \func{}{wxSocketServer}{\param{wxSockAddress\&}{ address}, \param{wxSocketFlags}{ flags = wxSOCKET_NONE}}
1245
1246 Constructs a new server and tries to bind to the specified {\it address}.
1247 Before trying to accept new connections, test whether it succeeded with
1248 \helpref{wxSocketBase::Ok}{wxsocketbaseok}.
1249
1250 \wxheading{Parameters}
1251
1252 \docparam{address}{Specifies the local address for the server (e.g. port number).}
1253
1254 \docparam{flags}{Socket flags (See \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags})}
1255
1256 %
1257 % ~wxSocketServer
1258 %
1259 \membersection{wxSocketServer::\destruct{wxSocketServer}}
1260
1261 \func{}{\destruct{wxSocketServer}}{\void}
1262
1263 Destructor (it doesn't close the accepted connections).
1264
1265 %
1266 % Accept
1267 %
1268 \membersection{wxSocketServer::Accept}\label{wxsocketserveraccept}
1269
1270 \func{wxSocketBase *}{Accept}{\param{bool}{ wait = TRUE}}
1271
1272 Accepts an incoming connection request, and creates a new
1273 \helpref{wxSocketBase}{wxsocketbase} object which represents
1274 the server-side of the connection.
1275
1276 If {\it wait} is TRUE and there are no pending connections to be
1277 accepted, it will wait for the next incoming connection to
1278 arrive. {\bf Warning:} This will block the GUI.
1279
1280 If {\it wait} is FALSE, it will try to accept a pending connection
1281 if there is one, but it will always return immediately without blocking
1282 the GUI. If you want to use Accept in this way, you can either check for
1283 incoming connections with \helpref{WaitForAccept}{wxsocketserverwaitforaccept}
1284 or catch {\bf wxSOCKET\_CONNECTION} events, then call Accept once you know
1285 that there is an incoming connection waiting to be accepted.
1286
1287 \wxheading{Return value}
1288
1289 Returns an opened socket connection, or NULL if an error occurred or
1290 if the {\it wait} parameter was FALSE and there were no pending
1291 connections.
1292
1293 \wxheading{See also}
1294
1295 \helpref{wxSocketServer::WaitForAccept}{wxsocketserverwaitforaccept},
1296 \helpref{wxSocketBase::SetNotify}{wxsocketbasesetnotify},
1297 \helpref{wxSocketBase::Notify}{wxsocketbasenotify},
1298 \helpref{wxSocketServer::AcceptWith}{wxsocketserveracceptwith}
1299
1300 %
1301 % AcceptWith
1302 %
1303 \membersection{wxSocketServer::AcceptWith}\label{wxsocketserveracceptwith}
1304
1305 \func{bool}{AcceptWith}{\param{wxSocketBase\&}{ socket}, \param{bool}{ wait = TRUE}}
1306
1307 Accept an incoming connection using the specified socket object.
1308
1309 \wxheading{Parameters}
1310
1311 \docparam{socket}{Socket to be initialized}
1312
1313 \wxheading{Return value}
1314
1315 Returns TRUE on success, or FALSE if an error occurred or if the
1316 {\it wait} parameter was FALSE and there were no pending
1317 connections.
1318
1319 \helpref{wxSocketServer::WaitForAccept}{wxsocketserverwaitforaccept},
1320 \helpref{wxSocketBase::SetNotify}{wxsocketbasesetnotify},
1321 \helpref{wxSocketBase::Notify}{wxsocketbasenotify},
1322 \helpref{wxSocketServer::Accept}{wxsocketserveraccept}
1323
1324 %
1325 % WaitForAccept
1326 %
1327 \membersection{wxSocketServer::WaitForAccept}\label{wxsocketserverwaitforaccept}
1328
1329 \func{bool}{WaitForAccept}{\param{long}{ seconds = -1}, \param{long}{ millisecond = 0}}
1330
1331 This function waits for an incoming connection. Use it if you want to call
1332 \helpref{Accept}{wxsocketserveraccept} or \helpref{AcceptWith}{wxsocketserveracceptwith}
1333 with {\it wait} set to FALSE, to detect when an incoming connection is waiting
1334 to be accepted.
1335
1336 \wxheading{Parameters}
1337
1338 \docparam{seconds}{Number of seconds to wait.
1339 If -1, it will wait for the default timeout,
1340 as set with \helpref{SetTimeout}{wxsocketbasesettimeout}.}
1341
1342 \docparam{millisecond}{Number of milliseconds to wait.}
1343
1344 \wxheading{Return value}
1345
1346 Returns TRUE if an incoming connection arrived, FALSE if the timeout elapsed.
1347
1348 \wxheading{See also}
1349
1350 \helpref{wxSocketServer::Accept}{wxsocketserveraccept},
1351 \helpref{wxSocketServer::AcceptWith}{wxsocketserveracceptwith},
1352 \helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait}
1353