Updated to reflect latest changes

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@6597 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/socket.tex

@@ -16,7 +16,7 @@ defines all basic IO functionality.
 
 \wxheading{Derived from}
 
-\helpref{wxEvtHandler}{wxevthandler}
+\helpref{wxObject}{wxobject}
 
 \wxheading{Include files}
 
@@ -139,13 +139,20 @@ Functions that perform basic IO functionality.
 
 Functions that perform a timed wait on a certain IO condition.
 
+\helpref{InterruptWait}{wxsocketbaseinterruptwait}\\
 \helpref{Wait}{wxsocketbasewait}\\
+\helpref{WaitForLost}{wxsocketbasewaitforlost}\\
 \helpref{WaitForRead}{wxsocketbasewaitforread}\\
 \helpref{WaitForWrite}{wxsocketbasewaitforwrite}\\
-\helpref{WaitForLost}{wxsocketbasewaitforlost}
+
+and also:
+
+\helpref{wxSocketServer::WaitForAccept}{wxsocketserverwaitforaccept}\\
+\helpref{wxSocketClient::WaitOnConnect}{wxsocketclientwaitonconnect}
 
 Functions that allow applications to customize socket IO as needed.
 
+\helpref{GetFlags}{wxsocketbasegetflags}\\
 \helpref{SetFlags}{wxsocketbasesetflags}\\
 \helpref{SetTimeout}{wxsocketbasesettimeout}
 
@@ -155,11 +162,14 @@ Functions that allow applications to receive socket events.
 
 \helpref{Notify}{wxsocketbasenotify}\\
 \helpref{SetNotify}{wxsocketbasesetnotify}\\
+\helpref{GetClientData}{wxsocketbasegetclientdata}\\
+\helpref{SetClientData}{wxsocketbasesetclientdata}\\
 \helpref{SetEventHandler}{wxsocketbaseseteventhandler}
 
 Callback functions are also available, but they are provided for backwards
-compatibility only. Their use is discouraged in favour of events, and should
+compatibility only. Their use is strongly discouraged in favour of events,
-be considered deprecated.
+and should be considered deprecated. Callbacks may be unsupported in future
+releases of wxWindows.
 
 \helpref{Callback}{wxsocketbasecallback}\\
 \helpref{CallbackData}{wxsocketbasecallbackdata}
@@ -188,8 +198,8 @@ Default constructor. Don't use it directly; instead, use
 \func{}{\destruct{wxSocketBase}}{\void}
 
 Destructor. Do not destroy a socket using the delete operator directly;
-use \helpref{Destroy}{wxsocketbasedestroy} instead. Also, do not create socket
+use \helpref{Destroy}{wxsocketbasedestroy} instead. Also, do not create
-objects in the stack.
+socket objects in the stack.
 
 %
 % Callback
@@ -211,8 +221,7 @@ void SocketCallback(wxSocketBase& sock, wxSocketNotify evt, char *cdata);
 The first parameter is a reference to the socket object in which the
 event occured. The second parameter tells you which event occured.
 (See \helpref{wxSocket events}{wxsocketbase}). The third parameter
-is the user data you specified using
+is the user data you specified using \helpref{CallbackData}{wxsocketbasecallbackdata}.
-\helpref{CallbackData}{wxsocketbasecallbackdata}.
 
 Note that events are preferred over callbacks where possible.
 
@@ -312,6 +321,16 @@ Returns TRUE if an error occured in the last IO operation.
 Use this function to check for an error condition after one of the
 following calls: Discard, Peek, Read, ReadMsg, Unread, Write, WriteMsg.
 
+%
+% GetClientData
+%
+\membersection{wxSocketBase::GetClientData}\label{wxsocketbasegetclientdata}
+
+\constfunc{void *}{GetClientData}{\void}
+
+Returns a pointer of the client data for this socket, as set with
+\helpref{SetClientData}{wxsocketbasesetclientdata}
+
 %
 % GetLocal
 %
@@ -327,6 +346,15 @@ address, local port, ...).
 
 It returns TRUE if no errors happened, FALSE otherwise.
 
+%
+% GetFlags
+%
+\membersection{wxSocketBase::GetFlags}\label{wxsocketbasegetflags}
+
+\constfunc{wxSocketFlags}{GetFlags}{\void}
+
+Returns current IO flags, as set with \helpref{SetFlags}{wxsocketbasesetflags}
+
 %
 % GetPeer
 %
