Some documentation enhancements for wxRichTextCtrl

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

diff --git a/docs/latex/wx/socket.tex b/docs/latex/wx/socket.tex
index 41936b4a603f415b085f1260be3adee84f1a6773..de3c5c5a88d708c04dbe246862400fdead31745f 100644 (file)
--- a/docs/latex/wx/socket.tex
+++ b/docs/latex/wx/socket.tex
@@ -6,7 +6,7 @@
 %% Created:     1999
 %% RCS-ID:      $Id$
 %% Copyright:   (c) wxWidgets team
 %% Created:     1999
 %% RCS-ID:      $Id$
 %% Copyright:   (c) wxWidgets team

-%% License:     wxWidgets license
+%% License:     wxWindows license

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


@@ -14,6 +14,13 @@
 wxSocketBase is the base class for all socket-related objects, and it
 defines all basic IO functionality.
 
 wxSocketBase is the base class for all socket-related objects, and it
 defines all basic IO functionality.
 

+Note: (Workaround for implementation limitation for wxWidgets up to 2.5.x)
+If you want to use sockets or derived classes such as wxFTP in a secondary thread,
+call wxSocketBase::Initialize() (undocumented) from the main thread before creating 
+any sockets - in wxApp::OnInit for example. 
+See http://wiki.wxwidgets.org/wiki.pl?WxSocket or
+http://www.litwindow.com/knowhow/knowhow.html for more details.
+

 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}


@@ -102,13 +109,13 @@ a \helpref{wxSocketEvent}{wxsocketevent} argument.
 
 \latexignore{\rtfignore{\wxheading{Function groups}}}
 
 
 \latexignore{\rtfignore{\wxheading{Function groups}}}
 

-\membersection{Construction and destruction}
+\membersection{Construction and destruction}\label{socketconstruction}

 
 \helpref{wxSocketBase}{wxsocketbaseconstruct}\\
 \helpref{\destruct{wxSocketBase}}{wxsocketbasedestruct}\\
 \helpref{Destroy}{wxsocketbasedestroy}
 
 
 \helpref{wxSocketBase}{wxsocketbaseconstruct}\\
 \helpref{\destruct{wxSocketBase}}{wxsocketbasedestruct}\\
 \helpref{Destroy}{wxsocketbasedestroy}
 

-\membersection{Socket state}
+\membersection{Socket state}\label{socketstate}

 
 Functions to retrieve current state and miscellaneous info.
 
 
 Functions to retrieve current state and miscellaneous info.
 


@@ -120,11 +127,11 @@ Functions to retrieve current state and miscellaneous info.
 \helpref{IsDisconnected}{wxsocketbaseisdisconnected}\\
 \helpref{LastCount}{wxsocketbaselastcount}\\
 \helpref{LastError}{wxsocketbaselasterror}\\
 \helpref{IsDisconnected}{wxsocketbaseisdisconnected}\\
 \helpref{LastCount}{wxsocketbaselastcount}\\
 \helpref{LastError}{wxsocketbaselasterror}\\

-\helpref{Ok}{wxsocketbaseok}\\
+\helpref{IsOk}{wxsocketbaseisok}\\

 \helpref{SaveState}{wxsocketbasesavestate}\\
 \helpref{RestoreState}{wxsocketbaserestorestate}
 
 \helpref{SaveState}{wxsocketbasesavestate}\\
 \helpref{RestoreState}{wxsocketbaserestorestate}
 

-\membersection{Basic IO}
+\membersection{Basic IO}\label{socketbasicio}

 
 Functions that perform basic IO functionality.
 
 
 Functions that perform basic IO functionality.
 


@@ -154,9 +161,10 @@ Functions that allow applications to customize socket IO as needed.
 
 \helpref{GetFlags}{wxsocketbasegetflags}\\
 \helpref{SetFlags}{wxsocketbasesetflags}\\
 
 \helpref{GetFlags}{wxsocketbasegetflags}\\
 \helpref{SetFlags}{wxsocketbasesetflags}\\

-\helpref{SetTimeout}{wxsocketbasesettimeout}
+\helpref{SetTimeout}{wxsocketbasesettimeout}\\
+\helpref{SetLocal}{wxsocketbasesetlocal}\\

 
 

-\membersection{Handling socket events}
+\membersection{Handling socket events}\label{socketevents}

 
 Functions that allow applications to receive socket events.
 
 
 Functions that allow applications to receive socket events.
 


@@ -166,14 +174,6 @@ Functions that allow applications to receive socket events.
 \helpref{SetClientData}{wxsocketbasesetclientdata}\\
 \helpref{SetEventHandler}{wxsocketbaseseteventhandler}
 
 \helpref{SetClientData}{wxsocketbasesetclientdata}\\
 \helpref{SetEventHandler}{wxsocketbaseseteventhandler}
 

-Callback functions are also available, but they are provided for backwards
-compatibility only. Their use is strongly discouraged in favour of events,
-and should be considered deprecated. Callbacks may be unsupported in future
-releases of wxWidgets.
-
-\helpref{Callback}{wxsocketbasecallback}\\
-\helpref{CallbackData}{wxsocketbasecallbackdata}
-

 
 % ---------------------------------------------------------------------------
 % Members here
 
 % ---------------------------------------------------------------------------
 % Members here


