socket.tex

Wxpython Implemented on Windows CE, Source code

\item An incoming connection request has arrived (\helpref{wxSocketServer}{wxsocketserver} only)
\item The connection has been closed.
\end{itemize}

Note that it is recommended to use the individual Wait functions
to wait for the required condition, instead of this one.

\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 when any of the above conditions is satisfied,
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{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
%
\membersection{wxSocketBase::WaitForRead}\label{wxsocketbasewaitforread}

\func{bool}{WaitForRead}{\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).

\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 socket becomes readable, false on timeout.

\wxheading{See also}

\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait}, 
\helpref{wxSocketBase::Wait}{wxsocketbasewait}

%
% WaitForWrite
%
\membersection{wxSocketBase::WaitForWrite}\label{wxsocketbasewaitforwrite}

\func{bool}{WaitForWrite}{\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).

\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 socket becomes writable, false on timeout.

\wxheading{See also}

\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait}, 
\helpref{wxSocketBase::Wait}{wxsocketbasewait}

%
% Write
%
\membersection{wxSocketBase::Write}\label{wxsocketbasewrite}

\func{wxSocketBase\&}{Write}{\param{const void *}{ buffer}, \param{wxUint32}{ nbytes}}

This function writes a buffer of {\it nbytes} bytes to the socket.

Use \helpref{LastCount}{wxsocketbaselastcount} to verify the number of bytes actually written.

Use \helpref{Error}{wxsocketbaseerror} to determine if the operation succeeded.

\wxheading{Parameters}

\docparam{buffer}{Buffer with the data to be sent.}

\docparam{nbytes}{Number of bytes.}

\wxheading{Return value}

Returns a reference to the current object.

\wxheading{Remark/Warning}

The exact behaviour of wxSocketBase::Write depends on the combination
of flags being used. For a detailed explanation, see \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags}.

\wxheading{See also}

\helpref{wxSocketBase::Error}{wxsocketbaseerror}, 
\helpref{wxSocketBase::LastError}{wxsocketbaselasterror}, 
\helpref{wxSocketBase::LastCount}{wxsocketbaselastcount}, 
\helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags}

%
% WriteMsg
%
\membersection{wxSocketBase::WriteMsg}\label{wxsocketbasewritemsg}

\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} 
knows how much data should it actually read. So, a buffer sent with WriteMsg 
{\bf must} be read with ReadMsg. This function always waits for the entire
buffer to be sent, unless an error occurs.

Use \helpref{LastCount}{wxsocketbaselastcount} to verify the number of bytes actually written.

Use \helpref{Error}{wxsocketbaseerror} to determine if the operation succeeded.

\wxheading{Parameters}

\docparam{buffer}{Buffer with the data to be sent.}

\docparam{nbytes}{Number of bytes to send.}

\wxheading{Return value}

Returns a reference to the current object.

\wxheading{Remark/Warning}

wxSocketBase::WriteMsg will behave as if the {\bf wxSOCKET\_WAITALL} flag
was always set and it will always ignore the {\bf wxSOCKET\_NOWAIT} flag.
The exact behaviour of WriteMsg depends on the {\bf wxSOCKET\_BLOCK} flag.
For a detailed explanation, see \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags}.

\wxheading{See also}

\helpref{wxSocketBase::Error}{wxsocketbaseerror}, 
\helpref{wxSocketBase::LastError}{wxsocketbaselasterror}, 
\helpref{wxSocketBase::LastCount}{wxsocketbaselastcount}, 
\helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags}, 
\helpref{wxSocketBase::ReadMsg}{wxsocketbasereadmsg}


% ---------------------------------------------------------------------------
% CLASS wxSocketClient
% ---------------------------------------------------------------------------

\section{\class{wxSocketClient}}\label{wxsocketclient}

\wxheading{Derived from}

\helpref{wxSocketBase}{wxsocketbase}

\wxheading{Include files}

<wx/socket.h>

\latexignore{\rtfignore{\wxheading{Members}}}

% ---------------------------------------------------------------------------
% Members
% ---------------------------------------------------------------------------
%
% wxSocketClient
%
\membersection{wxSocketClient::wxSocketClient}\label{wxsocketclientctor}

\func{}{wxSocketClient}{\param{wxSocketFlags}{ flags = wxSOCKET\_NONE}}

Constructor.

