X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ed8297b98d205054c2ed18942992161a25acaf4c..c0bcc480680ecdf368839c119f5e984df757f893:/docs/latex/wx/socket.tex

diff --git a/docs/latex/wx/socket.tex b/docs/latex/wx/socket.tex
index 9a02f0bdfc..3247717456 100644
--- a/docs/latex/wx/socket.tex
+++ b/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
-be considered deprecated.
+compatibility only. Their use is strongly discouraged in favour of events,
+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
-objects in the stack.
+use \helpref{Destroy}{wxsocketbasedestroy} instead. Also, do not create
+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
-\helpref{CallbackData}{wxsocketbasecallbackdata}.
+is the user data you specified using \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
-asynchronous callbacks, as set with \helpref{Callback}{wxsocketbasecallback}
+\helpref{Notify}{wxsocketbasenotify}, user data, as set with
+\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.}
@@ -612,7 +672,7 @@ default is set to 10 minutes.
 %
 \membersection{wxSocketBase::Peek}\label{wxsocketbasepeek}
 
-\func{wxSocketBase\&}{Peek}{\param{char *}{ buffer}, \param{wxUint32}{ nbytes}}
+\func{wxSocketBase\&}{Peek}{\param{void *}{ buffer}, \param{wxUint32}{ nbytes}}
 
 This function peeks a buffer of {\it nbytes} bytes from the socket.
 Peeking a buffer doesn't delete it from the socket input queue.
@@ -648,7 +708,7 @@ of flags being used. For a detailed explanation, see \helpref{wxSocketBase::SetF
 %
 \membersection{wxSocketBase::Read}\label{wxsocketbaseread}
 
-\func{wxSocketBase\&}{Read}{\param{char *}{ buffer}, \param{wxUint32}{ nbytes}}
+\func{wxSocketBase\&}{Read}{\param{void *}{ buffer}, \param{wxUint32}{ nbytes}}
 
 This function reads a buffer of {\it nbytes} bytes from the socket.
 
@@ -683,7 +743,7 @@ of flags being used. For a detailed explanation, see \helpref{wxSocketBase::SetF
 %
 \membersection{wxSocketBase::ReadMsg}\label{wxsocketbasereadmsg}
 
-\func{wxSocketBase\&}{ReadMsg}{\param{char *}{ buffer}, \param{wxUint32}{ nbytes}}
+\func{wxSocketBase\&}{ReadMsg}{\param{void *}{ buffer}, \param{wxUint32}{ nbytes}}
 
 This function reads a buffer sent by \helpref{WriteMsg}{wxsocketbasewritemsg}
 on a socket. If the buffer passed to the function isn't big enough, the
@@ -724,7 +784,7 @@ For a detailed explanation, see \helpref{wxSocketBase::SetFlags}{wxsocketbaseset
 %
 \membersection{wxSocketBase::Unread}\label{wxsocketbaseunread}
 
-\func{wxSocketBase\&}{Unread}{\param{const char *}{ buffer}, \param{wxUint32}{ nbytes}}
+\func{wxSocketBase\&}{Unread}{\param{const void *}{ buffer}, \param{wxUint32}{ nbytes}}
 
 This function unreads a buffer. That is, the data in the buffer is put back
 in the incoming queue. This function is not affected by wxSocket flags.
@@ -783,22 +843,22 @@ 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::WaitForLost}{wxsocketbasewaitforlost}
+\helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite},
+\helpref{wxSocketClient::WaitOnConnect}{wxsocketclientwaitonconnect}
 
 %
-% WaitForRead
+% WaitForLost
 %
-\membersection{wxSocketBase::WaitForRead}\label{wxsocketbasewaitforread}
+\membersection{wxSocketBase::WaitForLost}\label{wxsocketbasewaitforlost}
 
-\func{bool}{WaitForRead}{\param{long}{ seconds = -1}, \param{long}{ millisecond = 0}}
+\func{bool}{Wait}{\param{long}{ seconds = -1}, \param{long}{ millisecond = 0}}
 
-This function waits until the socket is readable. This might mean that
-queued data is available for reading or, for streamed sockets, that
-the connection has been closed, so that a read operation will complete
-immediately without blocking (unless the {\bf wxSOCKET\_WAITALL} flag
-is set, in which case the operation might still block).
+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}
 
@@ -810,26 +870,25 @@ as set with \helpref{SetTimeout}{wxsocketbasesettimeout}.}
 
 \wxheading{Return value}
 
-Returns TRUE if the socket becomes readable, FALSE on timeout.
+Returns TRUE if the connection was lost, FALSE if the timeout was reached.
 
 \wxheading{See also}
 
-\helpref{wxSocketBase::Wait}{wxsocketbasewait}, 
-\helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite}, 
-\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost}
+\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
+\helpref{wxSocketBase::Wait}{wxsocketbasewait}
 
 %
-% WaitForWrite
+% WaitForRead
 %
-\membersection{wxSocketBase::WaitForWrite}\label{wxsocketbasewaitforwrite}
+\membersection{wxSocketBase::WaitForRead}\label{wxsocketbasewaitforread}
 
