* Stream doc.

[wxWidgets.git] / docs / latex / wx / socket.tex

\section{\class{wxSocketBase}}\label{wxsocketbase}

\wxheading{Derived from}

\helpref{wxEvtHandler}{wxevthandler}

% ---------------------------------------------------------------------------
% Event handling
% ---------------------------------------------------------------------------
\wxheading{Event handling}

To process events from a socket, use the following event handler macro to direct
 input to member
functions that take a \helpref{wxSocketEvent}{wxsocketevent} argument.

\twocolwidtha{7cm}%
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf EVT\_SOCKET(id, func)}}{A socket event occured.}
\end{twocollist}%

% ---------------------------------------------------------------------------
% See also ...
% ---------------------------------------------------------------------------
\wxheading{See also}

\helpref{wxSocketEvent}{wxsocketevent}\\
\helpref{wxSocketClient}{wxsocketclient}\\
\helpref{wxSocketServer}{wxsocketserver}

% ---------------------------------------------------------------------------
% Members
% ---------------------------------------------------------------------------
\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxSocketBase::wxSocketBase}

\func{}{wxSocketBase}{\void}

Default constructor but don't use it, you must use \helpref{wxSocketClient}{wxsocketclient}
or \helpref{wxSocketServer}{wxsocketserver}.

\membersection{wxSocketBase::\destruct{wxSocketBase}}

\func{}{\destruct{wxSocketBase}}{\void}

Destroys the wxSocketBase object.

% ---------------------------------------------------------------------------
% State functions
% ---------------------------------------------------------------------------

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

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

Returns TRUE if the socket is initialized and ready and FALSE in other
cases.

\membersection{wxSocketBase::Error}\label{wxsocketbaseerror}

\constfunc{bool}{Error}{\void}

Returns TRUE if an error occured.

\membersection{wxSocketBase::IsConnected}\label{wxsocketbaseconnected}

\constfunc{bool}{IsConnected}{\void}

Returns TRUE if the socket is connected.

\membersection{wxSocketBase::IsData}\label{wxsocketbaseisdata}

\constfunc{bool}{IsData}{\void}

Returns TRUE if some data is arrived on the socket. 

\membersection{wxSocketBase::IsDisconnected}\label{wxsocketbasedisconnected}

\constfunc{bool}{IsDisconnected}{\void}

Returns TRUE if the socket is disconnected.

\membersection{wxSocketBase::IsNoWait}\label{wxsocketbasenowait}

\constfunc{bool}{IsNoWait}{\void}

Returns TRUE if the socket mustn't wait.

\membersection{wxSocketBase::LastCount}\label{wxsocketbaselastcount}

\constfunc{size\_t}{LastCount}{\void}

Returns the number of bytes read or written by the last IO call.

\membersection{wxSocketBase::LastError}\label{wxsocketbaselasterror}

\constfunc{int}{LastError}{\void}

Returns an error in the errno format (see your C programmer's guide).

% ---------------------------------------------------------------------------
% IO calls
% ---------------------------------------------------------------------------
%
% Peek
%
\membersection{wxSocketBase::Peek}\label{wxsocketbasepeek}

\func{wxSocketBase\&}{Peek}{\param{char *}{ buffer}, \param{size\_t}{ nbytes}}

This function peeks a buffer of {\it nbytes} bytes from the socket. Peeking a buffer
doesn't delete it from the system socket in-queue.

\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{See also}

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

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

\func{wxSocketBase\&}{Read}{\param{char *}{ buffer}, \param{size\_t}{ nbytes}}

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

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

By default, Read uses an internal asynchronous manager: it will send data when
the socket requests them. It is particularly interesting when you enter a long
data transfer (e.g. a big file, an image, ...). But it is also buggy when you
simply discuss with the peer using user data. In this case, wxSocket prepares
itself to send data (Write wait for them to be sent) and during a GUI refresh
the user enters new data, which involves a new Read call though the previous
isn't finished. Well, in most cases it can work but it might fail too.
So I advise you to use the SPEED flag, which disables the asynchronous manager,
when you just want to discuss with the peer.

This remark is also valid for all IO call.

\wxheading{See also}

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

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

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxSocketBase::NONE}}{Normal functionnalities.}
\twocolitem{{\bf wxSocketBase::NOWAIT}}{Get the available data in the input queue and exit immediately.}
\twocolitem{{\bf wxSocketBase::WAITALL}}{Wait for all required data unless an error occured.}
\twocolitem{{\bf wxSocketBase::SPEED}}{Disable the asynchronous IO functionnality.}
\end{twocollist}

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

