socket.tex

Wxpython Implemented on Windows CE, Source code

Use \helpref{Error}{wxsocketbaseerror} first, in order to determine
if the last IO call failed. If this returns true, use LastError
to discover the cause of the error.

%
% Notify
%
\membersection{wxSocketBase::Notify}\label{wxsocketbasenotify}

\func{void}{Notify}{\param{bool}{ notify}}

According to the {\it notify} value, this function enables
or disables socket events. If {\it notify} is true, the events
configured with \helpref{SetNotify}{wxsocketbasesetnotify} will
be sent to the application. If {\it notify} is false; no events
will be sent.

% 
% Ok
%
\membersection{wxSocketBase::Ok}\label{wxsocketbaseok}

\constfunc{bool}{Ok}{\void}

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::RestoreState}\label{wxsocketbaserestorestate}

\func{void}{RestoreState}{\void}

This function restores the previous state of the socket, as saved
with \helpref{SaveState}{wxsocketbasesavestate}

Calls to SaveState and RestoreState can be nested.

\wxheading{See also}

\helpref{wxSocketBase::SaveState}{wxsocketbasesavestate}

%
% SaveState
%
\membersection{wxSocketBase::SaveState}\label{wxsocketbasesavestate}

\func{void}{SaveState}{\void}

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}, user data, as set with 
\helpref{SetClientData}{wxsocketbasesetclientdata}.

Calls to SaveState and RestoreState can be nested.

\wxheading{See also}

\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
%
\membersection{wxSocketBase::SetEventHandler}\label{wxsocketbaseseteventhandler}

\func{void}{SetEventHandler}{\param{wxEvtHandler\&}{ handler}, \param{int}{ id = -1}}

Sets an event handler to be called when a socket event occurs. The
handler will be called for those events for which notification is
enabled with \helpref{SetNotify}{wxsocketbasesetnotify} and 
\helpref{Notify}{wxsocketbasenotify}.

\wxheading{Parameters}

\docparam{handler}{Specifies the event handler you want to use.}

\docparam{id}{The id of socket event.}

\wxheading{See also}

\helpref{wxSocketBase::SetNotify}{wxsocketbasesetnotify}, 
\helpref{wxSocketBase::Notify}{wxsocketbasenotify}, 
\helpref{wxSocketEvent}{wxsocketevent}, 
\helpref{wxEvtHandler}{wxevthandler}

%
% SetFlags
%
\membersection{wxSocketBase::SetFlags}\label{wxsocketbasesetflags}

\func{void}{SetFlags}{\param{wxSocketFlags}{ flags}}

Use SetFlags to customize IO operation for this socket.
The {\it flags} parameter may be a combination of flags ORed together.
The following flags can be used:

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxSOCKET\_NONE}}{Normal functionality.}
\twocolitem{{\bf wxSOCKET\_NOWAIT}}{Read/write as much data as possible and return immediately.}
\twocolitem{{\bf wxSOCKET\_WAITALL}}{Wait for all required data to be read/written unless an error occurs.}
\twocolitem{{\bf wxSOCKET\_BLOCK}}{Block the GUI (do not yield) while reading/writing data.}
\twocolitem{{\bf wxSOCKET\_REUSEADDR}}{Allows the use of an in-use port (wxServerSocket only)}
\end{twocollist}

A brief overview on how to use these flags follows.

If no flag is specified (this is the same as {\bf wxSOCKET\_NONE}),
IO calls will return after some data has been read or written, even
when the transfer might not be complete. This is the same as issuing
exactly one blocking low-level call to recv() or send(). Note
that {\it blocking} here refers to when the function returns, not
to whether the GUI blocks during this time.

If {\bf wxSOCKET\_NOWAIT} is specified, IO calls will return immediately.
Read operations will retrieve only available data. Write operations will
write as much data as possible, depending on how much space is available
in the output buffer. This is the same as issuing exactly one nonblocking
low-level call to recv() or send(). Note that {\it nonblocking} here
refers to when the function returns, not to whether the GUI blocks during
this time.

If {\bf wxSOCKET\_WAITALL} is specified, IO calls won't return until ALL
the data has been read or written (or until an error occurs), blocking if
necessary, and issuing several low level calls if necessary. This is the
same as having a loop which makes as many blocking low-level calls to
recv() or send() as needed so as to transfer all the data. Note
that {\it blocking} here refers to when the function returns, not
to whether the GUI blocks during this time.

The {\bf wxSOCKET\_BLOCK} flag controls whether the GUI blocks during
IO operations. If this flag is specified, the socket will not yield
during IO calls, so the GUI will remain blocked until the operation
completes. If it is not used, then the application must take extra
care to avoid unwanted reentrance.

The {\bf wxSOCKET\_REUSEADDR} flag controls the use of the SO\_REUSEADDR standard
setsockopt() flag. This flag allows the socket to bind to a port that is already in use.
This is mostly used on UNIX-based systems to allow rapid starting and stopping of a server - 
otherwise you may have to wait several minutes for the port to become available.
wxSOCKET\_REUSEADDR can also be used with socket clients to (re)bind to a particular local port
for an outgoing connection.
This option can have surprising platform dependent behavior, so check the documentation for
your platform's implementation of setsockopt(). Note that on BSD-based systems (e.g. Mac OS X),
use of wxSOCKET\_REUSEADDR implies SO\_REUSEPORT in addition to SO\_REUSEADDR to be consistent
with Windows.

