1 \section{\class{wxSocketBase
}}\label{wxsocketbase
}
3 \wxheading{Derived from
}
5 \helpref{wxEvtHandler
}{wxevthandler
}
7 % ---------------------------------------------------------------------------
9 % ---------------------------------------------------------------------------
10 \wxheading{Event handling
}
12 To process events from a socket, use the following event handler macro to direct
14 functions that take a
\helpref{wxSocketEvent
}{wxsocketevent
} argument.
17 \begin{twocollist
}\itemsep=
0pt
18 \twocolitem{{\bf EVT
\_SOCKET(id, func)
}}{A socket event occured.
}
21 % ---------------------------------------------------------------------------
23 % ---------------------------------------------------------------------------
26 \helpref{wxSocketEvent
}{wxsocketevent
},
\helpref{wxSocketClient
}{wxsocketclient
},
\helpref{wxSocketServer
}{wxsocketserver
}
28 % ---------------------------------------------------------------------------
30 % ---------------------------------------------------------------------------
31 \latexignore{\rtfignore{\wxheading{Members
}}}
33 \membersection{wxSocketBase::wxSocketBase
}
35 \func{}{wxSocketBase
}{\void}
37 Default constructor but don't use it, you must use
\helpref{wxSocketClient
}{wxsocketclient
}
38 or
\helpref{wxSocketServer
}{wxsocketserver
}.
40 \membersection{wxSocketBase::
\destruct{wxSocketBase
}}
42 \func{}{\destruct{wxSocketBase
}}{\void}
44 Destroys the wxSocketBase object.
46 % ---------------------------------------------------------------------------
48 % ---------------------------------------------------------------------------
50 \membersection{wxSocketBase::Ok
}\label{wxsocketbaseok
}
52 \constfunc{bool
}{Ok
}{\void}
54 Returns TRUE if the socket is initialized and ready and FALSE in other
57 \membersection{wxSocketBase::Error
}\label{wxsocketbaseerror
}
59 \constfunc{bool
}{Error
}{\void}
61 Returns TRUE if an error occured.
63 \membersection{wxSocketBase::IsConnected
}\label{wxsocketbaseconnected
}
65 \constfunc{bool
}{IsConnected
}{\void}
67 Returns TRUE if the socket is connected.
69 \membersection{wxSocketBase::IsData
}\label{wxsocketbaseisdata
}
71 \constfunc{bool
}{IsData
}{\void}
73 Returns TRUE if some data is arrived on the socket.
75 \membersection{wxSocketBase::IsDisconnected
}\label{wxsocketbasedisconnected
}
77 \constfunc{bool
}{IsDisconnected
}{\void}
79 Returns TRUE if the socket is disconnected.
81 \membersection{wxSocketBase::IsNoWait
}\label{wxsocketbasenowait
}
83 \constfunc{bool
}{IsNoWait
}{\void}
85 Returns TRUE if the socket mustn't wait.
87 \membersection{wxSocketBase::LastCount
}\label{wxsocketbaselastcount
}
89 \constfunc{size
\_t}{LastCount
}{\void}
91 Returns the number of bytes read or written by the last IO call.
93 \membersection{wxSocketBase::LastError
}\label{wxsocketbaselasterror
}
95 \constfunc{int
}{LastError
}{\void}
97 Returns an error in the errno format (see your C programmer's guide).
99 % ---------------------------------------------------------------------------
101 % ---------------------------------------------------------------------------
105 \membersection{wxSocketBase::Peek
}\label{wxsocketbasepeek
}
107 \func{wxSocketBase\&
}{Peek
}{\param{char *
}{ buffer
},
\param{size
\_t}{ nbytes
}}
109 This function peeks a buffer of
{\it nbytes
} bytes from the socket. Peeking a buffer
110 doesn't delete it from the system socket in-queue.
112 \wxheading{Parameters
}
114 \docparam{buffer
}{Buffer where to put peeked data.
}
116 \docparam{nbytes
}{Number of bytes.
}
118 \wxheading{Return value
}
120 Returns a reference to the current object.
124 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
125 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
126 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
}
131 \membersection{wxSocketBase::Read
}\label{wxsocketbaseread
}
133 \func{wxSocketBase\&
}{Read
}{\param{char *
}{ buffer
},
\param{size
\_t}{ nbytes
}}
135 This function reads a buffer of
{\it nbytes
} bytes from the socket.
137 \wxheading{Parameters
}
139 \docparam{buffer
}{Buffer where to put read data.
}
141 \docparam{nbytes
}{Number of bytes.
}
143 \wxheading{Return value
}
145 Returns a reference to the current object.
149 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
150 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
151 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
}
153 \membersection{wxSocketBase::SetFlags
}\label{wxsocketbasesetflags
}
155 \func{void
}{SetFlags
}{\param{wxSockFlags
}{ flags
}}
158 \begin{twocollist
}\itemsep=
0pt
159 \twocolitem{{\bf wxSocketBase::NONE
}}{Normal functionnalities.
}
160 \twocolitem{{\bf wxSocketBase::NOWAIT
}}{Get the available data in the input queue and exit immediately.
}
161 \twocolitem{{\bf wxSocketBase::WAITALL
}}{Wait for all required data unless an error occured.
}
162 \twocolitem{{\bf wxSocketBase::SPEED
}}{Disable the asynchronous IO functionnality.
}
168 \membersection{wxSocketBase::Write
}\label{wxsocketbasewrite
}
170 \func{wxSocketBase\&
}{Write
}{\param{const char *
}{ buffer
},
\param{size
\_t}{ nbytes
}}
172 This function writes a buffer of
{\it nbytes
} bytes from the socket.
174 \wxheading{Parameters
}
176 \docparam{buffer
}{Buffer where to get the data to write.
}
178 \docparam{nbytes
}{Number of bytes.
}
180 \wxheading{Return value
}
182 Returns a reference to the current object.
186 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
187 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
188 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
}
193 \membersection{wxSocketBase::WriteMsg
}\label{wxsocketbasewritemsg
}
195 \func{wxSocketBase\&
}{WriteMsg
}{\param{const char *
}{ buffer
},
\param{size
\_t}{ nbytes
}}
197 This function writes a buffer of
{\it nbytes
} bytes from the socket. But it
198 writes a short header before so that ReadMsg can alloc the right size for
199 the buffer. So a buffer sent with WriteMsg
{\bf must
} be read with ReadMsg.
201 \wxheading{Parameters
}
203 \docparam{buffer
}{Buffer where to put data peeked.
}
205 \docparam{nbytes
}{Number of bytes.
}
207 \wxheading{Return value
}
209 Returns a reference to the current object.
213 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
214 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
215 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
},
216 \helpref{wxSocketBase::ReadMsg
}{wxsocketbasereadmsg
}
221 \membersection{wxSocketBase::ReadMsg
}\label{wxsocketbasereadmsg
}
223 \func{wxSocketBase\&
}{ReadMsg
}{\param{char *
}{ buffer
},
\param{size
\_t}{ nbytes
}}
225 This function reads a buffer sent by WriteMsg on a socket. If the buffer passed
226 to the function isn't big enough, the function filled it and then discard the
227 bytes left. This function always wait for the buffer to be entirely filled.
229 \wxheading{Parameters
}
231 \docparam{buffer
}{Buffer where to put read data.
}
233 \docparam{nbytes
}{Number of bytes allocated for the buffer.
}
235 \wxheading{Return value
}
237 Returns a reference to the current object.
241 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
242 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
243 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
},
244 \helpref{wxSocketBase::WriteMsg
}{wxsocketbasewritemsg
}
249 \membersection{wxSocketBase::UnRead
}\label{wxsocketbaseunread
}
251 \func{wxSocketBase\&
}{UnRead
}{\param{const char *
}{ buffer
},
\param{size
\_t}{ nbytes
}}
253 This function unreads a buffer. It means that the buffer is put in the top
254 of the incoming queue. But, it is put also at the end of all unread buffers.
255 It is useful for sockets because we can't seek it.
257 \wxheading{Parameters
}
259 \docparam{buffer
}{Buffer to be unread.
}
261 \docparam{nbytes
}{Number of bytes.
}
263 \wxheading{Return value
}
265 Returns a reference to the current object.
269 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
270 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
271 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
}
276 \membersection{wxSocketBase::Discard
}\label{wxsocketbasediscard
}
278 \func{wxSocketBase\&
}{Discard
}{\void}
280 This function simply deletes all bytes in the incoming queue. This function
283 % ---------------------------------------------------------------------------
285 % ---------------------------------------------------------------------------
286 \membersection{wxSocketBase::Wait
}\label{wxsocketbasewait
}
288 \func{bool
}{Wait
}{\param{long
}{ seconds = -
1},
\param{long
}{ microsecond =
0}}
290 This function waits for an event: it could be an incoming byte, the possibility
291 for the client to write, a lost connection, an incoming connection, an
292 established connection.
294 \wxheading{Parameters
}
296 \docparam{seconds
}{Number of seconds to wait. By default, it waits infinitely.
}
298 \docparam{microsecond
}{Number of microseconds to wait.
}
300 \wxheading{Return value
}
302 Returns TRUE if an event occured, FALSE if the timeout was reached.
306 \helpref{wxSocketBase::WaitForRead
}{wxsocketbasewaitforread
},
307 \helpref{wxSocketBase::WaitForWrite
}{wxsocketbasewaitforwrite
},
308 \helpref{wxSocketBase::WaitForLost
}{wxsocketbasewaitforlost
}
313 \membersection{wxSocketBase::WaitForRead
}\label{wxsocketbasewaitforread
}
315 \func{bool
}{WaitForRead
}{\param{long
}{ seconds = -
1},
\param{long
}{ microsecond =
0}}
317 This function waits for a read event.
319 \wxheading{Parameters
}
321 \docparam{seconds
}{Number of seconds to wait. By default, it waits infinitely.
}
323 \docparam{microsecond
}{Number of microseconds to wait.
}
325 \wxheading{Return value
}
327 Returns TRUE if a byte arrived, FALSE if the timeout was reached.
331 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
},
332 \helpref{wxSocketBase::WaitForWrite
}{wxsocketbasewaitforwrite
},
333 \helpref{wxSocketBase::WaitForLost
}{wxsocketbasewaitforlost
}
338 \membersection{wxSocketBase::WaitForWrite
}\label{wxsocketbasewaitforwrite
}
340 \func{bool
}{WaitForWrite
}{\param{long
}{ seconds = -
1},
\param{long
}{ microsecond =
0}}
342 This function waits for a write event.
344 \wxheading{Parameters
}
346 \docparam{seconds
}{Number of seconds to wait. By default, it waits infinitely.
}
348 \docparam{microsecond
}{Number of microseconds to wait.
}
350 \wxheading{Return value
}
352 Returns TRUE if a write event occured, FALSE if the timeout was reached.
356 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
},
357 \helpref{wxSocketBase::WaitForRead
}{wxsocketbasewaitforread
},
358 \helpref{wxSocketBase::WaitForLost
}{wxsocketbasewaitforlost
}
363 \membersection{wxSocketBase::WaitForLost
}\label{wxsocketbasewaitforlost
}
365 \func{bool
}{Wait
}{\param{long
}{ seconds = -
1},
\param{long
}{ microsecond =
0}}
367 This function waits for a "lost" event. For instance, the peer may have closed
368 the connection, or the connection may have been broken.
370 \wxheading{Parameters
}
372 \docparam{seconds
}{Number of seconds to wait. By default, it waits infinitely.
}
374 \docparam{microsecond
}{Number of microseconds to wait.
}
376 \wxheading{Return value
}
378 Returns TRUE if a "lost" event occured, FALSE if the timeout was reached.
382 \helpref{wxSocketBase::WaitForRead
}{wxsocketbasewaitforread
},
383 \helpref{wxSocketBase::WaitForWrite
}{wxsocketbasewaitforwrite
},
384 \helpref{wxSocketBase::WaitForLost
}{wxsocketbasewaitforlost
}
389 \membersection{wxSocketBase::RestoreState
}\label{wxsocketbaserestorestate
}
391 \func{void
}{RestoreState
}{\void}
393 This function restores a previously saved state.
397 \helpref{wxSocketBase::SaveState
}{wxsocketbasesavestate
}
399 % ---------------------------------------------------------------------------
401 % ---------------------------------------------------------------------------
405 \membersection{wxSocketBase::SaveState
}\label{wxsocketbasesavestate
}
407 \func{void
}{SaveState
}{\void}
409 This function saves the current state of the socket object in a stack:
410 actually it saves all flags and the state of the asynchronous callbacks.
414 \helpref{wxSocketBase::RestoreState
}{wxsocketbaserestorestate
}
416 % ---------------------------------------------------------------------------
418 % ---------------------------------------------------------------------------
419 \membersection{wxSocketBase::SetEventHandler
}\label{wxsocketbaseseteventhandler
}
421 \func{void
}{SetEventHandler
}{\param{wxEvtHandler\&
}{ evt
\_hdlr},
\param{int
}{ id = -
1}}
423 Sets an event handler to be called when a socket event occured.
425 \wxheading{Parameters
}
427 \docparam{evt
\_hdlr}{Specifies the event handler you want to use.
}
429 \docparam{id
}{The id of socket event.
}
433 \helpref{wxSocketEvent
}{wxsocketevent
}
435 % ---------------------------------------------------------------------------
436 % CLASS wxSocketClient
437 % ---------------------------------------------------------------------------
438 \section{\class{wxSocketClient
}}\label{wxsocketclient
}
440 \wxheading{Derived from
}
442 \helpref{wxSocketBase
}{wxsocketbase
}
444 % ---------------------------------------------------------------------------
446 % ---------------------------------------------------------------------------
450 \membersection{wxSocketClient::wxSocketClient
}
452 \func{}{wxSocketClient
}{\param{wxSockFlags
}{ flags = wxSocketBase::NONE
}}
454 Constructs a new wxSocketClient.
456 {\bf Warning !
} The created socket client needs to be registered to a socket handler (See
\helpref{wxSocketHandler
}{wxsockethandler
}).
458 \wxheading{Parameters
}
460 \docparam{flags
}{Socket flags (See
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
})
}
465 \membersection{wxSocketClient::
\destruct{wxSocketClient
}}
467 \func{}{\destruct{wxSocketClient
}}{\void}
469 Destructs a wxSocketClient object.
474 \membersection{wxSocketClient::Connect
}\label{wxsocketclientconnect
}
476 \func{bool
}{Connect
}{\param{wxSockAddress\&
}{ address
},
\param{bool
}{ wait = TRUE
}}
478 Connects to a server using the specified address. If
{\it wait
} is TRUE, Connect
479 will wait for the socket ready to send or receive data.
481 \wxheading{Parameters
}
483 \docparam{address
}{Address of the server.
}
485 \docparam{wait
}{If true, waits for the connection to be ready.
}
487 \wxheading{Return value
}
489 Returns TRUE if the connection is established and no error occurs.
493 \helpref{wxSocketClient::WaitOnConnect
}{wxsocketclientwaitonconnect
}
498 \membersection{wxSocketClient::WaitOnConnect
}\label{wxsocketclientwaitonconnect
}
500 \func{bool
}{WaitOnConnect
}{\param{long
}{ seconds = -
1},
\param{long
}{ microseconds =
0}}
502 Wait for a "connect" event.
506 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
} for a detailed description.
508 % ---------------------------------------------------------------------------
509 % CLASS: wxSocketEvent
510 % ---------------------------------------------------------------------------
511 \section{\class{wxSocketEvent
}}\label{wxsocketevent
}
513 This event class contains information about socket events.
515 \wxheading{Derived from
}
517 \helpref{wxEvent
}{wxevent
}
519 \wxheading{Event table macros
}
521 To process a socket event, use these event handler macros to direct input to member
522 functions that take a wxSocketEvent argument.
525 \begin{twocollist
}\itemsep=
0pt
526 \twocolitem{{\bf EVT
\_SOCKET(id, func)
}}{Process a socket event, supplying the member function.
}
531 \helpref{wxSocketHandler
}{wxsockethandler
},
\rtfsp
532 \helpref{wxSocketBase
}{wxsocketbase
},
\rtfsp
533 \helpref{wxSocketClient
}{wxsocketclient
},
\rtfsp
534 \helpref{wxSocketServer
}{wxsocketserver
}
536 \latexignore{\rtfignore{\wxheading{Members
}}}
538 \membersection{wxSocketEvent::wxSocketEvent
}
540 \func{}{wxSocketEvent
}{\param{int
}{ id =
0}}
544 \membersection{wxSocketEvent::SocketEvent
}\label{wxsocketeventsocketevent
}
546 \constfunc{wxSocketBase::wxRequestEvent
}{SocketEvent
}{\void}
548 Returns the socket event type.
550 % ---------------------------------------------------------------------------
551 % CLASS: wxSocketHandler
552 % ---------------------------------------------------------------------------
553 \section{\class{wxSocketHandler
}}\label{wxsockethandler
}
555 \wxheading{Derived from
}
557 \helpref{wxObject
}{wxobject
}
559 % ---------------------------------------------------------------------------
561 % ---------------------------------------------------------------------------
562 \latexignore{\rtfignore{\wxheading{Members
}}}
567 \membersection{wxSocketHandler::wxSocketHandler
}
569 \func{}{wxSocketHandler
}{\void}
571 Constructs a new wxSocketHandler.
573 It is advised to use
\helpref{wxSocketHandler::Master
}{wxsockethandlermaster
} to
574 get a socket handler. But creating a socket handler is useful to group
580 \membersection{wxSocketHandler::
\destruct{wxSocketHandler
}}
582 \func{}{\destruct{wxSocketHandler
}}{\void}
584 Destructs a wxSocketHandler object.
589 \membersection{wxSocketHandler::Register
}
591 \func{void
}{Register
}{\param{wxSocketBase *
}{socket
}}
593 Register a socket: if it is already registered in this handler it will just
596 \wxheading{Parameters
}
598 \docparam{socket
}{Socket to be registered.
}
603 \membersection{wxSocketHandler::UnRegister
}
605 \func{void
}{UnRegister
}{\param{wxSocketBase *
}{socket
}}
607 UnRegister a socket: if it isn't registered in this handler it will just
610 \wxheading{Parameters
}
612 \docparam{socket
}{Socket to be unregistered.
}
617 \membersection{wxSocketHandler::Count
}
619 \constfunc{unsigned long
}{Count
}{\void}
621 Returns the number of sockets registered in the handler.
623 \wxheading{Return value
}
625 Number of sockets registered.
630 \membersection{wxSocketHandler::CreateServer
}
632 \func{wxSocketServer *
}{CreateServer
}{\param{wxSockAddress\&
}{ address
},
\param{wxSocketBase::wxSockFlags
}{ flags = wxSocketbase::NONE
}}
634 Creates a new wxSocketServer object. The object is automatically registered
635 to the current socket handler.
636 For a detailed description of the parameters, see
\helpref{wxSocketServer::wxSocketServer
}{wxsocketserverconstr
}.
638 \wxheading{Return value
}
640 Returns a new socket server.
645 \membersection{wxSocketHandler::CreateClient
}
647 \func{wxSocketServer *
}{CreateClient
}{\param{wxSocketBase::wxSockFlags
}{ flags = wxSocketbase::NONE
}}
649 Creates a new wxSocketClient object. The object is automatically registered
650 to the current socket handler.
652 For a detailed description of the parameters, see
\helpref{wxSocketClient::Connect
}{wxsocketclientconnect
}.
654 \wxheading{Return value
}
656 Returns a new socket client.
661 \membersection{wxSocketHandler::Master
}\label{wxsockethandlermaster
}
663 \func{static wxSocketHandler\&
}{Master
}{\void}
665 Returns a default socket handler.
670 \membersection{wxSocketHandler::Wait
}
672 \func{int
}{Wait
}{\param{long
}{ seconds
},
\param{long
}{ microseconds
}}
674 Wait for an event on all registered sockets.
676 \wxheading{Parameters
}
678 \docparam{seconds
}{Number of seconds to wait. By default, it waits infinitely.
}
680 \docparam{microsecond
}{Number of microseconds to wait.
}
682 \wxheading{Return value
}
684 Returns
0 if a timeout occured, else the number of events detected.
688 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
}
693 \membersection{wxSocketHandler::YieldSock
}
695 \func{void
}{YieldSock
}{\void}
697 Execute pending requests in all registered sockets.
699 % ---------------------------------------------------------------------------
700 % CLASS: wxSocketServer
701 % ---------------------------------------------------------------------------
702 \section{\class{wxSocketServer
}}\label{wxsocketserver
}
704 \wxheading{Derived from
}
706 \helpref{wxSocketBase
}{wxsocketbase
}
708 % ---------------------------------------------------------------------------
710 % ---------------------------------------------------------------------------
711 \latexignore{\rtfignore{\wxheading{Members
}}}
716 \membersection{wxSocketServer::wxSocketServer
}\label{wxsocketserverconstr
}
718 \func{}{wxSocketServer
}{\param{wxSockAddress\&
}{ address
},
\param{wxSockFlags
}{ flags = wxSocketBase::NONE
}}
720 Constructs a new wxSocketServer.
722 {\bf Warning !
} The created object needs to be registered to a socket handler
723 (see
\helpref{wxSocketHandler
}{wxsockethandler
}).
725 \wxheading{Parameters
}
727 \docparam{address
}{Specifies the local address for the server (e.g. port number).
}
729 \docparam{flags
}{Socket flags (See
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
})
}
734 \membersection{wxSocketServer::
\destruct{wxSocketServer
}}
736 \func{}{\destruct{wxSocketServer
}}{\void}
738 Destructs a wxSocketServer object (it doesn't close the accepted connection).
743 \membersection{wxSocketServer::Accept
}
745 \func{wxSocketBase *
}{Accept
}{\void}
747 Creates a new object wxSocketBase and accepts an incoming connection.
{\bf Warning !
} This function will block the GUI.
749 \wxheading{Return value
}
751 Returns an opened socket connection.
755 \helpref{wxSocketServer::AcceptWith
}{wxsocketserveracceptwith
}
760 \membersection{wxSocketServer::AcceptWith
}\label{wxsocketserveracceptwith
}
762 \func{bool
}{AcceptWith
}{\param{wxSocketBase\&
}{ socket
}}
764 Accept an incoming connection using the specified socket object.
765 This is useful when someone wants to inherit wxSocketBase.
767 \wxheading{Parameters
}
769 \docparam{socket
}{Socket to be initialized
}
771 \wxheading{Return value
}
773 Returns TRUE if no error occurs, else FALSE.