\wxheading{Parameters}

\docparam{flags}{Socket flags (See \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags})}

%
% ~wxSocketClient
%
\membersection{wxSocketClient::\destruct{wxSocketClient}}\label{wxsocketclientdtor}

\func{}{\destruct{wxSocketClient}}{\void}

Destructor. Please see \helpref{wxSocketBase::Destroy}{wxsocketbasedestroy}.

%
% Connect
%
\membersection{wxSocketClient::Connect}\label{wxsocketclientconnect}

\func{bool}{Connect}{\param{wxSockAddress\&}{ address}, \param{bool}{ wait = true}}

\func{bool}{Connect}{\param{wxSockAddress\&}{ address}, \param{wxSockAddress\&}{ local},
\param{bool}{ wait = true}}

Connects to a server using the specified address.

If {\it wait} is true, Connect will wait until the connection
completes. {\bf Warning:} This will block the GUI.

If {\it wait} is false, Connect will try to establish the connection and
return immediately, without blocking the GUI. When used this way, even if
Connect returns false, the connection request can be completed later.
To detect this, use \helpref{WaitOnConnect}{wxsocketclientwaitonconnect},
or catch {\bf wxSOCKET\_CONNECTION} events (for successful establishment)
and {\bf wxSOCKET\_LOST} events (for connection failure).

\wxheading{Parameters}

\docparam{address}{Address of the server.}

\docparam{local}{Bind to the specified local address and port before connecting.
The local address and port can also be set using \helpref{SetLocal}{wxsocketbasesetlocal},
and then using the 2-parameter Connect method.}

\docparam{wait}{If true, waits for the connection to complete.}

\wxheading{Return value}

Returns true if the connection is established and no error occurs.

If {\it wait} was true, and Connect returns false, an error occurred
and the connection failed.

If {\it wait} was false, and Connect returns false, you should still
be prepared to handle the completion of this connection request, either
with \helpref{WaitOnConnect}{wxsocketclientwaitonconnect} or by
watching {\bf wxSOCKET\_CONNECTION} and {\bf wxSOCKET\_LOST} events.

\wxheading{See also}

\helpref{wxSocketClient::WaitOnConnect}{wxsocketclientwaitonconnect}, 
\helpref{wxSocketBase::SetNotify}{wxsocketbasesetnotify}, 
\helpref{wxSocketBase::Notify}{wxsocketbasenotify}

%
% WaitOnConnect
%
\membersection{wxSocketClient::WaitOnConnect}\label{wxsocketclientwaitonconnect}

\func{bool}{WaitOnConnect}{\param{long}{ seconds = -1}, \param{long}{ milliseconds = 0}}

Wait until a connection request completes, or until the specified timeout
elapses. Use this function after issuing a call
to \helpref{Connect}{wxsocketclientconnect} with {\it wait} set to false.

\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}

WaitOnConnect returns true if the connection request completes. This
does not necessarily mean that the connection was successfully 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:

\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 as needed.
}
bool success = client->IsConnected();
\end{verbatim}

\wxheading{See also}

\helpref{wxSocketClient::Connect}{wxsocketclientconnect}, 
\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait}, 
\helpref{wxSocketBase::IsConnected}{wxsocketbaseisconnected}

% ---------------------------------------------------------------------------
% CLASS: wxSocketEvent
% ---------------------------------------------------------------------------
\section{\class{wxSocketEvent}}\label{wxsocketevent}

This event class contains information about socket events.

\wxheading{Derived from}

\helpref{wxEvent}{wxevent}

\wxheading{Include files}

<wx/socket.h>

\wxheading{Event table macros}

To process a socket event, use these event handler macros to direct input
to member functions that take a wxSocketEvent argument.

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf EVT\_SOCKET(id, func)}}{Process a socket event, supplying the member function.}
\end{twocollist}

\wxheading{See also}

\helpref{wxSocketBase}{wxsocketbase}, 
\helpref{wxSocketClient}{wxsocketclient}, 
\helpref{wxSocketServer}{wxsocketserver}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxSocketEvent::wxSocketEvent}\label{wxsocketeventctor}

\func{}{wxSocketEvent}{\param{int}{ id = 0}}

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}

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::GetSocketEvent}\label{wxsocketeventgetsocketevent}

\constfunc{wxSocketNotify}{GetSocketEvent}{\void}

Returns the socket event type.