\wxheading{Derived from}
-\helpref{wxEvtHandler}{wxevthandler}
+\helpref{wxObject}{wxobject}
\wxheading{Include files}
\membersection{Construction and destruction}
\helpref{wxSocketBase}{wxsocketbaseconstruct}\\
-\helpref{\destruct{wxSocketBase}}{wxsocketbasedestruct}
+\helpref{\destruct{wxSocketBase}}{wxsocketbasedestruct}\\
+\helpref{wxDestroy}{wxsocketbasedestroy}
\membersection{Socket state}
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}
\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}
\func{}{\destruct{wxSocketBase}}{\void}
-Destructor.
+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.
%
% Callback
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.
This function shuts down the socket, disabling further transmission and
reception of data; it also disables events for the socket and frees the
-associated system resources. If you destroy a socket, Close is automatically
-called.
+associated system resources. Upon socket destruction, Close is automatically
+called. This means that you don't need to do it yourself, unless you
+explicitly want to disable further operation.
\wxheading{Remark/Warning}
application must therefore be prepared to handle socket event messages
even after calling Close.
+%
+% Destroy
+%
+\membersection{wxSocketBase::Destroy}\label{wxsocketbasedestroy}
+
+\func{bool}{Destroy}{\void}
+
+Destroys the socket safely. Use this function instead of the delete operator,
+since otherwise socket events could reach the application even after the
+socket has been destroyed. To prevent this problem, this function appends
+the wxSocket to a list of object to be deleted on idle time, after all
+events have been processed. For the same reason, you should avoid creating
+socket objects in the stack.
+
+Destroy calls \helpref{Close}{wxsocketbaseclose} automatically.
+
+\wxheading{Return value}
+
+Always TRUE.
+
%
% Discard
%
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
%
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
%
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
%
Returns TRUE if the socket is initialized and ready and FALSE in other
cases.
+\wxheading{Remark/Warning}
+
+For \helpref{wxSocketClient}{wxsocketclient}, Ok won't return TRUE unless
+the client is connected to a server.
+
+For \helpref{wxSocketServer}{wxsocketserver}, Ok will return TRUE if the
+server could bind to the specified address and is already listening for
+new connections.
+
+Ok does not check for IO errors; use \helpref{Error}{wxsocketbaseerror}
+instead for that purpose.
+
%
% RestoreState
%
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.
\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
%
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.}
\helpref{wxSocketBase::Notify}{wxsocketbasenotify},
\helpref{wxSocketEvent}{wxsocketevent},
\helpref{wxEvtHandler}{wxevthandler},
-\helpref{wxSocketBase::Callback}{wxsocketbasecallback},
-\helpref{wxSocketBase::CallbackData}{wxsocketbasecallbackdata}
%
% SetFlags
%
\membersection{wxSocketBase::SetFlags}\label{wxsocketbasesetflags}
-\func{void}{SetFlags}{\param{wxSocketBase::wxSockFlags}{ flags}}
+\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
%
\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.
%
\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.
%
\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
%
\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.
\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}
\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}
\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}
\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.
%
\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}
%
\membersection{wxSocketClient::wxSocketClient}
-\func{}{wxSocketClient}{\param{wxSockFlags}{ flags = wxSocketBase::NONE}}
+\func{}{wxSocketClient}{\param{wxSocketFlags}{ flags = wxSOCKET_NONE}}
Constructor.
\wxheading{See also}
\helpref{wxSocketClient::Connect}{wxsocketclientconnect},
+\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
\helpref{wxSocketBase::IsConnected}{wxsocketbaseisconnected}
% ---------------------------------------------------------------------------
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.
%
\membersection{wxSocketServer::wxSocketServer}\label{wxsocketserverconstr}
-\func{}{wxSocketServer}{\param{wxSockAddress\&}{ address}, \param{wxSockFlags}{ flags = wxSocketBase::NONE}}
+\func{}{wxSocketServer}{\param{wxSockAddress\&}{ address}, \param{wxSocketFlags}{ flags = wxSOCKET_NONE}}
Constructs a new server and tries to bind to the specified {\it address}.
Before trying to accept new connections, test whether it succeeded with
\wxheading{See also}
\helpref{wxSocketServer::Accept}{wxsocketserveraccept},
-\helpref{wxSocketServer::AcceptWith}{wxsocketserveracceptwith}
+\helpref{wxSocketServer::AcceptWith}{wxsocketserveracceptwith},
+\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait}
projects / wxWidgets.git / blobdiff