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