\membersection{Construction and destruction}
\helpref{wxSocketBase}{wxsocketbaseconstruct}\\
-\helpref{\destruct{wxSocketBase}}{wxsocketbasedestruct}
+\helpref{\destruct{wxSocketBase}}{wxsocketbasedestruct}\\
+\helpref{wxDestroy}{wxsocketbasedestroy}
\membersection{Socket state}
\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
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
%
\constfunc{bool}{IsData}{\void}
-Returns TRUE if the socket is readable. This might mean that
+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 \helpref{Read}{wxsocketbaseread},
-\helpref{ReadMsg}{wxsocketbasereadmsg} or \helpref{Peek}{wxsocketbasepeek}
-operation is guaranteed to complete immediately (unless the
-{\bf wxSOCKET\_WAITALL} flag is set).
+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).
\membersection{wxSocketBase::IsDisconnected}\label{wxsocketbaseisdisconnected}
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
%
%
\membersection{wxSocketBase::SetFlags}\label{wxsocketbasesetflags}
-\func{void}{SetFlags}{\param{wxSocketBase::wxSockFlags}{ flags}}
+\func{void}{SetFlags}{\param{wxSocketBase::wxSocketFlags}{ flags}}
\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.
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 \helpref{Read}{wxsocketbaseread},
-\helpref{ReadMsg}{wxsocketbasereadmsg} or \helpref{Peek}{wxsocketbasepeek}
-operation is guaranteed to complete immediately (unless the
-{\bf wxSOCKET\_WAITALL} flag is set).
+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 there is data to be read, FALSE if the timeout was reached
-or an error occured.
+Returns TRUE if the socket becomes readable, FALSE on timeout.
\wxheading{See also}
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 \helpref{Write}{wxsocketbasewrite}
-or \helpref{ReadMsg}{wxsocketbasewritemsg} operation is guaranteed to
-complete immediately (unless the {\bf wxSOCKET\_WAITALL} flag is set).
+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 socket becomes writable, FALSE if the timeout was reached.
+Returns TRUE if the socket becomes writable, FALSE on timeout.
\wxheading{See also}
%
\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{Return value}
-If the connection is succesfully established, returns TRUE.
+WaitOnConnect returns TRUE if the connection request completes. This
+does not necessarily mean that the connection was succesfully established;
+it might also happen that the connection was refused by the peer. Use
+\helpref{IsConnected}{wxsocketbaseisconnected} to distinguish between
+these two situations.
+
+If the timeout elapses, WaitOnConnect returns FALSE.
+
+These semantics allow code like this:
-If the timeout expires, or if the connection fails, returns FALSE.
-To distinguish between these two conditions, use \helpref{IsConnected}{wxsocketbaseisconnected}
+\begin{verbatim}
+// Issue the connection request
+client->Connect(addr, FALSE);
+
+// Wait until the request completes or until we decide to give up
+bool waitmore = TRUE;
+while ( !client->WaitOnConnect(seconds, millis) && waitmore )
+{
+ // possibly give some feedback to the user,
+ // and update waitmore if needed.
+}
+bool success = client->IsConnected();
+\end{verbatim}
\wxheading{See also}
Constructor.
-\membersection{wxSocketEvent::Socket}\label{wxsocketeventsocket}
+\membersection{wxSocketEvent::GetSocket}\label{wxsocketeventgetsocket}
-\constfunc{wxSocketBase *}{Socket}{\void}
+\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
projects / wxWidgets.git / blobdiff