miscellaneous wxFont enhancements (patch 1496606):

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

diff --git a/docs/latex/wx/socket.tex b/docs/latex/wx/socket.tex
index 9bede77f47e97d44f125724e6ed436d185b671f9..04a2515b898cbdad49e9f5cefb9590ef180d8f33 100644 (file)
--- a/docs/latex/wx/socket.tex
+++ b/docs/latex/wx/socket.tex
@@ -5,7 +5,7 @@
 %% Modified by:
 %% Created:     1999
 %% RCS-ID:      $Id$
 %% Modified by:
 %% Created:     1999
 %% RCS-ID:      $Id$

-%% Copyright:   (c) wxWindows team
+%% Copyright:   (c) wxWidgets team

 %% License:     wxWindows license
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 %% License:     wxWindows license
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 


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


@@ -124,7 +131,7 @@ Functions to retrieve current state and miscellaneous info.
 \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 wxWindows.
-
-\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


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