1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 %% Purpose: wxSocket docs
4 %% Author: Guillermo Rodriguez Garcia <guille@iies.es>
8 %% Copyright: (c) wxWidgets team
9 %% License: wxWindows 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
}\label{socketconstruction
}
114 \helpref{wxSocketBase
}{wxsocketbaseconstruct
}\\
115 \helpref{\destruct{wxSocketBase
}}{wxsocketbasedestruct
}\\
116 \helpref{Destroy
}{wxsocketbasedestroy
}
118 \membersection{Socket state
}\label{socketstate
}
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
}\label{socketbasicio
}
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
}\\
165 \helpref{SetLocal
}{wxsocketbasesetlocal
}\\
167 \membersection{Handling socket events
}\label{socketevents
}
169 Functions that allow applications to receive socket events.
171 \helpref{Notify
}{wxsocketbasenotify
}\\
172 \helpref{SetNotify
}{wxsocketbasesetnotify
}\\
173 \helpref{GetClientData
}{wxsocketbasegetclientdata
}\\
174 \helpref{SetClientData
}{wxsocketbasesetclientdata
}\\
175 \helpref{SetEventHandler
}{wxsocketbaseseteventhandler
}
178 % ---------------------------------------------------------------------------
180 % ---------------------------------------------------------------------------
182 \helponly{\insertatlevel{2}{
188 \membersection{wxSocketBase::wxSocketBase
}\label{wxsocketbaseconstruct
}
190 \func{}{wxSocketBase
}{\void}
192 Default constructor. Don't use it directly; instead, use
193 \helpref{wxSocketClient
}{wxsocketclient
} to construct a socket client, or
194 \helpref{wxSocketServer
}{wxsocketserver
} to construct a socket server.
196 \membersection{wxSocketBase::
\destruct{wxSocketBase
}}\label{wxsocketbasedestruct
}
198 \func{}{\destruct{wxSocketBase
}}{\void}
200 Destructor. Do not destroy a socket using the delete operator directly;
201 use
\helpref{Destroy
}{wxsocketbasedestroy
} instead. Also, do not create
202 socket objects in the stack.
208 \membersection{wxSocketBase::Close
}\label{wxsocketbaseclose
}
210 \func{void
}{Close
}{\void}
212 This function shuts down the socket, disabling further transmission and
213 reception of data; it also disables events for the socket and frees the
214 associated system resources. Upon socket destruction, Close is automatically
215 called, so in most cases you won't need to do it yourself, unless you
216 explicitly want to shut down the socket, typically to notify the peer
217 that you are closing the connection.
219 \wxheading{Remark/Warning
}
221 Although Close immediately disables events for the socket, it is possible
222 that event messages may be waiting in the application's event queue. The
223 application must therefore be prepared to handle socket event messages
224 even after calling Close.
229 \membersection{wxSocketBase::Destroy
}\label{wxsocketbasedestroy
}
231 \func{bool
}{Destroy
}{\void}
233 Destroys the socket safely. Use this function instead of the delete operator,
234 since otherwise socket events could reach the application even after the
235 socket has been destroyed. To prevent this problem, this function appends
236 the wxSocket to a list of object to be deleted on idle time, after all
237 events have been processed. For the same reason, you should avoid creating
238 socket objects in the stack.
240 Destroy calls
\helpref{Close
}{wxsocketbaseclose
} automatically.
242 \wxheading{Return value
}
249 \membersection{wxSocketBase::Discard
}\label{wxsocketbasediscard
}
251 \func{wxSocketBase\&
}{Discard
}{\void}
253 This function simply deletes all bytes in the incoming queue. This function
254 always returns immediately and its operation is not affected by IO flags.
256 Use
\helpref{LastCount
}{wxsocketbaselastcount
} to verify the number of bytes actually discarded.
258 If you use
\helpref{Error
}{wxsocketbaseerror
}, it will always return false.
263 \membersection{wxSocketBase::Error
}\label{wxsocketbaseerror
}
265 \constfunc{bool
}{Error
}{\void}
267 Returns true if an error occurred in the last IO operation.
269 Use this function to check for an error condition after one of the
270 following calls: Discard, Peek, Read, ReadMsg, Unread, Write, WriteMsg.
275 \membersection{wxSocketBase::GetClientData
}\label{wxsocketbasegetclientdata
}
277 \constfunc{void *
}{GetClientData
}{\void}
279 Returns a pointer of the client data for this socket, as set with
280 \helpref{SetClientData
}{wxsocketbasesetclientdata
}
285 \membersection{wxSocketBase::GetLocal
}\label{wxsocketbasegetlocal
}
287 \constfunc{bool
}{GetLocal
}{\param{wxSockAddress\&
}{addr
}}
289 This function returns the local address field of the socket. The local
290 address field contains the complete local address of the socket (local
291 address, local port, ...).
293 \wxheading{Return value
}
295 true if no error happened, false otherwise.
300 \membersection{wxSocketBase::GetFlags
}\label{wxsocketbasegetflags
}
302 \constfunc{wxSocketFlags
}{GetFlags
}{\void}
304 Returns current IO flags, as set with
\helpref{SetFlags
}{wxsocketbasesetflags
}
309 \membersection{wxSocketBase::GetPeer
}\label{wxsocketbasegetpeer
}
311 \constfunc{bool
}{GetPeer
}{\param{wxSockAddress\&
}{addr
}}
313 This function returns the peer address field of the socket. The peer
314 address field contains the complete peer host address of the socket
315 (address, port, ...).
317 \wxheading{Return value
}
319 true if no error happened, false otherwise.
324 \membersection{wxSocketBase::InterruptWait
}\label{wxsocketbaseinterruptwait
}
326 \func{void
}{InterruptWait
}{\void}
328 Use this function to interrupt any wait operation currently in progress.
329 Note that this is not intended as a regular way to interrupt a Wait call,
330 but only as an escape mechanism for exceptional situations where it is
331 absolutely necessary to use it, for example to abort an operation due to
332 some exception or abnormal problem. InterruptWait is automatically called
333 when you
\helpref{Close
}{wxsocketbaseclose
} a socket (and thus also upon
334 socket destruction), so you don't need to use it in these cases.
336 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
},
337 \helpref{wxSocketServer::WaitForAccept
}{wxsocketserverwaitforaccept
},
338 \helpref{wxSocketBase::WaitForLost
}{wxsocketbasewaitforlost
},
339 \helpref{wxSocketBase::WaitForRead
}{wxsocketbasewaitforread
},
340 \helpref{wxSocketBase::WaitForWrite
}{wxsocketbasewaitforwrite
},
341 \helpref{wxSocketClient::WaitOnConnect
}{wxsocketclientwaitonconnect
}
346 \membersection{wxSocketBase::IsConnected
}\label{wxsocketbaseisconnected
}
348 \constfunc{bool
}{IsConnected
}{\void}
350 Returns true if the socket is connected.
355 \membersection{wxSocketBase::IsData
}\label{wxsocketbaseisdata
}
357 \constfunc{bool
}{IsData
}{\void}
359 This function waits until the socket is readable. This might mean that
360 queued data is available for reading or, for streamed sockets, that
361 the connection has been closed, so that a read operation will complete
362 immediately without blocking (unless the
{\bf wxSOCKET
\_WAITALL} flag
363 is set, in which case the operation might still block).
365 \membersection{wxSocketBase::IsDisconnected
}\label{wxsocketbaseisdisconnected
}
370 \constfunc{bool
}{IsDisconnected
}{\void}
372 Returns true if the socket is not connected.
374 \membersection{wxSocketBase::LastCount
}\label{wxsocketbaselastcount
}
379 \constfunc{wxUint32
}{LastCount
}{\void}
381 Returns the number of bytes read or written by the last IO call.
383 Use this function to get the number of bytes actually transferred
384 after using one of the following IO calls: Discard, Peek, Read,
385 ReadMsg, Unread, Write, WriteMsg.
390 \membersection{wxSocketBase::LastError
}\label{wxsocketbaselasterror
}
392 \constfunc{wxSocketError
}{LastError
}{\void}
394 Returns the last wxSocket error. See
\helpref{wxSocket errors
}{wxsocketbase
}.
396 Please note that this function merely returns the last error code,
397 but it should not be used to determine if an error has occurred (this
398 is because successful operations do not change the LastError value).
399 Use
\helpref{Error
}{wxsocketbaseerror
} first, in order to determine
400 if the last IO call failed. If this returns true, use LastError
401 to discover the cause of the error.
406 \membersection{wxSocketBase::Notify
}\label{wxsocketbasenotify
}
408 \func{void
}{Notify
}{\param{bool
}{ notify
}}
410 According to the
{\it notify
} value, this function enables
411 or disables socket events. If
{\it notify
} is true, the events
412 configured with
\helpref{SetNotify
}{wxsocketbasesetnotify
} will
413 be sent to the application. If
{\it notify
} is false; no events
419 \membersection{wxSocketBase::Ok
}\label{wxsocketbaseok
}
421 \constfunc{bool
}{Ok
}{\void}
423 Returns true if the socket is initialized and ready and false in other
426 \wxheading{Remark/Warning
}
428 For
\helpref{wxSocketClient
}{wxsocketclient
}, Ok won't return true unless
429 the client is connected to a server.
431 For
\helpref{wxSocketServer
}{wxsocketserver
}, Ok will return true if the
432 server could bind to the specified address and is already listening for
435 Ok does not check for IO errors;
436 use
\helpref{Error
}{wxsocketbaseerror
} instead for that purpose.
441 \membersection{wxSocketBase::RestoreState
}\label{wxsocketbaserestorestate
}
443 \func{void
}{RestoreState
}{\void}
445 This function restores the previous state of the socket, as saved
446 with
\helpref{SaveState
}{wxsocketbasesavestate
}
448 Calls to SaveState and RestoreState can be nested.
452 \helpref{wxSocketBase::SaveState
}{wxsocketbasesavestate
}
457 \membersection{wxSocketBase::SaveState
}\label{wxsocketbasesavestate
}
459 \func{void
}{SaveState
}{\void}
461 This function saves the current state of the socket in a stack. Socket
462 state includes flags, as set with
\helpref{SetFlags
}{wxsocketbasesetflags
},
463 event mask, as set with
\helpref{SetNotify
}{wxsocketbasesetnotify
} and
464 \helpref{Notify
}{wxsocketbasenotify
}, user data, as set with
465 \helpref{SetClientData
}{wxsocketbasesetclientdata
}.
467 Calls to SaveState and RestoreState can be nested.
471 \helpref{wxSocketBase::RestoreState
}{wxsocketbaserestorestate
}
476 \membersection{wxSocketBase::SetClientData
}\label{wxsocketbasesetclientdata
}
478 \func{void
}{SetClientData
}{\param{void *
}{data
}}
480 Sets user-supplied client data for this socket. All socket events will
481 contain a pointer to this data, which can be retrieved with
482 the
\helpref{wxSocketEvent::GetClientData
}{wxsocketeventgetclientdata
} function.
487 \membersection{wxSocketBase::SetEventHandler
}\label{wxsocketbaseseteventhandler
}
489 \func{void
}{SetEventHandler
}{\param{wxEvtHandler\&
}{ handler
},
\param{int
}{ id = -
1}}
491 Sets an event handler to be called when a socket event occurs. The
492 handler will be called for those events for which notification is
493 enabled with
\helpref{SetNotify
}{wxsocketbasesetnotify
} and
494 \helpref{Notify
}{wxsocketbasenotify
}.
496 \wxheading{Parameters
}
498 \docparam{handler
}{Specifies the event handler you want to use.
}
500 \docparam{id
}{The id of socket event.
}
504 \helpref{wxSocketBase::SetNotify
}{wxsocketbasesetnotify
},
505 \helpref{wxSocketBase::Notify
}{wxsocketbasenotify
},
506 \helpref{wxSocketEvent
}{wxsocketevent
},
507 \helpref{wxEvtHandler
}{wxevthandler
}
512 \membersection{wxSocketBase::SetFlags
}\label{wxsocketbasesetflags
}
514 \func{void
}{SetFlags
}{\param{wxSocketFlags
}{ flags
}}
516 Use SetFlags to customize IO operation for this socket.
517 The
{\it flags
} parameter may be a combination of flags ORed together.
518 The following flags can be used:
521 \begin{twocollist
}\itemsep=
0pt
522 \twocolitem{{\bf wxSOCKET
\_NONE}}{Normal functionality.
}
523 \twocolitem{{\bf wxSOCKET
\_NOWAIT}}{Read/write as much data as possible and return immediately.
}
524 \twocolitem{{\bf wxSOCKET
\_WAITALL}}{Wait for all required data to be read/written unless an error occurs.
}
525 \twocolitem{{\bf wxSOCKET
\_BLOCK}}{Block the GUI (do not yield) while reading/writing data.
}
526 \twocolitem{{\bf wxSOCKET
\_REUSEADDR}}{Allows the use of an in-use port (wxServerSocket only)
}
529 A brief overview on how to use these flags follows.
531 If no flag is specified (this is the same as
{\bf wxSOCKET
\_NONE}),
532 IO calls will return after some data has been read or written, even
533 when the transfer might not be complete. This is the same as issuing
534 exactly one blocking low-level call to recv() or send(). Note
535 that
{\it blocking
} here refers to when the function returns, not
536 to whether the GUI blocks during this time.
538 If
{\bf wxSOCKET
\_NOWAIT} is specified, IO calls will return immediately.
539 Read operations will retrieve only available data. Write operations will
540 write as much data as possible, depending on how much space is available
541 in the output buffer. This is the same as issuing exactly one nonblocking
542 low-level call to recv() or send(). Note that
{\it nonblocking
} here
543 refers to when the function returns, not to whether the GUI blocks during
546 If
{\bf wxSOCKET
\_WAITALL} is specified, IO calls won't return until ALL
547 the data has been read or written (or until an error occurs), blocking if
548 necessary, and issuing several low level calls if necessary. This is the
549 same as having a loop which makes as many blocking low-level calls to
550 recv() or send() as needed so as to transfer all the data. Note
551 that
{\it blocking
} here refers to when the function returns, not
552 to whether the GUI blocks during this time.
554 The
{\bf wxSOCKET
\_BLOCK} flag controls whether the GUI blocks during
555 IO operations. If this flag is specified, the socket will not yield
556 during IO calls, so the GUI will remain blocked until the operation
557 completes. If it is not used, then the application must take extra
558 care to avoid unwanted reentrance.
560 The
{\bf wxSOCKET
\_REUSEADDR} flag controls the use of the SO
\_REUSEADDR standard
561 setsockopt() flag. This flag allows the socket to bind to a port that is already in use.
562 This is mostly used on UNIX-based systems to allow rapid starting and stopping of a server -
563 otherwise you may have to wait several minutes for the port to become available.
564 wxSOCKET_REUSEADDR can also be used with socket clients to (re)bind to a particular local port
565 for an outgoing connection.
566 This option can have surprising platform dependent behavior, so check the documentation for
567 your platform's implementation of setsockopt(). Note that on BSD-based systems (e.g. Mac OS X),
568 use of wxSOCKET_REUSEADDR implies SO_REUSEPORT in addition to SO_REUSEADDR to be consistent
573 {\bf wxSOCKET
\_NONE} will try to read at least SOME data, no matter how much.
575 {\bf wxSOCKET
\_NOWAIT} will always return immediately, even if it cannot
576 read or write ANY data.
578 {\bf wxSOCKET
\_WAITALL} will only return when it has read or written ALL
581 {\bf wxSOCKET
\_BLOCK} has nothing to do with the previous flags and
582 it controls whether the GUI blocks.
584 {\bf wxSOCKET
\_REUSEADDR} controls special platform-specific behavior for
585 reusing local addresses/ports.
590 \membersection{wxSocketBase::SetLocal
}\label{wxsocketbasesetlocal
}
592 \func{bool
}{SetLocal
}{\param{wxIPV4address\&
}{ local
}}
594 This function allows you to set the local address and port,
595 useful when an application needs to reuse a particular port. When
596 a local port is set for a
\helpref{wxSocketClient
}{wxsocketclient
},
597 {\bf bind
} will be called before
{\bf connect
}.
602 \membersection{wxSocketBase::SetNotify
}\label{wxsocketbasesetnotify
}
604 \func{void
}{SetNotify
}{\param{wxSocketEventFlags
}{ flags
}}
606 SetNotify specifies which socket events are to be sent to the event handler.
607 The
{\it flags
} parameter may be combination of flags ORed together. The
608 following flags can be used:
611 \begin{twocollist
}\itemsep=
0pt
612 \twocolitem{{\bf wxSOCKET
\_INPUT\_FLAG}}{to receive wxSOCKET
\_INPUT}
613 \twocolitem{{\bf wxSOCKET
\_OUTPUT\_FLAG}}{to receive wxSOCKET
\_OUTPUT}
614 \twocolitem{{\bf wxSOCKET
\_CONNECTION\_FLAG}}{to receive wxSOCKET
\_CONNECTION}
615 \twocolitem{{\bf wxSOCKET
\_LOST\_FLAG}}{to receive wxSOCKET
\_LOST}
621 sock.SetNotify(wxSOCKET_INPUT_FLAG | wxSOCKET_LOST_FLAG);
625 In this example, the user will be notified about incoming socket data and
626 whenever the connection is closed.
628 For more information on socket events see
\helpref{wxSocket events
}{wxsocketbase
}.
633 \membersection{wxSocketBase::SetTimeout
}\label{wxsocketbasesettimeout
}
635 \func{void
}{SetTimeout
}{\param{int
}{seconds
}}
637 This function sets the default socket timeout in seconds. This timeout
638 applies to all IO calls, and also to the
\helpref{Wait
}{wxsocketbasewait
} family
639 of functions if you don't specify a wait interval. Initially, the default
640 timeout is
10 minutes.
645 \membersection{wxSocketBase::Peek
}\label{wxsocketbasepeek
}
647 \func{wxSocketBase\&
}{Peek
}{\param{void *
}{ buffer
},
\param{wxUint32
}{ nbytes
}}
649 This function peeks a buffer of
{\it nbytes
} bytes from the socket.
650 Peeking a buffer doesn't delete it from the socket input queue.
652 Use
\helpref{LastCount
}{wxsocketbaselastcount
} to verify the number of bytes actually peeked.
654 Use
\helpref{Error
}{wxsocketbaseerror
} to determine if the operation succeeded.
656 \wxheading{Parameters
}
658 \docparam{buffer
}{Buffer where to put peeked data.
}
660 \docparam{nbytes
}{Number of bytes.
}
662 \wxheading{Return value
}
664 Returns a reference to the current object.
666 \wxheading{Remark/Warning
}
668 The exact behaviour of wxSocketBase::Peek depends on the combination
669 of flags being used. For a detailed explanation, see
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}
673 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
674 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
},
675 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
676 \helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}
681 \membersection{wxSocketBase::Read
}\label{wxsocketbaseread
}
683 \func{wxSocketBase\&
}{Read
}{\param{void *
}{ buffer
},
\param{wxUint32
}{ nbytes
}}
685 This function reads a buffer of
{\it nbytes
} bytes from the socket.
687 Use
\helpref{LastCount
}{wxsocketbaselastcount
} to verify the number of bytes actually read.
689 Use
\helpref{Error
}{wxsocketbaseerror
} to determine if the operation succeeded.
691 \wxheading{Parameters
}
693 \docparam{buffer
}{Buffer where to put read data.
}
695 \docparam{nbytes
}{Number of bytes.
}
697 \wxheading{Return value
}
699 Returns a reference to the current object.
701 \wxheading{Remark/Warning
}
703 The exact behaviour of wxSocketBase::Read depends on the combination
704 of flags being used. For a detailed explanation, see
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}.
708 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
709 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
},
710 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
711 \helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}
716 \membersection{wxSocketBase::ReadMsg
}\label{wxsocketbasereadmsg
}
718 \func{wxSocketBase\&
}{ReadMsg
}{\param{void *
}{ buffer
},
\param{wxUint32
}{ nbytes
}}
720 This function reads a buffer sent by
\helpref{WriteMsg
}{wxsocketbasewritemsg
}
721 on a socket. If the buffer passed to the function isn't big enough, the
722 remaining bytes will be discarded. This function always waits for the
723 buffer to be entirely filled, unless an error occurs.
725 Use
\helpref{LastCount
}{wxsocketbaselastcount
} to verify the number of bytes actually read.
727 Use
\helpref{Error
}{wxsocketbaseerror
} to determine if the operation succeeded.
729 \wxheading{Parameters
}
731 \docparam{buffer
}{Buffer where to put read data.
}
733 \docparam{nbytes
}{Size of the buffer.
}
735 \wxheading{Return value
}
737 Returns a reference to the current object.
739 \wxheading{Remark/Warning
}
741 wxSocketBase::ReadMsg will behave as if the
{\bf wxSOCKET
\_WAITALL} flag
742 was always set and it will always ignore the
{\bf wxSOCKET
\_NOWAIT} flag.
743 The exact behaviour of ReadMsg depends on the
{\bf wxSOCKET
\_BLOCK} flag.
744 For a detailed explanation, see
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}.
748 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
749 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
},
750 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
751 \helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
},
752 \helpref{wxSocketBase::WriteMsg
}{wxsocketbasewritemsg
}
757 \membersection{wxSocketBase::Unread
}\label{wxsocketbaseunread
}
759 \func{wxSocketBase\&
}{Unread
}{\param{const void *
}{ buffer
},
\param{wxUint32
}{ nbytes
}}
761 This function unreads a buffer. That is, the data in the buffer is put back
762 in the incoming queue. This function is not affected by wxSocket flags.
764 If you use
\helpref{LastCount
}{wxsocketbaselastcount
}, it will always return
{\it nbytes
}.
766 If you use
\helpref{Error
}{wxsocketbaseerror
}, it will always return false.
768 \wxheading{Parameters
}
770 \docparam{buffer
}{Buffer to be unread.
}
772 \docparam{nbytes
}{Number of bytes.
}
774 \wxheading{Return value
}
776 Returns a reference to the current object.
780 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
781 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
782 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
}
787 \membersection{wxSocketBase::Wait
}\label{wxsocketbasewait
}
789 \func{bool
}{Wait
}{\param{long
}{ seconds = -
1},
\param{long
}{ millisecond =
0}}
791 This function waits until any of the following conditions is true:
794 \item The socket becomes readable.
795 \item The socket becomes writable.
796 \item An ongoing connection request has completed (
\helpref{wxSocketClient
}{wxsocketclient
} only)
797 \item An incoming connection request has arrived (
\helpref{wxSocketServer
}{wxsocketserver
} only)
798 \item The connection has been closed.
801 Note that it is recommended to use the individual Wait functions
802 to wait for the required condition, instead of this one.
804 \wxheading{Parameters
}
806 \docparam{seconds
}{Number of seconds to wait.
807 If -
1, it will wait for the default timeout,
808 as set with
\helpref{SetTimeout
}{wxsocketbasesettimeout
}.
}
810 \docparam{millisecond
}{Number of milliseconds to wait.
}
812 \wxheading{Return value
}
814 Returns true when any of the above conditions is satisfied,
815 false if the timeout was reached.
819 \helpref{wxSocketBase::InterruptWait
}{wxsocketbaseinterruptwait
},
820 \helpref{wxSocketServer::WaitForAccept
}{wxsocketserverwaitforaccept
},
821 \helpref{wxSocketBase::WaitForLost
}{wxsocketbasewaitforlost
},
822 \helpref{wxSocketBase::WaitForRead
}{wxsocketbasewaitforread
},
823 \helpref{wxSocketBase::WaitForWrite
}{wxsocketbasewaitforwrite
},
824 \helpref{wxSocketClient::WaitOnConnect
}{wxsocketclientwaitonconnect
}
829 \membersection{wxSocketBase::WaitForLost
}\label{wxsocketbasewaitforlost
}
831 \func{bool
}{Wait
}{\param{long
}{ seconds = -
1},
\param{long
}{ millisecond =
0}}
833 This function waits until the connection is lost. This may happen if
834 the peer gracefully closes the connection or if the connection breaks.
836 \wxheading{Parameters
}
838 \docparam{seconds
}{Number of seconds to wait.
839 If -
1, it will wait for the default timeout,
840 as set with
\helpref{SetTimeout
}{wxsocketbasesettimeout
}.
}
842 \docparam{millisecond
}{Number of milliseconds to wait.
}
844 \wxheading{Return value
}
846 Returns true if the connection was lost, false if the timeout was reached.
850 \helpref{wxSocketBase::InterruptWait
}{wxsocketbaseinterruptwait
},
851 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
}
856 \membersection{wxSocketBase::WaitForRead
}\label{wxsocketbasewaitforread
}
858 \func{bool
}{WaitForRead
}{\param{long
}{ seconds = -
1},
\param{long
}{ millisecond =
0}}
860 This function waits until the socket is readable. This might mean that
861 queued data is available for reading or, for streamed sockets, that
862 the connection has been closed, so that a read operation will complete
863 immediately without blocking (unless the
{\bf wxSOCKET
\_WAITALL} flag
864 is set, in which case the operation might still block).
866 \wxheading{Parameters
}
868 \docparam{seconds
}{Number of seconds to wait.
869 If -
1, it will wait for the default timeout,
870 as set with
\helpref{SetTimeout
}{wxsocketbasesettimeout
}.
}
872 \docparam{millisecond
}{Number of milliseconds to wait.
}
874 \wxheading{Return value
}
876 Returns true if the socket becomes readable, false on timeout.
880 \helpref{wxSocketBase::InterruptWait
}{wxsocketbaseinterruptwait
},
881 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
}
886 \membersection{wxSocketBase::WaitForWrite
}\label{wxsocketbasewaitforwrite
}
888 \func{bool
}{WaitForWrite
}{\param{long
}{ seconds = -
1},
\param{long
}{ millisecond =
0}}
890 This function waits until the socket becomes writable. This might mean that
891 the socket is ready to send new data, or for streamed sockets, that the
892 connection has been closed, so that a write operation is guaranteed to
893 complete immediately (unless the
{\bf wxSOCKET
\_WAITALL} flag is set,
894 in which case the operation might still block).
896 \wxheading{Parameters
}
898 \docparam{seconds
}{Number of seconds to wait.
899 If -
1, it will wait for the default timeout,
900 as set with
\helpref{SetTimeout
}{wxsocketbasesettimeout
}.
}
902 \docparam{millisecond
}{Number of milliseconds to wait.
}
904 \wxheading{Return value
}
906 Returns true if the socket becomes writable, false on timeout.
910 \helpref{wxSocketBase::InterruptWait
}{wxsocketbaseinterruptwait
},
911 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
}
916 \membersection{wxSocketBase::Write
}\label{wxsocketbasewrite
}
918 \func{wxSocketBase\&
}{Write
}{\param{const void *
}{ buffer
},
\param{wxUint32
}{ nbytes
}}
920 This function writes a buffer of
{\it nbytes
} bytes to the socket.
922 Use
\helpref{LastCount
}{wxsocketbaselastcount
} to verify the number of bytes actually written.
924 Use
\helpref{Error
}{wxsocketbaseerror
} to determine if the operation succeeded.
926 \wxheading{Parameters
}
928 \docparam{buffer
}{Buffer with the data to be sent.
}
930 \docparam{nbytes
}{Number of bytes.
}
932 \wxheading{Return value
}
934 Returns a reference to the current object.
936 \wxheading{Remark/Warning
}
938 The exact behaviour of wxSocketBase::Write depends on the combination
939 of flags being used. For a detailed explanation, see
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}.
943 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
944 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
},
945 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
946 \helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}
951 \membersection{wxSocketBase::WriteMsg
}\label{wxsocketbasewritemsg
}
953 \func{wxSocketBase\&
}{WriteMsg
}{\param{const void *
}{ buffer
},
\param{wxUint32
}{ nbytes
}}
955 This function writes a buffer of
{\it nbytes
} bytes from the socket, but it
956 writes a short header before so that
\helpref{ReadMsg
}{wxsocketbasereadmsg
}
957 knows how much data should it actually read. So, a buffer sent with WriteMsg
958 {\bf must
} be read with ReadMsg. This function always waits for the entire
959 buffer to be sent, unless an error occurs.
961 Use
\helpref{LastCount
}{wxsocketbaselastcount
} to verify the number of bytes actually written.
963 Use
\helpref{Error
}{wxsocketbaseerror
} to determine if the operation succeeded.
965 \wxheading{Parameters
}
967 \docparam{buffer
}{Buffer with the data to be sent.
}
969 \docparam{nbytes
}{Number of bytes to send.
}
971 \wxheading{Return value
}
973 Returns a reference to the current object.
975 \wxheading{Remark/Warning
}
977 wxSocketBase::WriteMsg will behave as if the
{\bf wxSOCKET
\_WAITALL} flag
978 was always set and it will always ignore the
{\bf wxSOCKET
\_NOWAIT} flag.
979 The exact behaviour of WriteMsg depends on the
{\bf wxSOCKET
\_BLOCK} flag.
980 For a detailed explanation, see
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
}.
984 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
985 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
},
986 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
987 \helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
},
988 \helpref{wxSocketBase::ReadMsg
}{wxsocketbasereadmsg
}
991 % ---------------------------------------------------------------------------
992 % CLASS wxSocketClient
993 % ---------------------------------------------------------------------------
995 \section{\class{wxSocketClient
}}\label{wxsocketclient
}
997 \wxheading{Derived from
}
999 \helpref{wxSocketBase
}{wxsocketbase
}
1001 \wxheading{Include files
}
1005 \latexignore{\rtfignore{\wxheading{Members
}}}
1007 % ---------------------------------------------------------------------------
1009 % ---------------------------------------------------------------------------
1013 \membersection{wxSocketClient::wxSocketClient
}\label{wxsocketclientctor
}
1015 \func{}{wxSocketClient
}{\param{wxSocketFlags
}{ flags = wxSOCKET
\_NONE}}
1019 \wxheading{Parameters
}
1021 \docparam{flags
}{Socket flags (See
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
})
}
1026 \membersection{wxSocketClient::
\destruct{wxSocketClient
}}\label{wxsocketclientdtor
}
1028 \func{}{\destruct{wxSocketClient
}}{\void}
1030 Destructor. Please see
\helpref{wxSocketBase::Destroy
}{wxsocketbasedestroy
}.
1035 \membersection{wxSocketClient::Connect
}\label{wxsocketclientconnect
}
1037 \func{bool
}{Connect
}{\param{wxSockAddress\&
}{ address
},
\param{bool
}{ wait = true
}}
1039 \func{bool
}{Connect
}{\param{wxSockAddress\&
}{ address
},
\param{wxSockAddress\&
}{ local
},
1040 \param{bool
}{ wait = true
}}
1042 Connects to a server using the specified address.
1044 If
{\it wait
} is true, Connect will wait until the connection
1045 completes.
{\bf Warning:
} This will block the GUI.
1047 If
{\it wait
} is false, Connect will try to establish the connection and
1048 return immediately, without blocking the GUI. When used this way, even if
1049 Connect returns false, the connection request can be completed later.
1050 To detect this, use
\helpref{WaitOnConnect
}{wxsocketclientwaitonconnect
},
1051 or catch
{\bf wxSOCKET
\_CONNECTION} events (for successful establishment)
1052 and
{\bf wxSOCKET
\_LOST} events (for connection failure).
1054 \wxheading{Parameters
}
1056 \docparam{address
}{Address of the server.
}
1058 \docparam{local
}{Bind to the specified local address and port before connecting.
1059 The local address and port can also be set using
\helpref{SetLocal
}{wxsocketbasesetlocal
},
1060 and then using the
2-parameter Connect method.
}
1062 \docparam{wait
}{If true, waits for the connection to complete.
}
1064 \wxheading{Return value
}
1066 Returns true if the connection is established and no error occurs.
1068 If
{\it wait
} was true, and Connect returns false, an error occurred
1069 and the connection failed.
1071 If
{\it wait
} was false, and Connect returns false, you should still
1072 be prepared to handle the completion of this connection request, either
1073 with
\helpref{WaitOnConnect
}{wxsocketclientwaitonconnect
} or by
1074 watching
{\bf wxSOCKET
\_CONNECTION} and
{\bf wxSOCKET
\_LOST} events.
1076 \wxheading{See also
}
1078 \helpref{wxSocketClient::WaitOnConnect
}{wxsocketclientwaitonconnect
},
1079 \helpref{wxSocketBase::SetNotify
}{wxsocketbasesetnotify
},
1080 \helpref{wxSocketBase::Notify
}{wxsocketbasenotify
}
1085 \membersection{wxSocketClient::WaitOnConnect
}\label{wxsocketclientwaitonconnect
}
1087 \func{bool
}{WaitOnConnect
}{\param{long
}{ seconds = -
1},
\param{long
}{ milliseconds =
0}}
1089 Wait until a connection request completes, or until the specified timeout
1090 elapses. Use this function after issuing a call
1091 to
\helpref{Connect
}{wxsocketclientconnect
} with
{\it wait
} set to false.
1093 \wxheading{Parameters
}
1095 \docparam{seconds
}{Number of seconds to wait.
1096 If -
1, it will wait for the default timeout,
1097 as set with
\helpref{SetTimeout
}{wxsocketbasesettimeout
}.
}
1099 \docparam{millisecond
}{Number of milliseconds to wait.
}
1101 \wxheading{Return value
}
1103 WaitOnConnect returns true if the connection request completes. This
1104 does not necessarily mean that the connection was successfully established;
1105 it might also happen that the connection was refused by the peer. Use
1106 \helpref{IsConnected
}{wxsocketbaseisconnected
} to distinguish between
1107 these two situations.
1109 If the timeout elapses, WaitOnConnect returns false.
1111 These semantics allow code like this:
1114 // Issue the connection request
1115 client->Connect(addr, false);
1117 // Wait until the request completes or until we decide to give up
1118 bool waitmore = true;
1119 while ( !client->WaitOnConnect(seconds, millis) && waitmore )
1121 // possibly give some feedback to the user,
1122 // and update waitmore as needed.
1124 bool success = client->IsConnected();
1127 \wxheading{See also
}
1129 \helpref{wxSocketClient::Connect
}{wxsocketclientconnect
},
1130 \helpref{wxSocketBase::InterruptWait
}{wxsocketbaseinterruptwait
},
1131 \helpref{wxSocketBase::IsConnected
}{wxsocketbaseisconnected
}
1133 % ---------------------------------------------------------------------------
1134 % CLASS: wxSocketEvent
1135 % ---------------------------------------------------------------------------
1136 \section{\class{wxSocketEvent
}}\label{wxsocketevent
}
1138 This event class contains information about socket events.
1140 \wxheading{Derived from
}
1142 \helpref{wxEvent
}{wxevent
}
1144 \wxheading{Include files
}
1148 \wxheading{Event table macros
}
1150 To process a socket event, use these event handler macros to direct input
1151 to member functions that take a wxSocketEvent argument.
1154 \begin{twocollist
}\itemsep=
0pt
1155 \twocolitem{{\bf EVT
\_SOCKET(id, func)
}}{Process a socket event, supplying the member function.
}
1158 \wxheading{See also
}
1160 \helpref{wxSocketBase
}{wxsocketbase
},
1161 \helpref{wxSocketClient
}{wxsocketclient
},
1162 \helpref{wxSocketServer
}{wxsocketserver
}
1164 \latexignore{\rtfignore{\wxheading{Members
}}}
1166 \membersection{wxSocketEvent::wxSocketEvent
}\label{wxsocketeventctor
}
1168 \func{}{wxSocketEvent
}{\param{int
}{ id =
0}}
1172 \membersection{wxSocketEvent::GetClientData
}\label{wxsocketeventgetclientdata
}
1174 \func{void *
}{GetClientData
}{\void}
1176 Gets the client data of the socket which generated this event, as
1177 set with
\helpref{wxSocketBase::SetClientData
}{wxsocketbasesetclientdata
}.
1179 \membersection{wxSocketEvent::GetSocket
}\label{wxsocketeventgetsocket
}
1181 \constfunc{wxSocketBase *
}{GetSocket
}{\void}
1183 Returns the socket object to which this event refers to. This makes
1184 it possible to use the same event handler for different sockets.
1186 \membersection{wxSocketEvent::GetSocketEvent
}\label{wxsocketeventgetsocketevent
}
1188 \constfunc{wxSocketNotify
}{GetSocketEvent
}{\void}
1190 Returns the socket event type.