Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated to reflect latest changes

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@6597 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Guillermo Rodriguez Garcia
2000-03-10 17:59:20 +00:00
parent 27d0ab2482
commit 5adbbc2995
2 changed files with 146 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
docs/latex/wx/socket.tex
View File

@@ -16,7 +16,7 @@ defines all basic IO functionality.
\wxheading{Derived from}
\helpref{wxEvtHandler}{wxevthandler}
\helpref{wxObject}{wxobject}
\wxheading{Include files}
@@ -139,13 +139,20 @@ Functions that perform basic IO functionality.
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}
@@ -155,11 +162,14 @@ Functions that allow applications to receive socket events.
\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}
@@ -188,8 +198,8 @@ Default constructor. Don't use it directly; instead, use
\func{}{\destruct{wxSocketBase}}{\void}
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.
use \helpref{Destroy}{wxsocketbasedestroy} instead. Also, do not create
socket objects in the stack.
%
% Callback
@@ -211,8 +221,7 @@ void SocketCallback(wxSocketBase& sock, wxSocketNotify evt, char *cdata);
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.
@@ -312,6 +321,16 @@ Returns TRUE if an error occured in the last IO operation.
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
%
@@ -327,6 +346,15 @@ address, local port, ...).
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
%
@@ -342,6 +370,28 @@ address field contains the complete peer host address of the socket
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
%
@@ -463,8 +513,9 @@ Calls to SaveState and RestoreState can be nested.
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.
@@ -473,6 +524,18 @@ 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
%
@@ -485,11 +548,6 @@ handler will be called for those events for which notification is
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.}
@@ -502,8 +560,6 @@ See \helpref{Callback}{wxsocketbasecallback} and
\helpref{wxSocketBase::Notify}{wxsocketbasenotify},
\helpref{wxSocketEvent}{wxsocketevent},
\helpref{wxEvtHandler}{wxevthandler},
\helpref{wxSocketBase::Callback}{wxsocketbasecallback},
\helpref{wxSocketBase::CallbackData}{wxsocketbasecallbackdata}
%
% SetFlags
@@ -512,6 +568,10 @@ See \helpref{Callback}{wxsocketbasecallback} and
\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
\twocolitem{{\bf wxSOCKET\_NONE}}{Normal functionality.}
@@ -783,9 +843,39 @@ 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{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost}
\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
@@ -814,9 +904,8 @@ Returns TRUE if the socket becomes readable, FALSE on timeout.
\wxheading{See also}
\helpref{wxSocketBase::Wait}{wxsocketbasewait},
\helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite},
\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost}
\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
\helpref{wxSocketBase::Wait}{wxsocketbasewait}
%
% WaitForWrite
@@ -845,37 +934,8 @@ Returns TRUE if the socket becomes writable, FALSE on timeout.
\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}{ 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::WaitForRead}{wxsocketbasewaitforread},
\helpref{wxSocketBase::WaitForWrite}{wxsocketbasewaitforwrite},
\helpref{wxSocketBase::WaitForLost}{wxsocketbasewaitforlost}
\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
\helpref{wxSocketBase::Wait}{wxsocketbasewait}
%
% Write
@@ -1085,6 +1145,7 @@ bool success = client->IsConnected();
\wxheading{See also}
\helpref{wxSocketClient::Connect}{wxsocketclientconnect},
\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait},
\helpref{wxSocketBase::IsConnected}{wxsocketbaseisconnected}
% ---------------------------------------------------------------------------
@@ -1126,6 +1187,13 @@ functions that take a wxSocketEvent argument.
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}
@@ -1269,5 +1337,6 @@ Returns TRUE if an incoming connection arrived, FALSE if the timeout elapsed.
\wxheading{See also}
\helpref{wxSocketServer::Accept}{wxsocketserveraccept},
\helpref{wxSocketServer::AcceptWith}{wxsocketserveracceptwith}
\helpref{wxSocketServer::AcceptWith}{wxsocketserveracceptwith},
\helpref{wxSocketBase::InterruptWait}{wxsocketbaseinterruptwait}