@@ -201,67 +201,6 @@ 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
-%
-\membersection{wxSocketBase::Callback}\label{wxsocketbasecallback}
-
-\func{wxSocketBase::wxSockCbk}{Callback}{\param{wxSocketBase::wxSockCbk}{ callback}}
-
-You can setup a callback function to be called when an event occurs.
-The function will be called only for those events for which notification
-has been enabled with \helpref{Notify}{wxsocketbasenotify} and 
-\helpref{SetNotify}{wxsocketbasesetnotify}. The prototype of the
-callback must be as follows:
-
-\begin{verbatim}
-void SocketCallback(wxSocketBase& sock, wxSocketNotify evt, char *cdata);
-\end{verbatim}
-
-The first parameter is a reference to the socket object in which the
-event occurred. The second parameter tells you which event occurred.
-(See \helpref{wxSocket events}{wxsocketbase}). The third parameter
-is the user data you specified using \helpref{CallbackData}{wxsocketbasecallbackdata}.
-
-\wxheading{Return value}
-
-A pointer to the previous callback.
-
-\wxheading{Remark/Warning}
-
-Note that callbacks are now deprecated and unsupported, and they remain
-for backwards compatibility only. Use events instead.
-
-\wxheading{See also}
-
-\helpref{wxSocketBase::CallbackData}{wxsocketbasecallbackdata}, 
-\helpref{wxSocketBase::SetNotify}{wxsocketbasesetnotify}, 
-\helpref{wxSocketBase::Notify}{wxsocketbasenotify}
-
-%
-% CallbackData
-%
-\membersection{wxSocketBase::CallbackData}\label{wxsocketbasecallbackdata}
-
-\func{char *}{CallbackData}{\param{char *}{cdata}}
-
-This function sets the the user data which will be passed to a
-callback function set via \helpref{Callback}{wxsocketbasecallback}.
-
-\wxheading{Return value}
-
-A pointer to the previous user data.
-
-\wxheading{Remark/Warning}
-
-Note that callbacks are now deprecated and unsupported, and they remain
-for backwards compatibility only. Use events instead.
-
-\wxheading{See also}
-
-\helpref{wxSocketBase::Callback}{wxsocketbasecallback}, 
-\helpref{wxSocketBase::SetNotify}{wxsocketbasesetnotify}, 
-\helpref{wxSocketBase::Notify}{wxsocketbasenotify}

 
 %
 % Close
 
 %
 % Close


@@ -475,11 +414,11 @@ be sent to the application. If {\it notify} is false; no events
 will be sent.
 
 % 
 will be sent.
 
 % 

-% Ok
+% IsOk

 %
 %

-\membersection{wxSocketBase::Ok}\label{wxsocketbaseok}
+\membersection{wxSocketBase::IsOk}\label{wxsocketbaseisok}

 
 

-\constfunc{bool}{Ok}{\void}
+\constfunc{bool}{IsOk}{\void}

 
 Returns true if the socket is initialized and ready and false in other
 cases.
 
 Returns true if the socket is initialized and ready and false in other
 cases.


@@ -523,9 +462,7 @@ 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 
 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}, and asynchronous
-callback settings, as set with \helpref{Callback}{wxsocketbasecallback} 
-and \helpref{CallbackData}{wxsocketbasecallbackdata}.
+\helpref{SetClientData}{wxsocketbasesetclientdata}.

 
 Calls to SaveState and RestoreState can be nested.
 
 
 Calls to SaveState and RestoreState can be nested.
 


@@ -586,6 +523,7 @@ The following flags can be used:
 \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\_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.
 \end{twocollist}
 
 A brief overview on how to use these flags follows.


@@ -619,6 +557,17 @@ 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.
 
 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.
 So:
 
 {\bf wxSOCKET\_NONE} will try to read at least SOME data, no matter how much.


@@ -632,6 +581,21 @@ the data.
 {\bf wxSOCKET\_BLOCK} has nothing to do with the previous flags and
 it controls whether the GUI blocks.
 
 {\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
 %
 %
 % SetNotify
 %


@@ -1046,7 +1010,7 @@ For a detailed explanation, see \helpref{wxSocketBase::SetFlags}{wxsocketbaseset
 %
 % wxSocketClient
 %
 %
 % wxSocketClient
 %

-\membersection{wxSocketClient::wxSocketClient}
+\membersection{wxSocketClient::wxSocketClient}\label{wxsocketclientctor}

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


@@ -1059,7 +1023,7 @@ Constructor.
 %
 % ~wxSocketClient
 %
 %
 % ~wxSocketClient
 %

-\membersection{wxSocketClient::\destruct{wxSocketClient}}
+\membersection{wxSocketClient::\destruct{wxSocketClient}}\label{wxsocketclientdtor}

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


@@ -1072,6 +1036,9 @@ Destructor. Please see \helpref{wxSocketBase::Destroy}{wxsocketbasedestroy}.
 
 \func{bool}{Connect}{\param{wxSockAddress\&}{ address}, \param{bool}{ wait = true}}
 
 
 \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
 Connects to a server using the specified address.
 
 If {\it wait} is true, Connect will wait until the connection


@@ -1088,6 +1055,10 @@ and {\bf wxSOCKET\_LOST} events (for connection failure).
 
 \docparam{address}{Address of the server.}
 
 
 \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}
 \docparam{wait}{If true, waits for the connection to complete.}
 
 \wxheading{Return value}


@@ -1192,7 +1163,7 @@ to member functions that take a wxSocketEvent argument.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

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

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