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