@@ -342,6 +370,28 @@ address field contains the complete peer host address of the socket
 
 It returns TRUE if no errors happened, FALSE otherwise.
 
+%
+% InterruptWait
+%
+\membersection{wxSocketBase::InterruptWait}\label{wxsocketbaseinterruptwait}
+
+\func{void}{InterruptWait}{\void}
+
+Use this function to interrupt any wait operation currently in progress.
+Note that this is not intended as a regular way to interrupt a Wait call,
+but only as an escape mechanism for exceptional situations where it is
+absolutely necessary to use it, for example to abort an operation due to
+some exception or abnormal problem. InterruptWait is automatically called
+when you \helpref{Close}{wxsocketbaseclose} a socket (and thus also upon
+socket destruction), so you don't need to use it in these cases.
+
+\helpref{wxSocketBase::Wait}{wxsocketbasewait},
+\helpref{wxSocketServer::WaitForAccept}{wxsocketserverwaitforaccept},
+\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost},
+\helpref{wxSocketBase::WaitForRead}{wxsocketbasewaitforread},
+\helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite},
+\helpref{wxSocketClient::WaitOnConnect}{wxsocketclientwaitonconnect}
+
 %
 % IsConnected
 %
@@ -463,8 +513,9 @@ Calls to SaveState and RestoreState can be nested.
 This function saves the current state of the socket in a stack. Socket
 state includes flags, as set with \helpref{SetFlags}{wxsocketbasesetflags},
 event mask, as set with \helpref{SetNotify}{wxsocketbasesetnotify} and
-\helpref{Notify}{wxsocketbasenotify}, and current settings for the
+\helpref{Notify}{wxsocketbasenotify}, user data, as set with
-asynchronous callbacks, as set with \helpref{Callback}{wxsocketbasecallback}
+\helpref{SetClientData}{wxsocketbasesetclientdata}, and asynchronous
+callback settings, as set with \helpref{Callback}{wxsocketbasecallback}
 and \helpref{CallbackData}{wxsocketbasecallbackdata}.
 
 Calls to SaveState and RestoreState can be nested.
@@ -473,6 +524,18 @@ Calls to SaveState and RestoreState can be nested.
 
 \helpref{wxSocketBase::RestoreState}{wxsocketbaserestorestate}
 
+%
+% SetClientData
+%
+\membersection{wxSocketBase::SetClientData}\label{wxsocketbasesetclientdata}
+
+\func{void}{SetClientData}{\param{void *}{data}}
+
+Sets user-supplied client data for this socket. All socket events will
+contain a pointer to this data, which can be retrieved with the
+\helpref{wxSocketEvent::GetClientData}{wxsocketeventgetclientdata}
+function.
+
 %
 % SetEventHandler
 %
@@ -485,11 +548,6 @@ handler will be called for those events for which notification is
 enabled with \helpref{SetNotify}{wxsocketbasesetnotify} and
 \helpref{Notify}{wxsocketbasenotify}.
 
-You can also specify a callback function to be called when an event
-occurs, although if possible, events should be used instead of callbacks.
-See \helpref{Callback}{wxsocketbasecallback} and
-\helpref{CallbackData}{wxsocketbasecallbackdata}.
-
 \wxheading{Parameters}
 
 \docparam{evt\_hdlr}{Specifies the event handler you want to use.}
@@ -502,8 +560,6 @@ See \helpref{Callback}{wxsocketbasecallback} and
 \helpref{wxSocketBase::Notify}{wxsocketbasenotify}, 
 \helpref{wxSocketEvent}{wxsocketevent}, 
 \helpref{wxEvtHandler}{wxevthandler}, 
-\helpref{wxSocketBase::Callback}{wxsocketbasecallback}, 
-\helpref{wxSocketBase::CallbackData}{wxsocketbasecallbackdata}
 
 %
 % SetFlags
@@ -512,6 +568,10 @@ See \helpref{Callback}{wxsocketbasecallback} and
 
 \func{void}{SetFlags}{\param{wxSocketBase::wxSocketFlags}{ flags}}
 
+Use SetFlags to customize IO operation for this socket. The {\it flags}
+parameter is a combination of flags ORed toghether. The following flags
+can be used:
+
 \twocolwidtha{7cm}
 \begin{twocollist}\itemsep=0pt
 \twocolitem{{\bf wxSOCKET\_NONE}}{Normal functionality.}
