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