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}