@@ -783,9 +843,39 @@ FALSE if the timeout was reached.
 
 \wxheading{See also}
 
+\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
+\helpref{wxSocketServer::WaitForAccept}{wxsocketserverwaitforaccept},
+\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost},
 \helpref{wxSocketBase::WaitForRead}{wxsocketbasewaitforread}, 
-\helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite}, 
+\helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite},
-\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost}
+\helpref{wxSocketClient::WaitOnConnect}{wxsocketclientwaitonconnect}
+
+%
+% WaitForLost
+%
+\membersection{wxSocketBase::WaitForLost}\label{wxsocketbasewaitforlost}
+
+\func{bool}{Wait}{\param{long}{ seconds = -1}, \param{long}{ millisecond = 0}}
+
+This function waits until the connection is lost. This may happen if
+the peer gracefully closes the connection or if the connection breaks.
+
+\wxheading{Parameters}
+
+\docparam{seconds}{Number of seconds to wait.
+If -1, it will wait for the default timeout,
+as set with \helpref{SetTimeout}{wxsocketbasesettimeout}.}
+
+\docparam{millisecond}{Number of milliseconds to wait.}
+
+\wxheading{Return value}
+
+Returns TRUE if the connection was lost, FALSE if the timeout was reached.
+
+\wxheading{See also}
+
+\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
+\helpref{wxSocketBase::Wait}{wxsocketbasewait}
 
 %
 % WaitForRead
@@ -814,9 +904,8 @@ Returns TRUE if the socket becomes readable, FALSE on timeout.
 
 \wxheading{See also}
 
-\helpref{wxSocketBase::Wait}{wxsocketbasewait}, 
+\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
-\helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite}, 
+\helpref{wxSocketBase::Wait}{wxsocketbasewait}
-\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost}
 
 %
 % WaitForWrite
@@ -845,37 +934,8 @@ Returns TRUE if the socket becomes writable, FALSE on timeout.
 
 \wxheading{See also}
 
-\helpref{wxSocketBase::Wait}{wxsocketbasewait}, 
+\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
-\helpref{wxSocketBase::WaitForRead}{wxsocketbasewaitforread}, 
+\helpref{wxSocketBase::Wait}{wxsocketbasewait}
-\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost}
-
-%
-% WaitForLost
-%
-\membersection{wxSocketBase::WaitForLost}\label{wxsocketbasewaitforlost}
-
-\func{bool}{Wait}{\param{long}{ seconds = -1}, \param{long}{ millisecond = 0}}
-
-This function waits until the connection is lost. This may happen if
-the peer gracefully closes the connection or if the connection breaks.
-
-\wxheading{Parameters}
-
-\docparam{seconds}{Number of seconds to wait.
-If -1, it will wait for the default timeout,
-as set with \helpref{SetTimeout}{wxsocketbasesettimeout}.}
-
-\docparam{millisecond}{Number of milliseconds to wait.}
-
-\wxheading{Return value}
-
-Returns TRUE if the connection was lost, FALSE if the timeout was reached.
-
-\wxheading{See also}
-
-\helpref{wxSocketBase::WaitForRead}{wxsocketbasewaitforread}, 
-\helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite}, 
-\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost}
 
 %
 % Write
@@ -1085,6 +1145,7 @@ bool success = client->IsConnected();
 \wxheading{See also}
 
 \helpref{wxSocketClient::Connect}{wxsocketclientconnect},
+\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
 \helpref{wxSocketBase::IsConnected}{wxsocketbaseisconnected}
 
 % ---------------------------------------------------------------------------
@@ -1126,6 +1187,13 @@ functions that take a wxSocketEvent argument.
 
 Constructor.
 
+\membersection{wxSocketEvent::GetClientData}\label{wxsocketeventgetclientdata}
+
+\func{void *}{GetClientData}{\void}
+
+Gets the client data of the socket which generated this event, as
+set with \helpref{wxSocketBase::SetClientData}{wxsocketbasesetclientdata}.
+
 \membersection{wxSocketEvent::GetSocket}\label{wxsocketeventgetsocket}
 
 \constfunc{wxSocketBase *}{GetSocket}{\void}