So:

{\bf wxSOCKET\_NONE} will try to read at least SOME data, no matter how much.

{\bf wxSOCKET\_NOWAIT} will always return immediately, even if it cannot
read or write ANY data.

{\bf wxSOCKET\_WAITALL} will only return when it has read or written ALL
the data.

{\bf wxSOCKET\_BLOCK} has nothing to do with the previous flags and
it controls whether the GUI blocks.

{\bf wxSOCKET\_REUSEADDR} controls special platform-specific behavior for
reusing local addresses/ports.

%
% SetLocal
%
\membersection{wxSocketBase::SetLocal}\label{wxsocketbasesetlocal}

\func{bool}{SetLocal}{\param{wxIPV4address\&}{ local}}

This function allows you to set the local address and port,
useful when an application needs to reuse a particular port. When
a local port is set for a \helpref{wxSocketClient}{wxsocketclient},
{\bf bind} will be called before {\bf connect}.

%
% SetNotify
%
\membersection{wxSocketBase::SetNotify}\label{wxsocketbasesetnotify}

\func{void}{SetNotify}{\param{wxSocketEventFlags}{ flags}}

SetNotify specifies which socket events are to be sent to the event handler.
The {\it flags} parameter may be combination of flags ORed together. The
following flags can be used:

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxSOCKET\_INPUT\_FLAG}}{to receive wxSOCKET\_INPUT}
\twocolitem{{\bf wxSOCKET\_OUTPUT\_FLAG}}{to receive wxSOCKET\_OUTPUT}
\twocolitem{{\bf wxSOCKET\_CONNECTION\_FLAG}}{to receive wxSOCKET\_CONNECTION}
\twocolitem{{\bf wxSOCKET\_LOST\_FLAG}}{to receive wxSOCKET\_LOST}
\end{twocollist}

For example:

\begin{verbatim}
  sock.SetNotify(wxSOCKET_INPUT_FLAG | wxSOCKET_LOST_FLAG);
  sock.Notify(true);
\end{verbatim}

In this example, the user will be notified about incoming socket data and
whenever the connection is closed.

For more information on socket events see \helpref{wxSocket events}{wxsocketbase}.

%
% SetTimeout
%
\membersection{wxSocketBase::SetTimeout}\label{wxsocketbasesettimeout}

\func{void}{SetTimeout}{\param{int }{seconds}}

This function sets the default socket timeout in seconds. This timeout
applies to all IO calls, and also to the \helpref{Wait}{wxsocketbasewait} family
of functions if you don't specify a wait interval. Initially, the default
timeout is 10 minutes.

%
% Peek
%
\membersection{wxSocketBase::Peek}\label{wxsocketbasepeek}

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

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

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

\wxheading{Parameters}

\docparam{buffer}{Buffer where to put peeked data.}

\docparam{nbytes}{Number of bytes.}

\wxheading{Return value}

Returns a reference to the current object.

\wxheading{Remark/Warning}

The exact behaviour of wxSocketBase::Peek 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}

%
% Read
%
\membersection{wxSocketBase::Read}\label{wxsocketbaseread}

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

This function reads a buffer of {\it nbytes} bytes from the socket.

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

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

\wxheading{Parameters}

\docparam{buffer}{Buffer where to put read data.}

\docparam{nbytes}{Number of bytes.}

\wxheading{Return value}

Returns a reference to the current object.

\wxheading{Remark/Warning}

The exact behaviour of wxSocketBase::Read 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}

%
% ReadMsg
%
\membersection{wxSocketBase::ReadMsg}\label{wxsocketbasereadmsg}

\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
remaining bytes will be discarded. This function always waits for the
buffer to be entirely filled, unless an error occurs.

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

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

\wxheading{Parameters}

\docparam{buffer}{Buffer where to put read data.}

\docparam{nbytes}{Size of the buffer.}

\wxheading{Return value}

Returns a reference to the current object.

\wxheading{Remark/Warning}

wxSocketBase::ReadMsg 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 ReadMsg 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::WriteMsg}{wxsocketbasewritemsg}

%
% Unread
%
\membersection{wxSocketBase::Unread}\label{wxsocketbaseunread}

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

If you use \helpref{LastCount}{wxsocketbaselastcount}, it will always return {\it nbytes}.

If you use \helpref{Error}{wxsocketbaseerror}, it will always return false.

\wxheading{Parameters}

\docparam{buffer}{Buffer to be unread.}

\docparam{nbytes}{Number of bytes.}

\wxheading{Return value}

Returns a reference to the current object.

\wxheading{See also}

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

%
% Wait
%
\membersection{wxSocketBase::Wait}\label{wxsocketbasewait}

\func{bool}{Wait}{\param{long}{ seconds = -1}, \param{long}{ millisecond = 0}}

This function waits until any of the following conditions is true:
                                            
\begin{itemize}
\item The socket becomes readable.
\item The socket becomes writable.
\item An ongoing connection request has completed (\helpref{wxSocketClient}{wxsocketclient} only)