\func{wxSocketBase\&}{Write}{\param{const char *}{ buffer}, \param{size\_t}{ nbytes}}

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

\wxheading{Remark/Warning}

By default, Write uses an internal asynchronous manager: it will send data when
the socket requests them. It is particularly interesting when you enter a long
data transfer (e.g. a big file, an image, ...). But it is also buggy when you
simply discuss with the peer using user data. In this case, wxSocket prepares
itself to send data (Write wait for them to be sent) and during a GUI refresh
the user enters new data, which involves a new Write call though the previous
isn't finished. Well, in most cases it can work but it might fail too.  
So I advise you to use the SPEED flag, which disables the asynchronous manager,
when you just want to discuss with the peer.

\wxheading{Parameters}

\docparam{buffer}{Buffer where to get the data to write.}

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

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

\func{wxSocketBase\&}{WriteMsg}{\param{const char *}{ buffer}, \param{size\_t}{ nbytes}}

This function writes a buffer of {\it nbytes} bytes from the socket. But it
writes a short header before so that ReadMsg can alloc the right size for
the buffer. So a buffer sent with WriteMsg {\bf must} be read with ReadMsg.

\wxheading{Parameters}

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

\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}\\
\helpref{wxSocketBase::ReadMsg}{wxsocketbasereadmsg}

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

\func{wxSocketBase\&}{ReadMsg}{\param{char *}{ buffer}, \param{size\_t}{ nbytes}}

This function reads a buffer sent by WriteMsg on a socket. If the buffer passed
to the function isn't big enough, the function filled it and then discard the
bytes left. This function always wait for the buffer to be entirely filled.

\wxheading{Parameters}

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

\docparam{nbytes}{Number of bytes allocated for the buffer.}

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

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

\func{wxSocketBase\&}{UnRead}{\param{const char *}{ buffer}, \param{size\_t}{ nbytes}}

This function unreads a buffer. It means that the buffer is put in the top
of the incoming queue. But, it is put also at the end of all unread buffers.
It is useful for sockets because we can't seek it.

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

%
% Discard
%
\membersection{wxSocketBase::Discard}\label{wxsocketbasediscard}

\func{wxSocketBase\&}{Discard}{\void}

This function simply deletes all bytes in the incoming queue. This function
doesn't wait.

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

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

This function waits for an event: it could be an incoming byte, the possibility
for the client to write, a lost connection, an incoming connection, an
established connection.

\wxheading{Parameters}

\docparam{seconds}{Number of seconds to wait. By default, it waits infinitely.}

\docparam{microsecond}{Number of microseconds to wait.}

\wxheading{Return value}

Returns TRUE if an event occured, FALSE if the timeout was reached.

\wxheading{See also}

\helpref{wxSocketBase::WaitForRead}{wxsocketbasewaitforread}\\
\helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite}\\
\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost}

%
% WaitForRead
%
\membersection{wxSocketBase::WaitForRead}\label{wxsocketbasewaitforread}

\func{bool}{WaitForRead}{\param{long}{ seconds = -1}, \param{long}{ microsecond = 0}}

This function waits for a read event.

\wxheading{Parameters}

\docparam{seconds}{Number of seconds to wait. By default, it waits infinitely.}

\docparam{microsecond}{Number of microseconds to wait.}

\wxheading{Return value}

Returns TRUE if a byte arrived, FALSE if the timeout was reached.

\wxheading{See also}

\helpref{wxSocketBase::Wait}{wxsocketbasewait}\\
\helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite}\\
\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost}

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

\func{bool}{WaitForWrite}{\param{long}{ seconds = -1}, \param{long}{ microsecond = 0}}

This function waits for a write event.

\wxheading{Parameters}

\docparam{seconds}{Number of seconds to wait. By default, it waits infinitely.}

\docparam{microsecond}{Number of microseconds to wait.}

\wxheading{Return value}

Returns TRUE if a write event occured, FALSE if the timeout was reached.

\wxheading{See also}

\helpref{wxSocketBase::Wait}{wxsocketbasewait}\\
\helpref{wxSocketBase::WaitForRead}{wxsocketbasewaitforread}\\
\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost}

%
% WaitForLost
%
\membersection{wxSocketBase::WaitForLost}\label{wxsocketbasewaitforlost}

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

This function waits for a "lost" event. For instance, the peer may have closed
the connection, or the connection may have been broken.

\wxheading{Parameters}