@@ -1269,5 +1337,6 @@ Returns TRUE if an incoming connection arrived, FALSE if the timeout elapsed.
 \wxheading{See also}
 
 \helpref{wxSocketServer::Accept}{wxsocketserveraccept}, 
-\helpref{wxSocketServer::AcceptWith}{wxsocketserveracceptwith}
+\helpref{wxSocketServer::AcceptWith}{wxsocketserveracceptwith},
+\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait}
 

docs/latex/wx/tsamples.tex

@@ -287,22 +287,22 @@ The sample also provides some timings for adding/deleting/sorting a lot of
 
 The sockets sample demonstrates how to use the communication facilities
 provided by \helpref{wxSocket}{wxsocketbase}. There are two different
-applications in this sample: a server, which is implemented as a
+applications in this sample: a server, which is implemented using a
-\helpref{wxSocketServer}{wxsocketserver} object, and a client, which is
+\helpref{wxSocketServer}{wxsocketserver} object, and a client, which
-implemented with \helpref{wxSocketClient}{wxsocketclient}.
+is implemented as a \helpref{wxSocketClient}{wxsocketclient}.
 
-The server binds to the local address, using TCP port number 3000, sets
+The server binds to the local address, using TCP port number 3000,
-up an event handler to be notified of incoming connection requests
+sets up an event handler to be notified of incoming connection requests
-({\bf wxSOCKET\_CONNECTION} event), and stands there, waiting (listening
+({\bf wxSOCKET\_CONNECTION} events), and stands there, waiting for clients
-in the socket parlance) for clients. For each incoming client, a new
+({\it listening} in the socket parlance). For each accepted connection,
-\helpref{wxSocketBase}{wxsocketbase} object is created, which represents
+a new \helpref{wxSocketBase}{wxsocketbase} object is created. These
-the connection. Connections are independent from the server that created
+socket objects are independent from the server that created them, so
-them, so they set up their own event handler, and stay awaiting for 
+they set up their own event handler, and then request to be notified
-{\bf wxSOCKET\_INPUT} (incoming data) or {\bf wxSOCKET\_LOST} (connection
+of {\bf wxSOCKET\_INPUT} (incoming data) or {\bf wxSOCKET\_LOST}
-closed at the remote end) events. This event handler is the same for all
+(connection closed at the remote end) events. In the sample, the event
-connections, and demonstrates how to determine which socket the event
+handler is the same for all connections; to find out which socket the
-is addressed to by using the \helpref{Socket}{wxsocketeventsocket} function
+event is addressed to, the \helpref{GetSocket}{wxsocketeventgetsocket}
-in the \helpref{wxSocketEvent}{wxsocketevent} class.
+function is used.
 
 Although it might take some time to get used to the event-oriented
 system upon which wxSocket is built, the benefits are many. See, for
@@ -318,21 +318,20 @@ how to use the basic IO calls in \helpref{wxSocketBase}{wxsocketbase},
 such as \helpref{Read}{wxsocketbaseread}, \helpref{Write}{wxsocketbasewrite},
 \helpref{ReadMsg}{wxsocketbasereadmsg} and \helpref{WriteMsg}{wxsocketbasewritemsg},
 and how to set up the correct IO flags depending on what you are going to
-do. See the comments in the code for more information (a lengthy explanation
+do. See the comments in the code for more information. Note that because
-on socket flags is available in \helpref{SetFlags}{wxsocketbasesetflags}).
+both clients and connection objects in the server set up an event handler
-Note that because both clients and connection objects in the server set
+to catch {\bf wxSOCKET\_LOST} events, each one is immediately notified
-up an event handler to catch {\bf wxSOCKET\_LOST} events, each one is
+if the other end closes the connection.
-immediately notified if the other end closes the connection.
 
-There is also an URL test which demonstrates how to use the \helpref{wxURL}{wxurl}
+There is also an URL test which shows how to use the \helpref{wxURL}{wxurl}
-class.
+class to fetch data from a given URL.
 
-The sockets sample is work in progress. Coming soon:
+The sockets sample is work in progress. Some things to do:
 
 \begin{itemize}\itemsep=0pt
 \item More tests for basic socket functionality.
 \item More tests for protocol classes (wxProtocol and its descendants).
-\item Tests for the recently added datagram socket classes.
+\item Tests for the recently added (and still in alpha stage) datagram sockets.
 \item New samples which actually do something useful (suggestions accepted).
 \end{itemize}