1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 %% Purpose: wxSocket docs
4 %% Author: Guillermo Rodriguez Garcia <guille@iies.es>
8 %% Copyright: (c) wxWidgets team
9 %% License: wxWidgets license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12 \section{\class{wxSocketBase
}}\label{wxsocketbase
}
14 wxSocketBase is the base class for all socket-related objects, and it
15 defines all basic IO functionality.
17 Note: (Workaround for implementation limitation for wxWidgets up to
2.5.x)
18 If you want to use sockets or derived classes such as wxFTP in a secondary thread,
19 call wxSocketBase::Initialize() (undocumented) from the main thread before creating
20 any sockets - in wxApp::OnInit for example.
21 See http://wiki.wxwidgets.org/wiki.pl?WxSocket or
22 http://www.litwindow.com/knowhow/knowhow.html for more details.
24 \wxheading{Derived from
}
26 \helpref{wxObject
}{wxobject
}
28 \wxheading{Include files
}
32 \wxheading{wxSocket errors
}
35 \begin{twocollist
}\itemsep=
0pt
36 \twocolitem{{\bf wxSOCKET
\_NOERROR}}{No error happened.
}
37 \twocolitem{{\bf wxSOCKET
\_INVOP}}{Invalid operation.
}
38 \twocolitem{{\bf wxSOCKET
\_IOERR}}{Input/Output error.
}
39 \twocolitem{{\bf wxSOCKET
\_INVADDR}}{Invalid address passed to wxSocket.
}
40 \twocolitem{{\bf wxSOCKET
\_INVSOCK}}{Invalid socket (uninitialized).
}
41 \twocolitem{{\bf wxSOCKET
\_NOHOST}}{No corresponding host.
}
42 \twocolitem{{\bf wxSOCKET
\_INVPORT}}{Invalid port.
}
43 \twocolitem{{\bf wxSOCKET
\_WOULDBLOCK}}{The socket is non-blocking and the operation would block.
}
44 \twocolitem{{\bf wxSOCKET
\_TIMEDOUT}}{The timeout for this operation expired.
}
45 \twocolitem{{\bf wxSOCKET
\_MEMERR}}{Memory exhausted.
}
48 \wxheading{wxSocket events
}
51 \begin{twocollist
}\itemsep=
0pt
52 \twocolitem{{\bf wxSOCKET
\_INPUT}}{There is data available for reading.
}
53 \twocolitem{{\bf wxSOCKET
\_OUTPUT}}{The socket is ready to be written to.
}
54 \twocolitem{{\bf wxSOCKET
\_CONNECTION}}{Incoming connection request (server), or successful connection establishment (client).
}
55 \twocolitem{{\bf wxSOCKET
\_LOST}}{The connection has been closed.
}
58 A brief note on how to use these events:
60 The
{\bf wxSOCKET
\_INPUT} event will be issued whenever there is data
61 available for reading. This will be the case if the input queue was
62 empty and new data arrives, or if the application has read some data
63 yet there is still more data available. This means that the application
64 does not need to read all available data in response to a
65 {\bf wxSOCKET
\_INPUT} event, as more events will be produced as
68 The
{\bf wxSOCKET
\_OUTPUT} event is issued when a socket is first
69 connected with
\helpref{Connect
}{wxsocketclientconnect
} or accepted
70 with
\helpref{Accept
}{wxsocketserveraccept
}. After that, new
71 events will be generated only after an output operation fails
72 with
{\bf wxSOCKET
\_WOULDBLOCK} and buffer space becomes available
73 again. This means that the application should assume that it
74 can write data to the socket until an
{\bf wxSOCKET
\_WOULDBLOCK}
75 error occurs; after this, whenever the socket becomes writable
76 again the application will be notified with another
77 {\bf wxSOCKET
\_OUTPUT} event.
79 The
{\bf wxSOCKET
\_CONNECTION} event is issued when a delayed connection
80 request completes successfully (client) or when a new connection arrives
81 at the incoming queue (server).
83 The
{\bf wxSOCKET
\_LOST} event is issued when a close indication is
84 received for the socket. This means that the connection broke down or
85 that it was closed by the peer. Also, this event will be issued if
86 a connection request fails.
88 \wxheading{Event handling
}
90 To process events coming from a socket object, use the following event
91 handler macro to direct events to member functions that take
92 a
\helpref{wxSocketEvent
}{wxsocketevent
} argument.
95 \begin{twocollist
}\itemsep=
0pt
96 \twocolitem{{\bf EVT
\_SOCKET(id, func)
}}{Process a wxEVT
\_SOCKET event.
}
101 \helpref{wxSocketEvent
}{wxsocketevent
},
102 \helpref{wxSocketClient
}{wxsocketclient
},
103 \helpref{wxSocketServer
}{wxsocketserver
},
104 \helpref{Sockets sample
}{samplesockets
}
106 % ---------------------------------------------------------------------------
108 % ---------------------------------------------------------------------------
110 \latexignore{\rtfignore{\wxheading{Function groups
}}}
112 \membersection{Construction and destruction
}
114 \helpref{wxSocketBase
}{wxsocketbaseconstruct
}\\
115 \helpref{\destruct{wxSocketBase
}}{wxsocketbasedestruct
}\\
116 \helpref{Destroy
}{wxsocketbasedestroy
}
118 \membersection{Socket state
}
120 Functions to retrieve current state and miscellaneous info.
122 \helpref{Error
}{wxsocketbaseerror
}\\
123 \helpref{GetLocal
}{wxsocketbasegetlocal
}\\
124 \helpref{GetPeer
}{wxsocketbasegetpeer
}
125 \helpref{IsConnected
}{wxsocketbaseisconnected
}\\
126 \helpref{IsData
}{wxsocketbaseisdata
}\\
127 \helpref{IsDisconnected
}{wxsocketbaseisdisconnected
}\\
128 \helpref{LastCount
}{wxsocketbaselastcount
}\\
129 \helpref{LastError
}{wxsocketbaselasterror
}\\
130 \helpref{Ok
}{wxsocketbaseok
}\\
131 \helpref{SaveState
}{wxsocketbasesavestate
}\\
132 \helpref{RestoreState
}{wxsocketbaserestorestate
}
134 \membersection{Basic IO
}
136 Functions that perform basic IO functionality.
138 \helpref{Close
}{wxsocketbaseclose
}\\
139 \helpref{Discard
}{wxsocketbasediscard
}\\
140 \helpref{Peek
}{wxsocketbasepeek
}\\
141 \helpref{Read
}{wxsocketbaseread
}\\
142 \helpref{ReadMsg
}{wxsocketbasereadmsg
}\\
143 \helpref{Unread
}{wxsocketbaseunread
}\\
144 \helpref{Write
}{wxsocketbasewrite
}\\
145 \helpref{WriteMsg
}{wxsocketbasewritemsg
}
147 Functions that perform a timed wait on a certain IO condition.
149 \helpref{InterruptWait
}{wxsocketbaseinterruptwait
}\\
150 \helpref{Wait
}{wxsocketbasewait
}\\
151 \helpref{WaitForLost
}{wxsocketbasewaitforlost
}\\
152 \helpref{WaitForRead
}{wxsocketbasewaitforread
}\\
153 \helpref{WaitForWrite
}{wxsocketbasewaitforwrite
}\\
157 \helpref{wxSocketServer::WaitForAccept
}{wxsocketserverwaitforaccept
}\\
158 \helpref{wxSocketClient::WaitOnConnect
}{wxsocketclientwaitonconnect
}
160 Functions that allow applications to customize socket IO as needed.
162 \helpref{GetFlags
}{wxsocketbasegetflags
}\\
163 \helpref{SetFlags
}{wxsocketbasesetflags
}\\
164 \helpref{SetTimeout
}{wxsocketbasesettimeout
}
166 \membersection{Handling socket events
}
168 Functions that allow applications to receive socket events.
170 \helpref{Notify
}{wxsocketbasenotify
}\\
171 \helpref{SetNotify
}{wxsocketbasesetnotify
}\\
172 \helpref{GetClientData
}{wxsocketbasegetclientdata
}\\
173 \helpref{SetClientData
}{wxsocketbasesetclientdata
}\\
174 \helpref{SetEventHandler
}{wxsocketbaseseteventhandler
}
176 Callback functions are also available, but they are provided for backwards
177 compatibility only. Their use is strongly discouraged in favour of events,
178 and should be considered deprecated. Callbacks may be unsupported in future
179 releases of wxWidgets.
181 \helpref{Callback
}{wxsocketbasecallback
}\\
182 \helpref{CallbackData
}{wxsocketbasecallbackdata
}
185 % ---------------------------------------------------------------------------
187 % ---------------------------------------------------------------------------
189 \helponly{\insertatlevel{2}{
195 \membersection{wxSocketBase::wxSocketBase
}\label{wxsocketbaseconstruct
}
197 \func{}{wxSocketBase
}{\void}
199 Default constructor. Don't use it directly; instead, use
200 \helpref{wxSocketClient
}{wxsocketclient
} to construct a socket client, or
201 \helpref{wxSocketServer
}{wxsocketserver
} to construct a socket server.
203 \membersection{wxSocketBase::
\destruct{wxSocketBase
}}\label{wxsocketbasedestruct
}
205 \func{}{\destruct{wxSocketBase
}}{\void}
207 Destructor. Do not destroy a socket using the delete operator directly;
208 use
\helpref{Destroy
}{wxsocketbasedestroy
} instead. Also, do not create
209 socket objects in the stack.
214 \membersection{wxSocketBase::Callback
}\label{wxsocketbasecallback
}
216 \func{wxSocketBase::wxSockCbk
}{Callback
}{\param{wxSocketBase::wxSockCbk
}{ callback
}}
218 You can setup a callback function to be called when an event occurs.
219 The function will be called only for those events for which notification
220 has been enabled with
\helpref{Notify
}{wxsocketbasenotify
} and
221 \helpref{SetNotify
}{wxsocketbasesetnotify
}. The prototype of the
222 callback must be as follows:
225 void SocketCallback(wxSocketBase& sock, wxSocketNotify evt, char *cdata);
228 The first parameter is a reference to the socket object in which the
229 event occurred. The second parameter tells you which event occurred.
230 (See
\helpref{wxSocket events
}{wxsocketbase
}). The third parameter
231 is the user data you specified using
\helpref{CallbackData
}{wxsocketbasecallbackdata
}.
233 \wxheading{Return value
}
235 A pointer to the previous callback.
237 \wxheading{Remark/Warning
}
239 Note that callbacks are now deprecated and unsupported, and they remain
240 for backwards compatibility only. Use events instead.
244 \helpref{wxSocketBase::CallbackData
}{wxsocketbasecallbackdata
},
245 \helpref{wxSocketBase::SetNotify
}{wxsocketbasesetnotify
},
246 \helpref{wxSocketBase::Notify
}{wxsocketbasenotify
}
251 \membersection{wxSocketBase::CallbackData
}\label{wxsocketbasecallbackdata
}
253 \func{char *
}{CallbackData
}{\param{char *
}{cdata
}}
255 This function sets the the user data which will be passed to a
256 callback function set via
\helpref{Callback
}{wxsocketbasecallback
}.
258 \wxheading{Return value
}
260 A pointer to the previous user data.
262 \wxheading{Remark/Warning
}
264 Note that callbacks are now deprecated and unsupported, and they remain
265 for backwards compatibility only. Use events instead.
269 \helpref{wxSocketBase::Callback
}{wxsocketbasecallback
},
270 \helpref{wxSocketBase::SetNotify
}{wxsocketbasesetnotify
},
271 \helpref{wxSocketBase::Notify
}{wxsocketbasenotify
}
276 \membersection{wxSocketBase::Close
}\label{wxsocketbaseclose
}
278 \func{void
}{Close
}{\void}
280 This function shuts down the socket, disabling further transmission and
281 reception of data; it also disables events for the socket and frees the
282 associated system resources. Upon socket destruction, Close is automatically
283 called, so in most cases you won't need to do it yourself, unless you
284 explicitly want to shut down the socket, typically to notify the peer
285 that you are closing the connection.
287 \wxheading{Remark/Warning
}
289 Although Close immediately disables events for the socket, it is possible
290 that event messages may be waiting in the application's event queue. The
291 application must therefore be prepared to handle socket event messages
292 even after calling Close.
297 \membersection{wxSocketBase::Destroy
}\label{wxsocketbasedestroy
}
299 \func{bool
}{Destroy
}{\void}
301 Destroys the socket safely. Use this function instead of the delete operator,
302 since otherwise socket events could reach the application even after the
303 socket has been destroyed. To prevent this problem, this function appends
304 the wxSocket to a list of object to be deleted on idle time, after all
305 events have been processed. For the same reason, you should avoid creating
306 socket objects in the stack.
308 Destroy calls
\helpref{Close
}{wxsocketbaseclose
} automatically.
310 \wxheading{Return value
}
317 \membersection{wxSocketBase::Discard
}\label{wxsocketbasediscard
}
319 \func{wxSocketBase\&
}{Discard
}{\void}
321 This function simply deletes all bytes in the incoming queue. This function
322 always returns immediately and its operation is not affected by IO flags.
324 Use
\helpref{LastCount
}{wxsocketbaselastcount
} to verify the number of bytes actually discarded.
326 If you use
\helpref{Error
}{wxsocketbaseerror
}, it will always return false.
331 \membersection{wxSocketBase::Error
}\label{wxsocketbaseerror
}
333 \constfunc{bool
}{Error
}{\void}
335 Returns true if an error occurred in the last IO operation.
337 Use this function to check for an error condition after one of the
338 following calls: Discard, Peek, Read, ReadMsg, Unread, Write, WriteMsg.
343 \membersection{wxSocketBase::GetClientData
}\label{wxsocketbasegetclientdata
}
345 \constfunc{void *
}{GetClientData
}{\void}
347 Returns a pointer of the client data for this socket, as set with
348 \helpref{SetClientData
}{wxsocketbasesetclientdata
}
353 \membersection{wxSocketBase::GetLocal
}\label{wxsocketbasegetlocal
}
355 \constfunc{bool
}{GetLocal
}{\param{wxSockAddress\&
}{addr
}}
357 This function returns the local address field of the socket. The local
358 address field contains the complete local address of the socket (local
359 address, local port, ...).
361 \wxheading{Return value
}
363 true if no error happened, false otherwise.
368 \membersection{wxSocketBase::GetFlags
}\label{wxsocketbasegetflags
}
370 \constfunc{wxSocketFlags
}{GetFlags
}{\void}
372 Returns current IO flags, as set with
\helpref{SetFlags
}{wxsocketbasesetflags
}
377 \membersection{wxSocketBase::GetPeer
}\label{wxsocketbasegetpeer
}
379 \constfunc{bool
}{GetPeer
}{\param{wxSockAddress\&
}{addr
}}
381 This function returns the peer address field of the socket. The peer
382 address field contains the complete peer host address of the socket
383 (address, port, ...).
385 \wxheading{Return value
}
387 true if no error happened, false otherwise.
392 \membersection{wxSocketBase::InterruptWait
}\label{wxsocketbaseinterruptwait
}
394 \func{void
}{InterruptWait
}{\void}
396 Use this function to interrupt any wait operation currently in progress.
397 Note that this is not intended as a regular way to interrupt a Wait call,
398 but only as an escape mechanism for exceptional situations where it is
399 absolutely necessary to use it, for example to abort an operation due to
400 some exception or abnormal problem. InterruptWait is automatically called
401 when you
\helpref{Close
}{wxsocketbaseclose
} a socket (and thus also upon
402 socket destruction), so you don't need to use it in these cases.
404 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
},
405 \helpref{wxSocketServer::WaitForAccept
}{wxsocketserverwaitforaccept
},
406 \helpref{wxSocketBase::WaitForLost
}{wxsocketbasewaitforlost
},
407 \helpref{wxSocketBase::WaitForRead
}{wxsocketbasewaitforread
},
408 \helpref{wxSocketBase::WaitForWrite
}{wxsocketbasewaitforwrite
},
409 \helpref{wxSocketClient::WaitOnConnect
}{wxsocketclientwaitonconnect
}
414 \membersection{wxSocketBase::IsConnected
}\label{wxsocketbaseisconnected
}
416 \constfunc{bool
}{IsConnected
}{\void}
418 Returns true if the socket is connected.
423 \membersection{wxSocketBase::IsData
}\label{wxsocketbaseisdata
}
425 \constfunc{bool
}{IsData
}{\void}
427 This function waits until the socket is readable. This might mean that
428 queued data is available for reading or, for streamed sockets, that
429 the connection has been closed, so that a read operation will complete
430 immediately without blocking (unless the
{\bf wxSOCKET
\_WAITALL} flag
431 is set, in which case the operation might still block).
433 \membersection{wxSocketBase::IsDisconnected
}\label{wxsocketbaseisdisconnected
}
438 \constfunc{bool
}{IsDisconnected
}{\void}
440 Returns true if the socket is not connected.
442 \membersection{wxSocketBase::LastCount
}\label{wxsocketbaselastcount
}
447 \constfunc{wxUint32
}{LastCount
}{\void}
449 Returns the number of bytes read or written by the last IO call.
451 Use this function to get the number of bytes actually transferred
452 after using one of the following IO calls: Discard, Peek, Read,
453 ReadMsg, Unread, Write, WriteMsg.
458 \membersection{wxSocketBase::LastError
}\label{wxsocketbaselasterror
}
460 \constfunc{wxSocketError
}{LastError
}{\void}
462 Returns the last wxSocket error. See
\helpref{wxSocket errors
}{wxsocketbase
}.
464 Please note that this function merely returns the last error code,
465 but it should not be used to determine if an error has occurred (this
466 is because successful operations do not change the LastError value).
467 Use
\helpref{Error
}{wxsocketbaseerror
} first, in order to determine
468 if the last IO call failed. If this returns true, use LastError
469 to discover the cause of the error.
474 \membersection{wxSocketBase::Notify
}\label{wxsocketbasenotify
}
476 \func{void
}{Notify
}{\param{bool
}{ notify
}}
478 According to the
{\it notify
} value, this function enables
479 or disables socket events. If
{\it notify
} is true, the events
480 configured with
\helpref{SetNotify
}{wxsocketbasesetnotify
} will
481 be sent to the application. If
{\it notify
} is false; no events
487 \membersection{wxSocketBase::Ok
}\label{wxsocketbaseok
}
489 \constfunc{bool
}{Ok
}{\void}
491 Returns true if the socket is initialized and ready and false in other
494 \wxheading{Remark/Warning
}
496 For
\helpref{wxSocketClient
}{wxsocketclient
}, Ok won't return true unless
497 the client is connected to a server.
499 For
\helpref{wxSocketServer
}{wxsocketserver
}, Ok will return true if the
500 server could bind to the specified address and is already listening for
503 Ok does not check for IO errors;
504 use
\helpref{Error
}{wxsocketbaseerror
} instead for that purpose.
509 \membersection{wxSocketBase::RestoreState
}\label{wxsocketbaserestorestate
}
511 \func{void
}{RestoreState
}{\void}
513 This function restores the previous state of the socket, as saved
514 with
\helpref{SaveState
}{wxsocketbasesavestate
}
516 Calls to SaveState and RestoreState can be nested.
520 \helpref{wxSocketBase::SaveState
}{wxsocketbasesavestate
}
525 \membersection{wxSocketBase::SaveState
}\label{wxsocketbasesavestate
}
527 \func{void
}{SaveState
}{\void}
529 This function saves the current state of the socket in a stack. Socket
530 state includes flags, as set with
\helpref{SetFlags
}{wxsocketbasesetflags
},
531 event mask, as set with
\helpref{SetNotify
}{wxsocketbasesetnotify
} and
532 \helpref{Notify
}{wxsocketbasenotify
}, user data, as set with
533 \helpref{SetClientData
}{wxsocketbasesetclientdata
}, and asynchronous
534 callback settings, as set with
\helpref{Callback
}{wxsocketbasecallback
}
535 and
\helpref{CallbackData
}{wxsocketbasecallbackdata
}.
537 Calls to SaveState and RestoreState can be nested.
541 \helpref{wxSocketBase::RestoreState
}{wxsocketbaserestorestate
}
546 \membersection{wxSocketBase::SetClientData
}\label{wxsocketbasesetclientdata
}
548 \func{void
}{SetClientData
}{\param{void *
}{data
}}
550 Sets user-supplied client data for this socket. All socket events will
551 contain a pointer to this data, which can be retrieved with
552 the
\helpref{wxSocketEvent::GetClientData
}{wxsocketeventgetclientdata
} function.
557 \membersection{wxSocketBase::SetEventHandler
}\label{wxsocketbaseseteventhandler
}
559 \func{void
}{SetEventHandler
}{\param{wxEvtHandler\&
}{ handler
},
\param{int
}{ id = -
1}}
561 Sets an event handler to be called when a socket event occurs. The
562 handler will be called for those events for which notification is
563 enabled with
\helpref{SetNotify
}{wxsocketbasesetnotify
} and
564 \helpref{Notify
}{wxsocketbasenotify
}.
566 \wxheading{Parameters
}
568 \docparam{handler
}{Specifies the event handler you want to use.
}
570 \docparam{id
}{The id of socket event.
}
574 \helpref{wxSocketBase::SetNotify
}{wxsocketbasesetnotify
},
575 \helpref{wxSocketBase::Notify
}{wxsocketbasenotify
},
576 \helpref{wxSocketEvent
}{wxsocketevent
},
577 \helpref{wxEvtHandler
}{wxevthandler
}
582 \membersection{wxSocketBase::SetFlags
}\label{wxsocketbasesetflags
}
584 \func{void
}{SetFlags
}{\param{wxSocketFlags
}{ flags
}}
586 Use SetFlags to customize IO operation for this socket.
587 The
{\it flags
} parameter may be a combination of flags ORed together.
588 The following flags can be used:
591 \begin{twocollist
}\itemsep=
0pt
592 \twocolitem{{\bf wxSOCKET
\_NONE}}{Normal functionality.
}
593 \twocolitem{{\bf wxSOCKET
\_NOWAIT}}{Read/write as much data as possible and return immediately.
}
594 \twocolitem{{\bf wxSOCKET
\_WAITALL}}{Wait for all required data to be read/written unless an error occurs.
}
595 \twocolitem{{\bf wxSOCKET
\_BLOCK}}{Block the GUI (do not yield) while reading/writing data.
}
596 \twocolitem{{\bf wxSOCKET
\_REUSEADDR}}{Allows the use of an in-use port (wxServerSocket only)
}
599 A brief overview on how to use these flags follows.
601 If no flag is specified (this is the same as
{\bf wxSOCKET
\_NONE}),
602 IO calls will return after some data has been read or written, even
603 when the transfer might not be complete. This is the same as issuing
604 exactly one blocking low-level call to recv() or send(). Note
605 that
{\it blocking
} here refers to when the function returns, not
606 to whether the GUI blocks during this time.
608 If
{\bf wxSOCKET
\_NOWAIT} is specified, IO calls will return immediately.
609 Read operations will retrieve only available data. Write operations will
610 write as much data as possible, depending on how much space is available
611 in the output buffer. This is the same as issuing exactly one nonblocking
612 low-level call to recv() or send(). Note that
{\it nonblocking
} here
613 refers to when the function returns, not to whether the GUI blocks during
616 If
{\bf wxSOCKET
\_WAITALL} is specified, IO calls won't return until ALL
617 the data has been read or written (or until an error occurs), blocking if
618 necessary, and issuing several low level calls if necessary. This is the
619 same as having a loop which makes as many blocking low-level calls to
620 recv() or send() as needed so as to transfer all the data. Note
621 that
{\it blocking
} here refers to when the function returns, not
622 to whether the GUI blocks during this time.
624 The
{\bf wxSOCKET
\_BLOCK} flag controls whether the GUI blocks during
625 IO operations. If this flag is specified, the socket will not yield
626 during IO calls, so the GUI will remain blocked until the operation
627 completes. If it is not used, then the application must take extra
628 care to avoid unwanted reentrance.
630 The
{\bf wxSOCKET
\_REUSEADDR} flag controls the use of the SO_REUSEADDR standard
631 setsockopt() flag. This flag allows the socket to bind to a port that is already in use.
632 This is mostly used on UNIX-based systems to allow rapid starting and stopping of a server -
633 otherwise you may have to wait several minutes for the port to become available.
634 This option can have suprising platform dependent behavior, check the documentation for
635 your platforms implementation of setsockopt().
639 {\bf wxSOCKET
\_NONE} will try to read at least SOME data, no matter how much.
641 {\bf wxSOCKET
\_NOWAIT} will always return immediately, even if it cannot
642 read or write ANY data.
644 {\bf wxSOCKET
\_WAITALL} will only return when it has read or written ALL
647 {\bf wxSOCKET
\_BLOCK} has nothing to do with the previous flags and
648 it controls whether the GUI blocks.
650 (
\bf wxSOCKET
\_REUSEADDR} controls special platform-specific behavior for wxServerSocket.
655 \membersection{wxSocketBase::SetNotify
}\label{wxsocketbasesetnotify
}
657 \func{void
}{SetNotify
}{\param{wxSocketEventFlags
}{ flags
}}
659 SetNotify specifies which socket events are to be sent to the event handler.
660 The
{\it flags
} parameter may be combination of flags ORed together. The
661 following flags can be used:
664 \begin{twocollist
}\itemsep=
0pt
665 \twocolitem{{\bf wxSOCKET
\_INPUT\_FLAG}}{to receive wxSOCKET
\_INPUT}
666 \twocolitem{{\bf wxSOCKET
\_OUTPUT\_FLAG}}{to receive wxSOCKET
\_OUTPUT}
667 \twocolitem{{\bf wxSOCKET
\_CONNECTION\_FLAG}}{to receive wxSOCKET
\_CONNECTION}
668 \twocolitem{{\bf wxSOCKET
\_LOST\_FLAG}}{to receive wxSOCKET
\_LOST}
674 sock.SetNotify(wxSOCKET_INPUT_FLAG | wxSOCKET_LOST_FLAG);
678 In this example, the user will be notified about incoming socket data and
679 whenever the connection is closed.
681 For more information on socket events see
\helpref{wxSocket events
}{wxsocketbase
}.
686 \membersection{wxSocketBase::SetTimeout
}\label{wxsocketbasesettimeout
}
688 \func{void
}{SetTimeout
}{\param{int
}{seconds
}}
690 This function sets the default socket timeout in seconds. This timeout
691 applies to all IO calls, and also to the
\helpref{Wait
}{wxsocketbasewait
} family
692 of functions if you don't specify a wait interval. Initially, the default
693 timeout is
10 minutes.
698 \membersection{wxSocketBase::Peek
}\label{wxsocketbasepeek
}
700 \func{wxSocketBase\&
}{Peek
}{\param{void *
}{ buffer
},
\param{wxUint32
}{ nbytes
}}
702 This function peeks a buffer of
{\it nbytes
} bytes from the socket.
703 Peeking a buffer doesn't delete it from the socket input queue.
705 Use
\helpref{LastCount
}{wxsocketbaselastcount
} to verify the number of bytes actually peeked.
707 Use
\helpref{Error
}{wxsocketbaseerror
} to determine if the operation succeeded.
709 \wxheading{Parameters
}
711 \docparam{buffer
}{Buffer where to put peeked data.
}
713 \docparam{nbytes
}{Number of bytes.
}
715 \wxheading{Return value
}
717 Returns a reference to the current object.
719 \wxheading{Remark/Warning
}
721 The exact behaviour of wxSocketBase::Peek depends on the combination
722 of flags being used. For a detailed explanation, see
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}
726 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
727 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
},
728 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
729 \helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}
734 \membersection{wxSocketBase::Read
}\label{wxsocketbaseread
}
736 \func{wxSocketBase\&
}{Read
}{\param{void *
}{ buffer
},
\param{wxUint32
}{ nbytes
}}
738 This function reads a buffer of
{\it nbytes
} bytes from the socket.
740 Use
\helpref{LastCount
}{wxsocketbaselastcount
} to verify the number of bytes actually read.
742 Use
\helpref{Error
}{wxsocketbaseerror
} to determine if the operation succeeded.
744 \wxheading{Parameters
}
746 \docparam{buffer
}{Buffer where to put read data.
}
748 \docparam{nbytes
}{Number of bytes.
}
750 \wxheading{Return value
}
752 Returns a reference to the current object.
754 \wxheading{Remark/Warning
}
756 The exact behaviour of wxSocketBase::Read depends on the combination
757 of flags being used. For a detailed explanation, see
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}.
761 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
762 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
},
763 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
764 \helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}
769 \membersection{wxSocketBase::ReadMsg
}\label{wxsocketbasereadmsg
}
771 \func{wxSocketBase\&
}{ReadMsg
}{\param{void *
}{ buffer
},
\param{wxUint32
}{ nbytes
}}
773 This function reads a buffer sent by
\helpref{WriteMsg
}{wxsocketbasewritemsg
}
774 on a socket. If the buffer passed to the function isn't big enough, the
775 remaining bytes will be discarded. This function always waits for the
776 buffer to be entirely filled, unless an error occurs.
778 Use
\helpref{LastCount
}{wxsocketbaselastcount
} to verify the number of bytes actually read.
780 Use
\helpref{Error
}{wxsocketbaseerror
} to determine if the operation succeeded.
782 \wxheading{Parameters
}
784 \docparam{buffer
}{Buffer where to put read data.
}
786 \docparam{nbytes
}{Size of the buffer.
}
788 \wxheading{Return value
}
790 Returns a reference to the current object.
792 \wxheading{Remark/Warning
}
794 wxSocketBase::ReadMsg will behave as if the
{\bf wxSOCKET
\_WAITALL} flag
795 was always set and it will always ignore the
{\bf wxSOCKET
\_NOWAIT} flag.
796 The exact behaviour of ReadMsg depends on the
{\bf wxSOCKET
\_BLOCK} flag.
797 For a detailed explanation, see
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}.
801 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
802 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
},
803 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
804 \helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
},
805 \helpref{wxSocketBase::WriteMsg
}{wxsocketbasewritemsg
}
810 \membersection{wxSocketBase::Unread
}\label{wxsocketbaseunread
}
812 \func{wxSocketBase\&
}{Unread
}{\param{const void *
}{ buffer
},
\param{wxUint32
}{ nbytes
}}
814 This function unreads a buffer. That is, the data in the buffer is put back
815 in the incoming queue. This function is not affected by wxSocket flags.
817 If you use
\helpref{LastCount
}{wxsocketbaselastcount
}, it will always return
{\it nbytes
}.
819 If you use
\helpref{Error
}{wxsocketbaseerror
}, it will always return false.
821 \wxheading{Parameters
}
823 \docparam{buffer
}{Buffer to be unread.
}
825 \docparam{nbytes
}{Number of bytes.
}
827 \wxheading{Return value
}
829 Returns a reference to the current object.
833 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
834 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
835 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
}
840 \membersection{wxSocketBase::Wait
}\label{wxsocketbasewait
}
842 \func{bool
}{Wait
}{\param{long
}{ seconds = -
1},
\param{long
}{ millisecond =
0}}
844 This function waits until any of the following conditions is true:
847 \item The socket becomes readable.
848 \item The socket becomes writable.
849 \item An ongoing connection request has completed (
\helpref{wxSocketClient
}{wxsocketclient
} only)
850 \item An incoming connection request has arrived (
\helpref{wxSocketServer
}{wxsocketserver
} only)
851 \item The connection has been closed.
854 Note that it is recommended to use the individual Wait functions
855 to wait for the required condition, instead of this one.
857 \wxheading{Parameters
}
859 \docparam{seconds
}{Number of seconds to wait.
860 If -
1, it will wait for the default timeout,
861 as set with
\helpref{SetTimeout
}{wxsocketbasesettimeout
}.
}
863 \docparam{millisecond
}{Number of milliseconds to wait.
}
865 \wxheading{Return value
}
867 Returns true when any of the above conditions is satisfied,
868 false if the timeout was reached.
872 \helpref{wxSocketBase::InterruptWait
}{wxsocketbaseinterruptwait
},
873 \helpref{wxSocketServer::WaitForAccept
}{wxsocketserverwaitforaccept
},
874 \helpref{wxSocketBase::WaitForLost
}{wxsocketbasewaitforlost
},
875 \helpref{wxSocketBase::WaitForRead
}{wxsocketbasewaitforread
},
876 \helpref{wxSocketBase::WaitForWrite
}{wxsocketbasewaitforwrite
},
877 \helpref{wxSocketClient::WaitOnConnect
}{wxsocketclientwaitonconnect
}
882 \membersection{wxSocketBase::WaitForLost
}\label{wxsocketbasewaitforlost
}
884 \func{bool
}{Wait
}{\param{long
}{ seconds = -
1},
\param{long
}{ millisecond =
0}}
886 This function waits until the connection is lost. This may happen if
887 the peer gracefully closes the connection or if the connection breaks.
889 \wxheading{Parameters
}
891 \docparam{seconds
}{Number of seconds to wait.
892 If -
1, it will wait for the default timeout,
893 as set with
\helpref{SetTimeout
}{wxsocketbasesettimeout
}.
}
895 \docparam{millisecond
}{Number of milliseconds to wait.
}
897 \wxheading{Return value
}
899 Returns true if the connection was lost, false if the timeout was reached.
903 \helpref{wxSocketBase::InterruptWait
}{wxsocketbaseinterruptwait
},
904 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
}
909 \membersection{wxSocketBase::WaitForRead
}\label{wxsocketbasewaitforread
}
911 \func{bool
}{WaitForRead
}{\param{long
}{ seconds = -
1},
\param{long
}{ millisecond =
0}}
913 This function waits until the socket is readable. This might mean that
914 queued data is available for reading or, for streamed sockets, that
915 the connection has been closed, so that a read operation will complete
916 immediately without blocking (unless the
{\bf wxSOCKET
\_WAITALL} flag
917 is set, in which case the operation might still block).
919 \wxheading{Parameters
}
921 \docparam{seconds
}{Number of seconds to wait.
922 If -
1, it will wait for the default timeout,
923 as set with
\helpref{SetTimeout
}{wxsocketbasesettimeout
}.
}
925 \docparam{millisecond
}{Number of milliseconds to wait.
}
927 \wxheading{Return value
}
929 Returns true if the socket becomes readable, false on timeout.
933 \helpref{wxSocketBase::InterruptWait
}{wxsocketbaseinterruptwait
},
934 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
}
939 \membersection{wxSocketBase::WaitForWrite
}\label{wxsocketbasewaitforwrite
}
941 \func{bool
}{WaitForWrite
}{\param{long
}{ seconds = -
1},
\param{long
}{ millisecond =
0}}
943 This function waits until the socket becomes writable. This might mean that
944 the socket is ready to send new data, or for streamed sockets, that the
945 connection has been closed, so that a write operation is guaranteed to
946 complete immediately (unless the
{\bf wxSOCKET
\_WAITALL} flag is set,
947 in which case the operation might still block).
949 \wxheading{Parameters
}
951 \docparam{seconds
}{Number of seconds to wait.
952 If -
1, it will wait for the default timeout,
953 as set with
\helpref{SetTimeout
}{wxsocketbasesettimeout
}.
}
955 \docparam{millisecond
}{Number of milliseconds to wait.
}
957 \wxheading{Return value
}
959 Returns true if the socket becomes writable, false on timeout.
963 \helpref{wxSocketBase::InterruptWait
}{wxsocketbaseinterruptwait
},
964 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
}
969 \membersection{wxSocketBase::Write
}\label{wxsocketbasewrite
}
971 \func{wxSocketBase\&
}{Write
}{\param{const void *
}{ buffer
},
\param{wxUint32
}{ nbytes
}}
973 This function writes a buffer of
{\it nbytes
} bytes to the socket.
975 Use
\helpref{LastCount
}{wxsocketbaselastcount
} to verify the number of bytes actually written.
977 Use
\helpref{Error
}{wxsocketbaseerror
} to determine if the operation succeeded.
979 \wxheading{Parameters
}
981 \docparam{buffer
}{Buffer with the data to be sent.
}
983 \docparam{nbytes
}{Number of bytes.
}
985 \wxheading{Return value
}
987 Returns a reference to the current object.
989 \wxheading{Remark/Warning
}
991 The exact behaviour of wxSocketBase::Write depends on the combination
992 of flags being used. For a detailed explanation, see
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}.
996 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
997 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
},
998 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
999 \helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}
1004 \membersection{wxSocketBase::WriteMsg
}\label{wxsocketbasewritemsg
}
1006 \func{wxSocketBase\&
}{WriteMsg
}{\param{const void *
}{ buffer
},
\param{wxUint32
}{ nbytes
}}
1008 This function writes a buffer of
{\it nbytes
} bytes from the socket, but it
1009 writes a short header before so that
\helpref{ReadMsg
}{wxsocketbasereadmsg
}
1010 knows how much data should it actually read. So, a buffer sent with WriteMsg
1011 {\bf must
} be read with ReadMsg. This function always waits for the entire
1012 buffer to be sent, unless an error occurs.
1014 Use
\helpref{LastCount
}{wxsocketbaselastcount
} to verify the number of bytes actually written.
1016 Use
\helpref{Error
}{wxsocketbaseerror
} to determine if the operation succeeded.
1018 \wxheading{Parameters
}
1020 \docparam{buffer
}{Buffer with the data to be sent.
}
1022 \docparam{nbytes
}{Number of bytes to send.
}
1024 \wxheading{Return value
}
1026 Returns a reference to the current object.
1028 \wxheading{Remark/Warning
}
1030 wxSocketBase::WriteMsg will behave as if the
{\bf wxSOCKET
\_WAITALL} flag
1031 was always set and it will always ignore the
{\bf wxSOCKET
\_NOWAIT} flag.
1032 The exact behaviour of WriteMsg depends on the
{\bf wxSOCKET
\_BLOCK} flag.
1033 For a detailed explanation, see
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}.
1035 \wxheading{See also
}
1037 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
1038 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
},
1039 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
1040 \helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
},
1041 \helpref{wxSocketBase::ReadMsg
}{wxsocketbasereadmsg
}
1044 % ---------------------------------------------------------------------------
1045 % CLASS wxSocketClient
1046 % ---------------------------------------------------------------------------
1048 \section{\class{wxSocketClient
}}\label{wxsocketclient
}
1050 \wxheading{Derived from
}
1052 \helpref{wxSocketBase
}{wxsocketbase
}
1054 \wxheading{Include files
}
1058 \latexignore{\rtfignore{\wxheading{Members
}}}
1060 % ---------------------------------------------------------------------------
1062 % ---------------------------------------------------------------------------
1066 \membersection{wxSocketClient::wxSocketClient
}
1068 \func{}{wxSocketClient
}{\param{wxSocketFlags
}{ flags = wxSOCKET
\_NONE}}
1072 \wxheading{Parameters
}
1074 \docparam{flags
}{Socket flags (See
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
})
}
1079 \membersection{wxSocketClient::
\destruct{wxSocketClient
}}
1081 \func{}{\destruct{wxSocketClient
}}{\void}
1083 Destructor. Please see
\helpref{wxSocketBase::Destroy
}{wxsocketbasedestroy
}.
1088 \membersection{wxSocketClient::Connect
}\label{wxsocketclientconnect
}
1090 \func{bool
}{Connect
}{\param{wxSockAddress\&
}{ address
},
\param{bool
}{ wait = true
}}
1092 Connects to a server using the specified address.
1094 If
{\it wait
} is true, Connect will wait until the connection
1095 completes.
{\bf Warning:
} This will block the GUI.
1097 If
{\it wait
} is false, Connect will try to establish the connection and
1098 return immediately, without blocking the GUI. When used this way, even if
1099 Connect returns false, the connection request can be completed later.
1100 To detect this, use
\helpref{WaitOnConnect
}{wxsocketclientwaitonconnect
},
1101 or catch
{\bf wxSOCKET
\_CONNECTION} events (for successful establishment)
1102 and
{\bf wxSOCKET
\_LOST} events (for connection failure).
1104 \wxheading{Parameters
}
1106 \docparam{address
}{Address of the server.
}
1108 \docparam{wait
}{If true, waits for the connection to complete.
}
1110 \wxheading{Return value
}
1112 Returns true if the connection is established and no error occurs.
1114 If
{\it wait
} was true, and Connect returns false, an error occurred
1115 and the connection failed.
1117 If
{\it wait
} was false, and Connect returns false, you should still
1118 be prepared to handle the completion of this connection request, either
1119 with
\helpref{WaitOnConnect
}{wxsocketclientwaitonconnect
} or by
1120 watching
{\bf wxSOCKET
\_CONNECTION} and
{\bf wxSOCKET
\_LOST} events.
1122 \wxheading{See also
}
1124 \helpref{wxSocketClient::WaitOnConnect
}{wxsocketclientwaitonconnect
},
1125 \helpref{wxSocketBase::SetNotify
}{wxsocketbasesetnotify
},
1126 \helpref{wxSocketBase::Notify
}{wxsocketbasenotify
}
1131 \membersection{wxSocketClient::WaitOnConnect
}\label{wxsocketclientwaitonconnect
}
1133 \func{bool
}{WaitOnConnect
}{\param{long
}{ seconds = -
1},
\param{long
}{ milliseconds =
0}}
1135 Wait until a connection request completes, or until the specified timeout
1136 elapses. Use this function after issuing a call
1137 to
\helpref{Connect
}{wxsocketclientconnect
} with
{\it wait
} set to false.
1139 \wxheading{Parameters
}
1141 \docparam{seconds
}{Number of seconds to wait.
1142 If -
1, it will wait for the default timeout,
1143 as set with
\helpref{SetTimeout
}{wxsocketbasesettimeout
}.
}
1145 \docparam{millisecond
}{Number of milliseconds to wait.
}
1147 \wxheading{Return value
}
1149 WaitOnConnect returns true if the connection request completes. This
1150 does not necessarily mean that the connection was successfully established;
1151 it might also happen that the connection was refused by the peer. Use
1152 \helpref{IsConnected
}{wxsocketbaseisconnected
} to distinguish between
1153 these two situations.
1155 If the timeout elapses, WaitOnConnect returns false.
1157 These semantics allow code like this:
1160 // Issue the connection request
1161 client->Connect(addr, false);
1163 // Wait until the request completes or until we decide to give up
1164 bool waitmore = true;
1165 while ( !client->WaitOnConnect(seconds, millis) && waitmore )
1167 // possibly give some feedback to the user,
1168 // and update waitmore as needed.
1170 bool success = client->IsConnected();
1173 \wxheading{See also
}
1175 \helpref{wxSocketClient::Connect
}{wxsocketclientconnect
},
1176 \helpref{wxSocketBase::InterruptWait
}{wxsocketbaseinterruptwait
},
1177 \helpref{wxSocketBase::IsConnected
}{wxsocketbaseisconnected
}
1179 % ---------------------------------------------------------------------------
1180 % CLASS: wxSocketEvent
1181 % ---------------------------------------------------------------------------
1182 \section{\class{wxSocketEvent
}}\label{wxsocketevent
}
1184 This event class contains information about socket events.
1186 \wxheading{Derived from
}
1188 \helpref{wxEvent
}{wxevent
}
1190 \wxheading{Include files
}
1194 \wxheading{Event table macros
}
1196 To process a socket event, use these event handler macros to direct input
1197 to member functions that take a wxSocketEvent argument.
1200 \begin{twocollist
}\itemsep=
0pt
1201 \twocolitem{{\bf EVT
\_SOCKET(id, func)
}}{Process a socket event, supplying the member function.
}
1204 \wxheading{See also
}
1206 \helpref{wxSocketBase
}{wxsocketbase
},
1207 \helpref{wxSocketClient
}{wxsocketclient
},
1208 \helpref{wxSocketServer
}{wxsocketserver
}
1210 \latexignore{\rtfignore{\wxheading{Members
}}}
1212 \membersection{wxSocketEvent::wxSocketEvent
}
1214 \func{}{wxSocketEvent
}{\param{int
}{ id =
0}}
1218 \membersection{wxSocketEvent::GetClientData
}\label{wxsocketeventgetclientdata
}
1220 \func{void *
}{GetClientData
}{\void}
1222 Gets the client data of the socket which generated this event, as
1223 set with
\helpref{wxSocketBase::SetClientData
}{wxsocketbasesetclientdata
}.
1225 \membersection{wxSocketEvent::GetSocket
}\label{wxsocketeventgetsocket
}
1227 \constfunc{wxSocketBase *
}{GetSocket
}{\void}
1229 Returns the socket object to which this event refers to. This makes
1230 it possible to use the same event handler for different sockets.
1232 \membersection{wxSocketEvent::GetSocketEvent
}\label{wxsocketeventgetsocketevent
}
1234 \constfunc{wxSocketNotify
}{GetSocketEvent
}{\void}
1236 Returns the socket event type.