-\func{bool}{WaitForWrite}{\param{long}{ seconds = -1}, \param{long}{ millisecond = 0}}
+\func{bool}{WaitForRead}{\param{long}{ seconds = -1}, \param{long}{ millisecond = 0}}
 
-This function waits until the socket becomes writable. This might mean that
-the socket is ready to send new data, or for streamed sockets, that the
-connection has been closed, so that a write operation is guaranteed to
-complete immediately (unless the {\bf wxSOCKET\_WAITALL} flag is set,
-in which case the operation might still block).
+This function waits until the socket is readable. This might mean that
+queued data is available for reading or, for streamed sockets, that
+the connection has been closed, so that a read operation will complete
+immediately without blocking (unless the {\bf wxSOCKET\_WAITALL} flag
+is set, in which case the operation might still block).
 
 \wxheading{Parameters}
 
@@ -841,23 +900,25 @@ as set with \helpref{SetTimeout}{wxsocketbasesettimeout}.}
 
 \wxheading{Return value}
 
-Returns TRUE if the socket becomes writable, FALSE on timeout.
+Returns TRUE if the socket becomes readable, FALSE on timeout.
 
 \wxheading{See also}
 
-\helpref{wxSocketBase::Wait}{wxsocketbasewait}, 
-\helpref{wxSocketBase::WaitForRead}{wxsocketbasewaitforread}, 
-\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost}
+\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
+\helpref{wxSocketBase::Wait}{wxsocketbasewait}
 
 %
-% WaitForLost
+% WaitForWrite
 %
-\membersection{wxSocketBase::WaitForLost}\label{wxsocketbasewaitforlost}
+\membersection{wxSocketBase::WaitForWrite}\label{wxsocketbasewaitforwrite}
 
-\func{bool}{Wait}{\param{long}{ seconds = -1}, \param{long}{ millisecond = 0}}
+\func{bool}{WaitForWrite}{\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.
+This function waits until the socket becomes writable. This might mean that
+the socket is ready to send new data, or for streamed sockets, that the
+connection has been closed, so that a write operation is guaranteed to
+complete immediately (unless the {\bf wxSOCKET\_WAITALL} flag is set,
+in which case the operation might still block).
 
 \wxheading{Parameters}
 
@@ -869,20 +930,19 @@ as set with \helpref{SetTimeout}{wxsocketbasesettimeout}.}
 
 \wxheading{Return value}
 
-Returns TRUE if the connection was lost, FALSE if the timeout was reached.
+Returns TRUE if the socket becomes writable, FALSE on timeout.
 
 \wxheading{See also}
 
-\helpref{wxSocketBase::WaitForRead}{wxsocketbasewaitforread}, 
-\helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite}, 
-\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost}
+\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
+\helpref{wxSocketBase::Wait}{wxsocketbasewait}
 
 %
 % Write
 %
 \membersection{wxSocketBase::Write}\label{wxsocketbasewrite}
 
-\func{wxSocketBase\&}{Write}{\param{const char *}{ buffer}, \param{wxUint32}{ nbytes}}
+\func{wxSocketBase\&}{Write}{\param{const void *}{ buffer}, \param{wxUint32}{ nbytes}}
 
 This function writes a buffer of {\it nbytes} bytes to the socket.
 
@@ -917,7 +977,7 @@ of flags being used. For a detailed explanation, see \helpref{wxSocketBase::SetF
 %
 \membersection{wxSocketBase::WriteMsg}\label{wxsocketbasewritemsg}
 
-\func{wxSocketBase\&}{WriteMsg}{\param{const char *}{ buffer}, \param{wxUint32}{ nbytes}}
+\func{wxSocketBase\&}{WriteMsg}{\param{const void *}{ buffer}, \param{wxUint32}{ nbytes}}
 
 This function writes a buffer of {\it nbytes} bytes from the socket, but it
 writes a short header before so that \helpref{ReadMsg}{wxsocketbasereadmsg}
@@ -1085,6 +1145,7 @@ bool success = client->IsConnected();
 \wxheading{See also}
 
 \helpref{wxSocketClient::Connect}{wxsocketclientconnect},
+\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
 \helpref{wxSocketBase::IsConnected}{wxsocketbaseisconnected}
 
 % ---------------------------------------------------------------------------
@@ -1126,16 +1187,23 @@ functions that take a wxSocketEvent argument.
 
 Constructor.
 
-\membersection{wxSocketEvent::Socket}\label{wxsocketeventsocket}
+\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}.
 
-\constfunc{wxSocketBase *}{Socket}{\void}
+\membersection{wxSocketEvent::GetSocket}\label{wxsocketeventgetsocket}
+
+\constfunc{wxSocketBase *}{GetSocket}{\void}
 
 Returns the socket object to which this event refers to. This makes
 it possible to use the same event handler for different sockets.
 
-\membersection{wxSocketEvent::SocketEvent}\label{wxsocketeventsocketevent}
+\membersection{wxSocketEvent::GetSocketEvent}\label{wxsocketeventgetsocketevent}
 
-\constfunc{wxSocketNotify}{SocketEvent}{\void}
+\constfunc{wxSocketNotify}{GetSocketEvent}{\void}
 
 Returns the socket event type.
 
@@ -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}
 