\docparam{seconds}{Number of seconds to wait. By default, it waits infinitely.}

\docparam{microsecond}{Number of microseconds to wait.}

\wxheading{Return value}

Returns TRUE if a "lost" event occured, FALSE if the timeout was reached.

\wxheading{See also}

\helpref{wxSocketBase::WaitForRead}{wxsocketbasewaitforread}\\
\helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite}\\
\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost}

%
% RestoreState
%
\membersection{wxSocketBase::RestoreState}\label{wxsocketbaserestorestate}

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

This function restores a previously saved state.

\wxheading{See also}

\helpref{wxSocketBase::SaveState}{wxsocketbasesavestate}

% ---------------------------------------------------------------------------
% Socket state
% ---------------------------------------------------------------------------
%
% SaveState
%
\membersection{wxSocketBase::SaveState}\label{wxsocketbasesavestate}

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

This function saves the current state of the socket object in a stack:
actually it saves all flags and the state of the asynchronous callbacks. 

\wxheading{See also}

\helpref{wxSocketBase::RestoreState}{wxsocketbaserestorestate}

% ---------------------------------------------------------------------------
% Socket callbacks
% ---------------------------------------------------------------------------
\membersection{wxSocketBase::SetEventHandler}\label{wxsocketbaseseteventhandler}

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

Sets an event handler to be called when a socket event occured.

\wxheading{Parameters}

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

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

\wxheading{See also}

\helpref{wxSocketEvent}{wxsocketevent}

% ---------------------------------------------------------------------------
% CLASS wxSocketClient
% ---------------------------------------------------------------------------
\section{\class{wxSocketClient}}\label{wxsocketclient}

\wxheading{Derived from}

\helpref{wxSocketBase}{wxsocketbase}

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

\func{}{wxSocketClient}{\param{wxSockFlags}{ flags = wxSocketBase::NONE}}

Constructs a new wxSocketClient.

{\bf Warning !} The created socket client needs to be registered to a socket handler (See \helpref{wxSocketHandler}{wxsockethandler}).

\wxheading{Parameters}

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

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

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

Destructs a wxSocketClient object.

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

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

Connects to a server using the specified address. If {\it wait} is TRUE, Connect
will wait for the socket ready to send or receive data.

\wxheading{Parameters}

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

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

\wxheading{Return value}

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

\wxheading{See also}

\helpref{wxSocketClient::WaitOnConnect}{wxsocketclientwaitonconnect}

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

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

Wait for a "connect" event.

\wxheading{See also}

\helpref{wxSocketBase::Wait}{wxsocketbasewait} for a detailed description.

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

This event class contains information about socket events.

\wxheading{Derived from}

\helpref{wxEvent}{wxevent}

\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{wxSocketHandler}{wxsockethandler},\rtfsp
\helpref{wxSocketBase}{wxsocketbase},\rtfsp
\helpref{wxSocketClient}{wxsocketclient},\rtfsp
\helpref{wxSocketServer}{wxsocketserver}

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

\membersection{wxSocketEvent::wxSocketEvent}

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

Constructor.

\membersection{wxSocketEvent::SocketEvent}\label{wxsocketeventsocketevent}

\constfunc{wxSocketBase::wxRequestEvent}{SocketEvent}{\void}

Returns the socket event type.

% ---------------------------------------------------------------------------
% CLASS: wxSocketHandler
% ---------------------------------------------------------------------------
\section{\class{wxSocketHandler}}\label{wxsockethandler}

\wxheading{Derived from}

\helpref{wxObject}{wxobject}

% ---------------------------------------------------------------------------
% Members
% ---------------------------------------------------------------------------
\latexignore{\rtfignore{\wxheading{Members}}}

%
% wxSocketHandler
%
\membersection{wxSocketHandler::wxSocketHandler}

\func{}{wxSocketHandler}{\void}

Constructs a new wxSocketHandler.

It is advised to use \helpref{wxSocketHandler::Master}{wxsockethandlermaster} to
get a socket handler. But creating a socket handler is useful to group
many sockets.

%
% ~wxSocketHandler
%
\membersection{wxSocketHandler::\destruct{wxSocketHandler}}

\func{}{\destruct{wxSocketHandler}}{\void}

Destructs a wxSocketHandler object.

%
% Register
%
\membersection{wxSocketHandler::Register}

\func{void}{Register}{\param{wxSocketBase *}{socket}}

Register a socket: if it is already registered in this handler it will just
return immediately.

\wxheading{Parameters}

\docparam{socket}{Socket to be registered.}