47
docs/latex/wx/tsamples.tex
View File

@@ -287,22 +287,22 @@ The sample also provides some timings for adding/deleting/sorting a lot of
The sockets sample demonstrates how to use the communication facilities
provided by \helpref{wxSocket}{wxsocketbase}. There are two different
applications in this sample: a server, which is implemented as a
\helpref{wxSocketServer}{wxsocketserver} object, and a client, which is
implemented with \helpref{wxSocketClient}{wxsocketclient}.
applications in this sample: a server, which is implemented using a
\helpref{wxSocketServer}{wxsocketserver} object, and a client, which
is implemented as a \helpref{wxSocketClient}{wxsocketclient}.
The server binds to the local address, using TCP port number 3000, sets
up an event handler to be notified of incoming connection requests
({\bf wxSOCKET\_CONNECTION} event), and stands there, waiting (listening
in the socket parlance) for clients. For each incoming client, a new
\helpref{wxSocketBase}{wxsocketbase} object is created, which represents
the connection. Connections are independent from the server that created
them, so they set up their own event handler, and stay awaiting for
{\bf wxSOCKET\_INPUT} (incoming data) or {\bf wxSOCKET\_LOST} (connection
closed at the remote end) events. This event handler is the same for all
connections, and demonstrates how to determine which socket the event
is addressed to by using the \helpref{Socket}{wxsocketeventsocket} function
in the \helpref{wxSocketEvent}{wxsocketevent} class.
The server binds to the local address, using TCP port number 3000,
sets up an event handler to be notified of incoming connection requests
({\bf wxSOCKET\_CONNECTION} events), and stands there, waiting for clients
({\it listening} in the socket parlance). For each accepted connection,
a new \helpref{wxSocketBase}{wxsocketbase} object is created. These
socket objects are independent from the server that created them, so
they set up their own event handler, and then request to be notified
of {\bf wxSOCKET\_INPUT} (incoming data) or {\bf wxSOCKET\_LOST}
(connection closed at the remote end) events. In the sample, the event
handler is the same for all connections; to find out which socket the
event is addressed to, the \helpref{GetSocket}{wxsocketeventgetsocket}
function is used.
Although it might take some time to get used to the event-oriented
system upon which wxSocket is built, the benefits are many. See, for
@@ -318,21 +318,20 @@ how to use the basic IO calls in \helpref{wxSocketBase}{wxsocketbase},
such as \helpref{Read}{wxsocketbaseread}, \helpref{Write}{wxsocketbasewrite},
\helpref{ReadMsg}{wxsocketbasereadmsg} and \helpref{WriteMsg}{wxsocketbasewritemsg},
and how to set up the correct IO flags depending on what you are going to
do. See the comments in the code for more information (a lengthy explanation
on socket flags is available in \helpref{SetFlags}{wxsocketbasesetflags}).
Note that because both clients and connection objects in the server set
up an event handler to catch {\bf wxSOCKET\_LOST} events, each one is
immediately notified if the other end closes the connection.
do. See the comments in the code for more information. Note that because
both clients and connection objects in the server set up an event handler
to catch {\bf wxSOCKET\_LOST} events, each one is immediately notified
if the other end closes the connection.
There is also an URL test which demonstrates how to use the \helpref{wxURL}{wxurl}
class.
There is also an URL test which shows how to use the \helpref{wxURL}{wxurl}
class to fetch data from a given URL.
The sockets sample is work in progress. Coming soon:
The sockets sample is work in progress. Some things to do:
\begin{itemize}\itemsep=0pt
\item More tests for basic socket functionality.
\item More tests for protocol classes (wxProtocol and its descendants).
\item Tests for the recently added datagram socket classes.
\item Tests for the recently added (and still in alpha stage) datagram sockets.
\item New samples which actually do something useful (suggestions accepted).
\end{itemize}