1 \section{\class{wxSocketBase
}}\label{wxsocketbase
}
3 \wxheading{Derived from
}
5 \helpref{wxEvtHandler
}{wxevthandler
}
7 \wxheading{Include files
}
15 % ---------------------------------------------------------------------------
17 % ---------------------------------------------------------------------------
18 \wxheading{Event handling
}
20 To process events from a socket, use the following event handler macro to direct
22 functions that take a
\helpref{wxSocketEvent
}{wxsocketevent
} argument.
25 \begin{twocollist
}\itemsep=
0pt
26 \twocolitem{{\bf EVT
\_SOCKET(id, func)
}}{A socket event occured.
}
29 % ---------------------------------------------------------------------------
31 % ---------------------------------------------------------------------------
34 \helpref{wxSocketEvent
}{wxsocketevent
}\\
35 \helpref{wxSocketClient
}{wxsocketclient
}\\
36 \helpref{wxSocketServer
}{wxsocketserver
}
38 % ---------------------------------------------------------------------------
40 % ---------------------------------------------------------------------------
41 \latexignore{\rtfignore{\wxheading{Members
}}}
43 \membersection{wxSocketBase::wxSocketBase
}
45 \func{}{wxSocketBase
}{\void}
47 Default constructor but don't use it, you must use
\helpref{wxSocketClient
}{wxsocketclient
}
48 or
\helpref{wxSocketServer
}{wxsocketserver
}.
50 \membersection{wxSocketBase::
\destruct{wxSocketBase
}}
52 \func{}{\destruct{wxSocketBase
}}{\void}
54 Destroys the wxSocketBase object.
56 % ---------------------------------------------------------------------------
58 % ---------------------------------------------------------------------------
64 \membersection{wxSocketBase::SetFlags
}\label{wxsocketbasesetflags
}
66 \func{void
}{SetFlags
}{\param{wxSocketBase::wxSockFlags
}{ flags
}}
69 \begin{twocollist
}\itemsep=
0pt
70 \twocolitem{{\bf wxSocketBase::NONE
}}{Normal functionnalities.
}
71 \twocolitem{{\bf wxSocketBase::NOWAIT
}}{Get the available data in the input queue and exit immediately.
}
72 \twocolitem{{\bf wxSocketBase::WAITALL
}}{Wait for all required data unless an error occured.
}
73 \twocolitem{{\bf wxSocketBase::SPEED
}}{Disable the asynchronous IO functionnality.
}
79 \membersection{wxSocketBase::SetNotify
}\label{wxsocketbasesetnotify
}
81 \func{void
}{SetNotify
}{\param{GSocketEventFlags
}{ event_flags
}}
83 SetNotify setups which socket events are to be sent to the event handler.
84 For more information on socket events see GSocket events.
89 \membersection{wxSocketBase::Notify
}\label{wxsocketbasenotify
}
91 \func{void
}{Notify
}{\param{bool
}{ notify
}}
93 Notify will enable (notify is TRUE) or disable (notify is FALSE) the propagation
100 \membersection{wxSocketBase::Ok
}\label{wxsocketbaseok
}
102 \constfunc{bool
}{Ok
}{\void}
104 Returns TRUE if the socket is initialized and ready and FALSE in other
107 \membersection{wxSocketBase::Error
}\label{wxsocketbaseerror
}
109 \constfunc{bool
}{Error
}{\void}
111 Returns TRUE if an error occured.
113 \membersection{wxSocketBase::IsConnected
}\label{wxsocketbaseconnected
}
115 \constfunc{bool
}{IsConnected
}{\void}
117 Returns TRUE if the socket is connected.
119 \membersection{wxSocketBase::IsData
}\label{wxsocketbaseisdata
}
121 \constfunc{bool
}{IsData
}{\void}
123 Returns TRUE if some data is arrived on the socket.
125 \membersection{wxSocketBase::IsDisconnected
}\label{wxsocketbasedisconnected
}
127 \constfunc{bool
}{IsDisconnected
}{\void}
129 Returns TRUE if the socket is disconnected.
131 \membersection{wxSocketBase::IsNoWait
}\label{wxsocketbasenowait
}
133 \constfunc{bool
}{IsNoWait
}{\void}
135 Returns TRUE if the socket mustn't wait.
137 \membersection{wxSocketBase::LastCount
}\label{wxsocketbaselastcount
}
139 \constfunc{size
\_t}{LastCount
}{\void}
141 Returns the number of bytes read or written by the last IO call.
143 \membersection{wxSocketBase::LastError
}\label{wxsocketbaselasterror
}
145 \constfunc{GSocketError
}{LastError
}{\void}
147 Returns an error in the GSocket format. See GSocket errors.
149 % ---------------------------------------------------------------------------
151 % ---------------------------------------------------------------------------
155 \membersection{wxSocketBase::Peek
}\label{wxsocketbasepeek
}
157 \func{wxSocketBase\&
}{Peek
}{\param{char *
}{ buffer
},
\param{size
\_t}{ nbytes
}}
159 This function peeks a buffer of
{\it nbytes
} bytes from the socket. Peeking a buffer
160 doesn't delete it from the system socket in-queue.
162 \wxheading{Parameters
}
164 \docparam{buffer
}{Buffer where to put peeked data.
}
166 \docparam{nbytes
}{Number of bytes.
}
168 \wxheading{Return value
}
170 Returns a reference to the current object.
174 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
}\\
175 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
}\\
176 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
}
181 \membersection{wxSocketBase::Read
}\label{wxsocketbaseread
}
183 \func{wxSocketBase\&
}{Read
}{\param{char *
}{ buffer
},
\param{size
\_t}{ nbytes
}}
185 This function reads a buffer of
{\it nbytes
} bytes from the socket.
187 \wxheading{Parameters
}
189 \docparam{buffer
}{Buffer where to put read data.
}
191 \docparam{nbytes
}{Number of bytes.
}
193 \wxheading{Return value
}
195 Returns a reference to the current object.
197 \wxheading{Remark/Warning
}
199 By default, Read uses an internal asynchronous manager: it will send data when
200 the socket requests them. It is particularly interesting when you enter a long
201 data transfer (e.g. a big file, an image, ...). But it is also buggy when you
202 simply discuss with the peer using user data. In this case, wxSocket prepares
203 itself to send data (Write wait for them to be sent) and during a GUI refresh
204 the user enters new data, which involves a new Read call though the previous
205 isn't finished. Well, in most cases it can work but it might fail too.
206 So I advise you to use the SPEED flag, which disables the asynchronous manager,
207 when you just want to discuss with the peer.
209 This remark is also valid for all IO call.
213 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
},
214 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
},
215 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
}
220 \membersection{wxSocketBase::Write
}\label{wxsocketbasewrite
}
222 \func{wxSocketBase\&
}{Write
}{\param{const char *
}{ buffer
},
\param{size
\_t}{ nbytes
}}
224 This function writes a buffer of
{\it nbytes
} bytes from the socket.
226 \wxheading{Remark/Warning
}
228 By default, Write uses an internal asynchronous manager: it will send data when
229 the socket requests them. It is particularly interesting when you enter a long
230 data transfer (e.g. a big file, an image, ...). But it is also buggy when you
231 simply discuss with the peer using user data. In this case, wxSocket prepares
232 itself to send data (Write wait for them to be sent) and during a GUI refresh
233 the user enters new data, which involves a new Write call though the previous
234 isn't finished. Well, in most cases it can work but it might fail too.
235 So I advise you to use the SPEED flag, which disables the asynchronous manager,
236 when you just want to discuss with the peer.
238 \wxheading{Parameters
}
240 \docparam{buffer
}{Buffer where to get the data to write.
}
242 \docparam{nbytes
}{Number of bytes.
}
244 \wxheading{Return value
}
246 Returns a reference to the current object.
250 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
}\\
251 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
}\\
252 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
}
257 \membersection{wxSocketBase::WriteMsg
}\label{wxsocketbasewritemsg
}
259 \func{wxSocketBase\&
}{WriteMsg
}{\param{const char *
}{ buffer
},
\param{size
\_t}{ nbytes
}}
261 This function writes a buffer of
{\it nbytes
} bytes from the socket. But it
262 writes a short header before so that ReadMsg can alloc the right size for
263 the buffer. So a buffer sent with WriteMsg
{\bf must
} be read with ReadMsg.
265 \wxheading{Parameters
}
267 \docparam{buffer
}{Buffer where to put data peeked.
}
269 \docparam{nbytes
}{Number of bytes.
}
271 \wxheading{Return value
}
273 Returns a reference to the current object.
277 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
}\\
278 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
}\\
279 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
}\\
280 \helpref{wxSocketBase::ReadMsg
}{wxsocketbasereadmsg
}
285 \membersection{wxSocketBase::ReadMsg
}\label{wxsocketbasereadmsg
}
287 \func{wxSocketBase\&
}{ReadMsg
}{\param{char *
}{ buffer
},
\param{size
\_t}{ nbytes
}}
289 This function reads a buffer sent by WriteMsg on a socket. If the buffer passed
290 to the function isn't big enough, the function filled it and then discard the
291 bytes left. This function always wait for the buffer to be entirely filled.
293 \wxheading{Parameters
}
295 \docparam{buffer
}{Buffer where to put read data.
}
297 \docparam{nbytes
}{Number of bytes allocated for the buffer.
}
299 \wxheading{Return value
}
301 Returns a reference to the current object.
305 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
}\\
306 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
}\\
307 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
}\\
308 \helpref{wxSocketBase::WriteMsg
}{wxsocketbasewritemsg
}
313 \membersection{wxSocketBase::Unread
}\label{wxsocketbaseunread
}
315 \func{wxSocketBase\&
}{Unread
}{\param{const char *
}{ buffer
},
\param{size
\_t}{ nbytes
}}
317 This function unreads a buffer. It means that the buffer is put in the top
318 of the incoming queue. But, it is put also at the end of all unread buffers.
319 It is useful for sockets because we can't seek it.
321 \wxheading{Parameters
}
323 \docparam{buffer
}{Buffer to be unread.
}
325 \docparam{nbytes
}{Number of bytes.
}
327 \wxheading{Return value
}
329 Returns a reference to the current object.
333 \helpref{wxSocketBase::Error
}{wxsocketbaseerror
}\\
334 \helpref{wxSocketBase::LastCount
}{wxsocketbaselastcount
}\\
335 \helpref{wxSocketBase::LastError
}{wxsocketbaselasterror
}
340 \membersection{wxSocketBase::Discard
}\label{wxsocketbasediscard
}
342 \func{wxSocketBase\&
}{Discard
}{\void}
344 This function simply deletes all bytes in the incoming queue. This function
347 % ---------------------------------------------------------------------------
349 % ---------------------------------------------------------------------------
350 \membersection{wxSocketBase::Wait
}\label{wxsocketbasewait
}
352 \func{bool
}{Wait
}{\param{long
}{ seconds = -
1},
\param{long
}{ microsecond =
0}}
354 This function waits for an event: it could be an incoming byte, the possibility
355 for the client to write, a lost connection, an incoming connection, an
356 established connection.
358 \wxheading{Parameters
}
360 \docparam{seconds
}{Number of seconds to wait. By default, it waits infinitely.
}
362 \docparam{microsecond
}{Number of microseconds to wait.
}
364 \wxheading{Return value
}
366 Returns TRUE if an event occured, FALSE if the timeout was reached.
370 \helpref{wxSocketBase::WaitForRead
}{wxsocketbasewaitforread
}\\
371 \helpref{wxSocketBase::WaitForWrite
}{wxsocketbasewaitforwrite
}\\
372 \helpref{wxSocketBase::WaitForLost
}{wxsocketbasewaitforlost
}
377 \membersection{wxSocketBase::WaitForRead
}\label{wxsocketbasewaitforread
}
379 \func{bool
}{WaitForRead
}{\param{long
}{ seconds = -
1},
\param{long
}{ microsecond =
0}}
381 This function waits for a read event.
383 \wxheading{Parameters
}
385 \docparam{seconds
}{Number of seconds to wait. By default, it waits infinitely.
}
387 \docparam{microsecond
}{Number of microseconds to wait.
}
389 \wxheading{Return value
}
391 Returns TRUE if a byte arrived, FALSE if the timeout was reached.
395 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
}\\
396 \helpref{wxSocketBase::WaitForWrite
}{wxsocketbasewaitforwrite
}\\
397 \helpref{wxSocketBase::WaitForLost
}{wxsocketbasewaitforlost
}
402 \membersection{wxSocketBase::WaitForWrite
}\label{wxsocketbasewaitforwrite
}
404 \func{bool
}{WaitForWrite
}{\param{long
}{ seconds = -
1},
\param{long
}{ microsecond =
0}}
406 This function waits for a write event.
408 \wxheading{Parameters
}
410 \docparam{seconds
}{Number of seconds to wait. By default, it waits infinitely.
}
412 \docparam{microsecond
}{Number of microseconds to wait.
}
414 \wxheading{Return value
}
416 Returns TRUE if a write event occured, FALSE if the timeout was reached.
420 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
}\\
421 \helpref{wxSocketBase::WaitForRead
}{wxsocketbasewaitforread
}\\
422 \helpref{wxSocketBase::WaitForLost
}{wxsocketbasewaitforlost
}
427 \membersection{wxSocketBase::WaitForLost
}\label{wxsocketbasewaitforlost
}
429 \func{bool
}{Wait
}{\param{long
}{ seconds = -
1},
\param{long
}{ microsecond =
0}}
431 This function waits for a "lost" event. For instance, the peer may have closed
432 the connection, or the connection may have been broken.
434 \wxheading{Parameters
}
436 \docparam{seconds
}{Number of seconds to wait. By default, it waits infinitely.
}
438 \docparam{microsecond
}{Number of microseconds to wait.
}
440 \wxheading{Return value
}
442 Returns TRUE if a "lost" event occured, FALSE if the timeout was reached.
446 \helpref{wxSocketBase::WaitForRead
}{wxsocketbasewaitforread
}\\
447 \helpref{wxSocketBase::WaitForWrite
}{wxsocketbasewaitforwrite
}\\
448 \helpref{wxSocketBase::WaitForLost
}{wxsocketbasewaitforlost
}
453 \membersection{wxSocketBase::RestoreState
}\label{wxsocketbaserestorestate
}
455 \func{void
}{RestoreState
}{\void}
457 This function restores a previously saved state.
461 \helpref{wxSocketBase::SaveState
}{wxsocketbasesavestate
}
463 % ---------------------------------------------------------------------------
465 % ---------------------------------------------------------------------------
469 \membersection{wxSocketBase::SaveState
}\label{wxsocketbasesavestate
}
471 \func{void
}{SaveState
}{\void}
473 This function saves the current state of the socket object in a stack:
474 actually it saves all flags and the state of the asynchronous callbacks.
478 \helpref{wxSocketBase::RestoreState
}{wxsocketbaserestorestate
}
480 % ---------------------------------------------------------------------------
482 % ---------------------------------------------------------------------------
483 \membersection{wxSocketBase::SetEventHandler
}\label{wxsocketbaseseteventhandler
}
485 \func{void
}{SetEventHandler
}{\param{wxEvtHandler\&
}{ evt
\_hdlr},
\param{int
}{ id = -
1}}
487 Sets an event handler to be called when a socket event occured.
489 \wxheading{Parameters
}
491 \docparam{evt
\_hdlr}{Specifies the event handler you want to use.
}
493 \docparam{id
}{The id of socket event.
}
497 \helpref{wxSocketEvent
}{wxsocketevent
}
499 % ---------------------------------------------------------------------------
500 % CLASS wxSocketClient
501 % ---------------------------------------------------------------------------
502 \section{\class{wxSocketClient
}}\label{wxsocketclient
}
504 \wxheading{Derived from
}
506 \helpref{wxSocketBase
}{wxsocketbase
}
508 \wxheading{Include files
}
512 % ---------------------------------------------------------------------------
514 % ---------------------------------------------------------------------------
518 \membersection{wxSocketClient::wxSocketClient
}
520 \func{}{wxSocketClient
}{\param{wxSockFlags
}{ flags = wxSocketBase::NONE
}}
522 Constructs a new wxSocketClient.
524 \wxheading{Parameters
}
526 \docparam{flags
}{Socket flags (See
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
})
}
531 \membersection{wxSocketClient::
\destruct{wxSocketClient
}}
533 \func{}{\destruct{wxSocketClient
}}{\void}
535 Destroys a wxSocketClient object.
540 \membersection{wxSocketClient::Connect
}\label{wxsocketclientconnect
}
542 \func{bool
}{Connect
}{\param{wxSockAddress\&
}{ address
},
\param{bool
}{ wait = TRUE
}}
544 Connects to a server using the specified address. If
{\it wait
} is TRUE, Connect
545 will wait for the socket ready to send or receive data.
547 \wxheading{Parameters
}
549 \docparam{address
}{Address of the server.
}
551 \docparam{wait
}{If true, waits for the connection to be ready.
}
553 \wxheading{Return value
}
555 Returns TRUE if the connection is established and no error occurs.
559 \helpref{wxSocketClient::WaitOnConnect
}{wxsocketclientwaitonconnect
}
564 \membersection{wxSocketClient::WaitOnConnect
}\label{wxsocketclientwaitonconnect
}
566 \func{bool
}{WaitOnConnect
}{\param{long
}{ seconds = -
1},
\param{long
}{ microseconds =
0}}
568 Wait for a "connect" event.
572 \helpref{wxSocketBase::Wait
}{wxsocketbasewait
} for a detailed description.
574 % ---------------------------------------------------------------------------
575 % CLASS: wxSocketEvent
576 % ---------------------------------------------------------------------------
577 \section{\class{wxSocketEvent
}}\label{wxsocketevent
}
579 This event class contains information about socket events.
581 \wxheading{Derived from
}
583 \helpref{wxEvent
}{wxevent
}
585 \wxheading{Include files
}
589 \wxheading{Event table macros
}
591 To process a socket event, use these event handler macros to direct input to member
592 functions that take a wxSocketEvent argument.
595 \begin{twocollist
}\itemsep=
0pt
596 \twocolitem{{\bf EVT
\_SOCKET(id, func)
}}{Process a socket event, supplying the member function.
}
601 \helpref{wxSocketBase
}{wxsocketbase
},
\rtfsp
602 \helpref{wxSocketClient
}{wxsocketclient
},
\rtfsp
603 \helpref{wxSocketServer
}{wxsocketserver
}
605 \latexignore{\rtfignore{\wxheading{Members
}}}
607 \membersection{wxSocketEvent::wxSocketEvent
}
609 \func{}{wxSocketEvent
}{\param{int
}{ id =
0}}
613 \membersection{wxSocketEvent::SocketEvent
}\label{wxsocketeventsocketevent
}
615 \constfunc{GSocketEvent
}{SocketEvent
}{\void}
617 Returns the socket event type.
619 % ---------------------------------------------------------------------------
620 % CLASS: wxSocketServer
621 % ---------------------------------------------------------------------------
622 \section{\class{wxSocketServer
}}\label{wxsocketserver
}
624 \wxheading{Derived from
}
626 \helpref{wxSocketBase
}{wxsocketbase
}
628 \wxheading{Include files
}
632 % ---------------------------------------------------------------------------
634 % ---------------------------------------------------------------------------
635 \latexignore{\rtfignore{\wxheading{Members
}}}
640 \membersection{wxSocketServer::wxSocketServer
}\label{wxsocketserverconstr
}
642 \func{}{wxSocketServer
}{\param{wxSockAddress\&
}{ address
},
\param{wxSockFlags
}{ flags = wxSocketBase::NONE
}}
644 Constructs a new wxSocketServer.
646 \wxheading{Parameters
}
648 \docparam{address
}{Specifies the local address for the server (e.g. port number).
}
650 \docparam{flags
}{Socket flags (See
\helpref{wxSocketBase::SetFlags
}{wxsocketbasesetflags
})
}
655 \membersection{wxSocketServer::
\destruct{wxSocketServer
}}
657 \func{}{\destruct{wxSocketServer
}}{\void}
659 Destroys a wxSocketServer object (it doesn't close the accepted connection).
664 \membersection{wxSocketServer::Accept
}
666 \func{wxSocketBase *
}{Accept
}{\void}
668 Creates a new object wxSocketBase and accepts an incoming connection.
{\bf Warning !
} This function will block the GUI.
670 \wxheading{Return value
}
672 Returns an opened socket connection.
676 \helpref{wxSocketServer::AcceptWith
}{wxsocketserveracceptwith
}
681 \membersection{wxSocketServer::AcceptWith
}\label{wxsocketserveracceptwith
}
683 \func{bool
}{AcceptWith
}{\param{wxSocketBase\&
}{ socket
}}
685 Accept an incoming connection using the specified socket object.
686 This is useful when someone wants to inherit wxSocketBase.
688 \wxheading{Parameters
}
690 \docparam{socket
}{Socket to be initialized
}
692 \wxheading{Return value
}
694 Returns TRUE if no error occurs, else FALSE.