%% Created: 1999
%% RCS-ID: $Id$
%% Copyright: (c) wxWidgets team
-%% License: wxWidgets license
+%% License: wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\class{wxSocketBase}}\label{wxsocketbase}
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}
\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}
-\membersection{Socket state}
+\membersection{Socket state}\label{socketstate}
Functions to retrieve current state and miscellaneous info.
\helpref{SaveState}{wxsocketbasesavestate}\\
\helpref{RestoreState}{wxsocketbaserestorestate}
-\membersection{Basic IO}
+\membersection{Basic IO}\label{socketbasicio}
Functions that perform basic IO functionality.
\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.
\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
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
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.
\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.
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\_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
%
%
% wxSocketClient
%
-\membersection{wxSocketClient::wxSocketClient}
+\membersection{wxSocketClient::wxSocketClient}\label{wxsocketclientctor}
\func{}{wxSocketClient}{\param{wxSocketFlags}{ flags = wxSOCKET\_NONE}}
%
% ~wxSocketClient
%
-\membersection{wxSocketClient::\destruct{wxSocketClient}}
+\membersection{wxSocketClient::\destruct{wxSocketClient}}\label{wxsocketclientdtor}
\func{}{\destruct{wxSocketClient}}{\void}
\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
\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}
\latexignore{\rtfignore{\wxheading{Members}}}
-\membersection{wxSocketEvent::wxSocketEvent}
+\membersection{wxSocketEvent::wxSocketEvent}\label{wxsocketeventctor}
\func{}{wxSocketEvent}{\param{int}{ id = 0}}
projects / wxWidgets.git / blobdiff