%
% UnRegister
%
\membersection{wxSocketHandler::UnRegister}

\func{void}{UnRegister}{\param{wxSocketBase *}{socket}}

UnRegister a socket: if it isn't registered in this handler it will just
return.

\wxheading{Parameters}

\docparam{socket}{Socket to be unregistered.}

%
% Count
%
\membersection{wxSocketHandler::Count}

\constfunc{unsigned long}{Count}{\void}

Returns the number of sockets registered in the handler.

\wxheading{Return value}

Number of sockets registered.

%
% CreateServer
%
\membersection{wxSocketHandler::CreateServer}

\func{wxSocketServer *}{CreateServer}{\param{wxSockAddress\&}{ address}, \param{wxSocketBase::wxSockFlags}{ flags = wxSocketbase::NONE}}

Creates a new wxSocketServer object. The object is automatically registered
to the current socket handler.
For a detailed description of the parameters, see \helpref{wxSocketServer::wxSocketServer}{wxsocketserverconstr}.

\wxheading{Return value}

Returns a new socket server.

%
% CreateClient
%
\membersection{wxSocketHandler::CreateClient}

\func{wxSocketServer *}{CreateClient}{\param{wxSocketBase::wxSockFlags}{ flags = wxSocketbase::NONE}}

Creates a new wxSocketClient object. The object is automatically registered
to the current socket handler.

For a detailed description of the parameters, see \helpref{wxSocketClient::Connect}{wxsocketclientconnect}.

\wxheading{Return value}

Returns a new socket client.

%
% Master
%
\membersection{wxSocketHandler::Master}\label{wxsockethandlermaster}

\func{static wxSocketHandler\&}{Master}{\void}

Returns a default socket handler.

%
% Wait
%
\membersection{wxSocketHandler::Wait}

\func{int}{Wait}{\param{long}{ seconds},\param{long}{ microseconds}}

Wait for an event on all registered sockets.

\wxheading{Parameters}

\docparam{seconds}{Number of seconds to wait. By default, it waits infinitely.}

\docparam{microsecond}{Number of microseconds to wait.}

\wxheading{Return value}

Returns 0 if a timeout occured, else the number of events detected.

\wxheading{See also}

\helpref{wxSocketBase::Wait}{wxsocketbasewait}

%
% YieldSock
%
\membersection{wxSocketHandler::YieldSock}

\func{void}{YieldSock}{\void}

Execute pending requests in all registered sockets.

% ---------------------------------------------------------------------------
% CLASS: wxSocketServer
% ---------------------------------------------------------------------------
\section{\class{wxSocketServer}}\label{wxsocketserver}

\wxheading{Derived from}

\helpref{wxSocketBase}{wxsocketbase}

% ---------------------------------------------------------------------------
% Members
% ---------------------------------------------------------------------------
\latexignore{\rtfignore{\wxheading{Members}}}

%
% wxSocketServer
%
\membersection{wxSocketServer::wxSocketServer}\label{wxsocketserverconstr}

\func{}{wxSocketServer}{\param{wxSockAddress\&}{ address}, \param{wxSockFlags}{ flags = wxSocketBase::NONE}}

Constructs a new wxSocketServer.

{\bf Warning !} The created object needs to be registered to a socket handler
(see \helpref{wxSocketHandler}{wxsockethandler}).

\wxheading{Parameters}

\docparam{address}{Specifies the local address for the server (e.g. port number).}

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

%
% ~wxSocketServer
%
\membersection{wxSocketServer::\destruct{wxSocketServer}}

\func{}{\destruct{wxSocketServer}}{\void}

Destructs a wxSocketServer object (it doesn't close the accepted connection).

%
% Accept
%
\membersection{wxSocketServer::Accept}

\func{wxSocketBase *}{Accept}{\void}

Creates a new object wxSocketBase and accepts an incoming connection. {\bf Warning !} This function will block the GUI.

\wxheading{Return value}

Returns an opened socket connection.

\wxheading{See also}

\helpref{wxSocketServer::AcceptWith}{wxsocketserveracceptwith}

%
% AcceptWith
%
\membersection{wxSocketServer::AcceptWith}\label{wxsocketserveracceptwith}

\func{bool}{AcceptWith}{\param{wxSocketBase\&}{ socket}}

Accept an incoming connection using the specified socket object.
This is useful when someone wants to inherit wxSocketBase.

\wxheading{Parameters}

\docparam{socket}{Socket to be initialized}

\wxheading{Return value}

Returns TRUE if no error occurs, else FALSE.